Log Every Subagent Spawn With Inherited Permission Mode
A PreToolUse hook on the root session has no visibility into what a spawned subagent does — this is the one event that fires at the moment of spawn, regardless of what the subagent goes on to do, so at minimum there's a durable record that it existed and what mode it inherited.
1. Save this as the hook script
#!/usr/bin/env python3
"""SubagentStart hook — logs every subagent spawn."""
import json, sys, datetime
from pathlib import Path
data = json.load(sys.stdin)
log_path = Path(data.get("cwd", ".")) / ".claude" / "subagent_log.jsonl"
log_path.parent.mkdir(parents=True, exist_ok=True)
entry = {
"ts": datetime.datetime.utcnow().isoformat() + "Z",
"agent_type": data.get("agent_type"),
"agent_id": data.get("agent_id"),
"permission_mode": data.get("permission_mode"),
}
with open(log_path, "a") as f:
f.write(json.dumps(entry) + "\n")
sys.exit(0)
Save to a path inside your project, e.g. .claude/hooks/log-subagent-spawn-permission-mode.sh, then chmod +x it.
2. Wire it into .claude/settings.json
{
"hooks": {
"SubagentStart": [
{
"hooks": [
{"type": "command", "command": "python3 .claude/hooks/log-subagent-spawn-permission-mode.py"}
]
}
]
}
}
Before you use this
A hook runs with your local shell's permissions — review the script above before adding it, the same way you'd review any script you didn't write yourself. See our guide on hook security risks for the specific CVEs this category of feature has already produced.
Related hooks