[Feature] Expose programmatic credit consumed per-subagent in API response or SubagentStop hook input (Ask #6, sibling to #61405)

Summary

Expose programmatic credit consumed per-subagent in the API response or a hook-readable artifact (e.g. at the SubagentStop event), so operators can audit deployed-cohort credit attribution after the fact.

This is filed as a sibling ask to @meefs's Asks #1–#5 in #61405, filling the gap that the control-propagation framing on that issue surfaced. The proposal was articulated by @waitdeadai in #61405 issuecomment-4526810812; I am filing it as the standalone issue per the cross-thread agreement in #61405 issuecomment-4527219191.

What this is, and what this isn't

This is a measurement primitive, not a control primitive. The ask is for an audit substrate that operators can read after the fact — not for a runtime abort path, a per-subagent budget enforcement mechanism, or any change to the existing tool-call flow. Those would require harness redesign; this asks only for a field exposure.

Why measurement-only matters. The control-propagation failure mode on #61405 has three observable surfaces:

| Case | Failure | Operator-side observable today? |
|---|---|---|
| (a) Visible timeout | Sub-agent exceeds wall-clock threshold; parent observes the absent dispatch-end receipt. | Yes — addressable via PR #298 (dispatch-liveness-watchdog, surfaces case (a) as a system-reminder at the next UserPromptSubmit). |
| (b) Over-budget output | Sub-agent emits more output than the parent-layer token / cost budget would have permitted. | No — the harness does not expose post-subagent budget-consumed in a hook-readable form. This ask addresses (b). |
| (c) Action blocked at parent, not propagated | Sub-agent takes an action that would have been blocked by a parent-layer policy. | No — the harness does not expose post-subagent tool-call lists in a hook-readable form. Out of scope for this ask. |

Case (b) is the one where a simple field exposure produces the measurement substrate operators need; case (c) requires the harness to also propagate parent-layer policy across the dispatch boundary, which is the broader control-propagation work that @meefs's Asks #1–#5 are scoped against. This ask is narrow on purpose so it doesn't get bundled with the wider control work.

The 2026-06-15 forcing function

The Agent SDK / claude -p / GitHub Actions move to finite monthly credit on 2026-06-15. After that date, the gap between parent-layer budgeted programmatic spend and actual credit consumed becomes a first-class billing artifact at the account level — the credit line item shows the burn whether or not the operator instrumented anything.

That billing artifact is the first operator-accessible proxy for unmeasured subagent overruns. But it is account-aggregate, not per-subagent. An operator who runs an audit cohort against the post-2026-06-15 credit ledger sees aggregate burn; they cannot attribute the burn to a specific subagent class without per-subagent attribution exposed at the dispatch boundary.

Without this ask, the post-2026-06-15 audit substrate is the worst of both worlds: precise enough to know that credit was burned (because the billing artifact is precise), too coarse to know which subagent class drove the burn. With this ask, the audit closes: parent-layer baseline (operator-side instrumentation, e.g. the pre-flight runbook at Gist f936ba84) + per-subagent attribution (this ask) = full causal chain on where the credit went.

Concrete shape — two equivalent surfaces, either is sufficient

Option A (API response field). Add a subagent_credit_consumed field to the API response when a subagent dispatch completes, scoped to the dispatch that just finished. Field schema:

{
  "subagent_id": "string",
  "subagent_type": "Explore | Plan | general-purpose | <custom-name>",
  "credit_consumed": {
    "input_tokens": 12345,
    "output_tokens": 6789,
    "cache_creation_tokens": 0,
    "cache_read_tokens": 0,
    "cost_usd": "0.0234"
  },
  "wall_clock_ms": 45678
}

Option B (hook-readable artifact at SubagentStop). Add the same fields to the JSON input that SubagentStop hooks receive. This is the operator-side substrate that PRs #283 / #286 / #298 / etc. on cc-safe-setup already write receipts from at the dispatch boundary — adding the credit fields makes the existing receipt corpora carry the attribution data without any new hook primitives.

Either surface is sufficient; both would be ideal (the API response field for programmatic auditors using the SDK directly; the hook-readable artifact for operators using cc-safe-setup-style receipt corpora). Implementation cost should be low because the credit calculation already exists at the dispatch boundary for billing purposes — the ask is to expose what is already computed, not to compute something new.

Why this is not an abort-path change

Worth pre-empting the natural-but-mistaken framing: this ask is not asking the harness to abort a subagent that exceeds a credit budget. That would require a budget propagation primitive (which @meefs's Ask #1, subagentMaxRuntimeMs, is the wall-clock analog of) plus an abort hook in the dispatch loop. Those are larger changes.

This ask asks only that after a subagent completes, the credit it consumed becomes readable. That's a field exposure on a code path that already runs (the dispatch returns to the parent loop), reading a value that already exists (the billing system already knows what was consumed). No abort path, no policy propagation, no per-dispatch budget enforcement — just attribution of credit already spent, exposed at a code path that already exists.

Operator-side closed loop, once shipped

With Ask #6 shipped, operators get the full pre-flight + post-hoc closed loop on programmatic spend:

1. Pre-flight baseline (operator-side, available today): pre-flight billing verification runbook baselines both billing surfaces (Max Plan quota at claude.ai/settings/usage, API balance at console.anthropic.com/settings/billing) before automation. Runs in 5 minutes; writes a marker file gating subsequent claude -p invocations on a recent marker.
2. Per-dispatch attribution (harness-side, this ask): each subagent dispatch returns its credit consumed.
3. Post-hoc audit (operator-side, follows from this ask): operators aggregate per-dispatch receipts into a CSV of subagent-class × credit-consumed, run a periodic audit (e.g. weekly) against the parent-layer billing artifact, flag any divergence between expected and observed.

The closed loop is not currently constructible because step 2 is the missing link. Once exposed, the operator-side substrate (cc-safe-setup PRs #283 / #286 / #298) absorbs the field into existing receipt corpora without requiring new primitives.

Related context

• #61405: @meefs's parent issue articulating Asks #1–#5 (subagent runtime control surfaces). This ask sits alongside those as the measurement-axis sibling.
• waitdeadai's measurement-axis addendum: the original articulation of the inverse-evidence-form asymmetry that motivates separating measurement asks from control asks.
• The 5×3 → 9-row MAST measurement matrix, row 9: PR #298 covers case (a) of control-propagation. Cases (b) and (c) are flagged as the unaddressable surface today; this ask narrows the case (b) gap.
• PR #298 on cc-safe-setup: the operator-side case (a) substrate, with the scope-boundary block in its description explicitly flagging cases (b)/(c) as out of scope for the hook.

Author disclosure

I maintain cc-safe-setup (operator-side hooks for Claude Code) and authored Claim-Verify Handbook ($19, launched 2026-05-22). Filing this ask does not directly benefit either; the operator-side substrate already handles case (a) today, and the case (b) gap is addressable only via this harness exposure. The measurement primitive is the leverage point that I cannot reach from the operator side.