docs(hooks): spike PreToolUse reach into sub-agent tool calls

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/spike-pretooluse-subagent-reach.md

@@ -0,0 +1,109 @@
+# Spike: does a plugin `PreToolUse` hook reach sub-agent tool calls?
+
+**Date:** 2026-08-09
+**Claude Code version:** 2.1.226
+**Plugin:** voyage 5.9.1 (installed from `ktg-plugin-marketplace`)
+**Gates:** Step 10 of `plan.md` (`2026-06-30-trekresearch-storm-upgrade`)
+
+## Question
+
+Step 10 wants to enforce the conversation-turn cap in a `PreToolUse` hook. That
+is only viable if a **plugin** `PreToolUse` hook fires on tool calls made
+*inside a sub-agent*. If it does not, the cap must be enforced somewhere else
+and Step 10 becomes a documented downgrade instead.
+
+The question is genuinely open, not answerable from docs alone: the current
+[hooks reference](https://code.claude.com/docs/en/hooks) states that sub-agent
+tool calls fire the same hooks and carry `agent_id` / `agent_type`, while
+[issue #34692](https://github.com/anthropics/claude-code/issues/34692) reported
+the exact opposite behaviour. The answer is therefore version-dependent and had
+to be measured on the version actually in use.
+
+## Method
+
+A one-shot probe hook was registered for the `WebSearch` matcher, and a
+**headless child session** was launched to exercise it. The child was used
+because hooks are resolved when a session starts — a matcher added mid-session
+cannot be observed by the session that added it.
+
+Two deviations from the step as originally written, both forced and both
+verified not to affect the result:
+
+1. **The matcher was injected into the installed plugin's `hooks.json`, not the
+   repository's.** The plan assumed the repo working tree *is* the active plugin
+   root. It is not: `~/.claude/plugins/cache/ktg-plugin-marketplace/voyage/5.9.1/`
+   is a plain directory holding its own copy, and that copy is what loads.
+   Editing `hooks/hooks.json` in the repo would have measured nothing. The cache
+   file was backed up, modified, and restored — verified byte-identical to the
+   repo file afterwards.
+2. **The probe script lives under the session scratchpad, not `${TMPDIR}`.** A
+   pathguard hook refuses writes to `${TMPDIR}`. The load-bearing property was
+   only that the script sit **outside `hooks/scripts/`**, which
+   `tests/lib/doc-consistency.test.mjs:75-84` counts via `readdirSync`; the
+   scratchpad satisfies that just as well. The directory still holds 7 scripts.
+
+### Probe hook
+
+Logged every invocation as one JSON line (`tool_name`, `agent_id`,
+`agent_type`, plus the untouched stdin) and always exited `0`, so it could not
+alter the child's behaviour.
+
+### Commands
+
+```bash
+# 1. inject the temporary matcher into the INSTALLED plugin
+node -e '...push {matcher:"WebSearch", ...voyage-spike-hook.mjs} into hooks.PreToolUse...'
+
+# 2. exercise it from a fresh child session
+claude -p "Spawn exactly one sub-agent via the Agent tool (subagent_type: general-purpose).
+           Instruct that sub-agent to perform exactly ONE WebSearch for the query
+           'claude code hooks reference' and report back the first result title.
+           You MUST NOT call WebSearch yourself in the main context - only the
+           sub-agent may call it. When the sub-agent returns, reply with the word DONE." \
+  --allowedTools "Agent,Task,WebSearch" \
+  --max-turns 15
+
+# 3. restore
+cp "${TMPDIR}voyage-hooks-backup.json" <cache>/hooks/hooks.json
+```
+
+The child returned `DONE`.
+
+> An earlier attempt additionally passed `--permission-mode bypassPermissions`
+> and was refused by the auto-mode classifier. The flag was dropped;
+> `--allowedTools` alone was sufficient.
+
+## Raw observation
+
+The log contains **exactly one** record — so the main context did not call
+`WebSearch` itself, and the single entry is unambiguously the sub-agent's call:
+
+```json
+{"at":"2026-08-09T12:07:47.796Z","tool_name":"WebSearch",
+ "agent_id":"aa6d19525a4680fe0","agent_type":"general-purpose",
+ "raw_stdin":"{\"session_id\":\"b126fd6a-...\",\"cwd\":\"/Users/ktg/repos/ktg-plugin-marketplace/voyage\",
+   \"permission_mode\":\"auto\",\"agent_id\":\"aa6d19525a4680fe0\",\"agent_type\":\"general-purpose\",
+   \"effort\":{\"level\":\"xhigh\"},\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"WebSearch\",
+   \"tool_input\":{\"query\":\"claude code hooks reference\"},\"tool_use_id\":\"toolu_01Ka4...\"}"}
+```
+
+Both `agent_id` and `agent_type` are populated, matching the documented
+common-input fields for sub-agent-originated tool events. A main-context call
+would have carried neither.
+
+## Consequence for Step 10
+
+A plugin `PreToolUse` hook **does** observe sub-agent tool calls on CC 2.1.226,
+and can attribute them via `agent_id` / `agent_type`. Step 10 may therefore take
+the enforcement branch rather than the documented-downgrade branch.
+
+Two limits worth carrying forward, neither of which changes the verdict:
+
+- This measures `WebSearch` on one CC version. The behaviour regressed once
+  before (#34692), so the hook must fail **open**, never assume it is the only
+  gate, and the cap must remain correct if the hook silently stops firing.
+- The probe only establishes *reach*. Whether a **blocking** (exit 2) decision
+  from inside a sub-agent propagates usefully was not measured — the probe
+  always exited 0 by design.
+
+RESULT: FIRES