feat: add --debug flag for Claude Code debug logging

[gklein]

Add --debug [filter] flag to fullsend run that enables Claude Code debug logging inside the sandbox and extracts the log to the run output directory.

• --debug enables all debug categories via --debug-file
• --debug=api,hooks enables filtered categories via --debug-file combined with --debug ''
• Debug log extracted to /claude-debug.log alongside transcripts
• Off by default with zero overhead when not used

Uses NoOptDefVal="*" for optional-value flag semantics: --debug alone gives all categories, --debug= gives filtered output.

Closes #909

[github-actions]

fullsend review is working on this — view logs

[github-actions]

Site preview

Preview: https://48caae6f-site.fullsend-ai.workers.dev

Commit: cf683ff8dec63077902883431c174beba336ae61

[fullsend-ai-review]

Review

Both prior review findings have been addressed:

1. Missing quote-escaping test for debug filter → TestBuildClaudeCommand_DebugEscapesQuotes added
2. --debug-file path unquoted → now uses --debug-file '%s/%s'

No findings.

Previous run

Review: #911

Head SHA: 8555598
Timestamp: 2026-05-14T00:00:00Z
Outcome: comment-only

Summary

Clean, well-scoped feature addition that correctly implements the --debug flag for Claude Code debug logging. The three-way branching logic (disabled / all categories / filtered) is correct, shell escaping is applied to user input, and the extraction logic is properly gated. Two minor style observations below — neither is blocking.

Findings

Medium / Low / Info

• [style/conventions] internal/cli/run_test.go — Missing test for single-quote escaping in the debug filter value. Every other user-supplied parameter that flows into buildClaudeCommand (agentName, model, pluginDirs) has a dedicated quote-escaping test (e.g., TestBuildClaudeCommand_EscapesQuotes, TestBuildClaudeCommand_PluginDirEscapesQuotes). The debug filter applies the same strings.ReplaceAll(debug, "'", "'\\''") pattern but lacks a corresponding test.
  Remediation: Add a TestBuildClaudeCommand_DebugEscapesQuotes test, e.g. buildClaudeCommand("agent", "", "/repo", nil, "api'hooks") and assert the output contains --debug 'api'\\''hooks'.

• [style/conventions] internal/cli/run.go:1081 — The --debug-file path is unquoted in the format string (--debug-file %s/%s) while all other user-facing flags (--model, --agent, --plugin-dir) are single-quoted. Both path components are compile-time constants so this is not exploitable, but quoting would be consistent with the defense-in-depth style used throughout buildClaudeCommand.
  Remediation: Change to --debug-file '%s/%s' for consistency.

Footer

Outcome: comment-only
This review applies to SHA 85555982e84d94f9432ac3bd0ac80d5b55463e90. Any push to the PR head clears this review and requires a new evaluation.

Previous run (2)

Review: #911

Head SHA: a735252
Timestamp: 2026-05-14T12:00:00Z
Outcome: approve

Summary

Clean, well-scoped implementation of --debug flag support for Claude Code debug logging. The change correctly uses cobra's NoOptDefVal for optional-value flag semantics, properly escapes shell metacharacters in the debug filter string (consistent with existing defense-in-depth patterns for agentName and model), and includes good test coverage across all three modes (disabled, all categories, filtered categories). Two minor observations below, neither blocking.

Findings

Medium

• [Correctness] internal/cli/run.go:542-546 — Debug log extraction silently ignores download failure. When --debug is explicitly requested, the user expects diagnostic output. Other extraction steps (transcripts at line 533, output files at line 520) warn on failure with printer.StepWarn(...), but the debug log extraction only logs on success. If Claude Code fails to produce the log file (misconfigured --debug-file path, sandbox filesystem issue), the operator gets no feedback.
  Remediation: Add an else branch with printer.StepWarn("Failed to extract debug log: " + err.Error()) to match the convention used by adjacent extraction steps.

Info

• [Style/conventions] internal/cli/run.go:70 — The runAgent function signature now has 9 positional parameters (including the new debug string). This is pre-existing technical debt, not introduced by this PR, but worth noting as a candidate for an options struct in a future refactor.

Footer

Outcome: approve
This review applies to SHA a735252d74ea63fb92aa120a38d0fcedcf54e6e5. Any push to the PR head clears this review and requires a new evaluation.

[github-actions]

fullsend review is working on this — view logs

[gklein]

All changes in commit cf683ff

• Move constant to top of file (feat: add --debug flag for Claude Code debug logging #911 (comment))
  Done — moved claudeDebugLog and maxContextScanDepth into a grouped const block after imports.

• Format string spacing (feat: add --debug flag for Claude Code debug logging #911 (comment))
  The %s%s%s--agent pattern is pre-existing (was %s%s--agent before this PR). Each flag string includes a trailing space when non-empty, so separation is correct at runtime. Adding literal spaces in the format string would double-space when flags are populated. Keeping the convention as-is for consistency with modelFlag and pluginDirFlags.

• Factor out common --debug-file (feat: add --debug flag for Claude Code debug logging #911 (comment))
  Done — --debug-file is now set once when debug != "", and --debug '' is appended only when debug != "*". Also quoted the --debug-file path for consistency with --model, --agent, and --plugin-dir.

• Add quote-escaping test (review bot finding)
  Done — added TestBuildClaudeCommand_DebugEscapesQuotes to match the existing pattern for agent name and plugin dir escaping tests.

[rh-hemartin]

Looks good to me. I think we need a followup issue to separate the commands with spaces and remove the trailing spaces from the commands itself. I don't like to rely on every new command remembering to add a trailing space.