voyage/docs/spike-pretooluse-subagent-reach.md

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 states that sub-agent tool calls fire the same hooks and carry agent_id / agent_type, while issue #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

# 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:

{"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