Feature: Hook event for subagent spawning (OnAgentSpawn)

Resolved 💬 6 comments Opened Apr 16, 2026 by dracount Closed Apr 16, 2026

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.

View original on GitHub ↗

This issue has 6 comments on GitHub. Read the full discussion on GitHub ↗