prompt-hook fires on Claude Code's system-injected <task-notification> messages: 3.5s median, 7.4s max on the blocking path #1832

Summary

UserPromptSubmit fires for messages the user never typed. When a background agent (the Agent
tool) finishes, Claude Code injects a <task-notification> block into the turn as a user message,
and the hook receives it on stdin as input.prompt exactly like a real prompt.

Those blocks are long machine text: task IDs, toolu_* tool-use IDs, scratchpad paths, and the
finishing agent's prose summary about code. They trip hasStructuralKeyword(), which is sufficient
on its own, so the whole blob goes to codegraph_explore as the query:

const result = await handler.execute('codegraph_explore', { query: prompt });

Explore's cost tracks the number of distinct identifier-shaped tokens in the query. A notification
block carries a median of 27 of those. My typed prompts carry a median of 0. The result is a
multi-second stall on a hook that blocks the turn.

Measured against my own history, one indexed repo (~57 MB index, large Python codebase), v1.6.0
darwin-arm64, 8 days of ~/.claude/projects/*/*.jsonl:

36% of the hook's successful firings were on text I never wrote, at roughly 5x the cost of my real
prompts.

Relationship to #1654 and #1694

I checked both before filing. This is a third thing.

#1654 (ambiguous keywords escalate to HIGH) covers human-written prompts whose keywords are
lexically ambiguous. Every direction proposed there would leave this case untouched: routing
keywords through the index check, an "ambiguous interrogative" tier, requiring a second signal. A
task notification is a summary about code. It carries unambiguous structural keywords and
identifier-shaped tokens that verify against the index, because the agent really was working on
those symbols. It passes every proposed gate on the merits. Gate quality is not the problem here;
the input was never a prompt.

#1694 (16k injection cap vs Claude Code's 10k inline limit) covers what happens to the payload
after explore returns. I see that too, on every slow firing (Output too large (15.8KB) plus a 2 KB
preview), but it is already reported and closed. This issue is about the seconds spent before the
payload exists, and about the firing happening at all.

The 10,000-char query cap in ToolHandler (mcp/tools.js) does apply on this path and works
correctly. It sits above where the notifications live: of 82 notification blocks in my transcripts,
77 are under the cap and go straight through.

Repro

Any indexed repo. Both prompts below are ~9 KB and produce the same ~16 KB injection.

#!/usr/bin/env bash
set -euo pipefail
KEYWORDS="It traced the flow through the request handler and refactored the class hierarchy."

# A: 9 KB of repetitive prose, so almost no distinct identifier tokens.
A="<task-notification>$(for i in $(seq 1 110); do printf '%s ' "$KEYWORDS"; done)"
A="${A:0:9000}</task-notification>"

# B: 9 KB of THIS repo's own symbol names, so many distinct identifier tokens.
codegraph explore "request handling" > /tmp/cg-diverse.txt 2>/dev/null || true
B="<task-notification>$(head -c 8900 /tmp/cg-diverse.txt | tr '\n' ' ')</task-notification>"

for pair in "A:$A" "B:$B"; do
  label="${pair%%:*}"; prompt="${pair#*:}"
  json=$(python3 -c 'import json,sys;print(json.dumps({"session_id":"r","transcript_path":"/tmp/x","cwd":sys.argv[1],"permission_mode":"default","hook_event_name":"UserPromptSubmit","prompt":sys.argv[2]}))' "$PWD" "$prompt")
  start=$(python3 -c 'import time;print(time.time())')
  bytes=$(printf '%s' "$json" | codegraph prompt-hook | wc -c | tr -d ' ')
  end=$(python3 -c 'import time;print(time.time())')
  printf '%s: chars=%d  elapsed=%.2fs  injected=%s\n' "$label" "${#prompt}" \
    "$(python3 -c "print($end-$start)")" "$bytes"
done

A: chars=9020  elapsed=0.51s  injected=16301
B: chars=8899  elapsed=4.46s  injected=16303

Same length, same injected payload, 8.7x the wall time. Isolating the variable directly (identical
9,000-char prompts, distinct-token count computed with extractCodeTokens' own rules):

Standalone codegraph explore on the same index shows the same curve, around 0.45s per additional
KB of token-dense text, almost entirely user CPU (user 2.25 of real 2.27) rather than I/O.
Daemon auto-sync during these runs was 3-188 ms, so index contention is not a factor, and process
startup is ~50 ms.

Token density: notifications against typed prompts

Same repo, same 8 days, distinct identifier-shaped tokens per message:

The gate and its cost model were built for the second distribution. Notification blocks also cluster
right under the query cap, with a median of 6,011 chars and a p90 of 9,165, which is the most
expensive band that still gets explored.

What I'm not claiming

• Not that explore is slow in general. A normal query against this index returns in ~0.6s, fine for
  a blocking hook.
• Not that the token-count relationship is precisely linear. Five points on one index. The shape is
  clear; the constant is not.
• Not that my numbers generalize. One index, one machine, my own agent-heavy workflow. Sessions
  without background agents never see this, and my 14 typed prompts stayed near 727 ms. Anyone using
  the Agent tool on an indexed repo should see it. Anyone who doesn't, won't.
• I have not checked whether other hosts (Codex, ZCode per First-class install target + prompt-hook for ZCode (Z.ai) #1535) push comparable machine text
  through the same entry point.

Possible directions, none of which I'm confident in

1. Skip host-generated wrapper messages. A prompt opening with a known host wrapper
   (<task-notification>, <system-reminder>, <command-name>) is not a user prompt, and the
   hook's premise of front-loading context for what the user just asked doesn't apply. Cheapest and
   most targeted, but it hardcodes another host's private message format, which will drift. It also
   changes behavior with no warning for anyone currently getting useful injections from a
   slash-command wrapper.
2. Cap the query the hook sends, independent of ToolHandler's 10,000-char guard. Passing the
   first N distinct candidate tokens instead of the raw prompt is host-agnostic and bounds the
   blocking path for long human prompts too. Needs a recall measurement I haven't done, since
   truncation could drop the one token that mattered.
3. Budget the hook in time rather than size. Race the explore against a ~1s deadline and emit
   nothing if it doesn't finish, consistent with the "must NEVER break the user's prompt" contract
   in the docstring. Wastes the work anyway and makes injection nondeterministic across machines.

(1) and (2) are complementary. My instinct is (2) as the durable fix with (1) as a fast mitigation,
though I'd want the gate telemetry from #1143 to say how often HIGH fires on wrapper-shaped input
first.

Workaround

CODEGRAPH_NO_PROMPT_HOOK=1, the kill-switch already at the top of the prompt-hook action,
disables the injection while leaving the MCP tool and CLI working. In Claude Code it goes in the
env block of ~/.claude/settings.json.

Environment

• codegraph v1.6.0, darwin-arm64 (macOS 25.6)
• Claude Code 2.1.267, native install
• Index: ~57 MB codegraph.db, large Python repo, daemon healthy

Analysis and report authored with Claude Code.