@lucascouts/claude-agent-tui 0.1.0

package/dist/subagent-source.d.ts

@@ -0,0 +1,63 @@
+import type { SessionMessage } from "./engine-watcher.js";
+/**
+ * Injectable seam matching the SDK `listSubagents` signature: returns the agentIds spawned in this
+ * session. Async. Defaults to {@link defaultListSubagents}.
+ */
+export type ListSubagents = (sessionId: string, opts?: {
+    dir?: string;
+}) => Promise<string[]>;
+/**
+ * Injectable seam matching the SDK `getSubagentMessages` signature: returns one agent's sidechain
+ * messages in the reduced {@link SessionMessage} shape. Async. Defaults to
+ * {@link defaultGetSubagentMessages}.
+ */
+export type GetSubagentMessages = (sessionId: string, agentId: string, opts?: {
+    dir?: string;
+}) => Promise<SessionMessage[]>;
+/**
+ * Default {@link ListSubagents}: the SDK's pure `listSubagents`. Imported lazily (dynamic import) so
+ * the module never force-loads the SDK at eval time. Mirrors linearize.ts `defaultGetMessages`.
+ */
+export declare const defaultListSubagents: ListSubagents;
+/**
+ * Default {@link GetSubagentMessages}: the SDK's pure `getSubagentMessages`. Imported lazily (dynamic
+ * import) so the module never force-loads the SDK at eval time. Mirrors linearize.ts
+ * `defaultGetMessages`.
+ */
+export declare const defaultGetSubagentMessages: GetSubagentMessages;
+/**
+ * True when ANY message in `mainChain` carries a `Task`/`Agent` `tool_use` block — the only signal
+ * that a sidechain may exist (and thus the only justification for paying the `listSubagents` probe).
+ * Scans each message's `message.content` array for a block with `type === "tool_use"` whose `name`
+ * is `"Task"` or `"Agent"`. Tolerant of the reduced shape: missing/odd `content` is simply skipped.
+ * Story 044 exports it for the watcher/pump arm decision (reuse over re-implementation).
+ */
+export declare function hasSubagentSpawn(mainChain: SessionMessage[]): boolean;
+/**
+ * True iff at least one `Task`/`Agent` `tool_use` id in `mainChain` has NO matching `tool_result`
+ * block (`tool_use_id === id`) anywhere in the same chain; false when every spawn id is closed or
+ * no spawn exists. Story 044 / R2.2 — the pump's teardown gate: the sub-agent watcher stays armed
+ * only while a spawn is open. Single tolerant pass in the {@link hasSubagentSpawn} shape-reading
+ * style (skip non-object rows/messages/non-array content); `tool_result` blocks are read off ANY
+ * row type, mirroring the end-of-turn detector's `closedToolUseIds`.
+ */
+export declare function spawnIdsOpen(mainChain: SessionMessage[]): boolean;
+/**
+ * Source the merged subagent (sidechain) rows for a session, GUARDED by a main-chain `Task`/`Agent`
+ * `tool_use` probe (R1.2, R5.2).
+ *
+ * - If the main chain carries no `Task`/`Agent` `tool_use`, return `[]` WITHOUT calling
+ *   `listSubagents` — the R5.2 cheap path (no disk probe on the common no-subagent turn).
+ * - Otherwise call `listSubagents(sessionId, { dir })` for the agentIds, then
+ *   `getSubagentMessages(sessionId, agentId, { dir })` for each, and return the concatenation of all
+ *   rows in agentId order.
+ *
+ * Both readers are injected via `opts` (the lazy defaults are {@link defaultListSubagents} /
+ * {@link defaultGetSubagentMessages}); the deterministic unit tests pass stubs/spies.
+ */
+export declare function sourceSubagentRows(sessionId: string, mainChain: SessionMessage[], opts: {
+    dir?: string;
+    listSubagents: ListSubagents;
+    getSubagentMessages: GetSubagentMessages;
+}): Promise<SessionMessage[]>;
+//# sourceMappingURL=subagent-source.d.ts.map

package/dist/subagent-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-source.d.ts","sourceRoot":"","sources":["../src/subagent-source.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAK1D;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAE9F;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACpB,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAGlC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,mBAGxC,CAAC;AAOF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAmBrE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CA2BjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,cAAc,EAAE,EAC3B,IAAI,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAC;IAAC,mBAAmB,EAAE,mBAAmB,CAAA;CAAE,GAC7F,OAAO,CAAC,cAAc,EAAE,CAAC,CAa3B"}

package/dist/subagent-source.js

@@ -0,0 +1,132 @@
+// === Story 041 / §sidechain LIVE: guarded subagent-row sourcing (task 1.1) ====================
+//
+// Renders nested subagents (the `Task`/`Agent` tool spawns a sidechain conversation) at the LIVE
+// read path. The SDK exposes two pure, billing-free readers for that sidechain:
+//   - `listSubagents(sessionId, { dir })`        → the agentIds spawned in this session
+//   - `getSubagentMessages(sessionId, id, { dir })` → that agent's reduced-shape SessionMessage[]
+//
+// R5.2 CHEAP PATH: `listSubagents` touches disk (it scans the session's subagent transcripts). When
+// the main chain carries NO `Task`/`Agent` `tool_use` block there can be no sidechain, so we MUST
+// skip `listSubagents` entirely and return `[]` — never pay the probe for the common no-subagent
+// turn. This guard is the contract pinned by the unit test (a spy asserts 0 invocations).
+//
+// Both readers are LAZY-imported defaults (dynamic import at call time, mirroring linearize.ts
+// `defaultGetMessages`) so this module — and the deterministic unit tests, which always inject
+// stubs — never force-load the SDK at module-eval time. The two seams are fully injectable.
+/** The `tool_use` block `name`s whose presence in the main chain proves a sidechain may exist. */
+const SUBAGENT_TOOL_NAMES = new Set(["Task", "Agent"]);
+/**
+ * Default {@link ListSubagents}: the SDK's pure `listSubagents`. Imported lazily (dynamic import) so
+ * the module never force-loads the SDK at eval time. Mirrors linearize.ts `defaultGetMessages`.
+ */
+export const defaultListSubagents = async (sessionId, opts) => {
+    const sdk = await import("@anthropic-ai/claude-agent-sdk");
+    return sdk.listSubagents(sessionId, opts);
+};
+/**
+ * Default {@link GetSubagentMessages}: the SDK's pure `getSubagentMessages`. Imported lazily (dynamic
+ * import) so the module never force-loads the SDK at eval time. Mirrors linearize.ts
+ * `defaultGetMessages`.
+ */
+export const defaultGetSubagentMessages = async (sessionId, agentId, opts) => {
+    const sdk = await import("@anthropic-ai/claude-agent-sdk");
+    return sdk.getSubagentMessages(sessionId, agentId, opts);
+};
+/** Narrowing helper: a non-null plain object (so we can read string-keyed props safely). */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * True when ANY message in `mainChain` carries a `Task`/`Agent` `tool_use` block — the only signal
+ * that a sidechain may exist (and thus the only justification for paying the `listSubagents` probe).
+ * Scans each message's `message.content` array for a block with `type === "tool_use"` whose `name`
+ * is `"Task"` or `"Agent"`. Tolerant of the reduced shape: missing/odd `content` is simply skipped.
+ * Story 044 exports it for the watcher/pump arm decision (reuse over re-implementation).
+ */
+export function hasSubagentSpawn(mainChain) {
+    for (const msg of mainChain) {
+        if (!isObject(msg))
+            continue;
+        const inner = msg.message;
+        if (!isObject(inner))
+            continue;
+        const content = inner.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (isObject(block) &&
+                block.type === "tool_use" &&
+                typeof block.name === "string" &&
+                SUBAGENT_TOOL_NAMES.has(block.name)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * True iff at least one `Task`/`Agent` `tool_use` id in `mainChain` has NO matching `tool_result`
+ * block (`tool_use_id === id`) anywhere in the same chain; false when every spawn id is closed or
+ * no spawn exists. Story 044 / R2.2 — the pump's teardown gate: the sub-agent watcher stays armed
+ * only while a spawn is open. Single tolerant pass in the {@link hasSubagentSpawn} shape-reading
+ * style (skip non-object rows/messages/non-array content); `tool_result` blocks are read off ANY
+ * row type, mirroring the end-of-turn detector's `closedToolUseIds`.
+ */
+export function spawnIdsOpen(mainChain) {
+    const spawnIds = new Set();
+    const closedIds = new Set();
+    for (const msg of mainChain) {
+        if (!isObject(msg))
+            continue;
+        const inner = msg.message;
+        if (!isObject(inner))
+            continue;
+        const content = inner.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (!isObject(block))
+                continue;
+            if (block.type === "tool_use" &&
+                typeof block.id === "string" &&
+                typeof block.name === "string" &&
+                SUBAGENT_TOOL_NAMES.has(block.name)) {
+                spawnIds.add(block.id);
+            }
+            else if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+                closedIds.add(block.tool_use_id);
+            }
+        }
+    }
+    for (const id of spawnIds) {
+        if (!closedIds.has(id))
+            return true;
+    }
+    return false;
+}
+/**
+ * Source the merged subagent (sidechain) rows for a session, GUARDED by a main-chain `Task`/`Agent`
+ * `tool_use` probe (R1.2, R5.2).
+ *
+ * - If the main chain carries no `Task`/`Agent` `tool_use`, return `[]` WITHOUT calling
+ *   `listSubagents` — the R5.2 cheap path (no disk probe on the common no-subagent turn).
+ * - Otherwise call `listSubagents(sessionId, { dir })` for the agentIds, then
+ *   `getSubagentMessages(sessionId, agentId, { dir })` for each, and return the concatenation of all
+ *   rows in agentId order.
+ *
+ * Both readers are injected via `opts` (the lazy defaults are {@link defaultListSubagents} /
+ * {@link defaultGetSubagentMessages}); the deterministic unit tests pass stubs/spies.
+ */
+export async function sourceSubagentRows(sessionId, mainChain, opts) {
+    // R5.2 cheap path: no main-chain Task/Agent → no sidechain possible → skip the disk probe.
+    if (!hasSubagentSpawn(mainChain))
+        return [];
+    const { dir, listSubagents, getSubagentMessages } = opts;
+    const agentIds = await listSubagents(sessionId, { dir });
+    const rows = [];
+    for (const agentId of agentIds) {
+        const agentRows = await getSubagentMessages(sessionId, agentId, { dir });
+        rows.push(...agentRows);
+    }
+    return rows;
+}

package/dist/subagent-watcher.d.ts

@@ -0,0 +1,40 @@
+import type { SessionMessage } from "./engine-watcher.js";
+import { type ListSubagents, type GetSubagentMessages } from "./subagent-source.js";
+/** Default poll interval (ms) between sub-agent reader probes. */
+export declare const SUBAGENT_POLL_MS = 1000;
+export interface SubagentWatcherOptions {
+    sessionId: string;
+    /** session.cwd — passed to the readers as `{ dir }`. */
+    dir?: string;
+    /** Latest main chain (for the hasSubagentSpawn guard); refreshed by the pump via update(). */
+    mainChain: SessionMessage[];
+    listSubagents: ListSubagents;
+    getSubagentMessages: GetSubagentMessages;
+    /** Fired once per poll that observed >=1 NEW sub-agent row (new uuid). Never on an empty/no-change poll. */
+    onActivity: () => void | Promise<void>;
+    /** Injected for tests; defaults to a setTimeout/clearTimeout-backed one-shot scheduler. */
+    schedule?: (fn: () => void, ms: number) => () => void;
+    /** Poll interval (ms); default {@link SUBAGENT_POLL_MS}. */
+    pollMs?: number;
+}
+export interface SubagentWatcher {
+    /** Refresh the cached main chain so the spawn guard tracks the current turn. */
+    update(mainChain: SessionMessage[]): void;
+    /** Stop the poll, drop the seen-uuid set; idempotent. */
+    stop(): void;
+}
+/**
+ * Create a sub-agent activity watcher: poll the story-041 readers every `pollMs` while armed, fire
+ * `onActivity` only on observed progress (a new-uuid row), stop cleanly.
+ *
+ * SCHEDULING: `schedule` is ONE-SHOT — the same `DetectorSchedule` semantics as end-of-turn.ts
+ * (schedule(fn, ms) fires fn once after ms, returns a cancel) — and the watcher CHAINS one-shots:
+ * the first tick is armed at construction (`pollMs` from now); after each async poll body completes
+ * the next tick is re-armed, unless stopped. Why one-shot chaining instead of setInterval:
+ *   (a) one shared semantics with the rest of the fork's timer seams, so the SAME fake clock
+ *       drives detector + watcher in tests;
+ *   (b) re-arming AFTER the poll completes prevents overlapping polls when a read outlasts the
+ *       interval (setInterval would overlap).
+ */
+export declare function createSubagentWatcher(opts: SubagentWatcherOptions): SubagentWatcher;
+//# sourceMappingURL=subagent-watcher.d.ts.map

package/dist/subagent-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-watcher.d.ts","sourceRoot":"","sources":["../src/subagent-watcher.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAE9B,kEAAkE;AAClE,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,aAAa,EAAE,aAAa,CAAC;IAC7B,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,4GAA4G;IAC5G,UAAU,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,IAAI,CAAC;IACtD,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,MAAM,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IAC1C,yDAAyD;IACzD,IAAI,IAAI,IAAI,CAAC;CACd;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAwEnF"}

package/dist/subagent-watcher.js

@@ -0,0 +1,108 @@
+// === Story 044 / Option B: poll-based sub-agent activity watcher (task 3.2) ======================
+//
+// While a `Task`/`Agent` spawn is in flight on the main chain, the turn's real progress happens on
+// the SIDECHAIN (`subagents/*.jsonl`) — which the story-023 tail does not observe, so a long
+// sub-agent looks like a stall and trips the turn watchdog (the story-041 R4.2 live gap). This
+// watcher feeds that missing liveness: it POLLS the story-041 SDK readers (`listSubagents` +
+// `getSubagentMessages`, via `sourceSubagentRows`) instead of tailing the raw `subagents/*.jsonl`
+// files. Design rationale (Option B as planned):
+//   - reuses the 041 data path verbatim — same readers, same reduced shape, same R5.2 guard;
+//   - dissolves the class-028 late-discovery gap: before the sidechain materializes the readers
+//     simply return `[]`, so polling is harmless and needs no fs.watch arming dance (R2.1);
+//   - keeps engine-watcher.ts frozen — no second tail, no new fs seam.
+//
+// Liveness is PROGRESS-GATED (R5.2): `onActivity` fires at most once per poll, and only when the
+// poll observed at least one NEW row (a `uuid` not seen before). An empty poll, a no-change poll,
+// or a reader error fires NOTHING — a hung sub-agent must still let the stall watchdog trip.
+import { hasSubagentSpawn, sourceSubagentRows, } from "./subagent-source.js";
+/** Default poll interval (ms) between sub-agent reader probes. */
+export const SUBAGENT_POLL_MS = 1000;
+/**
+ * Default one-shot scheduler: `setTimeout`/`clearTimeout` with `.unref?.()` so an armed watcher
+ * never keeps the process alive on its own (mirrors `defaultSchedule` in end-of-turn.ts).
+ */
+const defaultSchedule = (fn, ms) => {
+    const handle = setTimeout(fn, ms);
+    handle.unref?.();
+    return () => clearTimeout(handle);
+};
+/**
+ * Create a sub-agent activity watcher: poll the story-041 readers every `pollMs` while armed, fire
+ * `onActivity` only on observed progress (a new-uuid row), stop cleanly.
+ *
+ * SCHEDULING: `schedule` is ONE-SHOT — the same `DetectorSchedule` semantics as end-of-turn.ts
+ * (schedule(fn, ms) fires fn once after ms, returns a cancel) — and the watcher CHAINS one-shots:
+ * the first tick is armed at construction (`pollMs` from now); after each async poll body completes
+ * the next tick is re-armed, unless stopped. Why one-shot chaining instead of setInterval:
+ *   (a) one shared semantics with the rest of the fork's timer seams, so the SAME fake clock
+ *       drives detector + watcher in tests;
+ *   (b) re-arming AFTER the poll completes prevents overlapping polls when a read outlasts the
+ *       interval (setInterval would overlap).
+ */
+export function createSubagentWatcher(opts) {
+    const { sessionId, dir, listSubagents, getSubagentMessages, onActivity, schedule = defaultSchedule, pollMs = SUBAGENT_POLL_MS, } = opts;
+    let mainChain = opts.mainChain;
+    const seen = new Set();
+    let stopped = false;
+    /** Cancel for the currently pending one-shot, if any (cleared when it fires). */
+    let cancelPending;
+    /** Arm the next one-shot tick — never after stop(). */
+    const arm = () => {
+        if (stopped)
+            return;
+        cancelPending = schedule(() => {
+            cancelPending = undefined;
+            void poll();
+        }, pollMs);
+    };
+    /** One poll body; always re-arms afterwards unless stopped (errors included — next poll retries). */
+    const poll = async () => {
+        try {
+            // R5.2 cheap path: no main-chain Task/Agent spawn → no sidechain possible → skip the
+            // readers entirely (zero sub-agent IO on the common no-subagent turn).
+            if (hasSubagentSpawn(mainChain)) {
+                const rows = await sourceSubagentRows(sessionId, mainChain, {
+                    dir,
+                    listSubagents,
+                    getSubagentMessages,
+                });
+                // Progress = rows with a NEW non-empty-string uuid. A uuid-less row is skipped — it never
+                // counts as progress and never crashes the poll.
+                const fresh = [];
+                for (const row of rows) {
+                    const uuid = row.uuid;
+                    if (typeof uuid !== "string" || uuid === "")
+                        continue;
+                    if (!seen.has(uuid))
+                        fresh.push(uuid);
+                }
+                if (fresh.length > 0 && !stopped) {
+                    for (const uuid of fresh)
+                        seen.add(uuid);
+                    await onActivity();
+                }
+            }
+        }
+        catch {
+            // A reader rejection (transient FS/SDK error) must not kill the chain: swallow and re-arm —
+            // the NEXT poll retries. Errors never fire onActivity (no liveness from failure).
+        }
+        if (!stopped)
+            arm();
+    };
+    // Arm the first tick at construction: the first probe lands `pollMs` from now.
+    arm();
+    return {
+        update(next) {
+            mainChain = next;
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            cancelPending?.();
+            cancelPending = undefined;
+            seen.clear();
+        },
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,119 @@
+import { PlanEntry, ToolCallContent, ToolCallLocation, ToolKind } from "@agentclientprotocol/sdk";
+import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import { TaskCreateInput, TaskCreateOutput, TaskUpdateInput } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
+import { ToolResultBlockParam, WebSearchToolResultBlockParam } from "@anthropic-ai/sdk/resources";
+import { BetaBashCodeExecutionToolResultBlockParam, BetaCodeExecutionToolResultBlockParam, BetaRequestMCPToolResultBlockParam, BetaTextEditorCodeExecutionToolResultBlockParam, BetaToolResultBlockParam, BetaToolSearchToolResultBlockParam, BetaWebFetchToolResultBlockParam, BetaWebSearchToolResultBlockParam } from "@anthropic-ai/sdk/resources/beta.mjs";
+import { Logger } from "./acp-agent.js";
+interface ToolInfo {
+    title: string;
+    kind: ToolKind;
+    content: ToolCallContent[];
+    locations?: ToolCallLocation[];
+}
+interface ToolUpdate {
+    title?: string;
+    content?: ToolCallContent[];
+    locations?: ToolCallLocation[];
+    _meta?: {
+        terminal_info?: {
+            terminal_id: string;
+        };
+        terminal_output?: {
+            terminal_id: string;
+            data: string;
+        };
+        terminal_exit?: {
+            terminal_id: string;
+            exit_code: number;
+            signal: string | null;
+        };
+    };
+}
+/**
+ * Convert an absolute file path to a project-relative path for display.
+ * Returns the original path if it's outside the project directory or if no cwd is provided.
+ */
+export declare function toDisplayPath(filePath: string, cwd?: string): string;
+/**
+ * Story 025 / Task 2.2 (R2.1, R2.3) — derive the ACP `toolCallId` from a JSONL
+ * `tool_use.id`. Pure, total and side-effect-free, and STABLE across the live and
+ * replay paths so a loaded thread re-derives identical ids.
+ *
+ * Default (`namespaced` omitted/false): returns the raw `tool_use.id` VERBATIM — the
+ * §7 reuse contract stories 017-021 assume, and the behaviour the live-Zed probe
+ * (Task 2.1, FORK.md) confirms or overturns. When the probe shows the user's Zed
+ * requires per-session uniqueness, callers pass `{ namespaced: true }` to get a
+ * deterministic `${sessionId}:${toolUseId}` id — identical for the same
+ * (toolUseId, sessionId) and distinct across sessions. The raw id stays embedded so
+ * the original `tool_use.id` remains recoverable.
+ */
+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;
+export type ClaudePlanEntry = {
+    content: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm: string;
+};
+export declare function planEntries(input: {
+    todos: ClaudePlanEntry[];
+} | undefined): PlanEntry[];
+/**
+ * Per-session task list accumulated from Task* tool calls (TaskCreate /
+ * TaskUpdate). The headless/SDK session emits these as incremental tool
+ * calls keyed by task ID, replacing the snapshot-style TodoWrite tool.
+ * Iteration order is insertion order (Map semantics), matching the order
+ * tasks are created.
+ */
+export type TaskEntry = {
+    subject: string;
+    status: "pending" | "in_progress" | "completed";
+    activeForm?: string;
+    description?: string;
+};
+export type TaskState = Map<string, TaskEntry>;
+/**
+ * Best-effort parse of a TaskCreate tool_result content into the structured
+ * TaskCreateOutput. The SDK delivers tool outputs either as a string or as
+ * an array of TextBlockParam-like blocks containing JSON text; try both.
+ */
+export declare function parseTaskCreateOutput(content: unknown): TaskCreateOutput | undefined;
+export declare function applyTaskCreate(state: TaskState, input: TaskCreateInput | undefined, output: TaskCreateOutput | undefined): void;
+export declare function applyTaskUpdate(state: TaskState, input: TaskUpdateInput | undefined): void;
+export declare function taskStateToPlanEntries(state: TaskState): PlanEntry[];
+export declare function markdownEscape(text: string): string;
+/**
+ * Builds diff ToolUpdate content from the structured toolResponse provided by
+ * the PostToolUse hook for diff-producing tools (Edit, Write). Unlike parsing
+ * the plain unified diff string, this uses the pre-parsed structuredPatch
+ * which supports multiple replacement sites (replaceAll) and always includes
+ * context lines for better readability.
+ */
+export declare function toolUpdateFromDiffToolResponse(toolResponse: unknown): {
+    content?: ToolCallContent[];
+    locations?: ToolCallLocation[];
+};
+export declare const registerHookCallback: (toolUseID: string, { onPostToolUseHook, }: {
+    onPostToolUseHook?: (toolUseID: string, toolInput: unknown, toolResponse: unknown) => Promise<void>;
+}) => void;
+export declare const createPostToolUseHook: (logger?: Logger, options?: {
+    onEnterPlanMode?: () => Promise<void>;
+}) => HookCallback;
+/**
+ * Hook callback for `TaskCreated` / `TaskCompleted` events. The SDK fires
+ * these for both user-facing TaskCreate tool calls and subagent task
+ * creation, giving us `task_id` + `task_subject` without having to parse
+ * tool_result payloads.
+ *
+ * Populating `taskState` from the hook means a later `TaskUpdate` (which
+ * typically only carries `taskId` + `status`) finds an existing entry with
+ * a real subject, instead of synthesizing a placeholder with empty content.
+ */
+export declare const createTaskHook: (options: {
+    taskState: TaskState;
+    onChange?: () => Promise<void>;
+}) => HookCallback;
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

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