[FEATURE] Enhanced Verbose/Debug Output Configuration with Resilient Parameter Handling

[stevenbaert]

Summary

Request for more granular and configurable verbose/debug output options when running Claude Code in GitHub Actions, with resilient parameter handling that gracefully falls back to defaults when options are deprecated or unavailable.

Current State

Available Options (claude-code-action v1.0)

Option	Type	Description
show_full_output	Action Input	Shows full JSON output including tool execution details (default: false)
claude_args: --verbose	CLI Flag	Enables verbose mode with expanded logging
claude_args: --debug	CLI Flag	Enables debug-level tracing
--output-format stream-json	CLI Flag	Outputs structured JSON for CI/debugging
ACTIONS_STEP_DEBUG=true	Env Var	Automatically enables full output in debug mode

Known Limitations (from existing issues)

1. anthropics/claude-code#4859: --debug outputs to stdout instead of stderr; --verbose has no effect in print mode
2. anthropics/claude-code#6308: All-or-nothing approach - no way to show timing/tokens without full debug logs
3. anthropics/claude-code#3217 / #7012: Verbose setting fails to persist across sessions
4. anthropics/claude-code#15066: Hook outputs not appearing in stream-json logs

Proposed Enhancement

1. New Workflow Input Parameters

Add configurable verbosity levels as workflow inputs:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Fix this bug"

    # Granular verbosity controls
    verbosity: "normal"  # Options: minimal | normal | verbose | debug
    show_tool_output: true
    show_timing: true
    show_token_usage: true
    log_format: "human"  # Options: human | json | stream-json

2. Environment Variable Configuration

Support configuration via environment variables in the settings input:

settings: |
  {
    "env": {
      "CLAUDE_VERBOSITY": "verbose",
      "CLAUDE_SHOW_TIMING": "true",
      "CLAUDE_SHOW_TOKENS": "true"
    }
  }

3. Verbosity Levels Definition

Level	Description	Shows
minimal	Errors only	Errors, permission denials, final status
normal	Default behavior	Init, result, errors, summary
verbose	Detailed execution	+ Tool calls, timing, token usage
debug	Full tracing	+ All internal events, JSON output

Resilient Parameter Handling (Critical)

Problem: When parameters are deprecated or phased out, workflows should not break.

Proposed Solution: Graceful Degradation Pattern

function resolveVerbosity(inputs: ActionInputs): VerbosityConfig {
  const warnings: string[] = [];
  const config: VerbosityConfig = { level: 'normal' }; // Safe default

  // Handle deprecated parameters gracefully
  const deprecatedParams = ['old_verbose_flag', 'legacy_debug_mode'];
  for (const param of deprecatedParams) {
    if (inputs[param] !== undefined) {
      warnings.push(`⚠️ Parameter '${param}' is deprecated. Use 'verbosity' instead.`);
    }
  }

  // Validate current parameters with fallback
  if (inputs.verbosity) {
    const validLevels = ['minimal', 'normal', 'verbose', 'debug'];
    if (validLevels.includes(inputs.verbosity)) {
      config.level = inputs.verbosity;
    } else {
      warnings.push(`⚠️ Unknown verbosity level '${inputs.verbosity}'. Falling back to 'normal'.`);
    }
  }

  // Log warnings but don't fail
  for (const warning of warnings) {
    core.warning(warning);
  }

  return config;
}

Key Principles

1. Never fail on unknown/deprecated parameters - Log warning, use default
2. Semantic versioning for breaking changes - Major version bump if behavior changes
3. Deprecation notices in logs - Clear messages about what to migrate to
4. Maintain backwards compatibility - Old parameters should work until next major version

Example Warning Output

⚠️ Deprecated parameter detected: 'verbose=true'
   This parameter will be removed in v2.0.
   Migration: Use 'verbosity: verbose' instead.
   
   Falling back to default behavior. Workflow will continue.

Optional: Auto-Report Feature

- uses: anthropics/claude-code-action@v1
  with:
    verbosity: verbose
    report_deprecated_params: true  # Creates issue if deprecated params used

When enabled, could automatically create/update an issue in the user's repo listing deprecated parameters detected.

Implementation Considerations

CLI Flag Mapping

switch (config.level) {
  case 'debug':
    cliArgs.push('--debug', '--verbose');
    break;
  case 'verbose':
    cliArgs.push('--verbose');
    break;
  case 'minimal':
    cliArgs.push('--quiet'); // May need new flag
    break;
}

Integration with show_full_output

// show_full_output takes precedence for backwards compatibility
if (inputs.show_full_output === 'true') {
  config.level = 'debug';
}

Testing Matrix

Scenario	Expected Behavior
verbosity: unknown_value	Warning + fallback to normal
verbose: true (deprecated)	Warning + map to verbosity: verbose
No verbosity params	Use normal default
ACTIONS_STEP_DEBUG=true	Override to debug (existing behavior)

Related Issues

• anthropics/claude-code#4859 - Debug/verbose modes not outputting to stderr
• anthropics/claude-code#6308 - Timing/tokens without verbose logs
• anthropics/claude-code#3217 - Verbose setting persistence
• PR #580 - Added show_full_output

Success Criteria

1. Users can configure verbosity without using claude_args
2. Deprecated parameters log warnings but don't break workflows
3. Clear migration path documented for each deprecation
4. Verbosity levels are intuitive and well-documented
5. Backwards compatibility maintained until major version bump

[stanley1208]

Hi! I'd like to take this on. Reading through the proposal, I think there's a tighter scope that gets the core user value shipped while deferring some of the more ambitious pieces.

I wanted to share that thinking before I dive in.
The problem here is that there's no middle ground in the output today. You either get almost nothing, or you turn on debug and get flooded. Users prefer something in between, to see which tools ran, how long they took, and the token usage, without all the rest of the debug output.
Here's the scope I'd propose for the first PR:
In scope:

• New verbosity input with three levels: normal, verbose, debug
• Backward compat: existing show_full_output: true maps to verbosity: debug; false is the default and behaves like verbosity: normal
• Graceful fallback when an unknown value is passed (warn and default to normal)
• Tests and documentation for the above

Deferred to follow-up PRs:

• The minimal level: --quiet doesn't exist in the upstream Claude Code CLI, so this is a cross-repo dependency I'd rather not block on
• The four boolean inputs (show_tool_output, show_timing, show_token_usage)
• log_format option (overlaps with the existing --output-format flag, worth its own design discussion)
• Env-var configuration via settings
• The auto-report feature (creating issues in user repos has security and rate-limit implications worth a separate conversation)
  The reasoning is just to keep the first PR small and reviewable. Once the verbosity input lands as a foundation, the rest is incremental work.

Let me know what you think of this scope. Happy to discuss further or be assigned to this if it looks right.