What

Make the Pi adapter's before_agent_start handler await _mcpBridgeReady before returning so the LLM call dispatched right after the handler sees the ctx_* tools in Pi's registry.

Why — race reported in #472 (comment 4412197109)

Pi subagents may miss ctx_* tools due to an async registration race.

Each subagent starts a fresh pi --mode json -p --no-session process. context-mode's Pi adapter registers ctx_* tools through the MCP bridge, but that bootstrap runs fire-and-forget via _mcpBridgeReady. The child process can start the prompt before registration finishes, so the initial tool registry may not include ctx_execute, ctx_batch_execute, etc.

This does not look like a frontmatter allowlist issue; the agents already include the ctx tool names. context-mode likely needs to await bridge setup, or block first agent start until _mcpBridgeReady settles.

The reporter's diagnosis is correct. In src/adapters/pi/extension.ts the bridge bootstrap was kicked off fire-and-forget at the bottom of piExtension(pi):

_mcpBridgeReady = bootstrapMCPTools(pi, serverBundle).then(...)

For long-lived Pi sessions the race usually closes before the user types a prompt, so the bug stayed invisible. For subagents (pi --mode json -p --no-session) the gap between extension load and the first before_agent_start is too small for the spawn → initialize → tools/list → pi.registerTool round-trip, so the first (and often only) prompt of a subagent goes out with an empty ctx_* registry and the routing block (~2.5K tokens) becomes dead weight — the LLM is told to call ctx_execute / ctx_search / etc. but Pi has not yet registered them.

Fix

Add a single await _mcpBridgeReady at the top of the before_agent_start handler. The promise resolves on bootstrap success and on failure (matching the existing best-effort contract — failures are logged to stderr but never propagated), so a missing or broken bundle still cannot break agent start.

Coverage added

tests/pi-extension.test.ts → Pi MCP bridge (#426) > pi-extension.ts wiring (#426 regression guard):

• before_agent_start awaits MCP bridge bootstrap so ctx_* are registered before LLM call
  • Calls registerPiExtension, opens a session, then immediately triggers before_agent_start (the same race a fresh subagent process exhibits).
  • Pre-asserts pi.registerTool has been called 0 times (race window confirmed open — guards against the test passing for the wrong reason if the bridge ever stops racing).
  • Post-asserts the canonical ctx_* set (ctx_execute, ctx_search, ctx_index, ctx_batch_execute, ctx_fetch_and_index) has been registered through pi.registerTool by the time the handler resolves.

Verified the test fails on next without the fix (race confirmed) and passes with the fix.

Test plan

• npm run typecheck — passes
• npx vitest run tests/pi-extension.test.ts — 47 passed (1 new + 46 existing, no flakes)
• npm test — full suite green (2474 passed, 25 pre-existing skips). The two [vitest-pool]: Timeout terminating forks worker notices on kiro-hooks are pre-existing on next and unrelated to this change (16/16 tests in that file pass when run alone).
• Pre-built bundles regenerated by npm run build reverted before commit per CONTRIBUTING.

Files touched

• src/adapters/pi/extension.ts — single await _mcpBridgeReady + comment explaining the subagent race.
• tests/pi-extension.test.ts — race regression test added to the existing pi-extension.ts wiring (#426 regression guard) block (no new test file per CONTRIBUTING).