my-pi/pi-tool-search/docs/same-turn-race-bug.md

# Same-turn tool activation race — findings

> Historical upstream document from snapshot `v0.3.6`. The locally maintained implementation no longer uses the old hidden steer/retry mitigation described below. Current behavior is documented in [`dynamic-tool-loading.md`](./dynamic-tool-loading.md).

## Bug

When the LLM emits parallel tool calls in a single assistant message — for
example `tool_search(["subagent"])` together with `subagent(...)` — the second
call fails with `Tool subagent not found`.

Live repro (observed in this project, 2026-04-23):

1. Turn A: `tool_search(["subagent"])` → `Enabled: subagent`; `subagent(...)`
   in the same reply → ❌ `Tool not found`.
2. Turn B (agent continuation, no user input): `subagent(...)` → ❌ still not
   found.
3. Turn C (after fresh user message): `subagent(...)` → ✅ works.

## Root cause

Two compounding issues in pi-coding-agent core.

### 1. Tool schema is frozen per provider request

`setActiveTools(["tool_search", ...unlocked])` updates `agent.state.tools`, but
the outgoing LLM request payload (`tools: [...]`) is built **before**
`tool_search` executes. The model that produced the parallel call never saw
`subagent` in its tool schema — it guessed based on `tool_search`'s
description.

### 2. `before_agent_start` only fires on user-initiated turns

The extension's hook that re-applies `setActiveTools` runs once per fresh user
turn. Agentic-loop continuations (model → tool → model → tool…) do **not**
re-trigger it. So even after `tool_search` mutates state in Turn A, the next
LLM call in the same loop still uses the stale schema from Turn A's start.

## What we checked

- `pi-coding-agent/dist/core/agent-session.js:550` —
  `setActiveToolsByName` assigns `this.agent.state.tools = tools`. Pure state
  mutation, no schema re-send.
- `pi-coding-agent/dist/core/agent-session.js:172` — `beforeToolCall` hook
  fires only for resolved tools; unknown names never reach it.
- `pi-coding-agent/dist/core/sdk.js:195` — `onPayload(payload, model)`
  receives the **already-built, provider-specific** request. Tools are baked
  in.
- `ExtensionAPI.getAllTools(): ToolInfo[]` — `ToolInfo = Pick<ToolDefinition,
  "name"|"description"|"parameters"> & { sourceInfo }`. **No `execute`.**
- `ExtensionAPI.on("tool_call", ...)` result type is `{ block?, reason? }` —
  cannot replace the tool result.

## Extension-only fixes considered

| Option | Fixes parallel calls | Fixes mid-loop | Fragile | Viable |
|---|---|---|---|---|
| Prompt mitigation (tell model to call `tool_search` alone) | ❌ | ❌ | — | ✅ shipped |
| `before_provider_request` payload rewrite | ❌ (too late) | ✅ | ✅ yes | ⚠️ |
| Proxy `invoke(tool, args)` tool | ✅ | ✅ | — | ❌ dead |

### Why the proxy `invoke` pattern is dead

`pi.getAllTools()` returns metadata only. The callable `execute()` lives on
`ToolDefinition` / `RegisteredTool`, but no public API returns those. An
extension cannot dispatch another extension's tool programmatically.

### Why `before_provider_request` rewrite is fragile

The hook receives the raw provider payload. To inject unlocked tool schemas
mid-loop you would need per-provider surgery:

- OpenAI: `payload.tools = [{ type: "function", function: { name, description, parameters } }]`
- Anthropic: `payload.tools = [{ name, description, input_schema }]`
- Gemini: `payload.tools = [{ functionDeclarations: [...] }]`
- plus Azure / Copilot / Codex adapters, plus TypeBox → JSON-Schema
  conversion with provider-specific quirks (Gemini's restricted subset, etc.).

Breaks every time a provider is added or its payload shape changes. Duplicates
logic pi-coding-agent already has internally.

It also does **not** fix the parallel-call case — by the time
`before_provider_request` fires, the model has already emitted both calls.

## Current mitigation (shipped)

`extensions/index.ts` updates:

- `tool_search` description explicitly says: "STOP after calling
  tool_search. Do NOT call newly-enabled tools in same response. Tool
  schema is frozen for current response."
- `promptSnippet` reinforces rule.
- Active tools now refresh on every `turn_start`, not only fresh user prompts,
  so unlocked tools stay available during agent-loop continuations.
- Successful `tool_search` queues hidden steer hint telling model to continue
  original task in next turn and retry any same-response failure immediately.

This does not make same-response parallel call succeed, but it removes need for
fresh user message in common recovery path.

## Real fix (upstream)

The structural fix belongs in `pi-coding-agent`:

1. **Re-resolve active tools per batch iteration.** Don't snapshot at batch
   start; look up each tool name when it's about to be dispatched.
2. **Sequential dispatch when a mutating tool is in the batch.** Or always
   sequential — parallel `Promise.all` dispatch races `setActiveTools`.
3. **Re-send schema after mid-loop `setActiveTools`.** Or mark the active-tool
   set as dirty and rebuild payload on next provider request.
4. **Graceful unknown-tool result.** When a dispatched tool name is not in the
   active set, return a structured tool_result (`"tool X not active this
   turn — retry next turn"`) instead of falling through to MCP or throwing.

With (1)+(2) alone, the parallel-call case works. With (3), mid-loop
continuations also work. (4) makes the failure mode recoverable by the model
when it does speculate.

## Recommended action

- Keep prompt mitigation + per-turn refresh + hidden retry hint in
  `extensions/index.ts`.
- Document remaining limitation in README (same-response parallel call with
  `tool_search` can still fail until core is fixed).
- File upstream issue against `pi-coding-agent` referencing this doc.

## File map

| Path | Role |
|---|---|
| `extensions/index.ts` | This extension; prompt mitigation lives here |
| `pi-coding-agent/dist/core/agent-session.js:550` | `setActiveToolsByName` — state-only mutation |
| `pi-coding-agent/dist/core/agent-session.js:172` | `beforeToolCall` hook — only fires for resolved tools |
| `pi-coding-agent/dist/core/sdk.js:195` | `onPayload` — already-built payload; provider-specific |
| `pi-coding-agent/dist/core/extensions/types.d.ts` | `ToolInfo` (metadata only), `ToolCallEventResult` (`{block, reason}`) |