[FEATURE] PreAgentSpawn hook: executable cost policy for sub-agent dispatch

Is your feature request related to a problem?

Claude Code models are not cost-aware. When Claude decides to spawn a sub-agent, it makes no consideration of cost implications — model tier, context size, whether the task warrants delegation at all. The only available mechanism for influencing this behavior is natural language in CLAUDE.md, which is advisory to a model that has no pricing information, no budget constraints, and no obligation to comply consistently.

This is compounded by a structural problem: a model's training cutoff virtually guarantees that pricing knowledge is stale. An instruction like "use Haiku for file reads" asks the model to apply current relative pricing data it cannot have. The price delta between Opus 4.7 and Haiku 4.5 — which can approach 10× once cache rates and the 200K extended-context cliff are factored in — is not reliably known to the model. Executable policy doesn't have this problem.

This is not an acceptable cost governance interface for professional or enterprise use.

Background

Sub-agent spawning has significant and non-obvious cost implications:

• Sub-agents inherit the parent session's model by default, meaning an Opus 4.7 / 1M context session spawns Opus 4.7 sub-agents for tasks Haiku could perform (file reading, searching, grepping) at a fraction of the cost. After accounting for cache read rates ($0.50/MTok vs $0.10/MTok) and the 200K extended-context pricing cliff, the cost difference can reasonably approach 10×.
• The existing model parameter on the Agent tool call is silently inoperative (#54448), leaving users with no working override mechanism at all.
• Sub-agent cache costs are invisible to the caller (#55121), making post-hoc JSONL analysis the only way to understand what was spent.

Describe the solution you'd like

A PreAgentSpawn hook, analogous to PreToolUse/PostToolUse, firing before each Agent tool invocation. The hook receives:

• The proposed task description / prompt
• The proposed model (currently always inherited from parent)
• Estimated scope if available

The hook returns a routing policy decision:

• Model to use
• Whether to proceed as sub-agent or inline
• Any spawn constraints

Claude treats the response as advisory — it may override if the task is genuinely incompatible with the specified model — but must notify the caller (not the GUI; this is an API, and headless contexts must be first-class) when it does so and why. Silent override defeats the purpose entirely.

Audit trail is mandatory, not optional

Every spawn decision must produce a structured log entry regardless of whether the hook fires, whether Claude overrides it, or whether the session has a hook configured at all. This "digital exhaust" is the mechanism by which cost governance actually works at scale — not technical enforcement at the developer layer.

On enterprise policy architecture

At scale (multiple business units, thousands of developers), a flat single hook is insufficient. The architecture needs hierarchical policy composition: org-level → BU-level → project-level → session-level, with explicit allow/deny semantics at each layer and inheritance from above.

A critical design principle: symmetric responsibility and authority. A developer should not be made responsible for anything they cannot actually control. They control what the platform gives them control over — session-level policy and their own prompts. Everything above that is org policy, and responsibility for it belongs to whoever sets it. The right enforcement mechanism at higher layers is not technical blocking at the developer level — which creates asymmetric responsibility and drowns central policy orgs in support tickets from developers hitting walls they didn't build and can't move. The right mechanism is making spend visible at the organizational layer that has both the authority and the incentive to act on it: one level above the budget owner, not at the individual developer.

Budget enforcement is explicitly out of scope for this hook. Anthropic already enforces at the quota level. Below that, organizations have budgets and manage them. The hook is a routing and optimization policy interface, not a budget cop. The audit trail feeds whatever spend visibility tooling the organization chooses to build; that is not Anthropic's responsibility to enforce and should not be distributed to developers who lack the authority to manage it.

Prior art / not a duplicate

Several existing issues document symptoms of this gap:

• #54448 — model override parameter is silently inoperative
• #53610 — multi-agent runtime lacks mechanical enforcement
• #54393 — post-mortem on multi-agent coordination failures
• #54861 and #54426 — related service behavior complaints

All of these complain about what the service does. This issue is about what the platform doesn't provide: a proper, executable interface for cost optimization policy that doesn't rely on a model that is structurally incapable of making cost-aware decisions.