@tekmidian/pai 0.42.0 → 0.42.2

package/docs/cache-keepalive.md

@@ -0,0 +1,82 @@
+# Worker prompt-cache keepalive
+
+Why `workers.cacheKeepaliveSecs` exists, what the provider cache actually
+does, and the measured numbers behind the default.
+
+## Mechanism
+
+Workers on an anthropic-compat GLM endpoint (`protocol: "anthropic"`) carry no
+`cache_control` blocks, yet the endpoint caches implicitly: the final `result`
+usage of a real worker run showed `cache_read_input_tokens: 1,129,984` with
+`cache_creation_input_tokens: 0` (worker `20260918-120947-11956`, 2026-09-18).
+
+The keepalive arms that implicit cache for future spawns with a trivial
+single-turn worker (`src/workers/keepalive.ts`) driven by the daemon on
+`workers.cacheKeepaliveSecs` (`src/daemon/daemon/scheduler.ts`,
+`startCacheKeepalive`). The beat goes through `runWorker` itself — the
+maximal sharing of prefix construction (env, tool grants, contract prompt) —
+so a beat and a real worker differ in nothing but the user message. Beats run
+in the workers logDir, adopt no session identity, notify nobody, and write one
+`WORKER-KEEPALIVE` ledger line each; on a Postgres backend they also store one
+observation row via `storeObservationWithProject`.
+
+Measurement constraints (measured, not assumed): per-turn `assistant` events
+on this endpoint always carry `usage: {input_tokens: 0, output_tokens: 0}`
+with no cache fields; the only real usage is the final `result` event. A
+single-turn worker therefore reads its first-turn usage straight off its
+result line, and `duration_api_ms` is the TTFT proxy.
+
+## Measured numbers (2026-09-18, probe `scripts/probe-cache-keepalive.ts`)
+
+Every spawn is a fresh claude process and session; prompt identical; class
+`simple` on glm-5.3-flash. "gap" = time between the two spawns of a pair.
+
+| pair | gap | spawn | input_tokens | cache_read | cache_creation | duration_api_ms |
+|------|-----|-------|--------------|-----------|----------------|-----------------|
+| back-to-back | ~16 s | 1 | 17,906 | 0 | 0 | 12,911 |
+| back-to-back | ~16 s | 2 | 15,282 | **2,624** | 0 | **7,316** |
+| gap 120 s | ~2.2 min | 1 | 17,957 | 0 | 0 | 8,401 |
+| gap 120 s | ~2.2 min | 2 | 17,909 | 0 | 0 | 9,812 |
+| gap 240 s | ~4.4 min | 1 | 17,909 | 0 | 0 | 10,827 |
+| gap 240 s | ~4.4 min | 2 | 17,881 | 0 | 0 | 10,037 |
+| gap 360 s | 6 min | 1 | 17,949 | 0 | 0 | 10,132 |
+| gap 360 s | 6 min | 2 | 17,951 | 0 | 0 | 9,714 |
+
+## Armed-cadence proof (60 s beats through the real beat code, then a pair)
+
+| run | after | input_tokens | cache_read | duration_api_ms |
+|-----|-------|--------------|-----------|-----------------|
+| beat 125003 | — | 14,445 | 0 | 5,307 |
+| beat 125111 | ~68 s | 14,010 | 0 | 5,480 |
+| beat 125220 | ~69 s | 14,010 | 0 | 8,577 |
+| probe-1 125232 | ~12 s | 17,989 | 0 | 6,687 |
+| probe-2 125242 | ~10 s | 17,736 | **256** | 10,034 |
+
+Ledger lines: `WORKER-KEEPALIVE id=… provider=glm model=glm-5.3-flash
+input_tokens=… cache_read_input_tokens=… duration_api_ms=…` land as designed.
+
+## Decision
+
+1. **Cross-session implicit caching exists, but only at seconds range.**
+   Spawn 2 of the back-to-back pair is a different process and session than
+   spawn 1 and still got `cache_read > 0` — but the only positive readings
+   across nine pairs came 10–16 s after the previous identical request
+   (2,624 tokens at ~16 s; 256 at ~10 s), and the hit size is unstable. At
+   every gap ≥ 60 s — including a 60 s heartbeat cadence proven live through
+   the shipped beat code — every spawn was cold.
+2. **A keepalive therefore cannot hold this cache at any cadence the
+   constraints allow** ("cadence is minutes, not seconds"): holding it would
+   need a beat every few seconds, billing ~14–18k fresh input tokens per
+   beat around the clock, to serve at best a few hundred to ~2.6k cached
+   tokens to the next spawn. The drafted "default = TTL/2" rule assumed a
+   TTL in minutes; the measured TTL/2 ≈ 5–30 s, which no sane daemon
+   interval meets, and a 60 s default was disproven by the armed proof.
+3. **Therefore `DEFAULT_CACHE_KEEPALIVE_SECS = 0`** (a deliberate deviation
+   from the drafted spec, per its own STOP-on-negative-evidence rule): the
+   instrument ships — knob, beat, daemon wiring, ledger, observations, tests
+   — and stays off unless the operator explicitly arms it
+   (`"cacheKeepaliveSecs": <secs>` in the workers section). The honest
+   reading of the measurement: this endpoint's implicit cache is a
+   short-range replay buffer, not a warmable baseline; new-worker cold starts
+   cannot be removed by a heartbeat, and the fix would have to live in the
+   provider (explicit `cache_control` support) rather than in the daemon.

package/docs/commands/worker.md

@@ -68,6 +68,7 @@ Grant MCP tools by naming mcp__server__tool in --allowedTools (the server loads
 | `--agent <name>` | Run the agent definition ~/.claude/agents/<name>.md on a worker |  |
 | `--model <model>` | Override the provider's model for this run |  |
 | `--label <text>` | Short task label shown in ps / follow / status line |  |
+| `--cwd <dir>` | Directory the worker runs in (default: this process's cwd) |  |
 | `--mcp <names>` | MCP servers/sets this worker may use (comma-separated; see `pai worker mcp`) |  |
 | `--no-pane` | Do not open a follow pane for this worker |  |
 | `--worktree` | Run in a git worktree on branch worker/<id> (default for implement/complex/plan in a git repo) |  |

package/docs/merge-demo.md

@@ -0,0 +1 @@
+Worker merge demo, created by a worktree agent.

package/docs/provider-abstraction.md

@@ -7,6 +7,7 @@ The entire assistant stack — interactive sessions, workers, follow panes, hook
 What that buys:
 
 - **No single-vendor lock-in.** Providers are entries in a registry (`src/workers/config.ts`): protocol (`anthropic`/`openai`), engine (`claude`/`codex`), model ids, key files, cost tiers, capability tags, quota probes. Switching is `pai worker providers use <name>`; disabling routing entirely is `pai worker off`.
+- **Plain Anthropic stays a first-class choice.** The reserved provider name `anthropic` needs no registry entry — it is Claude Code's own OAuth/Max-plan login, with no base URL override and no API key. `pai worker providers use anthropic` makes it the default; `--provider anthropic` or a class pointed at `anthropic` uses it for one run. `pai worker providers` lists it as `anthropic  [built-in]`.
 - **Plan/quota-aware instrumentation.** The statusline reads the *active provider's* real plan utilization (5-hour rolling window and weekly quota with reset times), not a hardcoded vendor endpoint.
 - **Cost routing per task class.** Work is dispatched by class (`draft`, `spotcheck`, `complex`, …); each class maps to a provider and model, so cheap work lands on cheap models without touching code.
 - **Provider swaps are configuration, not surgery.** Every seam that used to assume one vendor — daemon LLM spawns, compaction-history family detection, context-window defaults, tier aliases — has been patched at protocol level (see below), so a new provider is a registry entry plus a key file.
@@ -40,11 +41,60 @@ The `fast` slot is what cheap classes resolve to; the runner also honors the pla
 
 `statusline-command.sh` derives everything it can from the session's model id instead of assuming one vendor:
 
-- **Plan utilization** — glm sessions fetch the provider's plan quota (5-hour window and weekly credit window, `nextResetTime` rendered as reset times); claude models keep the existing Anthropic OAuth path. Each source has its own 60-second cache. On fetch failure the provider windows show `?` rather than silently falling back to another plan's numbers. `PAI_ZAI_QUOTA_URL` overrides the endpoint (kill switch / testing).
+- **Session provider from the registry** — the session's model id (any `[…]` variant suffix stripped) is matched against every `workers.providers.<name>.models` value in the PAI config, so a session belongs to the provider that lists its model, not to a name prefix. No config, no `jq`, unreadable JSON or no match ⇒ the built-in `anthropic` path, silently.
+- **Plan utilization** — a provider with a `usage` block has its quota fetched and rendered from that block (see below); the built-in `anthropic` provider keeps the OAuth path (5-hour, 1d pace, 7-day). Each provider caches to `/tmp/claude/statusline-usage-<provider>.json` for `ttlSeconds` (default 60) and refreshes in the background, so the line never waits on the network. On fetch failure the windows show `?`, and a provider with no `usage` block shows `<provider> usage n/a` — never another plan's numbers.
 - **Context window from the model id** — a `[1m]` variant suffix means a 1,000,000-token window (`statusline-command.sh:126`); ids with no marker keep the previous default. The same derivation lives in TypeScript as `contextWindowFromModelId()` (`src/utils/model-window.ts`), so the session hooks and the worker meter agree with the statusline.
 - **`(N% left)`** — remaining context until auto-compact, computed against that derived window.
 - **Worker row** — line 4 lists the workers this session launched, running ones with their current step (`pai worker status-line`, `statusline-command.sh:634`).
 
+#### Provider usage blocks
+
+A provider's quota endpoint is configuration. `workers.providers.<name>.usage` (schema: `ProviderUsage` / `UsageWindow`, `src/workers/config.ts`) names a JSON `GET` endpoint plus one jq expression per window, and the statusline renders `<label> <window>: <pct>% → <reset>` for each:
+
+| field | meaning |
+| --- | --- |
+| `url` | endpoint returning the usage JSON |
+| `authHeader` | header template, default `Authorization: Bearer`; the key from the provider's `keyFile` is appended after a space. A value with no space (e.g. `x-api-key`) is sent as `<value>: <key>` |
+| `label` | display label for the segments, default the provider name |
+| `ttlSeconds` | cache TTL, default 60 |
+| `windows[].name` | window label, e.g. `5h` |
+| `windows[].percent` | jq expression yielding 0–100 — an arithmetic expression is fine, so a percentage can be computed from a used/limit pair |
+| `windows[].resetAt` | jq expression yielding the reset time |
+| `windows[].resetUnit` | `ms` (default), `s` or `iso` |
+
+Reset times render as `HH:MM` within the next 24 hours and `<weekday> HH:MM` beyond it. The first window's `percent` doubles as the response probe: a reply that yields no number for it is not cached, so a rejected key answering `HTTP 200` with an empty body never masquerades as a valid zero reading.
+
+Two working blocks. A Z.ai-style credit plan, whose two windows live in one array distinguished by `number`, with epoch-millisecond resets:
+
+```json
+"usage": {
+  "url": "https://api.z.ai/api/monitor/usage/quota/limit",
+  "authHeader": "Authorization: Bearer",
+  "label": "zai",
+  "ttlSeconds": 60,
+  "windows": [
+    { "name": "5h", "percent": ".data.limits[]? | select(.number == 5) | .percentage", "resetAt": ".data.limits[]? | select(.number == 5) | .nextResetTime", "resetUnit": "ms" },
+    { "name": "7d", "percent": ".data.limits[]? | select(.number == 1) | .percentage", "resetAt": ".data.limits[]? | select(.number == 1) | .nextResetTime", "resetUnit": "ms" }
+  ]
+}
+```
+
+And a coding plan that reports *fractions* (`0.0262` = 2.62%, hence the `* 100`), ISO-8601 resets, and a request-count window that has no percentage at all — computed here from its used/limit pair:
+
+```json
+"usage": {
+  "url": "https://api.kimi.ai/coding/v1/usages",
+  "authHeader": "Authorization: Bearer",
+  "label": "kimi",
+  "ttlSeconds": 60,
+  "windows": [
+    { "name": "5h", "percent": ".usages.limit_5h.used_ratio * 100", "resetAt": ".usages.limit_5h.reset_time", "resetUnit": "iso" },
+    { "name": "30d", "percent": ".usages.limit_month_total.used_ratio * 100", "resetAt": ".usages.limit_month_total.reset_time", "resetUnit": "iso" },
+    { "name": "req", "percent": "(.limits[0].detail.used | tonumber) / (.limits[0].detail.limit | tonumber) * 100", "resetAt": ".limits[0].detail.resetTime", "resetUnit": "iso" }
+  ]
+}
+```
+
 ### Seam patches
 
 The seams that previously hardcoded one vendor, now patched:
@@ -82,6 +132,6 @@ Two further instruments are deployed configuration in the PAI config dir rather
 
 ## Current limits
 
-The layer is proven against one non-Anthropic provider so far (the `glm` endpoint); other Anthropic-protocol providers are expected to work but have not been exercised end-to-end, and OpenAI-protocol providers additionally depend on the translating proxy. Instrumentation still special-cases per-provider quota endpoints as providers are added. The seam audit that drove these patches lives outside this repository; new seams are patched as they surface, and each patch carries a unit test pinning the provider-neutral behaviour (`src/workers/daemon-llm.test.ts`, `src/workers/model.test.ts`, `src/workers/agents.test.ts`, `src/hooks/ts/lib/context-fill.test.ts`).
+The layer is proven against one non-Anthropic provider so far (the `glm` endpoint); other Anthropic-protocol providers are expected to work but have not been exercised end-to-end, and OpenAI-protocol providers additionally depend on the translating proxy. Quota endpoints are no longer special-cased in code — a provider's windows are its `usage` block — but a provider whose response needs more than a jq expression per window (paging, a second request, an auth flow other than a single header) would still need code. The seam audit that drove these patches lives outside this repository; new seams are patched as they surface, and each patch carries a unit test pinning the provider-neutral behaviour (`src/workers/daemon-llm.test.ts`, `src/workers/model.test.ts`, `src/workers/agents.test.ts`, `src/hooks/ts/lib/context-fill.test.ts`).
 
 For the full worker command reference see [worker.md](worker.md) and [commands/worker.md](commands/worker.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.42.0",
+  "version": "0.42.2",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/plugins/core/hooks/hooks.json

@@ -17,12 +17,24 @@
       "command": "${PAI_DIR}/Hooks/initialize-session.mjs",
       "description": "Create numbered session note and register in PAI registry"
     },
+    {
+      "event": "SessionStart",
+      "matcher": "resume|compact",
+      "command": "${PAI_DIR}/Hooks/mcp-deferred-reminder.mjs",
+      "description": "Heal stale deferred MCP tool handles on resumed sessions: ToolSearch-and-retry instead of trusting a stale disconnect conclusion"
+    },
     {
       "event": "PreToolUse",
       "matcher": "Bash",
       "command": "${PAI_DIR}/Hooks/security-validator.mjs",
       "description": "Validate shell commands against security rules before execution"
     },
+    {
+      "event": "PreToolUse",
+      "matcher": "mcp__",
+      "command": "${PAI_DIR}/Hooks/mcp-deferred-gate.mjs",
+      "description": "Correct deferred MCP tool calls: ToolSearch remedy instead of a false 'MCP server disconnected' report"
+    },
     {
       "event": "Stop",
       "command": "${PAI_DIR}/Hooks/stop-hook.mjs",

package/src/hooks/ts/lib/mcp-deferred-gate.test.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect } from "vitest";
+import {
+  decideMcpGate,
+  isMcpTool,
+  lastToolSearchSurfacingIndex,
+  scanTranscriptEvidence,
+  type GateHookInput,
+} from "./mcp-deferred-gate.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures — the transcript shapes that matter for the gate
+// ---------------------------------------------------------------------------
+
+const TOOL = "mcp__aibroker__aibroker_rename";
+
+function hookInput(toolName = TOOL): GateHookInput {
+  return {
+    session_id: "test-session",
+    transcript_path: "/tmp/nonexistent-transcript.jsonl",
+    cwd: "/tmp/project",
+    tool_name: toolName,
+    tool_input: { from: "a", to: "b" },
+  };
+}
+
+/** A tool_use entry for `name` with the given input. */
+function toolUseLine(id: string, name: string, input: unknown): string {
+  return JSON.stringify({
+    message: { role: "assistant", content: [{ type: "tool_use", id, name, input }] },
+  });
+}
+
+/** A tool_result for `id`; `errorText` marks it failed with that message. */
+function toolResultLine(id: string, errorText?: string): string {
+  const block: Record<string, unknown> = {
+    type: "tool_result",
+    tool_use_id: id,
+    content: [{ type: "text", text: errorText ?? "ok" }],
+  };
+  if (errorText) block.is_error = true;
+  return JSON.stringify({ message: { role: "user", content: [block] } });
+}
+
+/** What the schema gate's rejection looks like in the transcript. */
+const GATE_ERROR =
+  "InputValidationError: tool schema not loaded. The following deferred tools are " +
+  "available via ToolSearch. Their schemas are NOT loaded — calling them directly will " +
+  'fail. Use ToolSearch with query "select:mcp__aibroker__aibroker_rename" to load tool ' +
+  "schemas before calling them.";
+
+/** What a mid-session re-registration's stale-handle rejection looks like (2026-09-18 incident). */
+const STALE_ERROR = "Error: 411 deferred tools are no longer available: aibroker_rename";
+
+// ---------------------------------------------------------------------------
+// isMcpTool
+// ---------------------------------------------------------------------------
+
+describe("isMcpTool", () => {
+  it("accepts mcp__server__tool names", () => {
+    expect(isMcpTool(TOOL)).toBe(true);
+  });
+
+  it("rejects core tools and bare mcp__ prefixes", () => {
+    expect(isMcpTool("Read")).toBe(false);
+    expect(isMcpTool("Bash")).toBe(false);
+    expect(isMcpTool("mcp__")).toBe(false);
+    expect(isMcpTool("mcp__server")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scanTranscriptEvidence
+// ---------------------------------------------------------------------------
+
+describe("scanTranscriptEvidence", () => {
+  it("sees a ToolSearch that surfaced the tool", () => {
+    const transcript = [
+      toolUseLine("t1", "ToolSearch", { query: `select:${TOOL}` }),
+      toolResultLine("t1"),
+    ].join("\n");
+    expect(scanTranscriptEvidence(transcript, TOOL).surfacedByToolSearch).toBe(true);
+  });
+
+  it("sees a prior successful call but not a gate-failed one", () => {
+    const failed = [
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1", GATE_ERROR),
+    ].join("\n");
+    expect(scanTranscriptEvidence(failed, TOOL).succeededBefore).toBe(false);
+
+    const succeeded = [
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1"),
+    ].join("\n");
+    expect(scanTranscriptEvidence(succeeded, TOOL).succeededBefore).toBe(true);
+  });
+
+  it("ignores junk lines and empty input", () => {
+    expect(scanTranscriptEvidence("not json\n\n{broken", TOOL)).toEqual({
+      surfacedByToolSearch: false,
+      succeededBefore: false,
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// decideMcpGate — (a) deferred/failure context gets the correction
+// ---------------------------------------------------------------------------
+
+describe("decideMcpGate: deferred and failed-call contexts", () => {
+  it("corrects a deferred tool with no transcript evidence (first attempt)", () => {
+    const decision = decideMcpGate(hookInput(), "");
+    expect(decision.action).toBe("correct");
+
+    const parsed = JSON.parse(decision.output);
+    expect(parsed.hookSpecificOutput.permissionDecision).toBe("deny");
+    const reason = parsed.hookSpecificOutput.permissionDecisionReason as string;
+
+    // The remedy: ToolSearch with the exact select: form of the full tool name.
+    expect(reason).toContain("ToolSearch");
+    expect(reason).toContain(`select:${TOOL}`);
+    // The misreport this hook exists to prevent, denied in plain words.
+    expect(reason.toLowerCase()).toContain("not disconnected");
+    expect(reason).toContain("do not report an outage");
+  });
+
+  it("corrects the retry after a gate failure (observed incident shape)", () => {
+    const transcript = [
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1", GATE_ERROR),
+    ].join("\n");
+    const decision = decideMcpGate(hookInput(), transcript);
+
+    expect(decision.action).toBe("correct");
+    const reason = JSON.parse(decision.output).hookSpecificOutput.permissionDecisionReason;
+    expect(reason).toContain(`select:${TOOL}`);
+    expect(reason.toLowerCase()).toContain("not disconnected");
+  });
+
+  it("emits a countable observation for every correction", () => {
+    const decision = decideMcpGate(hookInput(), "");
+    expect(decision.observation).not.toBeNull();
+    expect(decision.observation?.type).toBe("decision");
+    expect(decision.observation?.tool_name).toBe(TOOL);
+    expect(decision.observation?.title).toContain("MCP deferred-tool gate");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// decideMcpGate — (a2) stale deferred-tool handles after a re-registration
+// ---------------------------------------------------------------------------
+
+describe("decideMcpGate: stale deferred-tool handles", () => {
+  it("corrects the retry after a re-registration invalidated the handle (2026-09-18 incident)", () => {
+    // The tool was surfaced by ToolSearch earlier — evidence would normally
+    // pass it through — but the handle is dead now, so the gate must deny.
+    const transcript = [
+      toolUseLine("t0", "ToolSearch", { query: `select:${TOOL}` }),
+      toolResultLine("t0"),
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1", STALE_ERROR),
+    ].join("\n");
+    const decision = decideMcpGate(hookInput(), transcript);
+
+    expect(decision.action).toBe("correct");
+    const reason = JSON.parse(decision.output).hookSpecificOutput.permissionDecisionReason;
+    expect(reason).toContain("ToolSearch");
+    expect(reason).toContain(`select:${TOOL}`);
+    expect(reason.toLowerCase()).toContain("not disconnected");
+    expect(reason).toContain("do not report an outage");
+  });
+
+  it("re-arms even when the tool ran successfully before the re-registration", () => {
+    const transcript = [
+      toolUseLine("t0", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t0"),
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1", STALE_ERROR),
+    ].join("\n");
+    expect(decideMcpGate(hookInput(), transcript).action).toBe("correct");
+  });
+
+  it("passes once a ToolSearch after the invalidation reloaded the entry", () => {
+    const transcript = [
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1", STALE_ERROR),
+      toolUseLine("t2", "ToolSearch", { query: `select:${TOOL}` }),
+      toolResultLine("t2"),
+    ].join("\n");
+    const decision = decideMcpGate(hookInput(), transcript);
+    expect(decision.action).toBe("pass");
+    expect(JSON.parse(decision.output).hookSpecificOutput.permissionDecision).toBe("allow");
+  });
+
+  it("corrects when only the tool input carries the stale-handle text", () => {
+    const input = hookInput();
+    input.tool_input = { text: `411 ${"deferred tools are no longer available"}` };
+    expect(decideMcpGate(input, "").action).toBe("correct");
+  });
+});
+
+describe("lastToolSearchSurfacingIndex", () => {
+  it("finds the last surfacing ToolSearch and returns -1 when absent", () => {
+    const transcript = [
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1", STALE_ERROR),
+      toolUseLine("t2", "ToolSearch", { query: `select:${TOOL}` }),
+      toolResultLine("t2"),
+    ].join("\n");
+    // After the stale error, i.e. the remedy postdates the invalidation.
+    expect(lastToolSearchSurfacingIndex(transcript, TOOL)).toBeGreaterThan(
+      transcript.lastIndexOf("deferred tools are no longer available"),
+    );
+    expect(lastToolSearchSurfacingIndex("not json", TOOL)).toBe(-1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// decideMcpGate — (b) normal contexts pass through untouched
+// ---------------------------------------------------------------------------
+
+describe("decideMcpGate: pass-through", () => {
+  it("passes through after ToolSearch surfaced the tool", () => {
+    const transcript = [
+      toolUseLine("t1", "ToolSearch", { query: `select:${TOOL}` }),
+      toolResultLine("t1"),
+    ].join("\n");
+    const decision = decideMcpGate(hookInput(), transcript);
+
+    expect(decision.action).toBe("pass");
+    expect(decision.observation).toBeNull();
+    const parsed = JSON.parse(decision.output);
+    expect(parsed.hookSpecificOutput.permissionDecision).toBe("allow");
+    expect(decision.output).not.toContain("ToolSearch");
+  });
+
+  it("passes through a tool that already ran successfully", () => {
+    const transcript = [
+      toolUseLine("t1", TOOL, { from: "a", to: "b" }),
+      toolResultLine("t1"),
+    ].join("\n");
+    const decision = decideMcpGate(hookInput(), transcript);
+
+    expect(decision.action).toBe("pass");
+    expect(JSON.parse(decision.output).hookSpecificOutput.permissionDecision).toBe("allow");
+  });
+
+  it("passes non-mcp tools through regardless of transcript", () => {
+    const decision = decideMcpGate(hookInput("Read"), "");
+    expect(decision.action).toBe("pass");
+    expect(decision.observation).toBeNull();
+  });
+
+  it("passes on missing tool_name or junk input", () => {
+    expect(decideMcpGate({}, "").action).toBe("pass");
+    expect(decideMcpGate({ tool_name: "" }, "").action).toBe("pass");
+  });
+});