fix: add --max-turns 1 to Claude preflight check for reliable completion

[subsy]

The preflight check was timing out because it didn't limit Claude to a
single turn. Without --max-turns 1, Claude could run multiple turns or
attempt tool use, potentially exceeding the 30-second timeout even for
a simple test prompt.

This matches the behavior of a working manual test:
claude -p "Say OK" --max-turns 1

Fixes #161

Summary by CodeRabbit

• New Features
  • Added agent preflight validation to run a quick, bounded feasibility check before operations.
  • Performs a minimal one-turn test, captures output and timing, and identifies timeouts or execution failures.
  • Returns timing information and actionable error suggestions to help troubleshoot availability issues.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
ralph-tui	Ignored		Jan 20, 2026 2:12pm

[coderabbitai]

Walkthrough

A preflight override is added to ClaudeAgentPlugin that verifies Claude CLI presence, runs a bounded one-turn test prompt using --max-turns 1, captures stdout, measures duration, and returns an AgentPreflightResult indicating success or structured failure (timeout, execution error, or empty output).

Changes

Cohort / File(s)	Summary
Claude Agent Preflight Override src/plugins/agents/builtin/claude.ts	Adds override async preflight(options?: { timeout?: number }) implementing: CLI detection, timed spawn of claude with a minimal prompt and --max-turns 1, stdout capture, timeout and execution failure handling, empty-output detection, and returning structured AgentPreflightResult with durationMs and guidance via getPreflightSuggestion.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ClaudeAgentPlugin
  participant ClaudeCLI as "claude (external CLI)"
  Caller->>ClaudeAgentPlugin: request preflight(timeout?)
  ClaudeAgentPlugin->>ClaudeAgentPlugin: detect claude CLI
  ClaudeAgentPlugin->>ClaudeCLI: spawn process with test prompt (--max-turns 1)
  Note right of ClaudeCLI: runs test prompt\nwrites to stdout or fails
  ClaudeCLI-->>ClaudeAgentPlugin: stdout / error (or no output)
  ClaudeAgentPlugin->>ClaudeAgentPlugin: evaluate output, measure duration
  alt success (non-empty stdout)
    ClaudeAgentPlugin-->>Caller: AgentPreflightResult { success: true, durationMs }
  else timeout / exec error / empty output
    ClaudeAgentPlugin-->>Caller: AgentPreflightResult { success: false, reason, suggestion, durationMs }
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• feat(agents): add preflight system and doctor command #130: Adds base preflight infrastructure (preflight signature, AgentPreflightResult type, and suggestion framework) that this Claude-specific override extends.

Poem

🐰 I hopped a quick test to see,
A single prompt, one-turn spree,
Claudes replied — no mystery,
Timed and checked, now safe and free 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change—adding --max-turns 1 to the Claude preflight check—which directly addresses the timeout issue documented in the PR.
Linked Issues check	✅ Passed	The implementation adds a bounded preflight check with --max-turns 1 that prevents timeouts by limiting Claude to single-turn responses, directly resolving issue #161.
Out of Scope Changes check	✅ Passed	All changes are scoped to implementing the preflight override in ClaudeAgentPlugin; no unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 1.21951% with 81 lines in your changes missing coverage. Please review.
✅ Project coverage is 40.70%. Comparing base (f5a1286) to head (d6e6479).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/plugins/agents/builtin/claude.ts	1.21%	81 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #165      +/-   ##
==========================================
- Coverage   40.87%   40.70%   -0.18%     
==========================================
  Files          72       72              
  Lines       19912    19996      +84     
==========================================
  Hits         8140     8140              
- Misses      11772    11856      +84     

Files with missing lines	Coverage Δ
src/plugins/agents/builtin/claude.ts	39.63% <1.21%> (-5.88%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.