Summary

Please expose taskBudget from claude-code-action so reviewers can opt into API-side token-budget awareness. The SDK has supported it since @anthropic-ai/claude-agent-sdk v0.2.84 (CHANGELOG); the action pins 0.3.144 as of v1.0.124, so the capability is already in the dependency closure. Today there's no way to set it from the action layer.

What I'm using claude-code-action for

CI code review on every PR in our monorepo (systemtwosecurity/detectionsai, ~30 PRs/day). One Opus 4.7 review pass per PR, sticky comment + inline findings.

Why this matters in practice

We did a 14-day forensic audit of our review runs (writeup). Headline number: 37% of completed review runs hit --max-turns despite --effort xhigh and risk-tiered turn caps (currently 8/25/45/70 + size adjustments up to 110). The agent has no in-prompt visibility into its remaining budget, so it can't pace verification work — it just hits the cap and exits, often without posting the findings it was about to write up. PR #2495 in our repo (4 successive max_turns runs while the visible sticky still read "No issues found" from an earlier run) is the canonical case.

We've worked around this by manually threading MAX_TURNS into the PR Context block of the prompt and adding budget-discipline instructions ("post by turn MAX_TURNS-4"), but the model has no actual budget telemetry. That's exactly what taskBudget provides.

Current state in the action

• base-action/src/parse-sdk-options.ts builds an explicit SdkOptions (model, maxTurns, allowedTools, systemPrompt, extraArgs, ...). No taskBudget field. Anything in claude_args lands in extraArgs (CLI passthrough), where the bundled Claude Code CLI 2.1.144 doesn't recognize a --task-budget flag and silently ignores it.
• action.yml v1.0.124 has no task_budget input.
• Grep across the action repo at v1.0.124: zero taskBudget / task-budget references.

What I'd like to be able to do

Two options that would unblock us (either is fine):

Option A — recognized claude_args flag. Have parse-sdk-options.ts recognize something like --task-budget=200000 (or --task-budget-total=200000 to make the shape obvious) and route it to sdkOptions.taskBudget = { total: 200000 }. ~10 LoC.

Option B — first-class action input. Add a task_budget input to action.yml:

task_budget:
  description: "API-side token budget (total tokens). When set, the model is made aware of its remaining budget. Maps to SDK `taskBudget.total`. See https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/sdk.d.ts (taskBudget option, @alpha)."
  required: false
  default: ""

… wired into sdkOptions.taskBudget. A bit more LoC but more discoverable.

Either is fine; both leave room for the API-side option to evolve (it's still @alpha in the SDK).

Workaround alternatives I've considered

• Fork-and-patch the action. Doable but creates drift from upstream and we'd lose your release cadence + bug fixes.
• Bypass the action and call the SDK directly. Substantial — we'd lose the GH App token handling, sticky-comment plumbing, inline-comment MCP server, etc.

So the cleanest path forward is just to expose the SDK option from the action layer. Happy to send a PR if a maintainer can point at the preferred API shape (Option A vs B).

References

• SDK type definition: package/sdk.d.ts:1475-1483 in @anthropic-ai/claude-agent-sdk@0.3.144
• SDK CHANGELOG (v0.2.84): "Added taskBudget option for API-side token budget awareness, allowing the model to pace tool use within a token limit"
• Beta header: task-budgets-2026-03-13 (sent automatically by SDK when taskBudget is set)