@tekmidian/pai 0.42.6 → 0.44.0

package/dist/hooks/mcp-deferred-reminder.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/hooks/ts/lib/mcp-deferred-gate.ts", "../../../src/hooks/ts/lib/mcp-deferred-reminder.ts", "../../../src/hooks/ts/lib/worker-session.ts", "../../../src/hooks/ts/session-start/mcp-deferred-reminder.ts"],
-  "sourcesContent": ["/**\n * mcp-deferred-gate.ts \u2014 pure pieces of the deferred MCP tool gate.\n *\n * Claude Code defers MCP tool schemas: an mcp__server__tool call fails input\n * validation unless the session surfaced the schema via ToolSearch first.\n * Sessions misread that error as \"MCP server disconnected\" and report an\n * outage that never happened (observed with a rename tool while every server\n * was connected).\n *\n * A second failure shape: when an MCP server re-registers mid-session, the\n * session's deferred tool handles are invalidated and calls fail with the\n * harness text \"N deferred tools are no longer available\" (observed 2026-09-18,\n * N=411, a rename tool). Sessions misread that as a disconnect too. The gate\n * denies that shape with the same ToolSearch remedy; a ToolSearch that\n * surfaces the tool after the last invalidation re-arms the pass-through.\n *\n * The decision is evidence-based: the session transcript either shows the tool\n * was surfaced (a ToolSearch mentioning it) or already ran successfully \u2014 in\n * which case the schema is loaded and the call passes through untouched \u2014 or\n * it shows neither, in which case the call is about to hit the gate (or is a\n * retry that just did) and gets the corrective instruction.\n *\n * Split out of the pre-tool-use entrypoint (which calls main() at import\n * time) so the decision is testable without spawning a hook process, per the\n * transcript-text.ts precedent.\n */\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface GateHookInput {\n  session_id?: string;\n  transcript_path?: string;\n  cwd?: string;\n  tool_name?: string;\n  tool_input?: unknown;\n}\n\nexport interface GateEvidence {\n  /** A ToolSearch call in the transcript mentions this tool by full name. */\n  surfacedByToolSearch: boolean;\n  /** This tool already ran successfully \u2014 its schema must be loaded. */\n  succeededBefore: boolean;\n}\n\nexport interface GateObservation {\n  type: \"decision\";\n  title: string;\n  narrative: string;\n  tool_name: string;\n  tool_input_summary: string;\n  files_read: string[];\n  files_modified: string[];\n  concepts: string[];\n}\n\nexport interface GateDecision {\n  action: \"pass\" | \"correct\";\n  /** The JSON string to write to stdout, same shape as sibling PreToolUse hooks. */\n  output: string;\n  /** Observation payload for the daemon when a correction fired, else null. */\n  observation: GateObservation | null;\n}\n\n// ---------------------------------------------------------------------------\n// Decision\n// ---------------------------------------------------------------------------\n\nexport const PASS_OUTPUT = JSON.stringify({\n  hookSpecificOutput: { hookEventName: \"PreToolUse\", permissionDecision: \"allow\" },\n});\n\n/**\n * Harness text emitted when a mid-session MCP server re-registration\n * invalidates the session's deferred tool handles.\n */\nexport const STALE_HANDLE_MARKER = \"deferred tools are no longer available\";\n\n/** True for MCP tool names (`mcp__<server>__<tool>`), false for everything else. */\nexport function isMcpTool(name: string): boolean {\n  return name.startsWith(\"mcp__\") && name.split(\"__\").length >= 3 && !!name.split(\"__\")[2];\n}\n\n/**\n * Scan transcript text (JSONL, one entry per line, tolerant of junk) for\n * evidence that `toolName` is loadable in this session.\n */\nexport function scanTranscriptEvidence(transcriptText: string, toolName: string): GateEvidence {\n  const toolUseIds = new Set<string>();\n  let surfacedByToolSearch = false;\n  let succeededBefore = false;\n\n  for (const line of transcriptText.split(\"\\n\")) {\n    const trimmed = line.trim();\n    if (!trimmed) continue;\n    let entry: unknown;\n    try {\n      entry = JSON.parse(trimmed);\n    } catch {\n      continue;\n    }\n    const message = (entry as { message?: { content?: unknown } })?.message;\n    const content = message?.content;\n    if (!Array.isArray(content)) continue;\n\n    for (const block of content as Array<Record<string, unknown>>) {\n      if (!block || typeof block !== \"object\") continue;\n      if (block.type === \"tool_use\" && typeof block.name === \"string\") {\n        if (block.name === toolName && typeof block.id === \"string\") {\n          toolUseIds.add(block.id);\n        } else if (block.name === \"ToolSearch\") {\n          // Liberal match: the query may be \"select:<tool>\" or a keyword list.\n          if (JSON.stringify(block.input ?? \"\").includes(toolName)) {\n            surfacedByToolSearch = true;\n          }\n        }\n      } else if (\n        block.type === \"tool_result\" &&\n        typeof block.tool_use_id === \"string\" &&\n        toolUseIds.has(block.tool_use_id) &&\n        !block.is_error\n      ) {\n        succeededBefore = true;\n      }\n    }\n  }\n\n  return { surfacedByToolSearch, succeededBefore };\n}\n\n/**\n * Byte index of the last transcript line where a ToolSearch call surfaced\n * `toolName` (same liberal match as scanTranscriptEvidence), or -1 if never.\n * Used to order the stale-handle remedy against the last invalidation.\n */\nexport function lastToolSearchSurfacingIndex(\n  transcriptText: string,\n  toolName: string,\n): number {\n  let last = -1;\n  let offset = 0;\n  for (const line of transcriptText.split(\"\\n\")) {\n    const start = offset;\n    offset += line.length + 1;\n    const trimmed = line.trim();\n    if (!trimmed) continue;\n    let entry: unknown;\n    try {\n      entry = JSON.parse(trimmed);\n    } catch {\n      continue;\n    }\n    const content = (entry as { message?: { content?: unknown } })?.message?.content;\n    if (!Array.isArray(content)) continue;\n    for (const block of content as Array<Record<string, unknown>>) {\n      if (\n        block?.type === \"tool_use\" &&\n        block.name === \"ToolSearch\" &&\n        JSON.stringify(block.input ?? \"\").includes(toolName)\n      ) {\n        last = start;\n      }\n    }\n  }\n  return last;\n}\n\n/** The ToolSearch remedy shared by both correction shapes. */\nfunction buildRemedy(toolName: string): string {\n  return (\n    `Remedy: call ToolSearch with query \"select:${toolName}\" to load the fresh registry ` +\n    `entry, then call ${toolName} again with the same arguments.`\n  );\n}\n\n/** The corrective instruction fed back to the session on a deny. */\nexport function buildCorrection(toolName: string): string {\n  return (\n    `${toolName} is a deferred MCP tool: its schema is not loaded in this session yet, so this ` +\n    `call would fail input validation. The MCP server is NOT disconnected \u2014 do not report an ` +\n    `outage and do not retry the call unchanged. ${buildRemedy(toolName)}`\n  );\n}\n\n/** Same remedy for the stale-handle shape: a re-registration invalidated a loaded schema. */\nexport function buildStaleHandleCorrection(toolName: string): string {\n  return (\n    `${toolName}'s deferred tool handle is stale: the MCP server re-registered mid-session, ` +\n    `invalidating the schema this session had loaded (\"${STALE_HANDLE_MARKER}\"). The MCP ` +\n    `server is NOT disconnected \u2014 do not report an outage and do not retry the call ` +\n    `unchanged. ${buildRemedy(toolName)}`\n  );\n}\n\n/** The deny decision shared by both failure shapes. */\nfunction correctDecision(toolName: string, reason: string, narrative: string): GateDecision {\n  return {\n    action: \"correct\",\n    output: JSON.stringify({\n      hookSpecificOutput: {\n        hookEventName: \"PreToolUse\",\n        permissionDecision: \"deny\",\n        permissionDecisionReason: reason,\n      },\n    }),\n    observation: {\n      type: \"decision\",\n      title: `MCP deferred-tool gate corrected: ${toolName}`,\n      narrative,\n      tool_name: toolName,\n      tool_input_summary: toolName,\n      files_read: [],\n      files_modified: [],\n      concepts: [\"mcp\", \"deferred\", \"toolsearch\"],\n    },\n  };\n}\n\n/**\n * The whole gate: given hook input and the session transcript, decide whether\n * this mcp__ call passes through or gets the deferred-schema correction.\n */\nexport function decideMcpGate(input: GateHookInput, transcriptText: string): GateDecision {\n  const toolName = typeof input.tool_name === \"string\" ? input.tool_name : \"\";\n  if (!isMcpTool(toolName)) {\n    return { action: \"pass\", output: PASS_OUTPUT, observation: null };\n  }\n\n  // Stale-handle shape: a mid-session re-registration invalidated loaded\n  // schemas. Overrides the normal evidence pass-through, because a tool that\n  // was surfaced (or even ran) earlier can still have a dead handle now. The\n  // gate re-arms to pass-through only once a ToolSearch re-surfaced the tool\n  // after the last invalidation.\n  const toolInputText = JSON.stringify(input.tool_input ?? \"\");\n  const lastStale = transcriptText.lastIndexOf(STALE_HANDLE_MARKER);\n  if (toolInputText.includes(STALE_HANDLE_MARKER) || lastStale !== -1) {\n    const remedyAt = lastToolSearchSurfacingIndex(transcriptText, toolName);\n    if (remedyAt === -1 || remedyAt <= lastStale) {\n      return correctDecision(\n        toolName,\n        buildStaleHandleCorrection(toolName),\n        `Blocked a retry against a stale deferred-tool handle for ${toolName} and issued ` +\n          \"the ToolSearch remedy (server not disconnected)\",\n      );\n    }\n    return { action: \"pass\", output: PASS_OUTPUT, observation: null };\n  }\n\n  const evidence = scanTranscriptEvidence(transcriptText, toolName);\n  if (evidence.surfacedByToolSearch || evidence.succeededBefore) {\n    return { action: \"pass\", output: PASS_OUTPUT, observation: null };\n  }\n\n  return correctDecision(\n    toolName,\n    buildCorrection(toolName),\n    `Blocked a call to deferred MCP tool ${toolName} and issued the ToolSearch remedy ` +\n      \"(server not disconnected)\",\n  );\n}\n", "/**\n * mcp-deferred-reminder.ts \u2014 pure pieces of the session-start deferred-handle reminder.\n *\n * A resumed session inherits its transcript, and a transcript can contain a\n * mid-session MCP re-registration: the deferred tool handles the session held\n * are stale from then on (\"deferred tools are no longer available\"). The\n * call-time gate (../pre-tool-use/mcp-deferred-gate.ts) can only correct a call\n * that is still ATTEMPTED \u2014 but a resumed session that already concluded once\n * that \"the MCP server is disconnected\" never retries, so the gate never fires\n * (observed 2026-09-18: 37s of thinking, then a skip on \"aibroker is down\n * right now\"). The cure has to arrive before the first tool call, at session\n * start: a fresh claim that stale history is not evidence, so the model\n * attempts the call and lands in the gate if the handle really is stale.\n *\n * Fired for sources \"resume\" and \"compact\" only \u2014 fresh sessions have no\n * stale handles and no stale conclusions to unlearn.\n *\n * Split out of the session-start entrypoint so the decision is testable\n * without spawning a hook process, per the mcp-deferred-gate.ts precedent.\n */\n\n// Reused so reminder and gate corrections read as one instrument.\nimport { STALE_HANDLE_MARKER } from \"./mcp-deferred-gate.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface ReminderHookInput {\n  source?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Decision\n// ---------------------------------------------------------------------------\n\n/**\n * SessionStart sources the reminder applies to. \"startup\" and \"clear\" begin\n * with an empty session state \u2014 nothing to heal there.\n */\nexport const REMINDER_SOURCES = new Set([\"resume\", \"compact\"]);\n\n/** The exact reminder text; exported so tests can match against the real thing. */\nexport function buildReminder(): string {\n  return (\n    `<system-reminder>\\n` +\n    `Resumed sessions keep stale deferred MCP tool handles: a mid-session MCP server ` +\n    `re-registration invalidates every loaded mcp__ schema (\"${STALE_HANDLE_MARKER}\"). ` +\n    `If any mcp__ tool call fails or a tool seems unavailable: run ToolSearch with query ` +\n    `\"select:<full tool name>\" and retry once. A prior \"the MCP server is disconnected\" ` +\n    `conclusion in this history is stale evidence \u2014 do not skip the retry; only a call ` +\n    `failing after a fresh ToolSearch proves an outage.\\n` +\n    `</system-reminder>`\n  );\n}\n\n/**\n * The whole reminder: given hook input, return the stdout payload for sources\n * resume/compact, or null for every other (silent exit 0).\n */\nexport function decideMcpDeferredReminder(input: ReminderHookInput): string | null {\n  if (typeof input.source !== \"string\" || !REMINDER_SOURCES.has(input.source)) {\n    return null;\n  }\n  return buildReminder();\n}\n", "/**\n * Worker-session detection.\n *\n * A disposable headless worker (a `claude -p` run started by an orchestrating\n * session, possibly against a different model provider with a different\n * context window) shares the project directory and the hook configuration\n * with the real session that spawned it. Left alone, the hooks treat it as a\n * session in its own right: they inject project context into it, create and\n * rename a numbered session note for it, autosave it, and enqueue a\n * model-written handover for it. Its compactions also land in the project's\n * transcript folder, where they are indistinguishable from a real session's\n * and drag the measured compaction trigger down (observed 2026-09-17: two\n * workers compacting at ~151k tokens pulled a project's trigger from ~784k\n * to ~151k, and the real session's handover fired at ~50k tokens).\n *\n * The launcher marks such sessions with `PAI_WORKER=1`. Every hook that does\n * per-session bookkeeping returns immediately when this predicate is true.\n * Deliberately NOT guarded: the security validator (a worker's shell\n * commands must still be checked) and observability capture.\n */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n  return env.PAI_WORKER === \"1\";\n}\n", "#!/usr/bin/env node\n\n/**\n * mcp-deferred-reminder.ts \u2014 SessionStart hook (matchers: resume, compact)\n *\n * Resumed sessions can inherit stale deferred MCP tool handles (a mid-session\n * server re-registration) together with a stale \"the MCP server is\n * disconnected\" conclusion from before the restart \u2014 a combination that makes\n * the session skip the retry the call-time gate would need in order to fire.\n * This hook injects the counter-instruction at session start, before any tool\n * call: see ../lib/mcp-deferred-reminder.ts for the rationale and text.\n *\n * stdout is captured by Claude Code and injected into the session context,\n * same channel as session-commands/inject-observations. Never blocks session\n * start: always exits 0.\n */\n\nimport { decideMcpDeferredReminder, type ReminderHookInput } from \"../lib/mcp-deferred-reminder.js\";\nimport { isWorkerSession } from \"../lib/worker-session.js\";\n\nasync function main() {\n  if (isWorkerSession()) return; // disposable worker: no per-session bookkeeping\n  let input: ReminderHookInput = {};\n\n  try {\n    const decoder = new TextDecoder();\n    let raw = '';\n    const timeoutPromise = new Promise<void>((resolve) => { setTimeout(resolve, 500); });\n    const readPromise = (async () => {\n      for await (const chunk of process.stdin) {\n        raw += decoder.decode(chunk, { stream: true });\n      }\n    })();\n    await Promise.race([readPromise, timeoutPromise]);\n    if (raw.trim()) {\n      input = JSON.parse(raw) as ReminderHookInput;\n    }\n  } catch {\n    // Junk input: stay silent, exit 0\n    process.exit(0);\n  }\n\n  const reminder = decideMcpDeferredReminder(input);\n  if (reminder) {\n    console.log(reminder);\n    console.error(`mcp-deferred-reminder: injected reminder for source=${input.source}`);\n  }\n\n  process.exit(0);\n}\n\nmain().catch(() => {\n  process.exit(0);\n});\n"],
+  "sourcesContent": ["/**\n * mcp-deferred-gate.ts \u2014 pure pieces of the deferred MCP tool gate.\n *\n * Claude Code defers MCP tool schemas: an mcp__server__tool call fails input\n * validation unless the session surfaced the schema via ToolSearch first.\n * Sessions misread that error as \"MCP server disconnected\" and report an\n * outage that never happened (observed with a rename tool while every server\n * was connected).\n *\n * A second failure shape: when an MCP server re-registers mid-session, the\n * session's deferred tool handles are invalidated and calls fail with the\n * harness text \"N deferred tools are no longer available\" (observed 2026-09-18,\n * N=411, a rename tool). Sessions misread that as a disconnect too. The gate\n * denies that shape with the same ToolSearch remedy; a ToolSearch that\n * surfaces the tool after the last invalidation re-arms the pass-through.\n *\n * The decision is evidence-based: the session transcript either shows the tool\n * was surfaced (a ToolSearch mentioning it) or already ran successfully \u2014 in\n * which case the schema is loaded and the call passes through untouched \u2014 or\n * it shows neither, in which case the call is about to hit the gate (or is a\n * retry that just did) and gets the corrective instruction.\n *\n * Split out of the pre-tool-use entrypoint (which calls main() at import\n * time) so the decision is testable without spawning a hook process, per the\n * transcript-text.ts precedent.\n */\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface GateHookInput {\n  session_id?: string;\n  transcript_path?: string;\n  cwd?: string;\n  tool_name?: string;\n  tool_input?: unknown;\n}\n\nexport interface GateEvidence {\n  /** A ToolSearch call in the transcript mentions this tool by full name. */\n  surfacedByToolSearch: boolean;\n  /** This tool already ran successfully \u2014 its schema must be loaded. */\n  succeededBefore: boolean;\n}\n\nexport interface GateObservation {\n  type: \"decision\";\n  title: string;\n  narrative: string;\n  tool_name: string;\n  tool_input_summary: string;\n  files_read: string[];\n  files_modified: string[];\n  concepts: string[];\n}\n\nexport interface GateDecision {\n  action: \"pass\" | \"correct\";\n  /** The JSON string to write to stdout, same shape as sibling PreToolUse hooks. */\n  output: string;\n  /** Observation payload for the daemon when a correction fired, else null. */\n  observation: GateObservation | null;\n}\n\n// ---------------------------------------------------------------------------\n// Decision\n// ---------------------------------------------------------------------------\n\nexport const PASS_OUTPUT = JSON.stringify({\n  hookSpecificOutput: { hookEventName: \"PreToolUse\", permissionDecision: \"allow\" },\n});\n\n/**\n * Harness text emitted when a mid-session MCP server re-registration\n * invalidates the session's deferred tool handles.\n */\nexport const STALE_HANDLE_MARKER = \"deferred tools are no longer available\";\n\n/** True for MCP tool names (`mcp__<server>__<tool>`), false for everything else. */\nexport function isMcpTool(name: string): boolean {\n  return name.startsWith(\"mcp__\") && name.split(\"__\").length >= 3 && !!name.split(\"__\")[2];\n}\n\n/**\n * Scan transcript text (JSONL, one entry per line, tolerant of junk) for\n * evidence that `toolName` is loadable in this session.\n */\nexport function scanTranscriptEvidence(transcriptText: string, toolName: string): GateEvidence {\n  const toolUseIds = new Set<string>();\n  let surfacedByToolSearch = false;\n  let succeededBefore = false;\n\n  for (const line of transcriptText.split(\"\\n\")) {\n    const trimmed = line.trim();\n    if (!trimmed) continue;\n    let entry: unknown;\n    try {\n      entry = JSON.parse(trimmed);\n    } catch {\n      continue;\n    }\n    const message = (entry as { message?: { content?: unknown } })?.message;\n    const content = message?.content;\n    if (!Array.isArray(content)) continue;\n\n    for (const block of content as Array<Record<string, unknown>>) {\n      if (!block || typeof block !== \"object\") continue;\n      if (block.type === \"tool_use\" && typeof block.name === \"string\") {\n        if (block.name === toolName && typeof block.id === \"string\") {\n          toolUseIds.add(block.id);\n        } else if (block.name === \"ToolSearch\") {\n          // Liberal match: the query may be \"select:<tool>\" or a keyword list.\n          if (JSON.stringify(block.input ?? \"\").includes(toolName)) {\n            surfacedByToolSearch = true;\n          }\n        }\n      } else if (\n        block.type === \"tool_result\" &&\n        typeof block.tool_use_id === \"string\" &&\n        toolUseIds.has(block.tool_use_id) &&\n        !block.is_error\n      ) {\n        succeededBefore = true;\n      }\n    }\n  }\n\n  return { surfacedByToolSearch, succeededBefore };\n}\n\n/**\n * Byte index of the last transcript line where a ToolSearch call surfaced\n * `toolName` (same liberal match as scanTranscriptEvidence), or -1 if never.\n * Used to order the stale-handle remedy against the last invalidation.\n */\nexport function lastToolSearchSurfacingIndex(\n  transcriptText: string,\n  toolName: string,\n): number {\n  let last = -1;\n  let offset = 0;\n  for (const line of transcriptText.split(\"\\n\")) {\n    const start = offset;\n    offset += line.length + 1;\n    const trimmed = line.trim();\n    if (!trimmed) continue;\n    let entry: unknown;\n    try {\n      entry = JSON.parse(trimmed);\n    } catch {\n      continue;\n    }\n    const content = (entry as { message?: { content?: unknown } })?.message?.content;\n    if (!Array.isArray(content)) continue;\n    for (const block of content as Array<Record<string, unknown>>) {\n      if (\n        block?.type === \"tool_use\" &&\n        block.name === \"ToolSearch\" &&\n        JSON.stringify(block.input ?? \"\").includes(toolName)\n      ) {\n        last = start;\n      }\n    }\n  }\n  return last;\n}\n\n/** The ToolSearch remedy shared by both correction shapes. */\nfunction buildRemedy(toolName: string): string {\n  return (\n    `Remedy: call ToolSearch with query \"select:${toolName}\" to load the fresh registry ` +\n    `entry, then call ${toolName} again with the same arguments.`\n  );\n}\n\n/** The corrective instruction fed back to the session on a deny. */\nexport function buildCorrection(toolName: string): string {\n  return (\n    `${toolName} is a deferred MCP tool: its schema is not loaded in this session yet, so this ` +\n    `call would fail input validation. The MCP server is NOT disconnected \u2014 do not report an ` +\n    `outage and do not retry the call unchanged. ${buildRemedy(toolName)}`\n  );\n}\n\n/** Same remedy for the stale-handle shape: a re-registration invalidated a loaded schema. */\nexport function buildStaleHandleCorrection(toolName: string): string {\n  return (\n    `${toolName}'s deferred tool handle is stale: the MCP server re-registered mid-session, ` +\n    `invalidating the schema this session had loaded (\"${STALE_HANDLE_MARKER}\"). The MCP ` +\n    `server is NOT disconnected \u2014 do not report an outage and do not retry the call ` +\n    `unchanged. ${buildRemedy(toolName)}`\n  );\n}\n\n/** The deny decision shared by both failure shapes. */\nfunction correctDecision(toolName: string, reason: string, narrative: string): GateDecision {\n  return {\n    action: \"correct\",\n    output: JSON.stringify({\n      hookSpecificOutput: {\n        hookEventName: \"PreToolUse\",\n        permissionDecision: \"deny\",\n        permissionDecisionReason: reason,\n      },\n    }),\n    observation: {\n      type: \"decision\",\n      title: `MCP deferred-tool gate corrected: ${toolName}`,\n      narrative,\n      tool_name: toolName,\n      tool_input_summary: toolName,\n      files_read: [],\n      files_modified: [],\n      concepts: [\"mcp\", \"deferred\", \"toolsearch\"],\n    },\n  };\n}\n\n/**\n * The whole gate: given hook input and the session transcript, decide whether\n * this mcp__ call passes through or gets the deferred-schema correction.\n */\nexport function decideMcpGate(input: GateHookInput, transcriptText: string): GateDecision {\n  const toolName = typeof input.tool_name === \"string\" ? input.tool_name : \"\";\n  if (!isMcpTool(toolName)) {\n    return { action: \"pass\", output: PASS_OUTPUT, observation: null };\n  }\n\n  // Stale-handle shape: a mid-session re-registration invalidated loaded\n  // schemas. Overrides the normal evidence pass-through, because a tool that\n  // was surfaced (or even ran) earlier can still have a dead handle now. The\n  // gate re-arms to pass-through only once a ToolSearch re-surfaced the tool\n  // after the last invalidation.\n  const toolInputText = JSON.stringify(input.tool_input ?? \"\");\n  const lastStale = transcriptText.lastIndexOf(STALE_HANDLE_MARKER);\n  if (toolInputText.includes(STALE_HANDLE_MARKER) || lastStale !== -1) {\n    const remedyAt = lastToolSearchSurfacingIndex(transcriptText, toolName);\n    if (remedyAt === -1 || remedyAt <= lastStale) {\n      return correctDecision(\n        toolName,\n        buildStaleHandleCorrection(toolName),\n        `Blocked a retry against a stale deferred-tool handle for ${toolName} and issued ` +\n          \"the ToolSearch remedy (server not disconnected)\",\n      );\n    }\n    return { action: \"pass\", output: PASS_OUTPUT, observation: null };\n  }\n\n  const evidence = scanTranscriptEvidence(transcriptText, toolName);\n  if (evidence.surfacedByToolSearch || evidence.succeededBefore) {\n    return { action: \"pass\", output: PASS_OUTPUT, observation: null };\n  }\n\n  return correctDecision(\n    toolName,\n    buildCorrection(toolName),\n    `Blocked a call to deferred MCP tool ${toolName} and issued the ToolSearch remedy ` +\n      \"(server not disconnected)\",\n  );\n}\n", "/**\n * mcp-deferred-reminder.ts \u2014 pure pieces of the session-start deferred-handle reminder.\n *\n * A resumed session inherits its transcript, and a transcript can contain a\n * mid-session MCP re-registration: the deferred tool handles the session held\n * are stale from then on (\"deferred tools are no longer available\"). The\n * call-time gate (../pre-tool-use/mcp-deferred-gate.ts) can only correct a call\n * that is still ATTEMPTED \u2014 but a resumed session that already concluded once\n * that \"the MCP server is disconnected\" never retries, so the gate never fires\n * (observed 2026-09-18: 37s of thinking, then a skip on \"aibroker is down\n * right now\"). The cure has to arrive before the first tool call, at session\n * start: a fresh claim that stale history is not evidence, so the model\n * attempts the call and lands in the gate if the handle really is stale.\n *\n * Fired for sources \"resume\" and \"compact\" only \u2014 fresh sessions have no\n * stale handles and no stale conclusions to unlearn.\n *\n * Split out of the session-start entrypoint so the decision is testable\n * without spawning a hook process, per the mcp-deferred-gate.ts precedent.\n */\n\n// Reused so reminder and gate corrections read as one instrument.\nimport { STALE_HANDLE_MARKER } from \"./mcp-deferred-gate.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport interface ReminderHookInput {\n  source?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Decision\n// ---------------------------------------------------------------------------\n\n/**\n * SessionStart sources the reminder applies to. \"startup\" and \"clear\" begin\n * with an empty session state \u2014 nothing to heal there.\n */\nexport const REMINDER_SOURCES = new Set([\"resume\", \"compact\"]);\n\n/** The exact reminder text; exported so tests can match against the real thing. */\nexport function buildReminder(): string {\n  return (\n    `<system-reminder>\\n` +\n    `Resumed sessions keep stale deferred MCP tool handles: a mid-session MCP server ` +\n    `re-registration invalidates every loaded mcp__ schema (\"${STALE_HANDLE_MARKER}\"). ` +\n    `If any mcp__ tool call fails or a tool seems unavailable: run ToolSearch with query ` +\n    `\"select:<full tool name>\" and retry once. A prior \"the MCP server is disconnected\" ` +\n    `conclusion in this history is stale evidence \u2014 do not skip the retry; only a call ` +\n    `failing after a fresh ToolSearch proves an outage.\\n` +\n    `</system-reminder>`\n  );\n}\n\n/**\n * The whole reminder: given hook input, return the stdout payload for sources\n * resume/compact, or null for every other (silent exit 0).\n */\nexport function decideMcpDeferredReminder(input: ReminderHookInput): string | null {\n  if (typeof input.source !== \"string\" || !REMINDER_SOURCES.has(input.source)) {\n    return null;\n  }\n  return buildReminder();\n}\n", "/**\n * Worker-session detection.\n *\n * A disposable headless worker (a `claude -p` run started by an orchestrating\n * session, possibly against a different model provider with a different\n * context window) shares the project directory and the hook configuration\n * with the real session that spawned it. Left alone, the hooks treat it as a\n * session in its own right: they inject project context into it, create and\n * rename a numbered session note for it, autosave it, and enqueue a\n * model-written handover for it. Its compactions also land in the project's\n * transcript folder, where they are indistinguishable from a real session's\n * and drag the measured compaction trigger down (observed 2026-09-17: two\n * workers compacting at ~151k tokens pulled a project's trigger from ~784k\n * to ~151k, and the real session's handover fired at ~50k tokens).\n *\n * The launcher marks such sessions with `PAI_WORKER=1`. Every hook that does\n * per-session bookkeeping returns immediately when this predicate is true.\n * Deliberately NOT guarded: the security validator (a worker's shell\n * commands must still be checked) and observability capture.\n */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n  return env.PAI_WORKER === \"1\";\n}\n", "#!/usr/bin/env node\n\n/**\n * mcp-deferred-reminder.ts \u2014 SessionStart hook (matchers: resume, compact)\n *\n * Resumed sessions can inherit stale deferred MCP tool handles (a mid-session\n * server re-registration) together with a stale \"the MCP server is\n * disconnected\" conclusion from before the restart \u2014 a combination that makes\n * the session skip the retry the call-time gate would need in order to fire.\n * This hook injects the counter-instruction at session start, before any tool\n * call: see ../lib/mcp-deferred-reminder.ts for the rationale and text.\n *\n * stdout is captured by Claude Code and injected into the session context,\n * same channel as inject-observations. Never blocks session start: always\n * exits 0.\n */\n\nimport { decideMcpDeferredReminder, type ReminderHookInput } from \"../lib/mcp-deferred-reminder.js\";\nimport { isWorkerSession } from \"../lib/worker-session.js\";\n\nasync function main() {\n  if (isWorkerSession()) return; // disposable worker: no per-session bookkeeping\n  let input: ReminderHookInput = {};\n\n  try {\n    const decoder = new TextDecoder();\n    let raw = '';\n    const timeoutPromise = new Promise<void>((resolve) => { setTimeout(resolve, 500); });\n    const readPromise = (async () => {\n      for await (const chunk of process.stdin) {\n        raw += decoder.decode(chunk, { stream: true });\n      }\n    })();\n    await Promise.race([readPromise, timeoutPromise]);\n    if (raw.trim()) {\n      input = JSON.parse(raw) as ReminderHookInput;\n    }\n  } catch {\n    // Junk input: stay silent, exit 0\n    process.exit(0);\n  }\n\n  const reminder = decideMcpDeferredReminder(input);\n  if (reminder) {\n    console.log(reminder);\n    console.error(`mcp-deferred-reminder: injected reminder for source=${input.source}`);\n  }\n\n  process.exit(0);\n}\n\nmain().catch(() => {\n  process.exit(0);\n});\n"],
   "mappings": ";;;;;;AAqEO,IAAM,cAAc,KAAK,UAAU;AAAA,EACxC,oBAAoB,EAAE,eAAe,cAAc,oBAAoB,QAAQ;AACjF,CAAC;AAMM,IAAM,sBAAsB;;;ACrC5B,IAAM,mBAAmB,oBAAI,IAAI,CAAC,UAAU,SAAS,CAAC;AAGtD,SAAS,gBAAwB;AACtC,SACE;AAAA,0IAE2D,mBAAmB;AAAA;AAOlF;AAMO,SAAS,0BAA0B,OAAyC;AACjF,MAAI,OAAO,MAAM,WAAW,YAAY,CAAC,iBAAiB,IAAI,MAAM,MAAM,GAAG;AAC3E,WAAO;AAAA,EACT;AACA,SAAO,cAAc;AACvB;;;AC7CO,SAAS,gBAAgB,MAAyB,QAAQ,KAAc;AAC7E,SAAO,IAAI,eAAe;AAC5B;;;ACFA,eAAe,OAAO;AACpB,MAAI,gBAAgB,EAAG;AACvB,MAAI,QAA2B,CAAC;AAEhC,MAAI;AACF,UAAM,UAAU,IAAI,YAAY;AAChC,QAAI,MAAM;AACV,UAAM,iBAAiB,IAAI,QAAc,CAAC,YAAY;AAAE,iBAAW,SAAS,GAAG;AAAA,IAAG,CAAC;AACnF,UAAM,eAAe,YAAY;AAC/B,uBAAiB,SAAS,QAAQ,OAAO;AACvC,eAAO,QAAQ,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC;AAAA,MAC/C;AAAA,IACF,GAAG;AACH,UAAM,QAAQ,KAAK,CAAC,aAAa,cAAc,CAAC;AAChD,QAAI,IAAI,KAAK,GAAG;AACd,cAAQ,KAAK,MAAM,GAAG;AAAA,IACxB;AAAA,EACF,QAAQ;AAEN,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,QAAM,WAAW,0BAA0B,KAAK;AAChD,MAAI,UAAU;AACZ,YAAQ,IAAI,QAAQ;AACpB,YAAQ,MAAM,uDAAuD,MAAM,MAAM,EAAE;AAAA,EACrF;AAEA,UAAQ,KAAK,CAAC;AAChB;AAEA,KAAK,EAAE,MAAM,MAAM;AACjB,UAAQ,KAAK,CAAC;AAChB,CAAC;",
   "names": []
 }

package/dist/hooks/whisper-reinject.mjs

@@ -7,6 +7,13 @@ if (!process.env.PAI_QUIET_NOTICES) process.env.PAI_QUIET_NOTICES = '1';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
+
+// src/hooks/ts/lib/worker-session.ts
+function isWorkerSession(env = process.env) {
+  return env.PAI_WORKER === "1";
+}
+
+// src/hooks/ts/post-tool-use/whisper-reinject.ts
 var QUIET_BELOW = 6;
 var EVERY = 8;
 function counterFile(sessionId) {
@@ -43,6 +50,7 @@ function main() {
     if (raw.trim()) sessionId = JSON.parse(raw).session_id ?? "";
   } catch {
   }
+  if (isWorkerSession()) return;
   const n = bump(counterFile(sessionId));
   if (n < QUIET_BELOW || n % EVERY !== 0) return;
   const lines = [

package/dist/hooks/whisper-reinject.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../../src/hooks/ts/post-tool-use/whisper-reinject.ts"],
-  "sourcesContent": ["#!/usr/bin/env node\n\n/**\n * whisper-reinject \u2014 put the output-shape rules back in view mid-turn.\n *\n * The whisper rules are injected once per user message, by the UserPromptSubmit\n * hook. That is the wrong place for the rules that govern how a turn is\n * *written*, because a long turn does not write its answer next to that\n * injection: it runs twenty tool calls first. Attention follows the tool\n * output, the injected block scrolls out of working memory, and by the time the\n * answer is composed the rules are gone. Nothing in the loop re-checks them, so\n * compliance decays with turn length \u2014 exactly the turns where it matters most.\n *\n * This fires after a tool call instead, so the reminder lands where the decay\n * happens. It stays quiet for short sequences (nothing has decayed yet) and\n * emits a compressed set \u2014 not all of them \u2014 every few calls after that. The\n * full rule set is deliberately not repeated: a wall of text re-read every few\n * calls is skimmed, and it costs context that the actual work needs.\n *\n * Only rules about the shape of the reply belong here. Rules about actions\n * (what may be sent, published, or committed) are enforced at the point of\n * action, not by reminding.\n */\nimport { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { tmpdir } from \"node:os\";\n\n/** Stay silent below this many tool calls \u2014 a short turn has not drifted yet. */\nconst QUIET_BELOW = 6;\n\n/** Re-emit every N calls once past QUIET_BELOW. */\nconst EVERY = 8;\n\nfunction counterFile(sessionId: string): string {\n  const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, \"\") || \"nosession\";\n  return join(tmpdir(), \"pai-whisper-reinject\", `${safe}.count`);\n}\n\nfunction bump(path: string): number {\n  try {\n    mkdirSync(dirname(path), { recursive: true });\n    const n = existsSync(path) ? Number.parseInt(readFileSync(path, \"utf-8\").trim(), 10) || 0 : 0;\n    const next = n + 1;\n    writeFileSync(path, String(next));\n    return next;\n  } catch {\n    return 0;\n  }\n}\n\nfunction localTime(): string {\n  const d = new Date();\n  const p = (n: number) => String(n).padStart(2, \"0\");\n  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;\n}\n\nfunction readStdin(): string {\n  try {\n    return readFileSync(0, \"utf-8\");\n  } catch {\n    return \"\";\n  }\n}\n\nfunction main(): void {\n  let sessionId = \"\";\n  try {\n    const raw = readStdin();\n    if (raw.trim()) sessionId = (JSON.parse(raw) as { session_id?: string }).session_id ?? \"\";\n  } catch { /* no session id \u2014 fall back to a shared counter */ }\n\n  const n = bump(counterFile(sessionId));\n  if (n < QUIET_BELOW || n % EVERY !== 0) return;\n\n  const lines = [\n    `CURRENT LOCAL TIME: ${localTime()} \u2014 use verbatim for any [YYYY-MM-DD HH:MM] stamp. Never estimate it, never increment a previous one.`,\n    `You are ${n} tool calls into this turn. Before the next one, check:`,\n    \"- One command at a time: say what you are about to run, run it, say what came back. Do not batch several steps into one call.\",\n    \"- Report what CHANGED, not what you learned. A finding is not a deliverable.\",\n    \"- Prove it: show the reading that says it failed before and works now.\",\n    \"- Found a fault while working? Fix it. Filing it is not fixing it.\",\n    \"- Corrections stay to one line. No re-litigating your own mistakes.\",\n  ];\n\n  console.log(`<system-reminder>\\n${lines.join(\"\\n\")}\\n</system-reminder>`);\n}\n\nmain();\n"],
-  "mappings": ";;;;;;AAuBA,SAAyB,YAAY,WAAW,cAAc,qBAAqB;AACnF,SAAS,SAAS,YAAY;AAC9B,SAAS,cAAc;AAGvB,IAAM,cAAc;AAGpB,IAAM,QAAQ;AAEd,SAAS,YAAY,WAA2B;AAC9C,QAAM,OAAO,UAAU,QAAQ,mBAAmB,EAAE,KAAK;AACzD,SAAO,KAAK,OAAO,GAAG,wBAAwB,GAAG,IAAI,QAAQ;AAC/D;AAEA,SAAS,KAAK,MAAsB;AAClC,MAAI;AACF,cAAU,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;AAC5C,UAAM,IAAI,WAAW,IAAI,IAAI,OAAO,SAAS,aAAa,MAAM,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,IAAI;AAC5F,UAAM,OAAO,IAAI;AACjB,kBAAc,MAAM,OAAO,IAAI,CAAC;AAChC,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,YAAoB;AAC3B,QAAM,IAAI,oBAAI,KAAK;AACnB,QAAM,IAAI,CAAC,MAAc,OAAO,CAAC,EAAE,SAAS,GAAG,GAAG;AAClD,SAAO,GAAG,EAAE,YAAY,CAAC,IAAI,EAAE,EAAE,SAAS,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC,CAAC;AAC5G;AAEA,SAAS,YAAoB;AAC3B,MAAI;AACF,WAAO,aAAa,GAAG,OAAO;AAAA,EAChC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,OAAa;AACpB,MAAI,YAAY;AAChB,MAAI;AACF,UAAM,MAAM,UAAU;AACtB,QAAI,IAAI,KAAK,EAAG,aAAa,KAAK,MAAM,GAAG,EAA8B,cAAc;AAAA,EACzF,QAAQ;AAAA,EAAsD;AAE9D,QAAM,IAAI,KAAK,YAAY,SAAS,CAAC;AACrC,MAAI,IAAI,eAAe,IAAI,UAAU,EAAG;AAExC,QAAM,QAAQ;AAAA,IACZ,uBAAuB,UAAU,CAAC;AAAA,IAClC,WAAW,CAAC;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,UAAQ,IAAI;AAAA,EAAsB,MAAM,KAAK,IAAI,CAAC;AAAA,mBAAsB;AAC1E;AAEA,KAAK;",
+  "sources": ["../../../src/hooks/ts/post-tool-use/whisper-reinject.ts", "../../../src/hooks/ts/lib/worker-session.ts"],
+  "sourcesContent": ["#!/usr/bin/env node\n\n/**\n * whisper-reinject \u2014 put the output-shape rules back in view mid-turn.\n *\n * The whisper rules are injected once per user message, by the UserPromptSubmit\n * hook. That is the wrong place for the rules that govern how a turn is\n * *written*, because a long turn does not write its answer next to that\n * injection: it runs twenty tool calls first. Attention follows the tool\n * output, the injected block scrolls out of working memory, and by the time the\n * answer is composed the rules are gone. Nothing in the loop re-checks them, so\n * compliance decays with turn length \u2014 exactly the turns where it matters most.\n *\n * This fires after a tool call instead, so the reminder lands where the decay\n * happens. It stays quiet for short sequences (nothing has decayed yet) and\n * emits a compressed set \u2014 not all of them \u2014 every few calls after that. The\n * full rule set is deliberately not repeated: a wall of text re-read every few\n * calls is skimmed, and it costs context that the actual work needs.\n *\n * Only rules about the shape of the reply belong here. Rules about actions\n * (what may be sent, published, or committed) are enforced at the point of\n * action, not by reminding.\n */\nimport { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { tmpdir } from \"node:os\";\nimport { isWorkerSession } from \"../lib/worker-session.js\";\n\n/** Stay silent below this many tool calls \u2014 a short turn has not drifted yet. */\nconst QUIET_BELOW = 6;\n\n/** Re-emit every N calls once past QUIET_BELOW. */\nconst EVERY = 8;\n\nfunction counterFile(sessionId: string): string {\n  const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, \"\") || \"nosession\";\n  return join(tmpdir(), \"pai-whisper-reinject\", `${safe}.count`);\n}\n\nfunction bump(path: string): number {\n  try {\n    mkdirSync(dirname(path), { recursive: true });\n    const n = existsSync(path) ? Number.parseInt(readFileSync(path, \"utf-8\").trim(), 10) || 0 : 0;\n    const next = n + 1;\n    writeFileSync(path, String(next));\n    return next;\n  } catch {\n    return 0;\n  }\n}\n\nfunction localTime(): string {\n  const d = new Date();\n  const p = (n: number) => String(n).padStart(2, \"0\");\n  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;\n}\n\nfunction readStdin(): string {\n  try {\n    return readFileSync(0, \"utf-8\");\n  } catch {\n    return \"\";\n  }\n}\n\nfunction main(): void {\n  let sessionId = \"\";\n  try {\n    const raw = readStdin();\n    if (raw.trim()) sessionId = (JSON.parse(raw) as { session_id?: string }).session_id ?? \"\";\n  } catch { /* no session id \u2014 fall back to a shared counter */ }\n\n  if (isWorkerSession()) return;\n\n  const n = bump(counterFile(sessionId));\n  if (n < QUIET_BELOW || n % EVERY !== 0) return;\n\n  const lines = [\n    `CURRENT LOCAL TIME: ${localTime()} \u2014 use verbatim for any [YYYY-MM-DD HH:MM] stamp. Never estimate it, never increment a previous one.`,\n    `You are ${n} tool calls into this turn. Before the next one, check:`,\n    \"- One command at a time: say what you are about to run, run it, say what came back. Do not batch several steps into one call.\",\n    \"- Report what CHANGED, not what you learned. A finding is not a deliverable.\",\n    \"- Prove it: show the reading that says it failed before and works now.\",\n    \"- Found a fault while working? Fix it. Filing it is not fixing it.\",\n    \"- Corrections stay to one line. No re-litigating your own mistakes.\",\n  ];\n\n  console.log(`<system-reminder>\\n${lines.join(\"\\n\")}\\n</system-reminder>`);\n}\n\nmain();\n", "/**\n * Worker-session detection.\n *\n * A disposable headless worker (a `claude -p` run started by an orchestrating\n * session, possibly against a different model provider with a different\n * context window) shares the project directory and the hook configuration\n * with the real session that spawned it. Left alone, the hooks treat it as a\n * session in its own right: they inject project context into it, create and\n * rename a numbered session note for it, autosave it, and enqueue a\n * model-written handover for it. Its compactions also land in the project's\n * transcript folder, where they are indistinguishable from a real session's\n * and drag the measured compaction trigger down (observed 2026-09-17: two\n * workers compacting at ~151k tokens pulled a project's trigger from ~784k\n * to ~151k, and the real session's handover fired at ~50k tokens).\n *\n * The launcher marks such sessions with `PAI_WORKER=1`. Every hook that does\n * per-session bookkeeping returns immediately when this predicate is true.\n * Deliberately NOT guarded: the security validator (a worker's shell\n * commands must still be checked) and observability capture.\n */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n  return env.PAI_WORKER === \"1\";\n}\n"],
+  "mappings": ";;;;;;AAuBA,SAAyB,YAAY,WAAW,cAAc,qBAAqB;AACnF,SAAS,SAAS,YAAY;AAC9B,SAAS,cAAc;;;ACLhB,SAAS,gBAAgB,MAAyB,QAAQ,KAAc;AAC7E,SAAO,IAAI,eAAe;AAC5B;;;ADOA,IAAM,cAAc;AAGpB,IAAM,QAAQ;AAEd,SAAS,YAAY,WAA2B;AAC9C,QAAM,OAAO,UAAU,QAAQ,mBAAmB,EAAE,KAAK;AACzD,SAAO,KAAK,OAAO,GAAG,wBAAwB,GAAG,IAAI,QAAQ;AAC/D;AAEA,SAAS,KAAK,MAAsB;AAClC,MAAI;AACF,cAAU,QAAQ,IAAI,GAAG,EAAE,WAAW,KAAK,CAAC;AAC5C,UAAM,IAAI,WAAW,IAAI,IAAI,OAAO,SAAS,aAAa,MAAM,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,IAAI;AAC5F,UAAM,OAAO,IAAI;AACjB,kBAAc,MAAM,OAAO,IAAI,CAAC;AAChC,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,YAAoB;AAC3B,QAAM,IAAI,oBAAI,KAAK;AACnB,QAAM,IAAI,CAAC,MAAc,OAAO,CAAC,EAAE,SAAS,GAAG,GAAG;AAClD,SAAO,GAAG,EAAE,YAAY,CAAC,IAAI,EAAE,EAAE,SAAS,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,CAAC,CAAC;AAC5G;AAEA,SAAS,YAAoB;AAC3B,MAAI;AACF,WAAO,aAAa,GAAG,OAAO;AAAA,EAChC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,OAAa;AACpB,MAAI,YAAY;AAChB,MAAI;AACF,UAAM,MAAM,UAAU;AACtB,QAAI,IAAI,KAAK,EAAG,aAAa,KAAK,MAAM,GAAG,EAA8B,cAAc;AAAA,EACzF,QAAQ;AAAA,EAAsD;AAE9D,MAAI,gBAAgB,EAAG;AAEvB,QAAM,IAAI,KAAK,YAAY,SAAS,CAAC;AACrC,MAAI,IAAI,eAAe,IAAI,UAAU,EAAG;AAExC,QAAM,QAAQ;AAAA,IACZ,uBAAuB,UAAU,CAAC;AAAA,IAClC,WAAW,CAAC;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,UAAQ,IAAI;AAAA,EAAsB,MAAM,KAAK,IAAI,CAAC;AAAA,mBAAsB;AAC1E;AAEA,KAAK;",
   "names": []
 }

package/dist/hooks/worker-status-line.mjs

@@ -8288,49 +8288,116 @@ function recordSessionMapEntry(logDir, cwd2, session, term2, now = Date.now()) {
   }
 }
 
+// src/workers/agentish.ts
+import { execFileSync } from "node:child_process";
+var AG2_SPEC_FALLBACK = "AG2. msg=kind line+k=v lines. kinds T R S Q A X. keys i id g goal o own n forbid d steps p proof u out l limits r res c changes t tests G gate I inst m images # nums w worst x next z note(<200ch). sep |. outcomes + - ~ ? !. @n=path declared once then reused; @n:12=file:line. tests as Name+ Name-. no prose, no articles, never restate, unknown=?. r=+ only if all t +.";
+var AG2_EXTENSIONS_FALLBACK = "y why(\u2264600ch)";
+var cachedSpec = null;
+function ag2Spec() {
+  if (cachedSpec) return cachedSpec;
+  try {
+    const out = execFileSync("aibroker", ["agentish", "spec"], {
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8"
+    });
+    const lines = out.split("\n").filter((l) => l.trim());
+    if (lines[0]?.startsWith("AG2.")) {
+      cachedSpec = { spec: lines[0], extensions: lines[1] ?? AG2_EXTENSIONS_FALLBACK, source: "aibroker" };
+      return cachedSpec;
+    }
+  } catch {
+  }
+  cachedSpec = { spec: AG2_SPEC_FALLBACK, extensions: AG2_EXTENSIONS_FALLBACK, source: "builtin" };
+  return cachedSpec;
+}
+
 // src/workers/report.ts
 var OPERATOR_MARK = "[operator]";
-var WORKER_CONTRACT_PROMPT = [
-  "You are a headless implementation worker, run non-interactively by an orchestrating session.",
-  "You are the worker: this task is yours to finish in this process. Never hand your whole task to a",
-  "single child worker and step back \u2014 that is delegation, not work. Child workers are for two things",
-  "only: (1) PARALLELISING independent parts of your task, each part a self-contained spec; (2) CHEAPER",
-  "bounded sub-tasks \u2014 probes, renders, test runs, lookups \u2014 run one tier down with --class spotcheck or",
-  "--class simple. Always pin --provider anthropic on children.",
-  "You own your children's results: run them in the foreground or poll until each has finished, read",
-  "their result, verify it, and fold it into your own report. When your turn ends this run ends and any",
-  "running child is killed, so never end with a child still running.",
-  "Ending your turn ends this run. There is no later wake-up: never call ScheduleWakeup, never say you",
-  "will pick something up later, never leave a background command as your final action. Finish, then",
-  "report.",
-  "No narration, no timestamps, no greetings, no summaries of what you read; act, verify, then stop.",
-  "Your ONE final message is a JSON object and nothing else \u2014 no prose before or after, no code fence:",
-  '{"changed":[{"path":"\u2026","summary":"\u2026"}],"commands":["\u2026"],"checks":[{"name":"\u2026","ok":true,"detail":"\u2026"}],"open":["\u2026"],"notes":"one line"}',
-  "changed: files you touched (path + one-line summary). commands: the commands that verify the work.",
-  "checks: each with ok true/false and the evidence in detail. open: what you could not finish, if anything.",
-  "notes: one line, the headline a reviewer reads first.",
-  "NEVER put a multi-line or quoted payload inline in a shell command \u2014 no heredocs (<<EOF), no long",
-  "-p '\u2026' specs for child workers, no inline JSON, no inline scripts. ALWAYS write it to a file with",
-  'the Write tool first and pass the file: -p "$(cat spec.txt)", --file spec.txt, or < spec.txt.',
-  "Inline quoting fails silently or dies with a parse error and burns a worker launch; there are no",
-  "exceptions.",
-  "Never inline code one-liners (python3 -c, node -e, ruby -e and friends) \u2014 the permission layer",
-  'denies them ("ztk: command denied by permission rules"); write the script to a file with the',
-  "Write tool and run it (python3 script.py), or use jq for JSON inspection.",
-  "",
-  `Operator messages: a user turn starting with ${OPERATOR_MARK} was typed by the operator while you`,
-  "run (the prompt of a resumed run is the operator's too). Answer it FIRST, in one or two plain lines \u2014",
-  "a question gets its answer, an instruction gets one line naming what will change \u2014 then continue the",
-  "task you were on.",
-  "",
-  "Sub-workers: you may start your own workers with `pai worker run --class <class> -p '<prompt>'`",
-  "(Bash tool). Your children run on their own provider and report back to you automatically when",
-  "they finish. Send a handoff UP instead of doing work yourself when a cheaper provider would",
-  "suffice, the task is out of your scope, or a decision is needed:",
-  '`pai worker handoff \'{"kind":"proposal","text":"\u2026","data":{\u2026}}\'` (kinds: proposal,',
-  "question, blocker; results are sent for you when you finish). Sibling workers are not a",
-  "coordination path \u2014 there is no sideways channel; everything goes up to your parent."
-].join("\n");
+function ag2ReportBlock() {
+  const spec = ag2Spec();
+  return [
+    spec.spec,
+    spec.extensions,
+    "Final message: one AG2 `R` message only \u2014 no prose, no code fence, no markdown.",
+    "R requires i (id), r (+ - ~ ? !), t (tests, Name+ Name-), c (path summary|path summary).",
+    "r=+ requires G=+ (gate) and p non-empty (proof command), and every t entry +. z= the answer/note,",
+    "one line, always present. x= what is left (omit if nothing). y= one line why when r is not +.",
+    "Example:",
+    "R",
+    "i=count-audit-ts",
+    "r=+",
+    "G=+",
+    "c=src/audit summary of files counted",
+    "t=Count+",
+    "p=wc -l src/audit/*.ts",
+    "z=19 files, 2523 lines"
+  ];
+}
+function jsonReportBlock(lead) {
+  return [
+    lead,
+    '{"changed":[{"path":"\u2026","summary":"\u2026"}],"commands":["\u2026"],"checks":[{"name":"\u2026","ok":true,"detail":"\u2026"}],"open":["\u2026"],"notes":"one line"}'
+  ];
+}
+function fileNotInlineBlock() {
+  return [
+    "NEVER put a multi-line or quoted payload inline in a shell command \u2014 no heredocs (<<EOF), no long",
+    "-p '\u2026' specs for child workers, no inline JSON, no inline scripts. ALWAYS write it to a file with",
+    'the Write tool first and pass the file: -p "$(cat spec.txt)", --file spec.txt, or < spec.txt.',
+    "Inline quoting fails silently or dies with a parse error and burns a worker launch; there are no",
+    "exceptions.",
+    "Never inline code one-liners (python3 -c, node -e, ruby -e and friends) \u2014 the permission layer",
+    'denies them ("ztk: command denied by permission rules"); write the script to a file with the',
+    "Write tool and run it (python3 script.py), or use jq for JSON inspection."
+  ];
+}
+function fullContractPrompt(format) {
+  const lines = [
+    "You are a headless implementation worker, run non-interactively by an orchestrating session.",
+    "You are the worker: this task is yours to finish in this process. Never hand your whole task to a",
+    "single child worker and step back \u2014 that is delegation, not work. Child workers are for two things",
+    "only: (1) PARALLELISING independent parts of your task, each part a self-contained spec; (2) CHEAPER",
+    "bounded sub-tasks \u2014 probes, renders, test runs, lookups \u2014 run one tier down with --class spotcheck or",
+    "--class simple. Always pin --provider anthropic on children.",
+    "You own your children's results: run them in the foreground or poll until each has finished, read",
+    "their result, verify it, and fold it into your own report. When your turn ends this run ends and any",
+    "running child is killed, so never end with a child still running.",
+    "Ending your turn ends this run. There is no later wake-up: never call ScheduleWakeup, never say you",
+    "will pick something up later, never leave a background command as your final action. Finish, then",
+    "report.",
+    "No narration, no timestamps, no greetings, no summaries of what you read; act, verify, then stop.",
+    ...fileNotInlineBlock(),
+    "",
+    `Operator messages: a user turn starting with ${OPERATOR_MARK} was typed by the operator while you`,
+    "run (the prompt of a resumed run is the operator's too). Answer it FIRST, in one or two plain lines \u2014",
+    "a question gets its answer, an instruction gets one line naming what will change \u2014 then continue the",
+    "task you were on.",
+    "",
+    "Sub-workers: you may start your own workers with `pai worker run --class <class> -p '<prompt>'`",
+    "(Bash tool). Your children run on their own provider and report back to you automatically when",
+    "they finish. Send a handoff UP instead of doing work yourself when a cheaper provider would",
+    "suffice, the task is out of your scope, or a decision is needed:",
+    '`pai worker handoff \'{"kind":"proposal","text":"\u2026","data":{\u2026}}\'` (kinds: proposal,',
+    "question, blocker; results are sent for you when you finish). Sibling workers are not a",
+    "coordination path \u2014 there is no sideways channel; everything goes up to your parent.",
+    ""
+  ];
+  lines.push(
+    ...format === "ag2" ? ag2ReportBlock() : jsonReportBlock(
+      "Your ONE final message is a JSON object and nothing else \u2014 no prose before or after, no code fence:"
+    )
+  );
+  if (format === "json") {
+    lines.push(
+      "changed: files you touched (path + one-line summary). commands: the commands that verify the work.",
+      "checks: each with ok true/false and the evidence in detail. open: what you could not finish, if anything.",
+      "notes: one line, the headline a reviewer reads first."
+    );
+  }
+  return lines.join("\n");
+}
+var WORKER_CONTRACT_PROMPT = fullContractPrompt("ag2");
 
 // src/workers/render.ts
 function shortModel(model) {