Feature: Hook event for subagent spawning (OnAgentSpawn)
Problem
Subagents do not inherit CLAUDE.md or any project-level instructions. The only way to pass rules to subagents is by instructing the model to manually prepend content to each subagent prompt.
In practice, the model progressively abbreviates these instructions across multi-subagent sessions. Auditing across two separate sessions showed the same pattern: the first subagent gets full rules, subsequent ones get progressively shortened summaries (down to ~5% coverage by task 4+). This is a model-level behavior under context pressure — no amount of instructions or memory prevents it.
Request
Add an OnAgentSpawn hook event that fires when the Agent tool is invoked, allowing users to intercept and modify subagent prompts before execution.
This fits naturally into the existing hook architecture (PreToolUse, PostToolUse, etc.) and would enable:
- Automatic preamble injection — prepend project rules to every subagent prompt without relying on the model
- Conditional injection — inject different rules based on agent type (e.g., code-writing agents get quality rules, Explore agents don't)
- Auditing/logging — track what subagents are being spawned and what they receive
- Rate limiting — control subagent spawn frequency
Simpler Alternative
If a full hook event is too heavy, a subagentPreamble setting in settings.json (string or file path) that the harness automatically prepends to every subagent prompt would also solve the core problem. Less flexible but simpler to implement.
Why This Matters
The current architecture puts instruction inheritance entirely on the model, which is the one component that can't be trusted to do it consistently. Moving enforcement to the harness eliminates the drift problem entirely.
6 Comments
Found 2 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
The progressive instruction abbreviation pattern you've documented (100% → ~5% by task 4+) is the same root cause as several other identity continuity issues in this tracker — the model treats the instruction set as context to be summarized during compaction, not as an invariant constraint that must survive intact across the session.
An OnAgentSpawn hook is the right structural fix because it moves instruction injection from the model's decision path (where it degrades) to the harness's execution path (where it's deterministic). The hook runs at spawn time before the subagent's first token, so it doesn't depend on the parent model remembering to include the rules.
Design considerations for the hook payload:
The hook should receive the full spawn context (parent session ID, subagent task description, requested tools) so it can make injection decisions. A hook that always injects the full CLAUDE.md is better than nothing, but a hook that can inspect the task and inject only relevant sections avoids the context bloat that causes compaction in the first place.
Alternative: spawn-time config inheritance
A simpler implementation that doesn't require a hook mechanism: subagents spawned within a project directory should automatically inherit the project's CLAUDE.md, the same way the parent session does. This is a configuration resolution change, not a new hook surface. The hook would then be for cases where the inherited config needs to be modified or augmented per-subagent.
The behavioral attestation angle:
When subagents operate with degraded instructions, they also operate with a degraded identity contract — they don't know what constraints they're supposed to be enforcing. From a trust perspective, a subagent that received only 5% of its governing instructions is not operating under the same identity as one that received 100%. This is why session-level identity continuity and instruction continuity need to be solved together.
Closing in favor of #29423 which covers the same core problem. Adding the hook/preamble suggestion there.
I think this is the right layer for the fix.
The important part of the report is that the failure happens during prompt construction, before the subagent has even started useful work. If inherited rules are routed through model-generated summaries, then rule coverage becomes probabilistic. The first subagent may get the full instruction set, while later subagents inherit an increasingly compressed version of it.
That makes this the same class of problem as compaction drift and context-visible rule violations: the rule exists somewhere, but the system relies on the model to preserve and reapply it under pressure. That is not reliable enough for project-level constraints.
An
OnAgentSpawnhook is the cleaner architecture because it moves inheritance into the harness layer. The parent session should not have to ask the model to remember which rules a subagent needs. The harness should be able to inject the required project/substrate preamble directly, before the subagent prompt forms.One additional point: the inherited block itself probably matters. If the hook injects normal reminder-style prose, some drift may remain. The injected content should behave more like an eligibility gate than a summary:
Subagent inheritance should probably not rely on compacted or model-generated summaries at all. Compaction is built to preserve task continuity, not exact rule coverage. If subagents need exact project authority, the harness should inject that authority directly outside the compaction loop.
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.