# 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