@lucascouts/claude-agent-tui 0.5.1 → 0.6.0

package/dist/permissions/gate-wiring.js

@@ -30,7 +30,7 @@
 // OFFLINE: this module spawns NO claude and bills nothing; the http server binds 127.0.0.1 only.
 import * as os from "node:os";
 import * as path from "node:path";
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { findFreePort } from "../gate/port.js";
 import { injectHook, restore } from "../gate/settings-writer.js";
 import { startHookServer } from "./hook-server.js";
@@ -86,6 +86,13 @@ export const DEFAULT_CORRELATION_POLL_MS = 50;
  *  fail-closed timeout deny. Tracked separately from the poll interval (the poll is 10-50ms; nudging on
  *  every poll would hammer the pump) — a nudge fires only once ~250ms has elapsed since the last one. */
 export const DEFAULT_CORRELATION_RENUDGE_MS = 250;
+/**
+ * FIX(watchdog-permission): while a permission dialog is pending the claude is BLOCKED and writes
+ * nothing to the JSONL, so the end-of-turn watchdog (120s of silence) would mistake a long human
+ * decision for a dead turn. Re-arm it every this-many ms via the bound `noteActivity` for as long as
+ * the dialog is open. Must stay well under TURN_STALL_WATCHDOG_MS (120_000).
+ */
+export const DEFAULT_PERMISSION_HEARTBEAT_MS = 30_000;
 /** Default window for the native prompt to APPEAR after an allow decision (#52822 sweep, ms).
  *  If no marker renders within it, allow-suppression held (the 2.1.161 case) — nothing to clear. */
 export const DEFAULT_PROMPT_APPEAR_MS = 1500;
@@ -112,6 +119,8 @@ class SessionGateImpl {
     constructor(opts) {
         this.opts = opts;
         this.port = 0;
+        /** Story 055 (R1.3) — set in {@link start} to a crypto-random per-session secret. */
+        this.token = "";
         this.settingsPath = "";
         this.correlator = new ToolUseCorrelator();
         /** Rolling tail of recent PTY output + absolute count of chars ever appended (probe offsets). */
@@ -141,14 +150,46 @@ class SessionGateImpl {
         this.permissionQueue = run.then(() => undefined, () => undefined);
         return run;
     }
+    /**
+     * FIX(watchdog-permission): start a heartbeat that re-arms the end-of-turn watchdog (via the bound
+     * `noteActivity`) every {@link DEFAULT_PERMISSION_HEARTBEAT_MS} while a permission dialog is open, so
+     * the human decision time is never counted as transcript silence. Self-reschedules through the
+     * injectable `schedule` (testable). Returns a stop fn; safe/no-op when `noteActivity` is unset.
+     */
+    startPermissionHeartbeat() {
+        const note = this.noteActivity;
+        if (!note)
+            return () => { };
+        let stopped = false;
+        const tick = () => {
+            if (stopped || this.torndown)
+                return;
+            try {
+                note();
+            }
+            catch {
+                // heartbeat is best-effort liveness; a failure never affects the decision
+            }
+            this.schedule(tick, DEFAULT_PERMISSION_HEARTBEAT_MS);
+        };
+        this.schedule(tick, DEFAULT_PERMISSION_HEARTBEAT_MS);
+        return () => {
+            stopped = true;
+        };
+    }
     /** Start the hook server, then write the scratch settings (server first, so the URL the settings
      *  point at is live before claude can ever read them; settings BEFORE the spawn is the caller's
      *  ordering contract — blocker c). */
     async start() {
         const findPort = this.opts.findPort ?? findFreePort;
         this.port = await findPort();
+        // Story 055 (R1.3): a per-session crypto-random secret bound into the hook URL (after the marker
+        // path). The hook-server rejects any PreToolUse POST that does not present it — the compensating
+        // control for the relaxed JSONL anti-forgery (decide() now seeds the correlator from the payload).
+        this.token = randomBytes(24).toString("hex");
         this.server = await startHookServer({
             port: this.port,
+            token: this.token,
             deciderTimeoutMs: this.opts.deciderTimeoutMs,
             onWarn: (m) => this.warn(m),
             onToolCall: (call) => this.decide(call),
@@ -159,6 +200,7 @@ class SessionGateImpl {
             this.backup = await injectHook({
                 settingsPath: this.settingsPath,
                 port: this.port,
+                token: this.token,
                 timeout: this.opts.hookTimeoutSeconds,
             });
         }
@@ -169,10 +211,11 @@ class SessionGateImpl {
             throw err;
         }
     }
-    bindSession(sessionId, nudge, resolveSubagentRelay) {
+    bindSession(sessionId, nudge, resolveSubagentRelay, noteActivity) {
         this.sessionId = sessionId;
         this.nudge = nudge;
         this.resolveSubagentRelay = resolveSubagentRelay;
+        this.noteActivity = noteActivity;
     }
     bindPty(pty) {
         this.pty = pty;
@@ -220,31 +263,45 @@ class SessionGateImpl {
                 `was bound to an ACP session — denying (cannot raise session/request_permission).`);
             return "deny";
         }
+        // FIX(gate-deadlock): the claude flushes the `tool_use` JSONL line only AFTER the hook decision,
+        // so correlating against the JSONL deadlocks — the line never reaches the pump during the wait
+        // (proven live 2026-06-25: total=9 frozen for 5s, the id only registered post-deny). Seed the
+        // correlator from the hook payload, the AUTHORITATIVE tool_use.id source, so the gate decides on
+        // the payload (the JSONL stays best-effort enrichment). Mirrors the ACP original's permission
+        // callback, which decided directly on the SDK-supplied tool id without a transcript round-trip.
+        this.correlator.ensureRegistered(call.toolUseId);
         await this.waitForCorrelation(call.toolUseId);
-        // === Story 054 (§9 subagent relay) — AFTER the correlation wait, BEFORE the ACP prompt. ========
-        // The hook payload carries NO parent id (ForwardedToolCall has no parent_tool_use_id); the ONLY
-        // source of a subagent inner tool's parent is the session's sidechainParentMap, read lazily via
-        // the bound resolver. An undefined relay = a MAIN-CHAIN tool → both fields stay undefined and the
-        // requestPermission call below is byte-identical to today (U1). A KNOWN subagent inner tool relays
-        // its dialog under the parent Task id Zed already rendered (R1/R2) — UNLESS it cannot be safely
-        // relayed (orphan parent, or it never became a clean JSONL match within the wait window), in which
-        // case we fail LOUD (R4): a VISIBLE deny through the gate's warn surface (→ this.logger.error),
-        // naming the subagent + inner tool, and return "deny" WITHOUT raising a dialog against a bogus id.
-        const relay = this.resolveSubagentRelay?.(call.toolUseId);
+        // === Story 054/055 (§9 subagent relay) — AFTER the correlation wait, BEFORE the ACP prompt. =====
+        // R2.2 — the dialog LABEL is sourced from the payload's `agent_type` (carried by parsePayload,
+        // story 055/2.1): transcript-independent and known NOW, so a subagent tool is always attributed
+        // even when its parent Task id is not (yet) resolvable. A main-chain payload has no agent_type →
+        // `subagentLabel` stays undefined and the requestPermission call below is byte-identical to today
+        // (U1: bare tool name, dialog under the inner id).
+        //
+        // R2.3 — parent-Task GROUPING is BEST-EFFORT. The hook payload carries NO parent id; the only
+        // source is the session's sidechainParentMap, read lazily via the bound resolver and populated by
+        // the (transcript-lagging) pump. WHEN it resolves a non-null parent, the dialog attaches under that
+        // parent Task id Zed already rendered. For a subagent whose row has NOT landed yet, give the pump a
+        // brief re-nudged window to register it mid-wait (the join is pump-fed, like the inner correlation);
+        // on expiry we relay the LABELLED dialog under the INNER id. An orphan (parentId === null) or an
+        // unresolved subagent is therefore PROMPTED (labelled), NEVER silently denied — this REPLACES the
+        // story-054 orphan/uncorrelated visible deny. The only deny here is requestPermission's own
+        // fail-closed (transport error / cancelled / duplicate id), propagated unchanged.
+        let subagentLabel = call.agentType;
+        let relay = this.resolveSubagentRelay?.(call.toolUseId);
+        if (!relay && call.agentType !== undefined) {
+            // A subagent tool (agent_type present) whose parent row may still be in flight: best-effort wait.
+            relay = await this.waitForSubagentParent(call.toolUseId);
+        }
         let dialogToolCallId;
-        let subagentLabel;
         if (relay) {
-            // isCleanMatch PROBES (does not consume); requestPermission's correlator.decide still consumes
-            // the inner id. The orphan branch short-circuits BEFORE the probe via `||`.
-            if (relay.parentId === null || !this.correlator.isCleanMatch(call.toolUseId)) {
-                this.warn(`[gate §9 subagent] FAIL CLOSED: subagent (${relay.subagentLabel}) tool "${call.toolName}" ` +
-                    `(tool_use ${call.toolUseId}) ${relay.parentId === null
-                        ? "is an orphan — no parent Task to attach the permission dialog to"
-                        : "never correlated in the JSONL within the wait window"} — denying (R4 visible deny).`);
-                return "deny";
+            // Prefer the payload label; fall back to the resolver's best-effort label (a pre-055 caller / a
+            // subagent payload that somehow omitted agent_type).
+            subagentLabel = call.agentType ?? relay.subagentLabel;
+            // Group ONLY under a real, resolvable parent; an orphan (null) falls through to the inner-id relay.
+            if (relay.parentId !== null) {
+                dialogToolCallId = relay.parentId;
             }
-            dialogToolCallId = relay.parentId;
-            subagentLabel = relay.subagentLabel;
         }
         // === Story 054 (R5) — SERIALIZE only the raise+inject critical section. ========================
         // dialogToolCallId/subagentLabel were computed above in the CONCURRENT prelude, so each enqueued
@@ -253,24 +310,33 @@ class SessionGateImpl {
         // requestPermission + armAllowSweep one at a time — no native-prompt keystroke crossing on the
         // shared PTY. A single sequential main-chain tool is a no-op through the queue (U1).
         return this.enqueuePermission(async () => {
-            const decision = await requestPermission({
-                client: this.opts.client,
-                sessionId,
-                toolCall: {
-                    toolUseId: call.toolUseId,
-                    toolName: call.toolName,
-                    toolInput: call.toolInput,
-                },
-                correlator: this.correlator,
-                onWarn: (m) => this.warn(m),
-                dialogToolCallId,
-                subagentLabel,
-            });
-            if (decision === "allow") {
-                // Return the allow body FIRST (claude is blocked on this response); sweep out of band.
-                this.armAllowSweep(call);
+            // FIX(watchdog-permission): the claude is blocked on this response with the JSONL silent, so
+            // re-arm the end-of-turn watchdog for as long as the dialog is open (a slow human decision is
+            // NOT a dead turn). Always cleared in `finally`, on success or throw.
+            const stopHeartbeat = this.startPermissionHeartbeat();
+            try {
+                const decision = await requestPermission({
+                    client: this.opts.client,
+                    sessionId,
+                    toolCall: {
+                        toolUseId: call.toolUseId,
+                        toolName: call.toolName,
+                        toolInput: call.toolInput,
+                    },
+                    correlator: this.correlator,
+                    onWarn: (m) => this.warn(m),
+                    dialogToolCallId,
+                    subagentLabel,
+                });
+                if (decision === "allow") {
+                    // Return the allow body FIRST (claude is blocked on this response); sweep out of band.
+                    this.armAllowSweep(call);
+                }
+                return decision;
+            }
+            finally {
+                stopHeartbeat();
             }
-            return decision;
         });
     }
     /** Bounded poll until the pump has registered `toolUseId` as a clean single JSONL match. On
@@ -318,6 +384,58 @@ class SessionGateImpl {
             this.schedule(poll, pollMs);
         });
     }
+    /**
+     * Story 055 (R2.3) — BEST-EFFORT parent grouping for a subagent inner tool. The `agent_id → parent
+     * tool_use.id` join lives only in the (transcript-lagging) pump-fed `sidechainParentMap`, so the
+     * parent may not be registered at decide()-time. Poll the lazy resolver, re-nudging the pump on the
+     * same {@link DEFAULT_CORRELATION_RENUDGE_MS} cadence so a sidechain row landing MID-WAIT is caught,
+     * and resolve with the relay AS SOON AS it appears. On expiry resolve `undefined` — the caller then
+     * relays the LABELLED dialog under the inner id (never a deny). Bounded by the same correlation
+     * window since the join is pump-fed exactly like the inner correlation; a torn-down gate resolves
+     * `undefined` immediately. Only ever called for a subagent payload (agent_type present), so a
+     * main-chain tool never incurs this wait.
+     */
+    waitForSubagentParent(innerToolUseId) {
+        const resolveNow = () => this.resolveSubagentRelay?.(innerToolUseId);
+        const immediate = resolveNow();
+        if (immediate)
+            return Promise.resolve(immediate);
+        const waitMs = this.opts.correlationWaitMs ?? DEFAULT_CORRELATION_WAIT_MS;
+        const pollMs = this.opts.correlationPollMs ?? DEFAULT_CORRELATION_POLL_MS;
+        const renudgeMs = this.opts.correlationRenudgeMs ?? DEFAULT_CORRELATION_RENUDGE_MS;
+        return new Promise((resolve) => {
+            let elapsed = 0;
+            let sinceNudge = 0;
+            const poll = () => {
+                if (this.torndown) {
+                    resolve(undefined);
+                    return;
+                }
+                const r = resolveNow();
+                if (r) {
+                    resolve(r);
+                    return;
+                }
+                elapsed += pollMs;
+                sinceNudge += pollMs;
+                if (sinceNudge >= renudgeMs) {
+                    sinceNudge = 0;
+                    try {
+                        this.nudge?.();
+                    }
+                    catch {
+                        // best-effort: a nudge failure only widens the grouping window; never rejects or decides
+                    }
+                }
+                if (elapsed >= waitMs) {
+                    resolve(undefined); // best-effort expiry — relay under the inner id (labelled), not a deny
+                    return;
+                }
+                this.schedule(poll, pollMs);
+            };
+            this.schedule(poll, pollMs);
+        });
+    }
     /**
      * #52822 sweep (allow path, best-effort by design): wait a bounded window for the native TUI
      * prompt to APPEAR in the post-decision PTY output; if it never renders, allow-suppression held

package/dist/permissions/hook-server.d.ts

@@ -10,6 +10,9 @@ export interface PreToolUsePayload {
     tool_name?: string;
     tool_input?: unknown;
     tool_use_id?: string;
+    /** Story 055 (R2.1) — present ONLY on a subagent-internal tool: the subagent's own id and type. */
+    agent_id?: string;
+    agent_type?: string;
 }
 /** The normalized tool call forwarded to the decider (camelCase, the shape request-permission uses). */
 export interface ForwardedToolCall {
@@ -18,6 +21,11 @@ export interface ForwardedToolCall {
     toolUseId: string;
     sessionId?: string;
     permissionMode?: string;
+    /** Story 055 (R2.1) — the subagent's own id (`agent_id`); undefined for a main-chain tool. */
+    agentId?: string;
+    /** Story 055 (R2.1/R2.2) — the subagent's type (`agent_type`); the dialog label source. Undefined
+     *  for a main-chain tool. There is NO parent tool_use.id in the payload (grouping is best-effort). */
+    agentType?: string;
 }
 /** The decider the server forwards each tool call to; returns the enforced `'allow'`/`'deny'`. */
 export type ToolCallDecider = (call: ForwardedToolCall) => Promise<"allow" | "deny"> | "allow" | "deny";
@@ -46,6 +54,13 @@ export interface StartHookServerOptions {
     createHttpServer?: () => Server;
     /** Optional diagnostics sink for fail-closed events (defaults to no-op). */
     onWarn?: (message: string) => void;
+    /**
+     * Story 055 (R1.3) — per-session secret token. WHEN set, a POST whose request path is not exactly
+     * `${FORK_HOOK_MARKER_PATH}/<token>` FAILS CLOSED (deny) WITHOUT invoking the decider — the
+     * compensating control for the relaxed JSONL anti-forgery. WHEN undefined, no token is enforced
+     * (the pre-055 behavior, used by the unit tests that construct the server directly).
+     */
+    token?: string;
 }
 /** Default decider timeout (ms) — long enough for an async Zed decision relay, short of a hang. */
 export declare const DEFAULT_DECIDER_TIMEOUT_MS = 600000;

package/dist/permissions/hook-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook-server.d.ts","sourceRoot":"","sources":["../../src/permissions/hook-server.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAIjG;sGACsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,iBAAiB,KACpB,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C,qCAAqC;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,mGAAmG;AACnG,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAsBlD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAyBlE;AAiCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkFjF"}
+{"version":3,"file":"hook-server.d.ts","sourceRoot":"","sources":["../../src/permissions/hook-server.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAMjG;sGACsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;0GACsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,iBAAiB,KACpB,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C,qCAAqC;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mGAAmG;AACnG,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAsBlD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CA6BlE;AAiCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8GjF"}

package/dist/permissions/hook-server.js

@@ -18,7 +18,9 @@
 // user's real config — that wiring is the engine-integration concern; this module is the standalone
 // server seam.
 import { createServer } from "node:http";
+import { appendFileSync } from "node:fs";
 import { LOOPBACK_HOST } from "../gate/port.js";
+import { FORK_HOOK_MARKER_PATH } from "../gate/settings-writer.js";
 import { allowDecision, denyDecision } from "./deny.js";
 /** Default decider timeout (ms) — long enough for an async Zed decision relay, short of a hang. */
 export const DEFAULT_DECIDER_TIMEOUT_MS = 600_000;
@@ -70,6 +72,10 @@ export function parsePayload(raw) {
         toolUseId,
         sessionId: typeof parsed.session_id === "string" ? parsed.session_id : undefined,
         permissionMode: typeof parsed.permission_mode === "string" ? parsed.permission_mode : undefined,
+        // R2.1 — carry the subagent attribution the §9 payload already ships (today they are dropped). A
+        // main-chain payload omits them → both stay undefined.
+        agentId: typeof parsed.agent_id === "string" ? parsed.agent_id : undefined,
+        agentType: typeof parsed.agent_type === "string" ? parsed.agent_type : undefined,
     };
 }
 /** Run the decider with a timeout; on timeout or throw, resolve `'deny'` (fail closed). */
@@ -110,7 +116,7 @@ async function decideWithTimeout(decider, call, timeoutMs, onWarn) {
  *   fails fast rather than spawning claude with an ungated hook URL).
  */
 export function startHookServer(opts) {
-    const { port, deciderTimeoutMs = DEFAULT_DECIDER_TIMEOUT_MS, createHttpServer = createServer, onWarn, } = opts;
+    const { port, deciderTimeoutMs = DEFAULT_DECIDER_TIMEOUT_MS, createHttpServer = createServer, onWarn, token, } = opts;
     let decider = opts.onToolCall;
     const server = createHttpServer();
     server.on("request", (req, res) => {
@@ -119,6 +125,29 @@ export function startHookServer(opts) {
             let call = null;
             try {
                 const raw = await readBody(req);
+                // DIAGNOSTIC (env-gated, off by default): capture EVERY raw PreToolUse POST the fork's
+                // hook-server receives — including the subagent-attributed fields (agent_id/agent_type) that
+                // parsePayload drops — so a live run can verify whether subagent-internal tools POST at all.
+                if (process.env.FORK_HOOK_LOG_RAW) {
+                    try {
+                        appendFileSync(process.env.FORK_HOOK_LOG_RAW, raw + "\n");
+                    }
+                    catch {
+                        // best-effort diagnostic — never let logging fail the request
+                    }
+                }
+                // R1.3 (story 055): validate the per-session token from the request path BEFORE the decider.
+                // A POST that does not present `${FORK_HOOK_MARKER_PATH}/<token>` is denied without ever
+                // reaching the decider — the forge-resistance that compensates the payload-seeded correlation.
+                if (token !== undefined) {
+                    const urlPath = (req.url ?? "").split("?")[0];
+                    if (urlPath !== `${FORK_HOOK_MARKER_PATH}/${token}`) {
+                        onWarn?.(`[gate §9] FAIL CLOSED: PreToolUse POST presented a missing/incorrect per-session token ` +
+                            `(url path "${urlPath}") — denying WITHOUT invoking the decider.`);
+                        writeDecision(res, denyDecision({ toolName: "(unauthorized)", toolUseId: "(unauthorized)" }));
+                        return;
+                    }
+                }
                 call = parsePayload(raw);
                 if (call === null) {
                     onWarn?.(`[gate §9] FAIL CLOSED: unparseable or identity-less PreToolUse payload — denying.`);

package/dist/permissions/request-permission.d.ts

@@ -70,6 +70,15 @@ export declare class ToolUseCorrelator {
      * observation marks it duplicate. Returns true on the FIRST registration, false on a duplicate.
      */
     register(toolUseId: string): boolean;
+    /**
+     * FIX(gate-deadlock): seed the correlator from the AUTHORITATIVE PreToolUse hook payload when the
+     * JSONL has not observed the id yet. The claude buffers the `tool_use` line and only flushes it to
+     * the transcript AFTER the hook decision, so waiting on the JSONL deadlocks (the line never arrives
+     * during the wait). Idempotent and safe: marks count=1 ONLY when unseen (0) — it never pushes an
+     * already-clean (1) id to duplicate (2), nor touches a genuine duplicate (>1). The pump's later
+     * observation of the same id (post-decision) is harmless: the id is already consumed by then.
+     */
+    ensureRegistered(toolUseId: string): void;
     /** True iff `toolUseId` was observed EXACTLY once in the JSONL and has not yet been consumed. */
     isCleanMatch(toolUseId: string): boolean;
     /**

package/dist/permissions/request-permission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-permission.d.ts","sourceRoot":"","sources":["../../src/permissions/request-permission.ts"],"names":[],"mappings":"AAoBA,yEAAyE;AACzE,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,eAAe,CAAC;AAEnG,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,oBAAoB,CAAC;CAC5B;AAED,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,MAAM,wBAAwB,GAChC;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,GACxB;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtF;AAED,iGAAiG;AACjG,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wFAAwF;AACxF,eAAO,MAAM,eAAe,UAAU,CAAC;AACvC,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC,gFAAgF;AAChF,wBAAgB,sBAAsB,IAAI,gBAAgB,EAAE,CAK3D;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,8FAA8F;IAC9F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,qGAAqG;IACrG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAE9C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAMpC,iGAAiG;IACjG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIxC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;CAS9C;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sFAAsF;IACtF,UAAU,EAAE,iBAAiB,CAAC;IAC9B,sGAAsG;IACtG,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;oGACgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAuDjG"}
+{"version":3,"file":"request-permission.d.ts","sourceRoot":"","sources":["../../src/permissions/request-permission.ts"],"names":[],"mappings":"AAoBA,yEAAyE;AACzE,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,eAAe,CAAC;AAEnG,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,oBAAoB,CAAC;CAC5B;AAED,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,MAAM,wBAAwB,GAChC;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,GACxB;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtF;AAED,iGAAiG;AACjG,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wFAAwF;AACxF,eAAO,MAAM,eAAe,UAAU,CAAC;AACvC,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC,gFAAgF;AAChF,wBAAgB,sBAAsB,IAAI,gBAAgB,EAAE,CAK3D;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,8FAA8F;IAC9F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,qGAAqG;IACrG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAE9C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAMpC;;;;;;;OAOG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAIzC,iGAAiG;IACjG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIxC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;CAS9C;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sFAAsF;IACtF,UAAU,EAAE,iBAAiB,CAAC;IAC9B,sGAAsG;IACtG,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;oGACgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CA0DjG"}

package/dist/permissions/request-permission.js

@@ -52,6 +52,18 @@ export class ToolUseCorrelator {
         this.seen.set(toolUseId, count + 1);
         return count === 0;
     }
+    /**
+     * FIX(gate-deadlock): seed the correlator from the AUTHORITATIVE PreToolUse hook payload when the
+     * JSONL has not observed the id yet. The claude buffers the `tool_use` line and only flushes it to
+     * the transcript AFTER the hook decision, so waiting on the JSONL deadlocks (the line never arrives
+     * during the wait). Idempotent and safe: marks count=1 ONLY when unseen (0) — it never pushes an
+     * already-clean (1) id to duplicate (2), nor touches a genuine duplicate (>1). The pump's later
+     * observation of the same id (post-decision) is harmless: the id is already consumed by then.
+     */
+    ensureRegistered(toolUseId) {
+        if ((this.seen.get(toolUseId) ?? 0) === 0)
+            this.seen.set(toolUseId, 1);
+    }
     /** True iff `toolUseId` was observed EXACTLY once in the JSONL and has not yet been consumed. */
     isCleanMatch(toolUseId) {
         return this.seen.get(toolUseId) === 1 && !this.consumed.has(toolUseId);
@@ -96,12 +108,15 @@ export async function requestPermission(opts) {
         result = await client.requestPermission({
             sessionId,
             toolCall: {
-                // Story 054: a subagent inner tool relays under the PARENT Task id Zed already rendered
-                // (dialogToolCallId), naming the inner tool + subagent in the title. A main-chain call (no
-                // dialogToolCallId) is byte-identical to today: toolCallId = inner id, title = bare tool name.
+                // Story 054/055: a subagent inner tool relays under the PARENT Task id Zed already rendered
+                // (dialogToolCallId) WHEN the parent is resolvable; otherwise it keeps the inner id. Story 055
+                // (R2.2) DECOUPLES the attributed title from dialogToolCallId: the title is labelled whenever
+                // `subagentLabel` is set (sourced from the payload's agent_type), so a fast subagent whose
+                // parent has not yet been resolved still renders `<tool> · from the <agent_type> agent` under
+                // the inner id. A main-chain call (no subagentLabel) stays byte-identical: bare tool name.
                 toolCallId: dialogToolCallId ?? toolCall.toolUseId,
-                title: dialogToolCallId !== undefined
-                    ? `${toolCall.toolName} · from the ${subagentLabel ?? "subagent"} agent`
+                title: subagentLabel !== undefined
+                    ? `${toolCall.toolName} · from the ${subagentLabel} agent`
                     : toolCall.toolName,
                 rawInput: toolCall.toolInput,
             },

package/dist/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,gCAAgC,CAAC;AA0BxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAC7E;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,MAAM,CAAqE;IACnF,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,WAAW,CAA8B;gBAErC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAMzD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBjC;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;OAGG;YACW,eAAe;IAU7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAyBrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxC;;OAEG;IACH,OAAO,IAAI,IAAI;CAehB"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,gCAAgC,CAAC;AA0BxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAC7E;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,MAAM,CAAqE;IACnF,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,WAAW,CAA8B;gBAErC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAMzD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBjC;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;OAGG;YACW,eAAe;IAU7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAgCrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxC;;OAEG;IACH,OAAO,IAAI,IAAI;CAehB"}

package/dist/settings.js

@@ -106,6 +106,13 @@ export class SettingsManager {
                             this.handleSettingsChange();
                         }
                     });
+                    // Story 059: a best-effort settings watcher must NOT keep the Node event loop alive on its
+                    // own. A settingsManager that escapes dispose() (an initialize/re-spawn race — see the
+                    // pre-existing-leak note in acp-agent.ts createSession) otherwise leaves a live fs.watch
+                    // handle that hangs `node:test` on process exit (the live ACP process is held open by its
+                    // stdio, never by this watcher). unref() detaches it from the loop's keep-alive set while
+                    // leaving the subscription fully functional.
+                    watcher.unref?.();
                     watcher.on("error", (error) => {
                         this.logger.error(`Settings watcher error for ${filePath}:`, error);
                     });
@@ -139,6 +146,8 @@ export class SettingsManager {
                 this.logger.error("Failed to reload settings:", error);
             }
         }, 100);
+        // Story 059: same rationale as the watcher unref — a pending debounce timer must not block exit.
+        this.debounceTimer?.unref?.();
     }
     /**
      * Returns the current merged settings

package/dist/tools.d.ts

@@ -50,8 +50,16 @@ export declare function toDisplayPath(filePath: string, cwd?: string): string;
 export declare function toolCallIdFor(toolUseId: string, sessionId: string, options?: {
     namespaced?: boolean;
 }): string;
-export declare function toolInfoFromToolUse(toolUse: any, supportsTerminalOutput?: boolean, cwd?: string): ToolInfo;
-export declare function toolUpdateFromToolResult(toolResult: ToolResultBlockParam | BetaToolResultBlockParam | BetaWebSearchToolResultBlockParam | BetaWebFetchToolResultBlockParam | WebSearchToolResultBlockParam | BetaCodeExecutionToolResultBlockParam | BetaBashCodeExecutionToolResultBlockParam | BetaTextEditorCodeExecutionToolResultBlockParam | BetaRequestMCPToolResultBlockParam | BetaToolSearchToolResultBlockParam, toolUse: any | undefined, supportsTerminalOutput?: boolean): ToolUpdate;
+/** Minimal shape of a raw JSONL `tool_use` block consumed by the tool mappers. */
+interface RawToolUse {
+    name: string;
+    id: string;
+    input?: unknown;
+}
+export declare function toolInfoFromToolUse(toolUse: RawToolUse, supportsTerminalOutput?: boolean, cwd?: string): ToolInfo;
+export declare function toolUpdateFromToolResult(toolResult: ToolResultBlockParam | BetaToolResultBlockParam | BetaWebSearchToolResultBlockParam | BetaWebFetchToolResultBlockParam | WebSearchToolResultBlockParam | BetaCodeExecutionToolResultBlockParam | BetaBashCodeExecutionToolResultBlockParam | BetaTextEditorCodeExecutionToolResultBlockParam | BetaRequestMCPToolResultBlockParam | BetaToolSearchToolResultBlockParam, toolUse: {
+    name?: string;
+} | undefined, supportsTerminalOutput?: boolean): ToolUpdate;
 export type ClaudePlanEntry = {
     content: string;
     status: "pending" | "in_progress" | "completed";

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -325,7 +325,11 @@ export function toolUpdateFromToolResult(toolResult, toolUse, supportsTerminalOu
     if ("is_error" in toolResult &&
         toolResult.is_error &&
         toolResult.content &&
-        toolResult.content.length > 0) {
+        toolResult.content.length > 0 &&
+        // Story 056 (#776): a FAILED Bash with a negotiated terminal must still render as terminal
+        // output (terminal_output + terminal_exit exit_code 1 via `case "Bash"`), not markdown — so it
+        // is excluded from this error-only early-return. Every other errored result is unchanged.
+        !(toolUse?.name === "Bash" && supportsTerminalOutput)) {
         // Only return errors
         return toAcpContentUpdate(toolResult.content, true);
     }

package/dist/usage.d.ts

@@ -32,6 +32,9 @@ export interface UsageOptions {
  *   • R3.1 — the optional `cost` field is INTENTIONALLY OMITTED and must NEVER be fabricated:
  *     the JSONL usage block carries only token counts, and `cost` is optional in the Zed v1 struct,
  *     so omitting it is contract-correct (an invented cost would violate §1 "never fabricate").
+ *     Story 059 EVIDENCE (2026-06-28): an audit of 5169 local transcripts found 0 carrying
+ *     `total_cost_usd` as a JSON key — it lives only in the SDK `result` envelope (`claude -p`), never
+ *     in the interactive PTY+tail JSONL mapped here (the 68 substring hits were all conversation text).
  */
 export declare function toUsageUpdate(message: UsageCarrier, options?: UsageOptions): UsageUpdateNotification | undefined;
 export interface UsageFlagOptions extends UsageOptions {

package/dist/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,iFAAiF;AACjF,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,aAAa,EAAE;IAAE,aAAa,EAAE,cAAc,CAAA;CAAE,CAAC,CAAC;AAEhG,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAChF;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,YAAiB,GACzB,uBAAuB,GAAG,SAAS,CAUrC;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,wFAAwF;IACxF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,gBAAqB,GAC7B,uBAAuB,EAAE,CAI3B"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,iFAAiF;AACjF,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,aAAa,EAAE;IAAE,aAAa,EAAE,cAAc,CAAA;CAAE,CAAC,CAAC;AAEhG,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAChF;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,YAAiB,GACzB,uBAAuB,GAAG,SAAS,CAUrC;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,wFAAwF;IACxF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,gBAAqB,GAC7B,uBAAuB,EAAE,CAI3B"}

package/dist/usage.js

@@ -1,9 +1,10 @@
-// Story 025 / Group 3 (R3.1, R3.2) — the optional, default-OFF UNSTABLE `usage_update`
-// mapping. `usage_update` exists ONLY in the @agentclientprotocol/sdk 0.22.1 schema and is
+// Story 025 / Group 3 (R3.1, R3.2) — the optional UNSTABLE `usage_update` mapping.
+// `usage_update` exists ONLY in the @agentclientprotocol/sdk 0.22.1 schema and is
 // best-effort per §1; it maps the JSONL message-event `usage.{input,output}_tokens` into the
-// SDK's { sessionUpdate:"usage_update", size, used } shape. The feature defaults OFF and stays
-// OFF in production until the live-Zed acceptance probe (Task 3.3, R8) confirms the user's Zed
-// tolerates it. A rejected emission is suppressed by the pump's per-session latch (Task 5.1).
+// SDK's { sessionUpdate:"usage_update", size, used } shape. Story 042 FLIPPED the default to ON
+// (story 039 confirmed the user's Zed ACCEPTS+RENDERS it by code); only the explicit opt-out
+// USAGE_UPDATE=0/false disables it (see usage-env.ts). A rejected emission is still suppressed by
+// the pump's per-session reject latch (Task 5.1, R8).
 //
 // Kept a self-contained module (cf. diff-source.ts) imported by the acp-agent pump; it does
 // NOT go through lib.ts (the frozen upstream export surface).
@@ -21,6 +22,9 @@
  *   • R3.1 — the optional `cost` field is INTENTIONALLY OMITTED and must NEVER be fabricated:
  *     the JSONL usage block carries only token counts, and `cost` is optional in the Zed v1 struct,
  *     so omitting it is contract-correct (an invented cost would violate §1 "never fabricate").
+ *     Story 059 EVIDENCE (2026-06-28): an audit of 5169 local transcripts found 0 carrying
+ *     `total_cost_usd` as a JSON key — it lives only in the SDK `result` envelope (`claude -p`), never
+ *     in the interactive PTY+tail JSONL mapped here (the 68 substring hits were all conversation text).
  */
 export function toUsageUpdate(message, options = {}) {
     const input = message.usage?.input_tokens;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Run the official Claude Code TUI in Zed's agent panel on your Claude Pro/Max subscription — an ACP-over-PTY bridge created for Anthropic's billing split (paused June 15; see README).",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -60,20 +60,20 @@
   "author": "lucascouts",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.28.1",
-    "@anthropic-ai/claude-agent-sdk": "0.3.183",
+    "@agentclientprotocol/sdk": "1.0.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.191",
     "node-pty": "1.1.0",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.105.0",
+    "@anthropic-ai/sdk": "0.106.0",
     "@eslint/js": "10.0.1",
-    "@types/node": "26.0.0",
-    "@typescript-eslint/eslint-plugin": "8.61.1",
-    "@typescript-eslint/parser": "8.61.1",
+    "@types/node": "26.0.1",
+    "@typescript-eslint/eslint-plugin": "8.62.0",
+    "@typescript-eslint/parser": "8.62.0",
     "eslint": "10.5.0",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.6.0",
+    "globals": "17.7.0",
     "prettier": "3.8.4",
     "ts-node": "10.9.2",
     "typescript": "6.0.3"