Feature request: Add `agent_depth` (or caller identity) to hook event payload

Use case

We're building a Claude Code plugin for autonomous architecture review and software delivery. It uses an orchestrator agent that spawns 30+ sub-agents per review round (pre-review analysts, dimension reviewers, a review lead, fix agents, etc.).

A critical invariant of this system: the orchestrator must coordinate but NEVER read the source document being reviewed. When the orchestrator reads the document, its judgment of sub-agent findings becomes biased — it starts evaluating findings against its own interpretation rather than trusting the structured review process. We call this "context poisoning." We need hooks to enforce this structural isolation.

Current limitation

The PreToolUse hook payload contains only:

{
  "tool_name": "Read",
  "tool_input": { "file_path": "/path/to/architecture.doc" },
  "cwd": "/path/to/project"
}

There is no field indicating whether the tool call originates from the top-level conversation (the orchestrator) or from a sub-agent spawned via the Agent tool. This means a hook cannot distinguish between:

• The orchestrator trying to read architecture.doc (should be BLOCKED)
• A dimension reviewer sub-agent trying to read architecture.doc (should be ALLOWED)

Both produce identical hook payloads. The hook has no way to enforce different access policies for different depths of the agent hierarchy.

Proposed solution

Add an agent_depth integer field to the hook event payload:

| Value | Meaning |
|-------|---------|
| 0 | Top-level conversation (the orchestrator) |
| 1 | Agent spawned by the orchestrator |
| 2 | Agent spawned by an agent spawned by the orchestrator |
| ... | etc. |

Example payload

{
  "tool_name": "Read",
  "tool_input": { "file_path": "/path/to/architecture.doc" },
  "cwd": "/path/to/project",
  "agent_depth": 0
}

Alternative approaches that would also work

• A session_id or agent_id string field that uniquely identifies the calling agent instance
• A parent_agent_id field enabling hooks to reconstruct the spawn tree
• An agent_stack array showing the chain of agent spawns (most expressive, possibly overkill)

Any of these would allow hooks to distinguish callers. The integer depth is the simplest and covers the most common case.

Impact

This would enable a class of hook-based enforcement that is currently impossible:

• Orchestrator isolation — prevent the orchestrator from reading source documents, enforcing separation between coordination and analysis
• Depth-based file scoping — sub-agents can be restricted to specific file paths based on their spawning depth
• Structural separation of concerns — multi-agent workflows can enforce role boundaries via hooks rather than prompt instructions
• Audit logging — hooks can attribute tool calls to specific agent depths for post-hoc analysis

Current workaround

We currently rely on prompt instructions ("do NOT read this file") combined with gate files. This is a discipline boundary, not a structural one. Models are trained toward helpfulness and routinely violate "don't read this file" instructions — especially under long context windows where the instruction drifts out of attention. We've observed this failure mode repeatedly in production review rounds.

We also experimented with filesystem-level isolation via bwrap/sandbox-exec, but this requires the hook to control the sandbox configuration, which still needs caller identity to set up correctly.

Environment

• Claude Code CLI (latest)
• Hook type: PreToolUse (also relevant for PostToolUse and Stop)
• Platform: Linux (Manjaro) and macOS