@letrquan/book 0.2.0

package/dist/sdk.d.ts

@@ -0,0 +1,4574 @@
+import { ChildProcess } from 'child_process';
+import { z } from 'zod';
+import { ChildProcess as ChildProcess$1 } from 'node:child_process';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+
+/**
+ * Time that measures, separated from time that labels.
+ *
+ * `Date.now()` is the settable wall clock. NTP steps it, a VM resumes with it
+ * wrong and then corrects, an operator fixes a drifted host, DST changes the
+ * offset. None of that matters over a five-minute chat, and all of it is
+ * near-certain over the multi-day runs Book is built for — which is why every
+ * *duration* decision here reads a monotonic source instead.
+ *
+ * What the two are for:
+ *
+ * - **`monotonicNowMs()`** — "how long has this been going?" Retry budgets,
+ *   flush deadlines, kill timeouts, elapsed run time. It only ever moves
+ *   forward, at a rate nothing can adjust, and its origin is arbitrary, so a
+ *   reading is meaningless on its own and comparable only to another reading
+ *   *from the same process*.
+ * - **`wallNowMs()`** — "when did this happen?" Anything written to a file, put
+ *   on screen, or compared against a stamp another process wrote. Still
+ *   `Date.now()`; the name exists so the choice is visible at the call site
+ *   rather than implied by its absence.
+ *
+ * **The origin is per-process, and that is the whole limit.** Two processes'
+ * monotonic clocks share no zero, so a monotonic reading cannot be persisted,
+ * sent, or compared across a process boundary. Cross-process liveness — the
+ * background-shell heartbeat, the run-status file `book status` reads, the
+ * retention sweeps — therefore stays on the wall clock by necessity, not by
+ * oversight. A backwards step there reads as "unexpectedly fresh" and a forward
+ * step can declare a live run stale; fixing that needs a sequence counter in the
+ * file, not a better clock. See `MILESTONES.md`.
+ *
+ * Injected rather than imported directly at the decision sites, per the
+ * module-level-mutable-state rule: a caller that needs to control time passes a
+ * `Clock`, and tests do exactly that instead of reaching for fake timers.
+ *
+ * One trap worth knowing when writing those tests: vitest's default
+ * `vi.useFakeTimers()` fakes `performance` too, so the monotonic clock stops
+ * with the fake wall clock and a test cannot tell the two apart. Use
+ * `vi.useFakeTimers({ toFake: ['Date'] })` to move the wall clock while the
+ * monotonic one keeps its own time — that divergence is the thing under test.
+ */
+/** A monotonic reading, in milliseconds. Only comparable within one process. */
+type MonotonicMs = number;
+interface Clock {
+    /** Milliseconds since an arbitrary fixed origin. Never goes backwards. */
+    monotonicNowMs(): MonotonicMs;
+    /** Milliseconds since the Unix epoch. Settable; use only for labels. */
+    wallNowMs(): number;
+}
+
+declare const providerModelSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    contextWindow: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    /** Whether this model accepts image input. Unknown models remain optimistic. */
+    vision: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Entered by hand rather than returned by the endpoint's model-list API.
+     * Refreshing the catalog keeps these, since they exist precisely because
+     * discovery does not list them.
+     */
+    manual: z.ZodOptional<z.ZodBoolean>;
+    /** Mutation-tool preference for this model; defaults to a family-level prior. */
+    editFormat: z.ZodOptional<z.ZodEnum<["patch", "replace", "whole"]>>;
+    effort: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+        default: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>>;
+        levels: z.ZodOptional<z.ZodArray<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+    }, {
+        default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+    }>]>>;
+}, "strip", z.ZodTypeAny, {
+    effort?: false | {
+        default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+    } | undefined;
+    label?: string | undefined;
+    contextWindow?: number | undefined;
+    maxOutputTokens?: number | undefined;
+    vision?: boolean | undefined;
+    manual?: boolean | undefined;
+    editFormat?: "patch" | "replace" | "whole" | undefined;
+}, {
+    effort?: false | {
+        default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+        levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+    } | undefined;
+    label?: string | undefined;
+    contextWindow?: number | undefined;
+    maxOutputTokens?: number | undefined;
+    vision?: boolean | undefined;
+    manual?: boolean | undefined;
+    editFormat?: "patch" | "replace" | "whole" | undefined;
+}>;
+declare const toolDiscoverySettingsSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<["auto", "eager", "deferred"]>>;
+    eagerToolCount: z.ZodDefault<z.ZodNumber>;
+    schemaTokenBudget: z.ZodDefault<z.ZodNumber>;
+    maxLoadedTools: z.ZodDefault<z.ZodNumber>;
+    searchLimit: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    mode: "auto" | "eager" | "deferred";
+    eagerToolCount: number;
+    schemaTokenBudget: number;
+    maxLoadedTools: number;
+    searchLimit: number;
+}, {
+    mode?: "auto" | "eager" | "deferred" | undefined;
+    eagerToolCount?: number | undefined;
+    schemaTokenBudget?: number | undefined;
+    maxLoadedTools?: number | undefined;
+    searchLimit?: number | undefined;
+}>;
+type ToolDiscoverySettings = z.infer<typeof toolDiscoverySettingsSchema>;
+declare const skillActivationSchema: z.ZodEnum<["auto", "name-only", "manual", "off"]>;
+type SkillActivation = z.infer<typeof skillActivationSchema>;
+declare const skillExecutionSchema: z.ZodEnum<["inherit", "ask", "deny"]>;
+type SkillExecution = z.infer<typeof skillExecutionSchema>;
+declare const skillSettingsSchema: z.ZodObject<{
+    /** Emergency switch that removes skill prompt and runtime effects without deleting packages. */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Per-skill visibility overrides keyed by the skill's declared name. */
+    overrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["auto", "name-only", "manual", "off"]>>>;
+    /** Per-skill activation consent policy. Tool calls still use the normal permission system. */
+    execution: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["inherit", "ask", "deny"]>>>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    overrides: Record<string, "manual" | "off" | "auto" | "name-only">;
+    execution: Record<string, "ask" | "deny" | "inherit">;
+}, {
+    enabled?: boolean | undefined;
+    overrides?: Record<string, "manual" | "off" | "auto" | "name-only"> | undefined;
+    execution?: Record<string, "ask" | "deny" | "inherit"> | undefined;
+}>;
+type SkillSettings = z.infer<typeof skillSettingsSchema>;
+type ProviderModelConfig = z.infer<typeof providerModelSchema>;
+/** The supported production strategy. */
+declare const compactStrategySchema: z.ZodLiteral<"summary">;
+type CompactStrategy = z.infer<typeof compactStrategySchema>;
+/**
+ * Full settings.json schema — all keys that book supports.
+ * New keys added in later milestones extend this schema.
+ */
+declare const bookSettingsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    /** Default strategy used to reduce historical conversation context. */
+    compactStrategy: z.ZodOptional<z.ZodLiteral<"summary">>;
+    /** Optional model used only to generate historical conversation checkpoints. */
+    compactModel: z.ZodOptional<z.ZodString>;
+    /** Max agent turns per user message. Omit for unlimited. */
+    maxTurns: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    effort: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>>;
+    /** TUI color theme: apple (default), dark, light, auto, a bundled palette, or a custom theme filename. */
+    theme: z.ZodOptional<z.ZodString>;
+    /**
+     * The shell the Bash tool spawns: `bash`, `pwsh`, `powershell`, `cmd`, `sh`,
+     * or an executable path. Honoured from the user-global layer, an explicit
+     * `--settings` document, or `BOOK_SHELL` only: a workspace file cannot pick
+     * the program every command is handed to.
+     */
+    shell: z.ZodOptional<z.ZodString>;
+    ui: z.ZodDefault<z.ZodObject<{
+        /** Show provider-native and embedded model reasoning in the interactive transcript. */
+        showThinking: z.ZodDefault<z.ZodBoolean>;
+        /** Play the full-screen fire sequence on a newly created interactive startup session. */
+        startupAnimation: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        showThinking: boolean;
+        startupAnimation: boolean;
+    }, {
+        showThinking?: boolean | undefined;
+        startupAnimation?: boolean | undefined;
+    }>>;
+    skills: z.ZodDefault<z.ZodObject<{
+        /** Emergency switch that removes skill prompt and runtime effects without deleting packages. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Per-skill visibility overrides keyed by the skill's declared name. */
+        overrides: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["auto", "name-only", "manual", "off"]>>>;
+        /** Per-skill activation consent policy. Tool calls still use the normal permission system. */
+        execution: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["inherit", "ask", "deny"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        overrides: Record<string, "manual" | "off" | "auto" | "name-only">;
+        execution: Record<string, "ask" | "deny" | "inherit">;
+    }, {
+        enabled?: boolean | undefined;
+        overrides?: Record<string, "manual" | "off" | "auto" | "name-only"> | undefined;
+        execution?: Record<string, "ask" | "deny" | "inherit"> | undefined;
+    }>>;
+    autoCompactEnabled: z.ZodOptional<z.ZodBoolean>;
+    /** Permission mode used by each host when no invocation-specific mode is supplied. */
+    defaultMode: z.ZodOptional<z.ZodEnum<["default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"]>>;
+    disableBypassPermissionsMode: z.ZodOptional<z.ZodBoolean>;
+    additionalDirectories: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    provider: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["openai", "anthropic"]>>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        models: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            contextWindow: z.ZodOptional<z.ZodNumber>;
+            maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+            /** Whether this model accepts image input. Unknown models remain optimistic. */
+            vision: z.ZodOptional<z.ZodBoolean>;
+            /**
+             * Entered by hand rather than returned by the endpoint's model-list API.
+             * Refreshing the catalog keeps these, since they exist precisely because
+             * discovery does not list them.
+             */
+            manual: z.ZodOptional<z.ZodBoolean>;
+            /** Mutation-tool preference for this model; defaults to a family-level prior. */
+            editFormat: z.ZodOptional<z.ZodEnum<["patch", "replace", "whole"]>>;
+            effort: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<false>, z.ZodObject<{
+                default: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>>;
+                levels: z.ZodOptional<z.ZodArray<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>, "many">>;
+            }, "strip", z.ZodTypeAny, {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            }, {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            }>]>>;
+        }, "strip", z.ZodTypeAny, {
+            effort?: false | {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            } | undefined;
+            label?: string | undefined;
+            contextWindow?: number | undefined;
+            maxOutputTokens?: number | undefined;
+            vision?: boolean | undefined;
+            manual?: boolean | undefined;
+            editFormat?: "patch" | "replace" | "whole" | undefined;
+        }, {
+            effort?: false | {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            } | undefined;
+            label?: string | undefined;
+            contextWindow?: number | undefined;
+            maxOutputTokens?: number | undefined;
+            vision?: boolean | undefined;
+            manual?: boolean | undefined;
+            editFormat?: "patch" | "replace" | "whole" | undefined;
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "openai" | "anthropic";
+        models: Record<string, {
+            effort?: false | {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            } | undefined;
+            label?: string | undefined;
+            contextWindow?: number | undefined;
+            maxOutputTokens?: number | undefined;
+            vision?: boolean | undefined;
+            manual?: boolean | undefined;
+            editFormat?: "patch" | "replace" | "whole" | undefined;
+        }>;
+        baseURL?: string | undefined;
+        baseUrl?: string | undefined;
+        apiKey?: string | undefined;
+    }, {
+        type?: "openai" | "anthropic" | undefined;
+        baseURL?: string | undefined;
+        baseUrl?: string | undefined;
+        apiKey?: string | undefined;
+        models?: Record<string, {
+            effort?: false | {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            } | undefined;
+            label?: string | undefined;
+            contextWindow?: number | undefined;
+            maxOutputTokens?: number | undefined;
+            vision?: boolean | undefined;
+            manual?: boolean | undefined;
+            editFormat?: "patch" | "replace" | "whole" | undefined;
+        }> | undefined;
+    }>>>;
+    permissions: z.ZodDefault<z.ZodObject<{
+        allow: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        ask: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        deny: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Decisions about `allow` rules the project layer declared. A project rule
+         * with no `approved` entry here never reaches the resolved allow list.
+         */
+        projectAllowRules: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["approved", "rejected"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        allow: string[];
+        ask: string[];
+        deny: string[];
+        projectAllowRules: Record<string, "approved" | "rejected">;
+    }, {
+        allow?: string[] | undefined;
+        ask?: string[] | undefined;
+        deny?: string[] | undefined;
+        projectAllowRules?: Record<string, "approved" | "rejected"> | undefined;
+    }>>;
+    sandbox: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        failIfUnavailable: z.ZodDefault<z.ZodBoolean>;
+        autoAllowBashIfSandboxed: z.ZodDefault<z.ZodBoolean>;
+        excludedCommands: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        allowUnsandboxedCommands: z.ZodDefault<z.ZodBoolean>;
+        filesystem: z.ZodDefault<z.ZodObject<{
+            allowWrite: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            denyWrite: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            denyRead: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            allowWrite: string[];
+            denyWrite: string[];
+            denyRead: string[];
+        }, {
+            allowWrite?: string[] | undefined;
+            denyWrite?: string[] | undefined;
+            denyRead?: string[] | undefined;
+        }>>;
+        network: z.ZodDefault<z.ZodObject<{
+            allowedDomains: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            deniedDomains: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            allowedDomains: string[];
+            deniedDomains: string[];
+        }, {
+            allowedDomains?: string[] | undefined;
+            deniedDomains?: string[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        failIfUnavailable: boolean;
+        autoAllowBashIfSandboxed: boolean;
+        excludedCommands: string[];
+        allowUnsandboxedCommands: boolean;
+        filesystem: {
+            allowWrite: string[];
+            denyWrite: string[];
+            denyRead: string[];
+        };
+        network: {
+            allowedDomains: string[];
+            deniedDomains: string[];
+        };
+    }, {
+        enabled?: boolean | undefined;
+        failIfUnavailable?: boolean | undefined;
+        autoAllowBashIfSandboxed?: boolean | undefined;
+        excludedCommands?: string[] | undefined;
+        allowUnsandboxedCommands?: boolean | undefined;
+        filesystem?: {
+            allowWrite?: string[] | undefined;
+            denyWrite?: string[] | undefined;
+            denyRead?: string[] | undefined;
+        } | undefined;
+        network?: {
+            allowedDomains?: string[] | undefined;
+            deniedDomains?: string[] | undefined;
+        } | undefined;
+    }>>;
+    hooks: z.ZodDefault<z.ZodObject<{
+        /**
+         * Decisions about hook entries the checked-in project layer declared. An
+         * entry whose fingerprint has no `approved` record here never reaches the
+         * resolved hooks.
+         */
+        projectEntries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["approved", "rejected"]>>>;
+        SessionStart: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        SessionEnd: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        UserPromptSubmit: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        PreToolUse: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        PostToolUse: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        Stop: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        PreCompact: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        PostCompact: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        SubagentStart: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        SubagentStop: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+        Notification: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            /** Tool(specifier) pattern to filter which events trigger this hook. */
+            matcher: z.ZodOptional<z.ZodString>;
+            /** Shell command to run (passed through system shell). */
+            command: z.ZodString;
+            /** Extra environment variables for this hook. */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }, {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        SessionStart: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        SessionEnd: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        UserPromptSubmit: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PreToolUse: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PostToolUse: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        Stop: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PreCompact: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PostCompact: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        SubagentStart: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        SubagentStop: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        Notification: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        projectEntries: Record<string, "approved" | "rejected">;
+    }, {
+        SessionStart?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        SessionEnd?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        UserPromptSubmit?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PreToolUse?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PostToolUse?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        Stop?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PreCompact?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PostCompact?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        SubagentStart?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        SubagentStop?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        Notification?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        projectEntries?: Record<string, "approved" | "rejected"> | undefined;
+    }>>;
+    retry: z.ZodDefault<z.ZodObject<{
+        maxAttempts: z.ZodDefault<z.ZodNumber>;
+        baseDelayMs: z.ZodDefault<z.ZodNumber>;
+        maxDelayMs: z.ZodDefault<z.ZodNumber>;
+        totalBudgetMs: z.ZodDefault<z.ZodNumber>;
+        requestTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        streamStallTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Stall ceiling while the model is thinking, which is a different regime.
+         *
+         * `streamStallTimeoutMs` is tuned for a chat: 20s of silence means something
+         * broke. But with adaptive thinking on — the default for every Opus and Sonnet
+         * model here, at `high` effort unless told otherwise — a long quiet stretch
+         * before the first token is the model working, not a fault. Applying the chat
+         * timeout to it cancels a healthy request and reports `stream_stall`.
+         */
+        thinkingStallTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        toolRetries: z.ZodDefault<z.ZodNumber>;
+        watchdog: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * How many times a turn may be re-sent after a transport fault that left the
+         * work intact — a stalled stream, a dropped socket.
+         *
+         * `maxAttempts` covers connection setup only; once a 200 response is streaming
+         * it is out of scope, so without this a single 20-second provider silence ended
+         * the run. Set to 0 to restore that behavior exactly.
+         */
+        streamReissueAttempts: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Separate allowance for continuing after the provider's output cap. A large
+         * generated file legitimately hits the cap on consecutive turns, and sharing
+         * the transport budget would leave nothing for a real socket drop afterwards.
+         */
+        outputCapContinuations: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxAttempts: number;
+        baseDelayMs: number;
+        maxDelayMs: number;
+        totalBudgetMs: number;
+        requestTimeoutMs: number;
+        streamStallTimeoutMs: number;
+        thinkingStallTimeoutMs: number;
+        toolRetries: number;
+        watchdog: boolean;
+        streamReissueAttempts: number;
+        outputCapContinuations: number;
+    }, {
+        maxAttempts?: number | undefined;
+        baseDelayMs?: number | undefined;
+        maxDelayMs?: number | undefined;
+        totalBudgetMs?: number | undefined;
+        requestTimeoutMs?: number | undefined;
+        streamStallTimeoutMs?: number | undefined;
+        thinkingStallTimeoutMs?: number | undefined;
+        toolRetries?: number | undefined;
+        watchdog?: boolean | undefined;
+        streamReissueAttempts?: number | undefined;
+        outputCapContinuations?: number | undefined;
+    }>>;
+    memory: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        autoSave: z.ZodDefault<z.ZodBoolean>;
+        requireApproval: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        autoSave: boolean;
+        requireApproval: boolean;
+    }, {
+        enabled?: boolean | undefined;
+        autoSave?: boolean | undefined;
+        requireApproval?: boolean | undefined;
+    }>>;
+    continuation: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Consecutive host-authored continuations before the run stops regardless. */
+        maxConsecutive: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Identical progress witnesses in a row before the run stops as no-progress.
+         * Minimum 1: a 0 here would fire on the first boundary, before any witness
+         * exists, and label a run that never got a chance to spin as spinning.
+         */
+        noProgressLimit: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Consecutive turns in which EVERY tool call was refused before the run stops.
+         *
+         * Enforced even when `enabled` is false, deliberately. The spin it catches
+         * predates continuation and needs no continuation to happen: a headless run in
+         * the default permission mode answers every prompt `deny`, so the model can
+         * re-issue a refused call forever while `toolCalls.length > 0` keeps the
+         * turn-end gate from ever firing. None of the existing anti-loop signals see it
+         * either — the repeated-failure breaker ignores anything that is not `error`,
+         * and `toolCallStats.failures` excludes `blocked` by construction.
+         *
+         * 0 disables the guard.
+         */
+        blockedToolTurnLimit: z.ZodDefault<z.ZodNumber>;
+        /** Turns between host-authored work-state messages; 0 disables them. */
+        planRefreshTurns: z.ZodDefault<z.ZodNumber>;
+        /** Wall-clock ceiling for one continued run; 0 means no ceiling. */
+        maxWallClockMs: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        maxConsecutive: number;
+        noProgressLimit: number;
+        blockedToolTurnLimit: number;
+        planRefreshTurns: number;
+        maxWallClockMs: number;
+    }, {
+        enabled?: boolean | undefined;
+        maxConsecutive?: number | undefined;
+        noProgressLimit?: number | undefined;
+        blockedToolTurnLimit?: number | undefined;
+        planRefreshTurns?: number | undefined;
+        maxWallClockMs?: number | undefined;
+    }>>;
+    agents: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<["adaptive", "manual", "off"]>>;
+        maxConcurrent: z.ZodDefault<z.ZodNumber>;
+        maxSpawned: z.ZodDefault<z.ZodNumber>;
+        maxDepth: z.ZodDefault<z.ZodLiteral<1>>;
+        persist: z.ZodDefault<z.ZodBoolean>;
+        includeUntrackedInSnapshot: z.ZodDefault<z.ZodBoolean>;
+        telemetry: z.ZodDefault<z.ZodBoolean>;
+        retentionDays: z.ZodDefault<z.ZodNumber>;
+        checks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>>;
+        /**
+         * Wall-clock ceiling for one `Check` run. The 120s default suits a focused
+         * suite; a full `npm test` on a large repository routinely exceeds it, and a
+         * check that always times out is worse than no check because the timeout was
+         * reported as a failing suite. Raise it per project rather than per invocation.
+         */
+        checkTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Simultaneous agent worktrees per repository; 0 disables the check.
+         *
+         * Nothing reclaims a worktree automatically outside the TUI, and the store's
+         * retention sweep runs once at startup with a 30-day default — so on a long
+         * unattended run the count only grows. Sized above `maxConcurrent` so ordinary
+         * fan-out is unaffected and only accumulation trips it.
+         */
+        maxWorktrees: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Re-drive agents that were interrupted by process death on the next start.
+         *
+         * A restart otherwise converts the whole pending backlog into terminal records
+         * nothing picks up, silently losing hours of child work on a wide fan-out. The
+         * re-drive is contained: explorers are read-only and patchers/validators run in
+         * their own worktree, so nothing reaches the parent workspace without the usual
+         * evidence gate. Only `process_exit` interruptions qualify — a user stop stays
+         * stopped.
+         */
+        resumeInterrupted: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Refuse a new worktree when free disk would fall below this; 0 disables.
+         * Worktrees share the filesystem with the workspace, so exhausting it breaks
+         * the root agent's own Edit and Bash, not just the child's.
+         */
+        minFreeDiskBytes: z.ZodDefault<z.ZodNumber>;
+        profiles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "xhigh", "max"]>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
+            color: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+            model?: string | undefined;
+            maxTurns?: number | undefined;
+            color?: string | undefined;
+        }, {
+            effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+            model?: string | undefined;
+            maxTurns?: number | undefined;
+            color?: string | undefined;
+        }>>>;
+        ui: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+        }, {
+            enabled?: boolean | undefined;
+        }>>;
+        routing: z.ZodDefault<z.ZodObject<{
+            inlineSearchBudget: z.ZodDefault<z.ZodNumber>;
+            exploreReminder: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            inlineSearchBudget: number;
+            exploreReminder: boolean;
+        }, {
+            inlineSearchBudget?: number | undefined;
+            exploreReminder?: boolean | undefined;
+        }>>;
+        forwardTextEvents: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "manual" | "adaptive" | "off";
+        maxConcurrent: number;
+        maxSpawned: number;
+        maxDepth: 1;
+        persist: boolean;
+        includeUntrackedInSnapshot: boolean;
+        telemetry: boolean;
+        retentionDays: number;
+        checks: Record<string, string | string[]>;
+        checkTimeoutMs: number;
+        maxWorktrees: number;
+        resumeInterrupted: boolean;
+        minFreeDiskBytes: number;
+        profiles: Record<string, {
+            effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+            model?: string | undefined;
+            maxTurns?: number | undefined;
+            color?: string | undefined;
+        }>;
+        ui: {
+            enabled: boolean;
+        };
+        routing: {
+            inlineSearchBudget: number;
+            exploreReminder: boolean;
+        };
+        forwardTextEvents: boolean;
+    }, {
+        mode?: "manual" | "adaptive" | "off" | undefined;
+        maxConcurrent?: number | undefined;
+        maxSpawned?: number | undefined;
+        maxDepth?: 1 | undefined;
+        persist?: boolean | undefined;
+        includeUntrackedInSnapshot?: boolean | undefined;
+        telemetry?: boolean | undefined;
+        retentionDays?: number | undefined;
+        checks?: Record<string, string | string[]> | undefined;
+        checkTimeoutMs?: number | undefined;
+        maxWorktrees?: number | undefined;
+        resumeInterrupted?: boolean | undefined;
+        minFreeDiskBytes?: number | undefined;
+        profiles?: Record<string, {
+            effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+            model?: string | undefined;
+            maxTurns?: number | undefined;
+            color?: string | undefined;
+        }> | undefined;
+        ui?: {
+            enabled?: boolean | undefined;
+        } | undefined;
+        routing?: {
+            inlineSearchBudget?: number | undefined;
+            exploreReminder?: boolean | undefined;
+        } | undefined;
+        forwardTextEvents?: boolean | undefined;
+    }>>;
+    toolDiscovery: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<["auto", "eager", "deferred"]>>;
+        eagerToolCount: z.ZodDefault<z.ZodNumber>;
+        schemaTokenBudget: z.ZodDefault<z.ZodNumber>;
+        maxLoadedTools: z.ZodDefault<z.ZodNumber>;
+        searchLimit: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "auto" | "eager" | "deferred";
+        eagerToolCount: number;
+        schemaTokenBudget: number;
+        maxLoadedTools: number;
+        searchLimit: number;
+    }, {
+        mode?: "auto" | "eager" | "deferred" | undefined;
+        eagerToolCount?: number | undefined;
+        schemaTokenBudget?: number | undefined;
+        maxLoadedTools?: number | undefined;
+        searchLimit?: number | undefined;
+    }>>;
+    toolExecution: z.ZodDefault<z.ZodObject<{
+        /** Shared across the root loop and managed children for parallel-safe tools. */
+        maxConcurrent: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxConcurrent: number;
+    }, {
+        maxConcurrent?: number | undefined;
+    }>>;
+    observability: z.ZodDefault<z.ZodObject<{
+        /** Persist a per-tool-call JSONL record for `book tool-stats`. */
+        toolTelemetry: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Default reporting window (in days) for `book tool-stats` and the target for
+         * `book tool-stats --prune`. Disk use is bounded by size-based log rotation;
+         * records are only deleted when they rotate out or are explicitly pruned.
+         */
+        toolTelemetryRetentionDays: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        toolTelemetry: boolean;
+        toolTelemetryRetentionDays: number;
+    }, {
+        toolTelemetry?: boolean | undefined;
+        toolTelemetryRetentionDays?: number | undefined;
+    }>>;
+    mcp: z.ZodDefault<z.ZodObject<{
+        /**
+         * Per-server trust decisions for workspace `.mcp.json` declarations.
+         * User-global servers (<BOOK_HOME>/.book/mcp.json) never require approval.
+         */
+        projectServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            /** Hash of the server's command/args/env at decision time; a mismatch re-prompts. */
+            fingerprint: z.ZodString;
+            choice: z.ZodEnum<["approved", "rejected"]>;
+        }, "strip", z.ZodTypeAny, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        projectServers: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }>;
+    }, {
+        projectServers?: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }> | undefined;
+    }>>;
+    commands: z.ZodDefault<z.ZodObject<{
+        /**
+         * Per-command trust decisions for `<workspace>/.book/commands/*.md` files
+         * that substitute shell into their prompt. That substitution runs outside the
+         * permission system and outside the sandbox, so a repository-controlled file
+         * needs a decision before it runs. User-global commands
+         * (<BOOK_HOME>/commands) were written by the user and never require one.
+         */
+        projectCommands: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            /** Digest of the shell the body substitutes at decision time; a mismatch re-prompts. */
+            fingerprint: z.ZodString;
+            choice: z.ZodEnum<["approved", "rejected"]>;
+        }, "strip", z.ZodTypeAny, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }>>>;
+    }, "strip", z.ZodTypeAny, {
+        projectCommands: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }>;
+    }, {
+        projectCommands?: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    mcp: {
+        projectServers: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }>;
+    };
+    env: Record<string, string>;
+    ui: {
+        showThinking: boolean;
+        startupAnimation: boolean;
+    };
+    skills: {
+        enabled: boolean;
+        overrides: Record<string, "manual" | "off" | "auto" | "name-only">;
+        execution: Record<string, "ask" | "deny" | "inherit">;
+    };
+    additionalDirectories: string[];
+    provider: Record<string, {
+        type: "openai" | "anthropic";
+        models: Record<string, {
+            effort?: false | {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            } | undefined;
+            label?: string | undefined;
+            contextWindow?: number | undefined;
+            maxOutputTokens?: number | undefined;
+            vision?: boolean | undefined;
+            manual?: boolean | undefined;
+            editFormat?: "patch" | "replace" | "whole" | undefined;
+        }>;
+        baseURL?: string | undefined;
+        baseUrl?: string | undefined;
+        apiKey?: string | undefined;
+    }>;
+    permissions: {
+        allow: string[];
+        ask: string[];
+        deny: string[];
+        projectAllowRules: Record<string, "approved" | "rejected">;
+    };
+    sandbox: {
+        enabled: boolean;
+        failIfUnavailable: boolean;
+        autoAllowBashIfSandboxed: boolean;
+        excludedCommands: string[];
+        allowUnsandboxedCommands: boolean;
+        filesystem: {
+            allowWrite: string[];
+            denyWrite: string[];
+            denyRead: string[];
+        };
+        network: {
+            allowedDomains: string[];
+            deniedDomains: string[];
+        };
+    };
+    hooks: {
+        SessionStart: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        SessionEnd: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        UserPromptSubmit: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PreToolUse: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PostToolUse: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        Stop: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PreCompact: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        PostCompact: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        SubagentStart: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        SubagentStop: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        Notification: {
+            command: string;
+            env: Record<string, string>;
+            matcher?: string | undefined;
+        }[];
+        projectEntries: Record<string, "approved" | "rejected">;
+    };
+    retry: {
+        maxAttempts: number;
+        baseDelayMs: number;
+        maxDelayMs: number;
+        totalBudgetMs: number;
+        requestTimeoutMs: number;
+        streamStallTimeoutMs: number;
+        thinkingStallTimeoutMs: number;
+        toolRetries: number;
+        watchdog: boolean;
+        streamReissueAttempts: number;
+        outputCapContinuations: number;
+    };
+    memory: {
+        enabled: boolean;
+        autoSave: boolean;
+        requireApproval: boolean;
+    };
+    continuation: {
+        enabled: boolean;
+        maxConsecutive: number;
+        noProgressLimit: number;
+        blockedToolTurnLimit: number;
+        planRefreshTurns: number;
+        maxWallClockMs: number;
+    };
+    agents: {
+        mode: "manual" | "adaptive" | "off";
+        maxConcurrent: number;
+        maxSpawned: number;
+        maxDepth: 1;
+        persist: boolean;
+        includeUntrackedInSnapshot: boolean;
+        telemetry: boolean;
+        retentionDays: number;
+        checks: Record<string, string | string[]>;
+        checkTimeoutMs: number;
+        maxWorktrees: number;
+        resumeInterrupted: boolean;
+        minFreeDiskBytes: number;
+        profiles: Record<string, {
+            effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+            model?: string | undefined;
+            maxTurns?: number | undefined;
+            color?: string | undefined;
+        }>;
+        ui: {
+            enabled: boolean;
+        };
+        routing: {
+            inlineSearchBudget: number;
+            exploreReminder: boolean;
+        };
+        forwardTextEvents: boolean;
+    };
+    toolDiscovery: {
+        mode: "auto" | "eager" | "deferred";
+        eagerToolCount: number;
+        schemaTokenBudget: number;
+        maxLoadedTools: number;
+        searchLimit: number;
+    };
+    toolExecution: {
+        maxConcurrent: number;
+    };
+    observability: {
+        toolTelemetry: boolean;
+        toolTelemetryRetentionDays: number;
+    };
+    commands: {
+        projectCommands: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }>;
+    };
+    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    model?: string | undefined;
+    maxTurns?: number | undefined;
+    compactStrategy?: "summary" | undefined;
+    compactModel?: string | undefined;
+    maxTokens?: number | undefined;
+    theme?: string | undefined;
+    shell?: string | undefined;
+    autoCompactEnabled?: boolean | undefined;
+    defaultMode?: "default" | "auto" | "acceptEdits" | "plan" | "dontAsk" | "bypassPermissions" | undefined;
+    disableBypassPermissionsMode?: boolean | undefined;
+}, {
+    effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+    mcp?: {
+        projectServers?: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }> | undefined;
+    } | undefined;
+    env?: Record<string, string> | undefined;
+    model?: string | undefined;
+    maxTurns?: number | undefined;
+    ui?: {
+        showThinking?: boolean | undefined;
+        startupAnimation?: boolean | undefined;
+    } | undefined;
+    compactStrategy?: "summary" | undefined;
+    compactModel?: string | undefined;
+    maxTokens?: number | undefined;
+    theme?: string | undefined;
+    shell?: string | undefined;
+    skills?: {
+        enabled?: boolean | undefined;
+        overrides?: Record<string, "manual" | "off" | "auto" | "name-only"> | undefined;
+        execution?: Record<string, "ask" | "deny" | "inherit"> | undefined;
+    } | undefined;
+    autoCompactEnabled?: boolean | undefined;
+    defaultMode?: "default" | "auto" | "acceptEdits" | "plan" | "dontAsk" | "bypassPermissions" | undefined;
+    disableBypassPermissionsMode?: boolean | undefined;
+    additionalDirectories?: string[] | undefined;
+    provider?: Record<string, {
+        type?: "openai" | "anthropic" | undefined;
+        baseURL?: string | undefined;
+        baseUrl?: string | undefined;
+        apiKey?: string | undefined;
+        models?: Record<string, {
+            effort?: false | {
+                default?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+                levels?: ("low" | "medium" | "high" | "xhigh" | "max")[] | undefined;
+            } | undefined;
+            label?: string | undefined;
+            contextWindow?: number | undefined;
+            maxOutputTokens?: number | undefined;
+            vision?: boolean | undefined;
+            manual?: boolean | undefined;
+            editFormat?: "patch" | "replace" | "whole" | undefined;
+        }> | undefined;
+    }> | undefined;
+    permissions?: {
+        allow?: string[] | undefined;
+        ask?: string[] | undefined;
+        deny?: string[] | undefined;
+        projectAllowRules?: Record<string, "approved" | "rejected"> | undefined;
+    } | undefined;
+    sandbox?: {
+        enabled?: boolean | undefined;
+        failIfUnavailable?: boolean | undefined;
+        autoAllowBashIfSandboxed?: boolean | undefined;
+        excludedCommands?: string[] | undefined;
+        allowUnsandboxedCommands?: boolean | undefined;
+        filesystem?: {
+            allowWrite?: string[] | undefined;
+            denyWrite?: string[] | undefined;
+            denyRead?: string[] | undefined;
+        } | undefined;
+        network?: {
+            allowedDomains?: string[] | undefined;
+            deniedDomains?: string[] | undefined;
+        } | undefined;
+    } | undefined;
+    hooks?: {
+        SessionStart?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        SessionEnd?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        UserPromptSubmit?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PreToolUse?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PostToolUse?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        Stop?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PreCompact?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        PostCompact?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        SubagentStart?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        SubagentStop?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        Notification?: {
+            command: string;
+            matcher?: string | undefined;
+            env?: Record<string, string> | undefined;
+        }[] | undefined;
+        projectEntries?: Record<string, "approved" | "rejected"> | undefined;
+    } | undefined;
+    retry?: {
+        maxAttempts?: number | undefined;
+        baseDelayMs?: number | undefined;
+        maxDelayMs?: number | undefined;
+        totalBudgetMs?: number | undefined;
+        requestTimeoutMs?: number | undefined;
+        streamStallTimeoutMs?: number | undefined;
+        thinkingStallTimeoutMs?: number | undefined;
+        toolRetries?: number | undefined;
+        watchdog?: boolean | undefined;
+        streamReissueAttempts?: number | undefined;
+        outputCapContinuations?: number | undefined;
+    } | undefined;
+    memory?: {
+        enabled?: boolean | undefined;
+        autoSave?: boolean | undefined;
+        requireApproval?: boolean | undefined;
+    } | undefined;
+    continuation?: {
+        enabled?: boolean | undefined;
+        maxConsecutive?: number | undefined;
+        noProgressLimit?: number | undefined;
+        blockedToolTurnLimit?: number | undefined;
+        planRefreshTurns?: number | undefined;
+        maxWallClockMs?: number | undefined;
+    } | undefined;
+    agents?: {
+        mode?: "manual" | "adaptive" | "off" | undefined;
+        maxConcurrent?: number | undefined;
+        maxSpawned?: number | undefined;
+        maxDepth?: 1 | undefined;
+        persist?: boolean | undefined;
+        includeUntrackedInSnapshot?: boolean | undefined;
+        telemetry?: boolean | undefined;
+        retentionDays?: number | undefined;
+        checks?: Record<string, string | string[]> | undefined;
+        checkTimeoutMs?: number | undefined;
+        maxWorktrees?: number | undefined;
+        resumeInterrupted?: boolean | undefined;
+        minFreeDiskBytes?: number | undefined;
+        profiles?: Record<string, {
+            effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
+            model?: string | undefined;
+            maxTurns?: number | undefined;
+            color?: string | undefined;
+        }> | undefined;
+        ui?: {
+            enabled?: boolean | undefined;
+        } | undefined;
+        routing?: {
+            inlineSearchBudget?: number | undefined;
+            exploreReminder?: boolean | undefined;
+        } | undefined;
+        forwardTextEvents?: boolean | undefined;
+    } | undefined;
+    toolDiscovery?: {
+        mode?: "auto" | "eager" | "deferred" | undefined;
+        eagerToolCount?: number | undefined;
+        schemaTokenBudget?: number | undefined;
+        maxLoadedTools?: number | undefined;
+        searchLimit?: number | undefined;
+    } | undefined;
+    toolExecution?: {
+        maxConcurrent?: number | undefined;
+    } | undefined;
+    observability?: {
+        toolTelemetry?: boolean | undefined;
+        toolTelemetryRetentionDays?: number | undefined;
+    } | undefined;
+    commands?: {
+        projectCommands?: Record<string, {
+            fingerprint: string;
+            choice: "approved" | "rejected";
+        }> | undefined;
+    } | undefined;
+}>;
+type BookSettings = z.infer<typeof bookSettingsSchema>;
+/**
+ * Resolved settings after layering (all defaults filled).
+ */
+type ResolvedSettings = Required<Omit<BookSettings, 'model' | 'compactModel' | 'maxTurns' | 'maxTokens' | 'effort' | 'theme' | 'shell' | 'autoCompactEnabled' | 'defaultMode' | 'disableBypassPermissionsMode'>> & Pick<BookSettings, 'model' | 'compactModel' | 'maxTurns' | 'maxTokens' | 'effort' | 'theme' | 'shell' | 'autoCompactEnabled' | 'defaultMode' | 'disableBypassPermissionsMode'>;
+
+declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+type MemoryType = (typeof MEMORY_TYPES)[number];
+type MemoryStatus = 'approved' | 'pending' | 'discarded';
+interface MemoryFileSummary {
+    name: string;
+    path: string;
+    type?: MemoryType;
+    status?: MemoryStatus;
+    title?: string;
+    created?: string;
+    updated?: string;
+    size: number;
+}
+interface LoadedMemoryContext {
+    dir: string;
+    indexFile: string | null;
+    indexLoaded: boolean;
+    indexLineCount: number;
+    loadedLineCount: number;
+    indexText: string;
+    files: MemoryFileSummary[];
+    candidates: MemoryFileSummary[];
+}
+
+interface LearnedModelWindowEntry {
+    contextWindow: number;
+    learnedAt: number;
+}
+interface ModelWindowStore {
+    get(model: string): number | undefined;
+    getEntry(model: string): LearnedModelWindowEntry | undefined;
+    ratchet(model: string, ceiling: number): boolean;
+    all(): Record<string, LearnedModelWindowEntry>;
+}
+
+type PermissionMode = 'default' | 'auto' | 'plan' | 'accept-edits' | 'dontAsk' | 'bypassPermissions';
+/**
+ * A command resolved to a direct argv spawn — no intermediate shell parses it.
+ *
+ * Sandboxed commands must use this form: joining a wrapper into one string and
+ * spawning it with `shell: true` lets any metacharacter in the user's command
+ * split at the *outer* shell, outside the sandbox. Callers that receive an
+ * `exec` spawn `file` with `args` and `shell: false`; when it is absent the raw
+ * command string goes to the platform shell as before. Unsandboxed commands
+ * use the same form when the session shell is spawned as argv (see
+ * `ResolvedShell`).
+ */
+interface CommandExecution {
+    file: string;
+    args: string[];
+}
+/** The program that interprets a Bash tool command string. */
+type ShellKind = 'bash' | 'pwsh' | 'powershell' | 'cmd' | 'sh';
+/** Where a shell selection came from, for diagnostics. */
+type ShellSource = 'setting' | 'launching-shell' | 'detected' | 'fallback';
+/**
+ * The shell the Bash tool spawns, resolved once per session by
+ * `resolveShell()` in `src/shell-selection.ts`.
+ *
+ * `file` is the executable spawned as argv; when absent the command string
+ * goes to Node's `shell: true` (`/bin/sh`, or `%ComSpec%` on Windows), which
+ * is the only way cmd.exe is ever driven because its quoting cannot be
+ * reproduced from a plain argument vector.
+ */
+interface ResolvedShell {
+    kind: ShellKind;
+    file?: string;
+    /** Short human name: "Git Bash", "PowerShell 7", "Windows PowerShell 5.1", "cmd.exe", "/bin/sh". */
+    label: string;
+    source: ShellSource;
+    /** Set when a requested shell could not be honoured and the automatic ladder was used instead. */
+    warning?: string;
+}
+/** What phase of retry is currently active (drives the TUI spinner label). */
+type RetryPhase = 'none' | 'transport' | 'stalled' | 'tool' | 'watchdog';
+/**
+ * Retry configuration — all tunables live here.
+ * Mirrors Claude Code's env vars: CLAUDE_CODE_MAX_RETRIES, API_TIMEOUT_MS,
+ * CLAUDE_CODE_RETRY_WATCHDOG, plus the stream-stall threshold.
+ */
+interface RetryConfig {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    totalBudgetMs: number;
+    requestTimeoutMs: number;
+    streamStallTimeoutMs: number;
+    toolRetries: number;
+    watchdog: boolean;
+    /**
+     * Re-sends of a turn after a transport failure that left the work intact.
+     * Optional, and absent means 0 — a caller that builds a RetryConfig by hand
+     * keeps the original end-the-run-on-any-stream-error behavior rather than
+     * silently inheriting a retry policy it never asked for.
+     */
+    streamReissueAttempts?: number;
+    /**
+     * Continuations allowed after the provider's output cap, budgeted separately
+     * from transport faults so a large generated file cannot drain the allowance a
+     * real socket drop needs. Optional, and absent means 0.
+     */
+    outputCapContinuations?: number;
+    /** Stall ceiling while the model is thinking; absent falls back to the chat one. */
+    thinkingStallTimeoutMs?: number;
+}
+type AgentTaskStatus = 'pending' | 'in_progress' | 'completed' | 'deleted';
+interface AgentTask {
+    id: string;
+    subject: string;
+    description?: string;
+    status: AgentTaskStatus;
+    activeForm?: string;
+    owner?: string;
+    metadata?: Record<string, unknown>;
+    blockedBy: string[];
+    blocks: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+type BackgroundShellStatus = 'starting' | 'running' | 'stopping' | 'exited' | 'failed' | 'killed' | 'timed_out' | 'lost';
+type BackgroundShellLifetime = 'session' | 'persistent';
+type BackgroundShellNotify = 'none' | 'ui' | 'agent';
+interface BackgroundShellRecord {
+    id: string;
+    command: string;
+    effectiveCommand: string;
+    title?: string;
+    workdir: string;
+    pid?: number;
+    runnerPid?: number;
+    process?: ChildProcess;
+    status: BackgroundShellStatus;
+    lifetime?: BackgroundShellLifetime;
+    notify?: BackgroundShellNotify;
+    output: string;
+    readOffset: number;
+    truncatedBytes: number;
+    outputRevision?: number;
+    completionSequence?: number;
+    completionAcknowledgedSequence?: number;
+    completionDeliveredSequence?: number;
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | string | null;
+    startedAt: number;
+    finishedAt?: number;
+    timeoutMs?: number;
+    deadlineAt?: number;
+    parentSessionId?: string;
+    rootRunId?: string;
+    parentRunId?: string;
+    persistentRecordPath?: string;
+    persistentControlPath?: string;
+    persistentOutputPath?: string;
+    persistentOutputRotationSequence?: number;
+    controlToken?: string;
+    timer?: NodeJS.Timeout;
+    retentionTimer?: NodeJS.Timeout;
+    sandboxed?: boolean;
+}
+interface BackgroundShellStore {
+    nextId: number;
+    shells: Map<string, BackgroundShellRecord>;
+}
+interface AgentConfig {
+    /** May be empty until an interactive user adds a BYOK provider. */
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+    /** Raw picker/settings reference, including provider prefix when configured. */
+    modelSelection?: string;
+    /**
+     * Set when the model id carries a `<prefix>/` matching no configured provider,
+     * so the run fell back to the default endpoint. Reported rather than thrown:
+     * the same spelling is a legitimate vendor-namespaced model id.
+     */
+    modelProviderWarning?: string;
+    /** Optional provider/model used only for historical conversation compaction. */
+    compactModel?: string;
+    /** Supported production context-reduction strategy. */
+    compactStrategy: CompactStrategy;
+    /** Max agent turns per user message. Undefined = unlimited. */
+    maxTurns?: number;
+    maxTokens: number;
+    /** True when maxTokens came from user config/env, not a default or model metadata. */
+    maxTokensExplicit?: boolean;
+    /** Default output-token limit to restore when selected model has no metadata. */
+    defaultMaxTokens?: number;
+    /** True when effort came from user config/env or an explicit runtime choice. */
+    effortExplicit?: boolean;
+    /** Default effort to restore when selected model has no metadata. */
+    defaultEffort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** Plain-model fallback values used after provider/model switches. */
+    defaultApiKey?: string;
+    defaultBaseUrl?: string;
+    defaultProvider?: 'anthropic' | 'openai' | 'auto';
+    autoCompactEnabled: boolean;
+    workspace: string;
+    animation: {
+        typewriterSpeed: number;
+        spinnerStyle: 'braille' | 'dots';
+    };
+    accessibility: {
+        screenReader: boolean;
+        reducedMotion: boolean;
+    };
+    /** Resolved layered settings (permissions, sandbox, etc.). */
+    settings: ResolvedSettings;
+    /**
+     * The shell the Bash tool spawns, resolved once at load from `BOOK_SHELL`,
+     * `settings.shell`, and what is installed. Optional so hand-built configs in
+     * tests keep working; the tool resolves it on demand when absent.
+     */
+    shell?: ResolvedShell;
+    /** Settings-layer context retained for live TUI re-resolution. */
+    settingsContext?: {
+        overridePath?: string;
+        noSettings?: boolean;
+    };
+    /** Retry configuration (from settings.json + env vars). */
+    retry: RetryConfig;
+    /** Thinking effort level (Anthropic adaptive thinking / output_config.effort). */
+    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    /** Explicit provider override: 'anthropic' | 'openai' | 'auto' (default: auto-detect). */
+    provider?: 'anthropic' | 'openai' | 'auto';
+    /** Metadata from settings.provider.<id>.models.<model>, if selected. */
+    modelInfo?: ProviderModelConfig;
+    /** Approved memory snapshot loaded once at session start. */
+    memoryContext?: LoadedMemoryContext;
+    /** Optional store for learned context window ceilings. */
+    modelWindowStore?: ModelWindowStore;
+}
+
+type ShellJobEvent = {
+    type: 'background_job_start';
+    job: BackgroundShellRecord;
+} | {
+    type: 'background_job_update';
+    job: BackgroundShellRecord;
+} | {
+    type: 'background_job_output';
+    jobId: string;
+    revision: number;
+} | {
+    type: 'background_job_result';
+    job: BackgroundShellRecord;
+} | {
+    type: 'background_job_dismiss';
+    jobId: string;
+};
+interface ShellStartOptions {
+    command: string;
+    effectiveCommand: string;
+    /**
+     * Present for sandboxed commands and for a session shell spawned as argv
+     * (Git Bash or PowerShell on Windows); absent means Node's `shell: true`.
+     */
+    exec?: CommandExecution;
+    workdir: string;
+    env: NodeJS.ProcessEnv;
+    sandboxed: boolean;
+    title?: string;
+    notify?: BackgroundShellNotify;
+    timeoutMs?: number;
+    lifetime?: 'session' | 'persistent';
+    workspace?: string;
+    envOverrides?: Record<string, string>;
+    parentSessionId?: string;
+    rootRunId?: string;
+    parentRunId?: string;
+}
+interface ShellOutputResult {
+    shell: BackgroundShellRecord;
+    output: string;
+    remaining: number;
+}
+interface ShellJobManagerOptions {
+    persistentRoot?: string;
+    /**
+     * Budgets for observing the detached runner's state transitions. The
+     * defaults suit an interactive host; tests on contended CI runners pass
+     * wider windows because the transitions are eventual, not latency-bound.
+     */
+    runnerStartBudgetMs?: number;
+    runnerStopBudgetMs?: number;
+    /**
+     * Injected by tests. Only the two budgets above read it: every other time in
+     * this file is a stamp shared with the detached runner process, and those
+     * stay on the wall clock because two processes share no monotonic origin.
+     */
+    clock?: Clock;
+}
+declare class ShellJobManager {
+    private readonly store;
+    private readonly options;
+    private readonly subscribers;
+    private workspace?;
+    private persistentPaths?;
+    private persistentStorageError?;
+    private monitor?;
+    constructor(store: BackgroundShellStore, options?: ShellJobManagerOptions);
+    private readonly clock;
+    subscribe(listener: (event: ShellJobEvent) => void): () => void;
+    configureWorkspace(workspace: string): void;
+    list(): BackgroundShellRecord[];
+    get(shellId: string): BackgroundShellRecord | undefined;
+    listPendingAgentCompletions(parentSessionId: string): BackgroundShellRecord[];
+    listPendingUiCompletions(): BackgroundShellRecord[];
+    start(options: ShellStartOptions): Promise<BackgroundShellRecord>;
+    readOutput(shellId: string, limit?: number): ShellOutputResult | undefined;
+    readTail(shellId: string, limit?: number): string | undefined;
+    stop(shellId: string, reason?: 'killed' | 'timed_out'): Promise<boolean>;
+    dismiss(shellId: string): void;
+    acknowledgeCompletion(shellId: string, sequence?: number, consumer?: 'ui' | 'agent'): void;
+    dispose(): void;
+    private emit;
+    private persistAcknowledgement;
+    private startPersistent;
+    private runnerInvocation;
+    private stopPersistent;
+    private refreshPersistentJobs;
+    private refreshPersistentRecord;
+    private reconcilePersistentState;
+    private applyPersistentState;
+    private recordFromPersistentState;
+    private appendOutput;
+    private clearTimer;
+    private finish;
+    private terminate;
+    private deleteRecord;
+    private pruneTerminalShells;
+    private scheduleRetention;
+}
+
+type AgentTerminalStatus = 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'interrupted';
+type AgentTerminalReason = 'normal_completion' | 'blocked_by_policy' | 'provider_error' | 'provider_timeout' | 'stream_stall' | 'protocol_error' | 'context_overflow' | 'budget_exceeded' | 'budget_unverifiable' | 'max_turns' | 'runtime_error' | 'caller_cancelled' | 'user_cancelled' | 'session_disposed' | 'session_replaced' | 'transport_interrupted' | 'output_cap' | 'credentials_rejected' | 'objective_complete' | 'continuation_limit' | 'blocked_plan' | 'no_progress' | 'all_tools_blocked' | 'plan_stop' | 'handoff_requested' | 'missing_terminal';
+interface AgentTerminalOutcome {
+    readonly status: AgentTerminalStatus;
+    readonly reason: AgentTerminalReason;
+    readonly message?: string;
+    readonly partialOutput: boolean;
+    readonly providerCode?: string;
+}
+
+interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** Context-pressure metric for auto-compact (includes Anthropic cache tokens when known). */
+    contextTokens?: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+/** Provider-native response data needed to replay a provider protocol exactly. */
+interface ProviderMessageMetadata {
+    /** Anthropic content blocks, including thinking signatures, in original order. */
+    anthropicContentBlocks?: Array<Record<string, unknown>>;
+}
+/** A session-owned image referenced by a user message. */
+interface ImageAttachment {
+    id: string;
+    sha256: string;
+    storageKey: string;
+    mediaType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+    byteSize: number;
+    displayName?: string;
+}
+/**
+ * Structured presentation data for local slash-command output.
+ *
+ * These snapshots stay UI-only: local command messages are excluded from the
+ * provider context and are never persisted as assistant turns.
+ */
+interface ConfigCommandDisplay {
+    kind: 'config';
+    snapshot: Record<string, unknown>;
+    runtime: {
+        model: string;
+        provider: string;
+        effort?: string;
+        mode: string;
+        maxTokens: number;
+        workspace: string;
+    };
+}
+type ContextWindowSource = 'declared' | 'learned' | 'family' | 'default';
+interface ContextCommandDisplay {
+    kind: 'context';
+    model: string;
+    maxTokens: number;
+    /** Origin of the context window: declared in settings, matched from a family prior, or product default. */
+    windowSource?: ContextWindowSource;
+    /** @deprecated Use `windowSource`. False/absent when maxTokens is the assumed default. */
+    windowDeclared?: boolean;
+    estimatedTokens: number;
+    totalMessages: number;
+    userMessages: number;
+    assistantMessages: number;
+    toolCalls: number;
+    toolResults: number;
+    userTokens: number;
+    assistantTokens: number;
+    ambient: {
+        commandCount: number;
+        skillCount?: number;
+        subagentCount?: number;
+        hasMemoryIndex?: boolean;
+        hasClaudeMdLoader: boolean;
+    };
+}
+interface UsageCommandDisplay {
+    kind: 'usage';
+    model: string;
+    currentTurn: number;
+    messageCount: number;
+    turnDurationMs: number;
+    usage: Usage | null;
+    rate?: {
+        inputPerMillion: number;
+        outputPerMillion: number;
+    };
+    estimatedCostUsd?: number;
+    /** Per-tool call/failure counters for this session, ordered by call count. */
+    toolCallStats?: Array<{
+        tool: string;
+        calls: number;
+        failures: Record<string, number>;
+    }>;
+}
+/** Compact completion metadata rendered as a host notification. */
+interface AgentNotificationDisplay {
+    deliveryId?: string;
+    sequence?: number;
+    agentId: string;
+    displayName: string;
+    status: 'completed' | 'failed' | 'stopped' | 'interrupted';
+    summary?: string;
+    error?: string;
+    evidenceIds: string[];
+    durationMs?: number;
+}
+type LocalCommandDisplay = ConfigCommandDisplay | ContextCommandDisplay | UsageCommandDisplay;
+interface Message {
+    id: string;
+    role: 'user' | 'assistant';
+    /** User-facing text shown in the TUI/history. */
+    content: string;
+    /** Provider-native reasoning/thinking text shown separately and replayed in later context. */
+    reasoningContent?: string;
+    /** Provider-native metadata used only when reconstructing provider requests. */
+    providerMetadata?: ProviderMessageMetadata;
+    /** Provider-facing text when it differs from the displayed content. */
+    contextContent?: string;
+    /**
+     * Host-rendered `<session-state>` block appended to this turn for the provider.
+     * Written once when the turn is first built and never rewritten, so rebuilds
+     * reproduce the message byte-for-byte behind the conversation cache breakpoint.
+     */
+    sessionState?: string;
+    /** Images attached to a user turn; bytes live in session attachment storage. */
+    attachments?: ImageAttachment[];
+    /** Whether this message is included in provider and compaction context. */
+    includeInContext: boolean;
+    kind?: 'conversation' | 'checkpoint' | 'local' | 'agent-notification';
+    /**
+     * The content was produced by resolving something -- a slash command's body, a
+     * delegated task prompt -- rather than typed by the user. The role still reads
+     * `user` because that is the turn's position in the conversation, so anything
+     * that means "the user's own words" must check this too.
+     */
+    derivedContent?: boolean;
+    /** Structured display data for automatically delivered child completions. */
+    agentNotifications?: AgentNotificationDisplay[];
+    toolCalls?: ToolCall[];
+    toolResults?: ToolResult[];
+    /** UI-only subagent activity. Never serialized as provider tool calls. */
+    nestedToolInvocations?: NestedToolInvocation[];
+    /** UI-only visual treatment for local slash-command output. */
+    localCommand?: LocalCommandDisplay;
+    fileObservations?: FileObservation[];
+    timestamp: number;
+}
+
+type AgentRunSource = 'tui' | 'headless' | 'sdk' | 'internal';
+type AgentModelIdentityStatus = 'verified' | 'requested_only' | 'unverifiable';
+interface AgentModelIdentity {
+    readonly provider: string;
+    readonly requestedModel: string;
+    readonly responseModel?: string;
+    readonly responseId?: string;
+    readonly finishReasons?: readonly string[];
+    readonly status: AgentModelIdentityStatus;
+}
+interface AgentRunAccounting {
+    readonly rootRunIds: readonly string[];
+    readonly runIds: readonly string[];
+    readonly directUsage: Usage | null;
+    readonly inclusiveUsage: Usage | null;
+    /**
+     * This execution's own spend. For a root snapshot that is the root turn alone —
+     * it deliberately excludes managed agents and subagents.
+     */
+    readonly costUsd: number | null;
+    /**
+     * Everything spent under this root, delegated work included. This is what a
+     * budget must be enforced against: `costUsd` omits every dollar a fan-out spent,
+     * which is most of the money in a run that delegates.
+     */
+    readonly inclusiveCostUsd: number | null;
+    readonly costStatus: 'known' | 'estimated' | 'unknown';
+    readonly pricingVersion: string;
+    readonly unknownModels: readonly string[];
+    readonly budgetUsd?: number;
+    readonly budgetStatus: 'not_configured' | 'within' | 'exceeded' | 'unknown';
+    readonly modelIdentities: readonly AgentModelIdentity[];
+    readonly completeness: 'partial' | 'complete';
+    readonly missingSources: readonly string[];
+}
+interface AgentRunAmbientSnapshot {
+    readonly schemaVersion: 2;
+    readonly fingerprint: string;
+    readonly capturedAt: number;
+    readonly model: {
+        readonly provider: string;
+        readonly requestedModel: string;
+        readonly modelSelection?: string;
+        readonly endpointFingerprint: string;
+        readonly effort?: string;
+        readonly maxTokens: number;
+        readonly maxTurns?: number;
+        readonly modelInfoFingerprint: string;
+    };
+    readonly settings: {
+        readonly fingerprint: string;
+        readonly agentsMode: 'adaptive' | 'manual' | 'off';
+    };
+    readonly tools: {
+        readonly fingerprint: string;
+        readonly count: number;
+        readonly names: readonly string[];
+        readonly activationState: 'fresh' | 'unverified';
+    };
+    readonly commands: {
+        readonly fingerprint: string;
+        readonly count: number;
+        readonly names: readonly string[];
+    };
+    readonly skills: {
+        readonly fingerprint: string;
+        readonly count: number;
+        readonly names: readonly string[];
+        readonly activationState: 'disabled' | 'not-captured';
+    };
+    readonly mcp: {
+        readonly fingerprint: string;
+        readonly count: number;
+        readonly names: readonly string[];
+    };
+    readonly agents: {
+        readonly fingerprint: string;
+        readonly count: number;
+        readonly names: readonly string[];
+        readonly mode: 'adaptive' | 'manual' | 'off';
+    };
+    readonly prompt: {
+        readonly fingerprint: string;
+        readonly systemPromptVersion: string;
+        readonly date: string;
+        readonly projectInstructionCount: number;
+    };
+    readonly memory: {
+        readonly fingerprint: string;
+        readonly enabled: boolean;
+        readonly indexLoaded: boolean;
+    };
+    readonly policies: {
+        readonly permissionMode: PermissionMode;
+        readonly hooksFingerprint: string;
+        readonly contextFingerprint: string;
+        readonly networkFingerprint: string;
+        readonly delegationFingerprint: string;
+    };
+    readonly runtime: {
+        readonly packageVersion: string;
+        readonly runtimeRevision: string;
+        readonly fixtureRevision: string;
+        readonly randomSeed: string;
+        readonly nodeVersion: string;
+        readonly platform: NodeJS.Platform;
+        readonly architecture: string;
+        readonly timezone: string;
+        readonly environmentFingerprint: string;
+        readonly workspaceFingerprint: string;
+    };
+    readonly bookHome: {
+        readonly pathFingerprint: string;
+        readonly isolation: 'shared' | 'configured' | 'isolated';
+        readonly contentsFingerprint?: string;
+        readonly contentsStatus: 'not-captured' | 'captured' | 'incomplete';
+        readonly fileCount?: number;
+        readonly totalBytes?: number;
+    };
+    readonly completeness: 'partial' | 'complete';
+    readonly missingSources: readonly string[];
+}
+/** Runtime attribution for one user request or a linked child execution. */
+interface AgentRunContext {
+    /** Unique execution identity. A resumed request receives a new value. */
+    readonly runId: string;
+    /** Root request identity shared by linked child executions. */
+    readonly rootRunId: string;
+    /** Parent execution for a child continuation or managed agent. */
+    readonly parentRunId?: string;
+    /** Previous run when a host resumes a request/session. */
+    readonly resumedFromRunId?: string;
+    readonly sessionId: string;
+    readonly source: AgentRunSource;
+    readonly startedAt: number;
+}
+interface AgentRunResult {
+    readonly context: AgentRunContext;
+    readonly outcome: AgentTerminalOutcome;
+    readonly usage: Usage | null;
+    readonly accounting?: AgentRunAccounting;
+    readonly ambient?: AgentRunAmbientSnapshot;
+}
+
+type SkillSource = 'user' | 'project';
+type SkillRootKind = 'book' | 'agents' | 'claude' | 'opencode';
+type SkillIssueSeverity = 'error' | 'warning';
+interface SkillIssue {
+    code: string;
+    message: string;
+    severity: SkillIssueSeverity;
+}
+interface SkillResource {
+    relativePath: string;
+    byteSize: number;
+    mtimeMs: number;
+    digest: string;
+}
+interface ShadowedSkill {
+    path: string;
+    source: SkillSource;
+    rootKind: SkillRootKind;
+}
+/** Metadata discovered without retaining or injecting the SKILL.md body. */
+interface Skill {
+    id: string;
+    version: string;
+    descriptorDigest: string;
+    resourceDigest: string;
+    name: string;
+    description: string;
+    whenToUse?: string;
+    license?: string;
+    compatibility?: string;
+    metadata: Record<string, string>;
+    /** Requested tool ceiling. It never grants permission by itself. */
+    allowedTools?: string[];
+    model?: string;
+    lifetime: 'turn' | 'run';
+    /** Absolute path to the skill entrypoint. */
+    path: string;
+    /** Absolute directory that owns the skill and its resources. */
+    rootPath: string;
+    source: SkillSource;
+    rootKind: SkillRootKind;
+    activation: SkillActivation;
+    execution: SkillExecution;
+    invocationCount: number;
+    entryByteSize: number;
+    entryMtimeMs: number;
+    resources: SkillResource[];
+    issues: SkillIssue[];
+    valid: boolean;
+    shadowed: ShadowedSkill[];
+}
+interface LoadedSkillBody {
+    body: string;
+    digest: string;
+    byteSize: number;
+}
+interface SkillRoot {
+    path: string;
+    source: SkillSource;
+    kind: SkillRootKind;
+}
+interface DiscoverSkillsOptions {
+    homeDir?: string;
+    bookHomeDir?: string;
+    includeUser?: boolean;
+    projectRoot?: string;
+    includeOpenCode?: boolean;
+    enabled?: boolean;
+    executionOverrides?: Readonly<Record<string, SkillExecution>>;
+}
+/** Roots are ordered from lowest to highest precedence. */
+declare function skillRoots(workspace: string, options?: DiscoverSkillsOptions): SkillRoot[];
+declare function discoverSkills(workspace: string, overrides?: Readonly<Record<string, SkillActivation>>, options?: DiscoverSkillsOptions): Skill[];
+declare function applySkillOverrides(skills: readonly Skill[], overrides: Readonly<Record<string, SkillActivation>>, executionOverrides?: Readonly<Record<string, SkillExecution>>, enabled?: boolean): Skill[];
+declare function loadSkillBody(skill: Skill): LoadedSkillBody;
+interface SkillListingResult {
+    text: string;
+    budgetChars: number;
+    visibleCount: number;
+    included: string[];
+    omitted: string[];
+    collapsed: string[];
+    charCount: number;
+}
+declare function buildSkillListing(skills: readonly Skill[], budgetChars?: number): SkillListingResult;
+declare function generateSkillListing(skills: readonly Skill[], budgetChars?: number): string;
+declare function explicitSkillMentions(prompt: string, skills: readonly Skill[]): string[];
+
+type SkillActivationReason = 'model' | 'user' | 'workflow' | 'subagent-preload';
+type SkillLifecycleEventType = 'skill_discovered' | 'skill_shadowed' | 'skill_activation_requested' | 'skill_activation_applied' | 'skill_activation_blocked' | 'skill_activation_expired' | 'skill_consent_requested' | 'skill_consent_granted' | 'skill_consent_denied' | 'skill_resource_read' | 'skill_resource_blocked' | 'skill_reloaded' | 'skill_watcher_failed';
+interface SkillLifecycleEvent {
+    type: SkillLifecycleEventType;
+    timestamp: number;
+    skill?: string;
+    reason?: SkillActivationReason;
+    details?: Record<string, unknown>;
+}
+interface SkillActivationFrame {
+    skillId: string;
+    skillName: string;
+    version: string;
+    descriptorDigest: string;
+    resourceDigest: string;
+    reason: SkillActivationReason;
+    bodyDigest: string;
+    bodyByteSize: number;
+    body: string;
+    activatedAt: number;
+    activatedAtTurn: number;
+    expires: 'turn' | 'run';
+    expiresAtTurn?: number;
+    allowedTools?: string[];
+    source: Skill['source'];
+    rootKind: Skill['rootKind'];
+    path: string;
+    resources: Skill['resources'];
+}
+type SkillActivationFrameSummary = Omit<SkillActivationFrame, 'body'>;
+interface SkillRegistrySnapshot {
+    catalogDigest: string;
+    skills: Skill[];
+    active: SkillActivationFrameSummary[];
+    previous: SkillActivationFrameSummary[];
+    effectiveTools?: string[];
+    promptCatalog?: Omit<SkillListingResult, 'text'>;
+    events: SkillLifecycleEvent[];
+}
+declare class SkillRegistryError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Session-owned catalog, activation frames, resources, and lifecycle evidence. */
+declare class SkillRegistry {
+    readonly workspace: string;
+    private settings;
+    private settingsFingerprint;
+    private readonly discoveryOptions;
+    private descriptors;
+    private readonly loadedBodies;
+    private readonly active;
+    private readonly previous;
+    private explicitRequests;
+    private consented;
+    private runNumber;
+    private effectiveTools?;
+    private promptCatalog?;
+    readonly events: SkillLifecycleEvent[];
+    constructor(workspace: string, settings: SkillSettings, discoveryOptions?: DiscoverSkillsOptions);
+    updateSettings(settings: SkillSettings): boolean;
+    reload(cause?: string): Skill[];
+    list(): Skill[];
+    get(name: string): Skill | undefined;
+    beginRun(prompt: string): string[];
+    endRun(cause?: string): void;
+    dispose(): void;
+    isExplicitlyRequested(name: string): boolean;
+    executionPolicy(name: string): Skill['execution'] | undefined;
+    activationPolicy(name: string, reason?: SkillActivationReason): 'allow' | 'ask' | 'deny' | undefined;
+    requestConsent(name: string, reason: SkillActivationReason): void;
+    grantConsent(name: string, reason?: SkillActivationReason): void;
+    denyConsent(name: string, reason: SkillActivationReason, cause?: string): void;
+    isActive(name: string, currentTurn?: number): boolean;
+    recordActivationBlocked(name: string, reason: SkillActivationReason, code: string, message: string): void;
+    recordWatcherFailure(message: string): void;
+    recordResourceBlocked(name: string, code: string, message: string): void;
+    activate(name: string, reason: SkillActivationReason, currentTurn?: number): SkillActivationFrame;
+    activeFrames(currentTurn?: number): SkillActivationFrame[];
+    previousFrames(): SkillActivationFrame[];
+    inspect(currentTurn?: number): SkillRegistrySnapshot;
+    recordPromptCatalog(contextWindow: number): void;
+    recordEffectiveTools(tools: readonly string[] | undefined): void;
+    renderActivePolicy(currentTurn?: number): string;
+    readResource(name: string, resourcePath: string, currentTurn?: number): {
+        content: string;
+        digest: string;
+        byteSize: number;
+        path: string;
+    };
+    catalogDigest(): string;
+    private block;
+    private expireAll;
+    private emit;
+}
+
+type AgentMode = 'adaptive' | 'manual' | 'off';
+type AgentRole = 'explorer' | 'reviewer' | 'patcher' | 'validator' | 'custom';
+type AgentStatus = 'queued' | 'starting' | 'running' | 'waiting_input' | 'waiting_permission' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+type AgentApplicationStatus = 'not_applied' | 'applied' | 'conflicted';
+type AgentTopology = 'single' | 'parallel_research' | 'explore_then_patch' | 'patch_validate';
+type IssueQuality = 'clear' | 'ambiguous' | 'unknown';
+type AgentIsolation = 'workspace-readonly' | 'worktree';
+interface AgentProfile {
+    name: string;
+    role: AgentRole;
+    description: string;
+    allowedTools: string[];
+    model?: string;
+    maxTurns?: number;
+    effort?: string;
+    isolation: AgentIsolation;
+    color?: string;
+}
+interface AgentActivitySummary {
+    kind: 'thinking' | 'tool' | 'waiting' | 'compacting';
+    label: string;
+    toolName?: string;
+    status: 'running' | 'completed' | 'failed';
+    startedAt: number;
+}
+interface AgentActivity extends AgentActivitySummary {
+    id: string;
+    /** Full live tool call used by hosts to render nested child activity. */
+    toolCall?: ToolCall;
+    /** Bounded, display-only result projection for realtime host rendering. */
+    result?: ToolResult;
+    finishedAt?: number;
+}
+interface AgentPlanRecord {
+    id: string;
+    parentSessionId?: string;
+    rootRunId?: string;
+    parentRunId?: string;
+    taskShape: string;
+    issueQuality: IssueQuality;
+    topology: AgentTopology;
+    rationale: string;
+    agentBudget: number;
+    createdAt: number;
+}
+interface AgentRunMetrics {
+    toolCalls: number;
+    compactions: number;
+    retries: number;
+}
+interface AgentSnapshot {
+    id: string;
+    repoRoot: string;
+    repoHash: string;
+    baseHead: string;
+    commit: string;
+    tree: string;
+    ref: string;
+    fingerprint: string;
+    dirty: boolean;
+    includeUntracked: boolean;
+    manifest: Array<{
+        status: string;
+        path: string;
+    }>;
+    createdAt: number;
+}
+interface PatchCandidate {
+    baseCommit: string;
+    headCommit: string;
+    branch: string;
+    agentId: string;
+}
+interface AgentRecord {
+    id: string;
+    profile?: string;
+    displayName?: string;
+    profileDescription?: string;
+    purpose?: string;
+    requestedModel?: string;
+    resolvedModel?: string;
+    provider?: string;
+    effort?: string;
+    isolation?: AgentIsolation;
+    currentActivity?: AgentActivitySummary;
+    /** @deprecated Use profile. Retained for persisted version 1 compatibility. */
+    name: string;
+    role: AgentRole;
+    /** @deprecated Use profileDescription. */
+    description: string;
+    parentSessionId?: string;
+    rootRunId?: string;
+    parentRunId?: string;
+    /** See {@link AgentSpawnRequest.notifyParentOnCompletion}. Defaults to true. */
+    notifyParentOnCompletion?: boolean;
+    runId?: string;
+    planId?: string;
+    status: AgentStatus;
+    /**
+     * Set when this record was interrupted by process death rather than by a
+     * decision, so a later start can tell "died mid-flight" from "genuinely
+     * stopped" and re-drive it.
+     */
+    resumable?: boolean;
+    /** The status held before the interruption, for the re-drive to reason about. */
+    resumedFromStatus?: AgentStatus;
+    applicationStatus: AgentApplicationStatus;
+    worktree?: string;
+    branch?: string;
+    snapshotId?: string;
+    prompt: string;
+    referencedEvidenceIds: string[];
+    /** Evidence published by this agent, kept separate from supplied inputs. */
+    producedEvidenceIds?: string[];
+    transcript: Message[];
+    pendingMessages: string[];
+    pendingQuestion?: UserQuestionRequest;
+    pendingQuestionCreatedAt?: number;
+    pendingPermission?: AgentPermissionRequest;
+    result?: string;
+    error?: string;
+    stopReason?: string;
+    patchCandidate?: PatchCandidate;
+    usage?: Usage;
+    createdAt: number;
+    startedAt?: number;
+    updatedAt: number;
+    finishedAt?: number;
+    /** Monotonic terminal-result generation used for durable parent delivery. */
+    completionSequence?: number;
+    /** Latest completion generation durably accepted by the parent host. */
+    completionDeliveredSequence?: number;
+    /** Monotonic execution generation for resumed/follow-up runs. */
+    runSequence?: number;
+    /** Start and usage for the current execution generation. */
+    runStartedAt?: number;
+    runUsage?: Usage;
+    runMetrics?: AgentRunMetrics;
+    /** Terminal outcome for the latest execution generation. */
+    runOutcome?: AgentTerminalOutcome;
+    /** Runtime-only warning when the latest state is waiting for durable storage. */
+    durabilityWarning?: string;
+}
+interface AgentSummary {
+    agentId: string;
+    displayName: string;
+    profile: string;
+    /**
+     * What this agent was spawned to do, bounded.
+     *
+     * The root's view of its own fan-out was `patcher-3 / interrupted / <no
+     * summary>` — enough to know something happened, not enough to decide anything
+     * — while purpose and planId sat unused on disk. After a compaction or two that
+     * is all the parent has left of a delegated unit of work.
+     */
+    purpose?: string;
+    /** Groups agents that share a snapshot and a plan. */
+    planId?: string;
+    status: AgentStatus;
+    resolvedModel: string;
+    isolation: AgentIsolation;
+    currentActivity?: AgentActivitySummary;
+    summary?: string;
+    summaryCharacters?: number;
+    summaryTruncated?: boolean;
+    error?: string;
+    errorCharacters?: number;
+    errorTruncated?: boolean;
+    usage?: Usage;
+    createdAt: number;
+    startedAt?: number;
+    updatedAt: number;
+    finishedAt?: number;
+    durabilityWarning?: string;
+}
+interface AgentCompletion extends AgentSummary {
+    evidenceIds: string[];
+    applicationStatus?: AgentApplicationStatus;
+}
+interface AgentCompletionNotification {
+    deliveryId: string;
+    sequence: number;
+    completion: AgentCompletion;
+    parentSessionId?: string;
+    rootRunId?: string;
+    parentRunId?: string;
+    runId?: string;
+    outcome?: AgentTerminalOutcome;
+}
+type EvidenceKind = 'finding' | 'hypothesis' | 'test_result' | 'patch_candidate' | 'blocker';
+type EvidenceVerificationState = 'unverified' | 'verified' | 'rejected' | 'inconclusive';
+interface EvidenceReference {
+    type: 'file' | 'command' | 'diff' | 'commit';
+    value: string;
+}
+interface EvidenceItem {
+    id: string;
+    kind: EvidenceKind;
+    sourceAgentId: string;
+    summary: string;
+    confidence: number;
+    references: EvidenceReference[];
+    verificationState: EvidenceVerificationState;
+    patchCandidate?: PatchCandidate;
+    reviewerAgentId?: string;
+    verdict?: 'pass' | 'fail' | 'inconclusive';
+    reviewNotes?: string;
+    createdAt: number;
+    reviewedAt?: number;
+    updatedAt: number;
+}
+type AgentRuntimeEvent = {
+    type: 'skill_lifecycle';
+    event: SkillLifecycleEvent;
+} | {
+    type: 'agent_status';
+    agent: AgentSummary;
+    parentSessionId?: string;
+    rootRunId?: string;
+    parentRunId?: string;
+} | {
+    type: 'agent_activity';
+    agentId: string;
+    activity: AgentActivity;
+} | {
+    type: 'agent_text_delta';
+    agentId: string;
+    text: string;
+} | {
+    type: 'agent_message';
+    agentId: string;
+    message: Message;
+} | {
+    type: 'agent_permission';
+    agentId: string;
+    request: AgentPermissionRequest;
+} | {
+    type: 'agent_start';
+    agent: AgentRecord;
+    snapshot?: Pick<AgentSnapshot, 'id' | 'manifest'>;
+} | {
+    type: 'agent_update';
+    agent: AgentRecord;
+} | {
+    type: 'agent_completion';
+    notification: AgentCompletionNotification;
+} | {
+    type: 'agent_result';
+    agent: AgentRecord;
+} | {
+    type: 'agent_question';
+    agentId: string;
+    request: UserQuestionRequest;
+} | {
+    type: 'evidence_update';
+    evidence: EvidenceItem;
+} | {
+    type: 'agent_persistence';
+    state: 'degraded' | 'recovered';
+    reason: 'busy' | 'unavailable';
+    errorCode?: string;
+    message: string;
+    agentId?: string;
+    retrying: boolean;
+    timestamp: number;
+} | {
+    type: 'agent_apply';
+    agentId: string;
+    evidenceId: string;
+    status: AgentApplicationStatus;
+    commit?: string;
+    error?: string;
+};
+interface AgentSpawnRequest {
+    agent: string;
+    description?: string;
+    prompt: string;
+    model?: string;
+    planId?: string;
+    evidenceIds?: string[];
+    parentSessionId?: string;
+    rootRunId?: string;
+    parentRunId?: string;
+    /**
+     * Whether this agent's terminal result is delivered to `parentSessionId` as a
+     * completion notification. Defaults to true.
+     *
+     * Set false by a host that owns the agent's output itself — `/review` renders
+     * its own report, so re-delivering each reviewer's completion would bill an
+     * extra model turn to re-narrate a report the user already has. Suppressing
+     * *delivery* is deliberately separate from clearing `parentSessionId`: the
+     * agent stays owned by the session, so it remains visible in that session's
+     * agent surface while it runs.
+     */
+    notifyParentOnCompletion?: boolean;
+}
+interface AgentPermissionRequest {
+    id: string;
+    agentId: string;
+    displayName: string;
+    toolName: string;
+    toolCall: ToolCall;
+    createdAt: number;
+}
+interface AgentApplyResult {
+    status: AgentApplicationStatus;
+    commit?: string;
+    error?: string;
+}
+
+/**
+ * A small, always-current file saying what a run is doing right now.
+ *
+ * `book status` answers "what was this asked to do and what has it spent" from the
+ * session JSONL, which is durable and never rewritten. What the JSONL cannot
+ * answer is *liveness*: at hour 90 the only on-disk signal that a run is healthy
+ * is the transcript's mtime, and that advances at exactly the same rate for a
+ * productive run, a refusal spin, and a run wedged on a permission prompt. The
+ * default `--output-format text` writes nothing at all until the run terminates,
+ * and the alternative is a firehose. Between silence and every reasoning delta
+ * there was nothing an operator could leave on.
+ *
+ * So: one bounded record, rewritten at each turn boundary, carrying the handful of
+ * facts a supervisor needs to decide "is this stuck" — plus a crash record written
+ * from the exit path, because when a long run dies today nothing durable says why.
+ *
+ * Deliberately synchronous. The file is ~1 KB against turns that take seconds, and
+ * the crash path runs inside `process.on('exit')`, where nothing async can run at
+ * all. Written to a temp file and renamed, so a reader never sees a torn record.
+ */
+declare const RUN_STATUS_VERSION = 1;
+interface RunStatusRecord {
+    readonly version: typeof RUN_STATUS_VERSION;
+    readonly sessionId: string;
+    readonly runId: string;
+    /** The process holding this run, so a reader can test liveness itself. */
+    readonly pid: number;
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    readonly turn: number;
+    readonly elapsedMs: number;
+    /** Canonical name of the most recent tool call, if any. */
+    readonly lastTool?: string;
+    /** The todo currently marked in progress, if any. */
+    readonly currentTodo?: string;
+    readonly openTodos: number;
+    readonly costUsd: number | null;
+    readonly budgetUsd?: number;
+    /** Free bytes on the volume holding the workspace, when the platform reports it. */
+    readonly freeDiskBytes?: number;
+    /** Set once the run has stopped, so a reader can tell finished from wedged. */
+    readonly terminal?: {
+        readonly status: string;
+        readonly reason: string;
+        readonly message?: string;
+    };
+    /**
+     * Set when the process died without a terminal outcome. This is the difference
+     * between "the objective finished" and "the socket died", which a supervisor
+     * otherwise cannot tell apart.
+     */
+    readonly crash?: {
+        readonly message: string;
+        readonly at: number;
+    };
+}
+interface RunStatusSeed {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly workspace: string;
+    readonly budgetUsd?: number;
+    readonly startedAt: number;
+    readonly home?: string;
+}
+interface RunStatusUpdate {
+    readonly turn: number;
+    readonly lastTool?: string;
+    readonly currentTodo?: string;
+    readonly openTodos: number;
+    readonly costUsd: number | null;
+    readonly terminal?: RunStatusRecord['terminal'];
+}
+/**
+ * Keeps one run's status file current.
+ *
+ * Created by a host rather than by the loop: a subagent and a managed agent both
+ * call `runAgentLoop` directly, and each writing its own liveness file would make
+ * "is the run alive" ambiguous. The host that owns the session owns the file.
+ */
+declare class RunStatusWriter {
+    private readonly seed;
+    private last;
+    private crashHandlerInstalled;
+    constructor(seed: RunStatusSeed);
+    update(update: RunStatusUpdate, now?: number): void;
+    /**
+     * Record that the process is dying without a terminal outcome.
+     *
+     * Synchronous by necessity: this runs from `process.on('exit')`, where the event
+     * loop is already closed and no promise will ever settle.
+     */
+    recordCrash(message: string, now?: number): void;
+    /**
+     * Install last-resort handlers so an unhandled fault leaves a record.
+     *
+     * There is no `uncaughtException` or `unhandledRejection` handler anywhere in the
+     * codebase, and `index.ts` ends in a bare `program.parse()` whose returned promise
+     * nothing awaits — so a rejection escaping the action handler becomes an unhandled
+     * rejection and the operator gets a stack trace on a stderr they may have
+     * redirected days ago. Returns a disposer.
+     */
+    installCrashHandlers(): () => void;
+    snapshot(): RunStatusRecord;
+}
+
+/**
+ * A slash command loaded from .book/commands/*.md or ~/.book/commands/*.md.
+ * Matches Claude Code's command loading model.
+ */
+interface SlashCommand {
+    /** File basename without extension — the command name invoked via /name */
+    name: string;
+    /** Human-readable description (from frontmatter `description`) */
+    description: string;
+    /** Argument hint shown in help and autocomplete (from frontmatter `argument-hint`) */
+    argumentHint?: string;
+    /** Named positional arguments for $name substitution (from frontmatter `arguments`) */
+    arguments?: string[];
+    /** Restrict which tools this command can use (from frontmatter `allowed-tools`) */
+    allowedTools?: string[];
+    /** Override model for this command (from frontmatter `model`) */
+    model?: string;
+    /** The raw Markdown body — injected as the prompt when invoked. */
+    body: string;
+    /** Source directory for priority/debugging (user vs project). */
+    source: 'user' | 'project';
+    /** Hide from / autocomplete and /help listing (default false). */
+    isHidden?: boolean;
+    /** Whether users can type /name to invoke (default true). */
+    userInvocable?: boolean;
+}
+/**
+ * A slash command a host performed itself instead of running a model turn for
+ * it (`book -p "/review"`, `query({ prompt: '/review' })`).
+ *
+ * Both renderings travel together because both hosts consume it: `output` is
+ * what a human reads, `data` is the command's own machine contract (`/review`
+ * projects `ReviewJsonReport` from `review/host.ts`). Carrying it on the result
+ * rather than only writing it to stdout is what keeps an SDK caller — whose
+ * stdout is a discard sink — from paying for the work and receiving nothing.
+ */
+interface HostCommandResult {
+    /** Command name as the user typed it (an alias, possibly). */
+    command: string;
+    output?: string;
+    data?: unknown;
+}
+
+/** What triggered a compaction attempt. */
+type CompactTrigger = 'manual' | 'auto';
+/**
+ * What the agent loop knows about the request behind a compaction and the
+ * compactor cannot see for itself. Hosts forward these into `RunCompactOptions`
+ * unchanged.
+ */
+interface CompactRequestHints {
+    /**
+     * The provider has just rejected the request as too large. The compactor
+     * must keep only the short tail: the residual tail was sized for a window
+     * the provider has said it does not have, and the loop gets one retry.
+     */
+    recovery?: boolean;
+    /**
+     * Estimated tokens of the request outside the history: system prompt, tool
+     * schemas, session state. The compaction target is measured against the
+     * preflight gate, which counts them.
+     */
+    requestOverheadTokens?: number;
+    /**
+     * The loop's estimate of the request whose provider-measured usage is being
+     * passed as pressure. Together they measure how far the estimator undercounts
+     * this session's text, and the target shrinks by that ratio.
+     */
+    estimatedRequestTokens?: number;
+}
+/**
+ * Result of `runCompact`. Discriminated so hosts can clear usage only on success
+ * and avoid treating blocked/too-short outcomes as a history rewrite.
+ */
+type CompactResult = {
+    status: 'compacted';
+    trigger: CompactTrigger;
+    replacementHistory: Message[];
+    summary: string;
+    compactId: string;
+    generation: number;
+    checkpoint: ConversationCheckpointV2;
+    checkpointVersion: 2;
+    summarizedCount: number;
+    retainedCount: number;
+    postContextTokens: number;
+    throughEventRef?: string;
+    preContextTokens?: number;
+    preMessageCount: number;
+    strategy?: 'single-pass' | 'multi-pass' | 'degraded-fallback';
+    modelCalls?: number;
+    degraded?: boolean;
+    warning?: string;
+} | {
+    status: 'skipped';
+    reason: 'too-short' | 'blocked' | 'disabled';
+    message?: string;
+} | {
+    status: 'failed';
+    reason: 'provider-error' | 'empty-summary' | 'aborted' | 'unexpected-stream' | 'invalid-checkpoint' | 'budget-overflow';
+    error: string;
+};
+interface CompactBoundary {
+    id: string;
+    trigger: CompactTrigger;
+    transcriptOrdinal: number;
+    preContextCount: number;
+    postContextCount: number;
+    preContextTokens?: number;
+    postContextTokens?: number;
+    generation: number;
+    checkpointVersion: 1 | 2;
+    timestamp: number;
+}
+interface RewindCheckpointMetadata {
+    snapshotId?: string;
+    gitHead?: string;
+    entryCount?: number;
+    logicalBytes?: number;
+    codeUnavailableReason?: string;
+}
+interface RewindTarget extends RewindCheckpointMetadata {
+    id: string;
+    userEventId: string;
+    prompt: string;
+    attachments?: ImageAttachment[];
+    timestamp: number;
+    codeAvailable: boolean;
+}
+interface SessionRecord {
+    type: 'user' | 'assistant' | 'local' | 'tool_call' | 'tool_result' | 'usage' | 'session_meta' | 'compact' | 'turn_checkpoint' | 'rewind' | 'plan';
+    eventId?: string;
+    timestamp: number;
+    data: unknown;
+}
+/**
+ * Payload stored in a SessionRecord of type `plan` — last record wins.
+ *
+ * The plan is the only long-horizon state with no other home: todos live on the
+ * per-invocation ToolContext and the task graph on the in-process SessionRuntime,
+ * so both die at process exit.
+ *
+ * Readers must tolerate absence: `SessionStore.load` dispatches record types with
+ * no default branch, so an older binary ignores this record rather than failing.
+ */
+interface PlanRecordData {
+    version: 1;
+    todos?: PersistedTodo[];
+    tasks?: AgentTask[];
+}
+interface PersistedTodo {
+    content: string;
+    status: string;
+    activeForm?: string;
+}
+interface CheckpointSourceRef {
+    eventRef: string;
+    quote?: string;
+    toolResultRef?: string;
+}
+type CompactCoverageReason = 'pass-limit' | 'context-overflow' | 'invalid-checkpoint' | 'post-budget';
+interface ConversationCheckpointCoverage {
+    /** This generation's coverage. Answers "is the checkpoint I just made sound?" */
+    status: 'complete' | 'degraded';
+    reasons: CompactCoverageReason[];
+    /**
+     * The accumulated record across every generation of this conversation. Kept
+     * separate because merging it into `status` made the signal saturate: one
+     * degraded generation marked every later one, so within a few hours of a long
+     * run everything read `degraded` and the flag stopped carrying information.
+     * Optional: absent on checkpoints written before the split.
+     */
+    lifetime?: {
+        status: 'complete' | 'degraded';
+        reasons: CompactCoverageReason[];
+    };
+    processedMessages: number;
+    omittedMessages: number;
+    partiallyProcessedMessages: number;
+    firstProcessedEventRef?: string;
+    lastProcessedEventRef?: string;
+}
+/**
+ * One user-authored constraint, recorded verbatim by the host.
+ *
+ * Host-owned: the reducer never writes this. It is extracted from the user's
+ * own turns by `agent/carried-ledger.ts` and re-attached after every
+ * generation, which is what lets it outlive the model-authored narrative that
+ * `fitCheckpoint` is free to rewrite.
+ */
+interface CarriedConstraint {
+    /** Stable across generations: derived from the normalized text. */
+    id: string;
+    /** The user's sentence, unrewritten. Truncated only past `CARRIED_ENTRY_MAX_CHARS`. */
+    text: string;
+    /**
+     * How explicit the user was. `strong` is an unambiguous directive ("must",
+     * "never", "do not"); `weak` is a softer steer ("only", "avoid", "prefer").
+     * The cap evicts `weak` before `strong`.
+     */
+    strength: 'strong' | 'weak';
+    /** The user turn the text came from. Never minimized away by the fitter. */
+    source: CheckpointSourceRef;
+    /** Generation at which the entry was first recorded. */
+    firstSeenGeneration: number;
+    /** Generation at which the user last restated it. */
+    lastSeenGeneration: number;
+    /** Id of the later entry that restates this one, when the host detected one. */
+    supersededBy?: string;
+}
+/**
+ * The Carried Ledger: a monotonic, host-owned record of what the user asked
+ * for, ordered oldest to newest and never reordered.
+ *
+ * `fitCheckpoint` may not evict from it. Its growth is bounded by its own cap
+ * (`capCarriedLedger`) instead, so "the fitter cannot touch it" does not turn
+ * into "it eats the checkpoint budget".
+ */
+interface CarriedLedger {
+    version: 1;
+    /** Oldest first. Later entries win over earlier ones on conflict. */
+    constraints: CarriedConstraint[];
+    /** Entries the cap had to drop. Non-zero means the ledger is lossy. */
+    droppedCount?: number;
+}
+interface ConversationCheckpointV2 {
+    version: 2;
+    generation: number;
+    state: {
+        summary: string;
+        status: 'active' | 'blocked' | 'complete' | 'unknown';
+    };
+    constraints: Array<{
+        text: string;
+        scope: 'global' | 'workspace' | 'task' | 'unknown';
+        sources: CheckpointSourceRef[];
+    }>;
+    files: Array<{
+        path: string;
+        summary: string;
+        sources: CheckpointSourceRef[];
+        observation?: FileObservation;
+    }>;
+    episodes: Array<{
+        task: string;
+        outcome: string;
+        status: 'complete' | 'partial' | 'failed' | 'unknown';
+        sources: CheckpointSourceRef[];
+    }>;
+    openThreads: Array<{
+        text: string;
+        sources: CheckpointSourceRef[];
+    }>;
+    statistics: {
+        summarizedMessages: number;
+        retainedMessages: number;
+        preTokens: number;
+        postTokens: number;
+    };
+    /** Missing on older V2 checkpoints, which are treated as complete. */
+    coverage?: ConversationCheckpointCoverage;
+    /**
+     * Host-owned verbatim user constraints. Absent on checkpoints written before
+     * the Carried Ledger, and absent when the conversation stated no constraint.
+     */
+    carried?: CarriedLedger;
+}
+interface SessionMeta {
+    id: string;
+    name?: string;
+    cwd: string;
+    createdAt: number;
+    updatedAt: number;
+    messageCount: number;
+}
+interface LoadedSession {
+    transcript: Message[];
+    contextHistory: Message[];
+    compactBoundaries: CompactBoundary[];
+    rewindTargets: RewindTarget[];
+    activeEventIds: string[];
+    meta: SessionMeta;
+    /**
+     * The newest `plan` record, if the session ever wrote one. Absent means no plan
+     * was ever recorded; present-but-empty means it was deliberately cleared. That
+     * distinction is what lets a resumed run tell "nothing to do" from "my plan did
+     * not survive the restart".
+     */
+    plan?: PlanRecordData;
+    /**
+     * Token totals recorded by earlier processes of this session, summed from the
+     * `usage` records. USD is deliberately not stored: pricing changes between
+     * processes, so cost is re-derived from these tokens at bootstrap.
+     */
+    carriedUsage?: Usage;
+    /** Models those tokens were spent on, for re-deriving the cost. */
+    carriedModels?: string[];
+    /** @deprecated Use contextHistory. */
+    history: Message[];
+}
+interface SessionHistorySearchResult {
+    ref: string;
+    role: Message['role'];
+    preview: string;
+    timestamp: number;
+}
+/** Minimal interface for SessionStore, defined here to avoid circular imports. */
+interface SessionStoreInterface {
+    create(meta: {
+        cwd: string;
+        name?: string;
+        id?: string;
+    }): string;
+    append(id: string, record: SessionRecord): void;
+    patchMeta(id: string, patch: {
+        name?: string;
+    }): void;
+    touch(id: string): void;
+    load(id: string): LoadedSession;
+    readRecords?(id: string): SessionRecord[];
+    fork?(sourceId: string, meta: {
+        cwd: string;
+        name?: string;
+        id?: string;
+    }): string;
+    searchCurrent?(id: string, query: string, limit?: number): SessionHistorySearchResult[];
+    readCurrent?(id: string, refs: string[]): Array<{
+        ref: string;
+        content: string;
+    }>;
+    listRewindTargets?(id: string): RewindTarget[];
+    listSnapshotReferences?(cwd: string): Set<string>;
+    list(): SessionMeta[];
+    findByName(name: string): SessionMeta | undefined;
+    findById(id: string): SessionMeta | undefined;
+    mostRecentInCwd(cwd: string): SessionMeta | undefined;
+    saveImageAttachment?(sessionId: string, image: {
+        bytes: Uint8Array;
+        mediaType: ImageAttachment['mediaType'];
+        displayName?: string;
+    }): ImageAttachment;
+    readImageAttachment?(sessionId: string, attachment: ImageAttachment): Uint8Array;
+    cleanup(days: number, preserveIds?: ReadonlySet<string>): number;
+}
+
+type ProviderContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+    data: string;
+};
+interface SystemPromptZones {
+    /** Cacheable session-stable system prompt prefix. */
+    cachedPrefix: string;
+    /** Dynamic per-turn system prompt suffix, such as the active todo list. */
+    dynamicSuffix: string;
+}
+interface ProviderMessage {
+    role: string;
+    content: string | ProviderContentPart[] | SystemPromptZones | null;
+    /** Prior assistant reasoning to replay as provider context when supported. */
+    reasoningContent?: string;
+    providerMetadata?: ProviderMessageMetadata;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+}
+interface ProviderStreamEvent {
+    type: 'text' | 'reasoning' | 'tool_call' | 'done' | 'error';
+    content?: string;
+    reasoning?: string;
+    toolCall?: ToolCall;
+    error?: string;
+    /** Stable machine-readable provider/transport classification when available. */
+    errorCode?: string;
+    usage?: Usage;
+    /** Provider response identity when the stream exposes it. */
+    responseModel?: string;
+    responseId?: string;
+    finishReasons?: string[];
+    providerMetadata?: ProviderMessageMetadata;
+}
+interface ProviderResponseMetadata {
+    provider: string;
+    requestedModel: string;
+    responseModel?: string;
+    responseId?: string;
+    finishReasons?: string[];
+}
+interface AgentLoopCallbacks {
+    onText: (text: string) => void;
+    /** Called with provider-native reasoning deltas, displayed separately from answer text. */
+    onReasoning?: (text: string) => void;
+    onToolCall: (call: ToolCall) => void;
+    onToolResult: (result: ToolResult) => void;
+    onError: (error: string) => void;
+    /**
+     * The current attempt was abandoned and the same turn is being retried, so
+     * everything already delivered for it should be dropped.
+     *
+     * Deltas are handed over as they arrive and cannot be recalled, so without
+     * this a retried turn leaves the abandoned attempt's text sitting in front of
+     * its replacement while persisted history keeps only the replacement. Holding
+     * the deltas back instead would render a long thinking phase as silence, which
+     * is the failure this whole path exists to stop showing people.
+     */
+    onAttemptDiscarded?: () => void;
+    onTurnStart: (turn: number) => void;
+    onDone: () => void;
+    /** Final runtime outcome. Emitted once; onError remains diagnostic only. */
+    onTerminal?: (outcome: AgentTerminalOutcome) => void;
+    onPermissionRequired: (toolCall: ToolCall) => Promise<PermissionResult | PermissionDecision>;
+    /** Reads the host's current permission mode while an agent loop is active. */
+    getMode?: () => PermissionMode;
+    /** @deprecated use onUsage for real token counts from the API. */
+    onTokenCount?: (count: number) => void;
+    onUsage?: (usage: Usage, response?: ProviderResponseMetadata) => void;
+    /** Called when a tool changes the live permission mode. */
+    onModeChange?: (mode: PermissionMode) => void;
+    /** Called when ExitPlanMode submits a plan for host approval. */
+    onPlanApprovalRequired?: (plan: string) => Promise<PlanApprovalResult>;
+    /**
+     * Called when the user approves a plan with "fresh context" (`approve-fresh`).
+     * The loop restores the pre-plan mode and stops the current turn; the host is
+     * responsible for reseeding a fresh context with the approved plan.
+     */
+    onPlanHandoff?: (handoff: {
+        plan: string;
+        mode: PermissionMode;
+    }) => void;
+    /** Called when the root agent or a Task subagent needs structured user input. */
+    onUserQuestionRequired?: UserQuestionHandler;
+    /**
+     * Called when the context approaches its limit mid-loop, and as the last
+     * resort after the provider rejects a request as too large (`hints.recovery`).
+     * Return a CompactResult; only `status: 'compacted'` replaces loop history.
+     * Hosts forward `hints` into `RunCompactOptions` unchanged.
+     */
+    onCompact?: (history: Message[], usage: Usage | null, hints?: CompactRequestHints) => Promise<CompactResult>;
+    /**
+     * Called when an assistant turn (including tool results) is finalized.
+     * Hosts should persist this immediately rather than slicing the final history.
+     */
+    onAssistantMessageComplete?: (message: Message) => void;
+    /** Called after each tool execution with the current agent todo list. */
+    onTodos?: (todos: Array<{
+        content: string;
+        status: string;
+        activeForm?: string;
+    }>) => void;
+    /**
+     * Fires after a tool wave that may have mutated the task graph, mirroring
+     * `onTodos`. The task tools have no callback of their own, so this is the seam a
+     * host uses to persist the plan; it fires per wave, not per mutation.
+     */
+    onTasks?: (tasks: AgentTask[]) => void;
+    /**
+     * A user-role message the loop itself appended (a continuation, a work-state
+     * refresh). Hosts write the user message before `send`, so without this the only
+     * writer to the session file never sees these and a `--resume` reads a
+     * conversation with unexplained gaps between assistant turns.
+     */
+    onUserMessageAppended?: (message: Message) => void;
+    /** Called when a transport-level retry starts (delay > 0). */
+    onRetry?: (phase: RetryPhase, attempt: number, max: number, delayMs: number) => void;
+    /** Called when the response stream stalls (no data for streamStallTimeoutMs). */
+    onStreamStall?: (countdownMs: number) => void;
+    /** Called when data resumes after a stream stall. */
+    onStreamResume?: () => void;
+    /**
+     * Called when the user picks "always allow" at a permission prompt — so the
+     * host can persist a Tool(specifier) rule (CC-aligned approval flow). The
+     * `rule` string is canonical (e.g. `Bash(npm install)` or `Read`).
+     */
+    onPersistPermissionRule?: (rule: string) => void;
+    /** Called when a hook lifecycle event fires (for --include-hook-events in stream-json mode). */
+    onHookEvent?: (event: string, payload: Record<string, unknown>) => void;
+    /** Called for managed-agent lifecycle, evidence, and application events. */
+    onAgentEvent?: (event: AgentRuntimeEvent) => void;
+}
+
+interface ProviderStreamOptions {
+    signal?: AbortSignal;
+    onRetry?: (attempt: number, max: number, delayMs: number) => void;
+    onStreamStall?: (countdownMs: number) => void;
+    onStreamResume?: () => void;
+    maxOutputTokens?: number;
+}
+interface Provider {
+    readonly id: string;
+    stream(config: AgentConfig, messages: ProviderMessage[], tools: ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderStreamEvent>;
+}
+
+interface SessionHistoryCapability {
+    store: SessionStoreInterface;
+    sessionId: () => string;
+}
+
+interface PreparedToolCall {
+    call: ToolCall;
+    tool: ToolDefinition;
+    timeoutMs: number;
+}
+type PrepareToolCallResult = {
+    status: 'ready';
+    prepared: PreparedToolCall;
+} | {
+    status: 'rejected';
+    result: ToolResult;
+};
+declare function createRegistry(): {
+    normalizeCall: (call: ToolCall) => ToolCall;
+    register(tool: ToolDefinition): void;
+    registerAll(toolList: ToolDefinition[]): void;
+    getTool(name: string): ToolDefinition | undefined;
+    getDefinitions(): ToolDefinition[];
+    prepare(call: ToolCall, context: ToolContext): PrepareToolCallResult;
+    executePrepared(prepared: PreparedToolCall, context: ToolContext, maxRetries?: number): Promise<ToolResult>;
+    execute(call: ToolCall, context: ToolContext, maxRetries?: number): Promise<ToolResult>;
+};
+type ToolRegistry = ReturnType<typeof createRegistry>;
+
+declare function createDefaultRegistry(capabilities?: {
+    sessionHistory?: SessionHistoryCapability;
+    agents?: boolean;
+}): ToolRegistry;
+
+type TodoStatus = 'pending' | 'in_progress' | 'completed';
+interface Todo {
+    content: string;
+    status: TodoStatus;
+    activeForm?: string;
+}
+
+/**
+ * A subagent definition loaded from .book/agents/<name>.md or
+ * ~/.book/agents/<name>.md. Matches Claude Code's subagent model.
+ */
+interface SubagentDef {
+    /** Name used for invocation via the Task tool. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** Strict capability rules. Empty denies all tools; `*` explicitly inherits. */
+    allowedTools: string[];
+    /** Override model for this subagent (optional). */
+    model?: string;
+    /** Maximum turns for this subagent. Undefined = unlimited. */
+    maxTurns?: number;
+    effort?: string;
+    isolation?: 'workspace-readonly' | 'worktree';
+    color?: string;
+    unknownTools?: string[];
+    /** The raw Markdown body — injected as the subagent's system prompt. */
+    body: string;
+    /** Source directory. */
+    source: 'user' | 'project' | 'builtin';
+}
+
+interface StaticDiscovery {
+    fingerprint: string;
+    skills: ReturnType<typeof discoverSkills>;
+    commands: SlashCommand[];
+    projectInstructions: string;
+    agents: SubagentDef[];
+}
+declare class AgentContextCache {
+    private readonly discoveries;
+    private readonly turnFingerprints;
+    private readonly turnGit;
+    beginTurn(): void;
+    invalidateGit(workspace: string): void;
+    invalidateWorkspace(workspace: string): void;
+    discovery(workspace: string): StaticDiscovery;
+    git(workspace: string, signal?: AbortSignal): Promise<string>;
+}
+
+/** Session-scoped concurrency bound for tools explicitly reviewed as parallel-safe. */
+declare class ToolExecutionScheduler {
+    private active;
+    private limit;
+    private readonly queue;
+    constructor(limit?: number);
+    setLimit(limit: number): void;
+    run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    private acquire;
+    private releasePermit;
+    private drain;
+}
+
+type BudgetStatus = AgentRunAccounting['budgetStatus'];
+interface CarriedSpend {
+    usage: Usage | null;
+    /** Null when a prior process could not price some of its spend. */
+    costUsd: number | null;
+}
+interface BudgetCheck {
+    allowed: boolean;
+    status: Exclude<BudgetStatus, 'not_configured'>;
+    message?: string;
+}
+/**
+ * In-memory accounting shared by all executions in one logical session.
+ *
+ * Missing provider-attempt usage is recorded only when such an attempt actually occurs.
+ */
+declare class RunAccounting {
+    private readonly roots;
+    private ensureExecution;
+    startRoot(context: AgentRunContext, budgetUsd?: number): void;
+    /**
+     * Restore spend recorded by earlier processes of the same root.
+     *
+     * Idempotent per root: the seed replaces rather than accumulates, so calling it
+     * twice with the same restored total cannot double-charge the budget.
+     */
+    seedRoot(rootRunId: string, carried: CarriedSpend): void;
+    startExecution(context: AgentRunContext): void;
+    record(context: AgentRunContext, usage: Usage, metadata: ProviderResponseMetadata): void;
+    markUsageUnknown(context: AgentRunContext, metadata: ProviderResponseMetadata, source: string): void;
+    checkBeforeModelCall(rootRunId: string, requestedModel: string): BudgetCheck;
+    /** Has a root by this id been started in THIS process? */
+    hasRoot(rootRunId: string): boolean;
+    /**
+     * The live budgeted root that work from a dead process should join.
+     *
+     * A managed agent re-driven after a restart still carries the previous
+     * process's `rootRunId`. Nothing recreates that root here, so `startExecution`
+     * would mint it with no `budgetUsd` and `checkBeforeModelCall` would then allow
+     * every call unconditionally — while the host's own gate stayed green, because
+     * the spend never reached its inclusive total either. Undefined when the answer
+     * is ambiguous, so adoption is never a guess.
+     */
+    budgetedRootRunId(): string | undefined;
+    snapshotRun(runId: string): AgentRunAccounting | undefined;
+    snapshotRoot(rootRunId: string): AgentRunAccounting;
+    snapshotAll(): AgentRunAccounting;
+    private makeSnapshot;
+}
+
+interface Sandbox {
+    /**
+     * Resolve a shell command into a sandboxed argv spawn.
+     *
+     * `workspaceRoot` is the only directory bound writable by default, and it is
+     * deliberately not the command's working directory: `workdir` is a
+     * model-supplied tool argument, and binding it would let the model widen its
+     * own sandbox to any path — `workdir: "/"` would shadow every other mount and
+     * hand back the whole host filesystem, read-write. Callers must keep the
+     * working directory inside the workspace; extra paths go through
+     * `sandbox.filesystem.allowWrite`.
+     *
+     * Returns null if the sandbox is unavailable.
+     */
+    wrap(command: string, workspaceRoot: string): CommandExecution | null;
+    /** One-line description of the policy actually enforced, for diagnostics. */
+    describe(): string;
+}
+
+interface SessionRuntimeOptions {
+    tasks?: AgentTask[];
+    todos?: Todo[];
+    backgroundShells?: BackgroundShellStore;
+    fileObservationLedger?: Map<string, FileObservation>;
+    toolDiscoveryState?: ToolDiscoveryState;
+    agentContextCache?: AgentContextCache;
+    toolExecutionScheduler?: ToolExecutionScheduler;
+    runAccounting?: RunAccounting;
+    runAmbientSnapshots?: Map<string, AgentRunAmbientSnapshot>;
+    traceId?: string;
+    skillRegistry?: SkillRegistry;
+    /** Skill root discovery options, shared by the registry and the watcher so they agree. */
+    skillDiscoveryOptions?: DiscoverSkillsOptions;
+}
+/** Mutable resources owned by one logical agent session. */
+declare class SessionRuntime {
+    readonly tasks: AgentTask[];
+    /**
+     * The session's todo list. A readonly *binding* over a mutable array, matching
+     * `tasks` — the loop seeds `ToolContext.todos` from it per invocation and
+     * TodoWrite mutates it in place, so the plan survives across invocations within
+     * one process and can be rehydrated from a `plan` record after a restart.
+     */
+    readonly todos: Todo[];
+    /**
+     * Set by a host that resumed a session with prior work but no persisted plan.
+     * Surfaced once in `<session-state>` so a dropped plan is a visible event.
+     */
+    planUnrestored: boolean;
+    readonly backgroundShells: BackgroundShellStore;
+    readonly fileObservationLedger: Map<string, FileObservation>;
+    readonly toolDiscoveryState: ToolDiscoveryState;
+    readonly agentContextCache: AgentContextCache;
+    readonly toolExecutionScheduler: ToolExecutionScheduler;
+    readonly traceId: string;
+    readonly runAccounting: RunAccounting;
+    readonly runAmbientSnapshots: Map<string, AgentRunAmbientSnapshot>;
+    readonly shellManager: ShellJobManager;
+    private sandboxInstance?;
+    private skillRegistry?;
+    private readonly skillDiscoveryOptions;
+    private skillWatcher?;
+    private skillWatcherWorkspace?;
+    private skillCatalogDirty;
+    private skillWatcherFailure?;
+    private readonly skillChangeListeners;
+    /** Advisory memory of recent identical tool failures (registry circuit breaker). */
+    readonly recentToolFailures: Map<string, number>;
+    /** Per-session tool call/failure counters keyed by canonical tool name. */
+    readonly toolCallStats: Map<string, {
+        calls: number;
+        failures: Record<string, number>;
+    }>;
+    agentManager?: AgentManager;
+    private readonly abortControllers;
+    private readonly timers;
+    private readonly childProcesses;
+    private disposed;
+    constructor(options?: SessionRuntimeOptions);
+    /**
+     * The session's sandbox, built once per distinct settings object.
+     *
+     * Building it per Bash call would re-emit its startup diagnostics — the
+     * unenforceable-domain-policy and skipped-path warnings — on every single
+     * command, interleaved into the Ink render or the headless stderr stream.
+     */
+    sandbox(settings: ResolvedSettings['sandbox']): Sandbox | null;
+    skills(workspace: string, settings: SkillSettings): SkillRegistry;
+    reloadSkills(workspace: string, settings: SkillSettings, cause?: string): SkillRegistry;
+    consumeSkillChanges(workspace: string, settings: SkillSettings): SkillRegistry;
+    subscribeSkillChanges(workspace: string, listener: () => void, enabled?: boolean): () => void;
+    get skillWatcherError(): string | undefined;
+    inspectSkills(currentTurn?: number): SkillRegistrySnapshot | undefined;
+    private ensureSkillWatcher;
+    private stopSkillWatcher;
+    trackAbortController(controller: AbortController): AbortController;
+    releaseAbortController(controller: AbortController): void;
+    trackTimer(timer: NodeJS.Timeout): NodeJS.Timeout;
+    releaseTimer(timer: NodeJS.Timeout): void;
+    trackChildProcess(child: ChildProcess$1): ChildProcess$1;
+    releaseChildProcess(child: ChildProcess$1): void;
+    recordRunAmbientSnapshot(runId: string, snapshot: AgentRunAmbientSnapshot): AgentRunAmbientSnapshot;
+    snapshotRunAmbient(runId: string): AgentRunAmbientSnapshot | undefined;
+    get isDisposed(): boolean;
+    /** Dispose every resource registered by this session exactly once. */
+    dispose(reason?: string): void;
+}
+
+declare function runAgentLoop(config: AgentConfig, registry: ToolRegistry, userMessage: string, history: Message[], callbacks: AgentLoopCallbacks, mode?: string, options?: {
+    signal?: AbortSignal;
+    isNewSession?: boolean;
+    /** When false, the host owns SessionStart/SessionEnd boundaries. */
+    manageSessionHooks?: boolean;
+    commands?: SlashCommand[];
+    allowedTools?: string[];
+    modelOverride?: string;
+    /** User-facing text to retain in history when userMessage is expanded context. */
+    displayMessage?: string;
+    /** Stable host-assigned identity for the user event. */
+    userMessageId?: string;
+    userMessageTimestamp?: number;
+    userFileObservations?: Message['fileObservations'];
+    userAttachments?: Message['attachments'];
+    resolveAttachment?: (attachment: ImageAttachment) => Promise<Uint8Array> | Uint8Array;
+    userMessageKind?: Message['kind'];
+    /** The prompt was resolved from a command or delegated, not typed by the user. */
+    userMessageDerived?: boolean;
+    /** Synthetic host notifications bypass user-authored prompt hooks and memory capture. */
+    skipUserPromptHooks?: boolean;
+    /** Host identity for each streamed assistant turn. */
+    assistantMessageId?: (turn: number) => string | undefined;
+    /** True when this loop is a subagent (Task tool) invocation — skips memory auto-capture. */
+    isSubagent?: boolean;
+    /**
+     * True when nobody is watching this run, so a refusal cannot be resolved by
+     * asking. Set by headless and the SDK; the TUI leaves it false.
+     */
+    unattended?: boolean;
+    /**
+     * Liveness writer for the run's status file, supplied by the host that owns
+     * the session. Subagents and managed agents call this loop directly, so
+     * letting the loop create its own would make "is the run alive" ambiguous.
+     */
+    statusWriter?: RunStatusWriter;
+    /** Display-only observer for tools invoked by this subagent. */
+    nestedToolObserver?: NestedToolObserver;
+    /** Trace id of the Task invocation that launched this subagent loop. */
+    parentToolTraceId?: string;
+    /** Nested agent names from the root agent to this loop. */
+    agentPath?: string[];
+    /** Extra managed-agent identity and policy appended to the system prompt. */
+    systemPromptAppend?: string;
+    /**
+     * Injected by tests. The loop reads it only for durations — how long this
+     * run has been going, how long a tool took — never for a stamp anything
+     * else will read.
+     */
+    clock?: Clock;
+    /** Hide delegation discovery from child agents. */
+    hideAgents?: boolean;
+    /** Managed child identity and parent-session attribution. */
+    agentId?: string;
+    agentRole?: AgentRole;
+    parentSessionId?: string;
+    /** Non-owning managed-agent coordinator used by child-only evidence tools. */
+    agentManager?: ToolContext['agentManager'];
+    /** Mutable resources owned by the logical session. */
+    runtime?: SessionRuntime;
+    /** Frozen attribution for this root or linked child execution. */
+    runContext?: AgentRunContext;
+    /** Override user-local oversized tool-output storage (primarily for isolated hosts/tests). */
+    toolOutputRoot?: string;
+    /** Override user-local tool-use telemetry storage (primarily for isolated hosts/tests). */
+    toolTelemetryRoot?: string;
+    /** User-global store for learned context window ceilings (primarily for isolated tests). */
+    modelWindowStore?: ModelWindowStore;
+    provider?: Provider;
+}): Promise<Message[]>;
+
+interface RunCompactOptions extends CompactRequestHints {
+    trigger: CompactTrigger;
+    focus?: string;
+    upcomingUserIntent?: string;
+    sessionId?: string;
+    preContextTokens?: number;
+    signal?: AbortSignal;
+    onHookEvent?: (event: string, payload: Record<string, unknown>) => void;
+    minMessages?: number;
+    provider?: Provider;
+    beforeModelCall?: (model: string) => {
+        allowed: boolean;
+        message?: string;
+    };
+    onUsage?: (usage: Usage, metadata: ProviderResponseMetadata) => void;
+    onUsageMissing?: (metadata: ProviderResponseMetadata) => void;
+    /** Overrides the reducer output cap for controlled evaluation experiments. */
+    checkpointMaxTokens?: number;
+    /** Overrides reducer reasoning effort for controlled evaluation experiments. */
+    effort?: AgentConfig['effort'];
+}
+declare function runCompact(config: AgentConfig, history: readonly Message[], options: RunCompactOptions): Promise<CompactResult>;
+
+declare function findGitRoot(workspace: string): Promise<string | undefined>;
+declare function createSyntheticSnapshot(workspace: string, includeUntracked?: boolean): Promise<AgentSnapshot>;
+declare function createAgentWorktree(snapshot: AgentSnapshot, agentId: string, worktreeRoot?: string, startCommit?: string): Promise<{
+    path: string;
+    branch: string;
+}>;
+declare function removeSnapshotRef(snapshot: AgentSnapshot): Promise<void>;
+declare function checkoutAgentCommit(worktree: string, commit: string): Promise<void>;
+declare function commitAgentWork(record: AgentRecord, snapshot: AgentSnapshot): Promise<PatchCandidate | undefined>;
+declare function applyVerifiedCandidate(snapshot: AgentSnapshot, candidate: PatchCandidate): Promise<AgentApplyResult>;
+
+type AtomicWriteOperation = 'lock' | 'serialize' | 'write' | 'fsync' | 'rename';
+type AtomicWriteResult = {
+    status: 'ok';
+    target: string;
+    attempts: number;
+    elapsedMs: number;
+} | {
+    status: 'busy';
+    target: string;
+    tempPath?: string;
+    operation: 'lock' | 'rename';
+    attempts: number;
+    elapsedMs: number;
+} | {
+    status: 'unavailable';
+    target: string;
+    tempPath?: string;
+    operation: AtomicWriteOperation;
+    errorCode?: string;
+    message: string;
+    attempts: number;
+    elapsedMs: number;
+};
+interface AtomicLockOwner {
+    schemaVersion: 1;
+    instanceId: string;
+    pid: number;
+    hostname: string;
+    createdAt: number;
+}
+interface AtomicJsonWriterOptions {
+    instanceId: string;
+    pid?: number;
+    hostname: string;
+    deadlineMs?: number;
+    now?: () => number;
+    randomId?: () => string;
+    sleep?: (milliseconds: number) => void;
+    isLockOwnerAlive?: (owner: AtomicLockOwner) => boolean;
+    staleLockMs?: number;
+    onStaleLock?: (target: string) => void;
+    fs?: Partial<AtomicJsonFileSystem>;
+}
+interface AtomicJsonFileSystem {
+    closeSync: typeof closeSync;
+    existsSync: typeof existsSync;
+    fsyncSync: typeof fsyncSync;
+    openSync: typeof openSync;
+    readFileSync: typeof readFileSync;
+    renameSync: typeof renameSync;
+    statSync: typeof statSync;
+    unlinkSync: typeof unlinkSync;
+    writeFileSync: typeof writeFileSync;
+}
+declare class AtomicJsonWriter {
+    private readonly fs;
+    private readonly instanceId;
+    private readonly pid;
+    private readonly hostname;
+    private readonly deadlineMs;
+    private readonly staleLockMs;
+    private readonly now;
+    private readonly randomId;
+    private readonly sleep;
+    private readonly isLockOwnerAlive?;
+    private readonly onStaleLock?;
+    constructor(options: AtomicJsonWriterOptions);
+    write(target: string, value: unknown, preparedTemp?: string): AtomicWriteResult;
+    private pause;
+    private reclaimStaleLock;
+}
+
+interface AgentStoreCleanup {
+    agents: AgentRecord[];
+    snapshots: AgentSnapshot[];
+}
+interface AgentStorePersistenceEvent {
+    type: 'agent_persistence';
+    state: 'degraded' | 'recovered';
+    reason: 'busy' | 'unavailable';
+    errorCode?: string;
+    message: string;
+    agentId?: string;
+    retrying: boolean;
+    timestamp: number;
+}
+interface AgentStoreOptions {
+    instanceId?: string;
+    pid?: number;
+    hostname?: string;
+    now?: () => number;
+    processStartedAt?: number;
+    heartbeatMs?: number;
+    leaseFreshMs?: number;
+    setTimeout?: typeof setTimeout;
+    clearTimeout?: typeof clearTimeout;
+    processAlive?: (pid: number) => boolean;
+    eventSink?: (event: AgentStorePersistenceEvent) => void;
+    writer?: AtomicJsonWriter;
+    writerOptions?: Omit<AtomicJsonWriterOptions, 'instanceId' | 'hostname'>;
+}
+declare class AgentStore {
+    readonly directory: string;
+    readonly instanceId: string;
+    private readonly statePath;
+    private readonly agentsDirectory;
+    private readonly agentSummariesDirectory;
+    private readonly plansDirectory;
+    private readonly evidenceDirectory;
+    private readonly snapshotsDirectory;
+    private readonly instancesDirectory;
+    private readonly leasePath;
+    private readonly pid;
+    private readonly hostname;
+    private readonly processStartedAt;
+    private readonly heartbeatMs;
+    private readonly leaseFreshMs;
+    private readonly now;
+    private readonly schedule;
+    private readonly cancel;
+    private readonly processAlive;
+    private readonly eventSink?;
+    private readonly writer;
+    private enabled;
+    private disposed;
+    private heartbeatTimer?;
+    private persistenceState;
+    private readonly agents;
+    private readonly agentOwners;
+    private readonly summaryAgentIds;
+    private readonly plans;
+    private readonly evidence;
+    private readonly snapshots;
+    private readonly pendingWrites;
+    constructor(repoHash: string, root?: string, enabled?: boolean, options?: AgentStoreOptions);
+    private ensureDirectories;
+    private safeLog;
+    private quarantine;
+    private readJson;
+    private targetMatchesId;
+    private loadDirectory;
+    private load;
+    private migrateAgent;
+    private agentPath;
+    private agentSummaryPath;
+    private agentSummary;
+    private planPath;
+    private evidencePath;
+    private snapshotPath;
+    private ownerMetadata;
+    private persistedAgent;
+    private discardFailedRequiredWrite;
+    private cancelPendingWrite;
+    private queueWrite;
+    private flushPending;
+    private schedulePending;
+    private enterDegraded;
+    private maybeRecover;
+    private flushAll;
+    listAgents(): AgentRecord[];
+    loadAgent(id: string): AgentRecord | undefined;
+    listPlans(): AgentPlanRecord[];
+    listEvidence(): EvidenceItem[];
+    listSnapshots(): AgentSnapshot[];
+    saveAgent(agent: AgentRecord, options?: {
+        defer?: boolean;
+        required?: boolean;
+    }): AtomicWriteResult;
+    removeAgent(agentId: string): void;
+    removePlan(planId: string): void;
+    removeEvidence(evidenceId: string): void;
+    removeSnapshot(snapshotId: string): void;
+    savePlan(plan: AgentPlanRecord): AtomicWriteResult;
+    saveEvidence(evidence: EvidenceItem, options?: {
+        required?: boolean;
+    }): AtomicWriteResult;
+    saveSnapshot(snapshot: AgentSnapshot): AtomicWriteResult;
+    recoverAbandonedAgents(): AgentRecord[];
+    markActiveInterrupted(): AgentRecord[];
+    isOwnedByCurrent(agentId: string): boolean;
+    isOwnedByLiveForeign(agentId: string): boolean;
+    hasPendingAgent(agentId: string): boolean;
+    getPersistenceState(): 'healthy' | 'degraded_busy' | 'degraded_unavailable';
+    cleanupDetailed(retentionDays: number): AgentStoreCleanup;
+    cleanup(retentionDays: number): number;
+    appendTelemetry(event: Record<string, unknown>): void;
+    dispose(): void;
+    private refreshForeignSummaries;
+    private refreshLease;
+    private scheduleHeartbeat;
+    private defaultProcessAlive;
+    private isInstanceAlive;
+    private isLockOwnerAlive;
+    private parseTemp;
+    private recoverTemps;
+}
+
+interface ManagerOptions {
+    storeRoot?: string;
+    worktreeRoot?: string;
+    eventSink?: (event: AgentRuntimeEvent) => void;
+    hookEventSink?: (event: string, payload: Record<string, unknown>) => void;
+    runLoop?: typeof runAgentLoop;
+    compactRunner?: typeof runCompact;
+    findGitRoot?: typeof findGitRoot;
+    createSnapshot?: typeof createSyntheticSnapshot;
+    createWorktree?: typeof createAgentWorktree;
+    checkoutWorktree?: typeof checkoutAgentCommit;
+    commitWork?: typeof commitAgentWork;
+    applyCandidate?: typeof applyVerifiedCandidate;
+    removeWorktree?: (record: AgentRecord, repoRoot?: string) => Promise<void>;
+    removeSnapshot?: typeof removeSnapshotRef;
+    runtime?: SessionRuntime;
+    permissionMode?: string;
+    persistPermissionRule?: (rule: string) => void;
+    createStore?: (repoHash: string, root: string | undefined, enabled: boolean) => AgentStore;
+}
+interface SubscribeOptions {
+    snapshot?: boolean;
+}
+interface PublishEvidenceInput {
+    kind: EvidenceKind;
+    summary: string;
+    confidence?: number;
+    references?: EvidenceReference[];
+}
+declare class AgentManager {
+    private config;
+    private readonly parentDefinitions;
+    private readonly options;
+    private store?;
+    private repoRoot?;
+    private initialized?;
+    private readonly agents;
+    private readonly hydratedAgentIds;
+    private readonly plans;
+    private readonly evidence;
+    private readonly snapshots;
+    private readonly planSnapshots;
+    private readonly snapshotPromises;
+    private readonly queue;
+    private readonly controllers;
+    private readonly questionResolvers;
+    private readonly permissionResolvers;
+    private readonly permissionRules;
+    private readonly activities;
+    private readonly waiters;
+    private readonly idleWaiters;
+    private active;
+    private interactivePermissions;
+    private permissionMode;
+    private permissionModeOverride?;
+    private readonly subscribers;
+    private legacyEventSink?;
+    private readonly textBuffers;
+    private readonly textTimers;
+    private hookEventSink?;
+    private exitHandler?;
+    private disposed;
+    private persistenceState;
+    constructor(config: AgentConfig, parentDefinitions: ToolDefinition[], options?: ManagerOptions);
+    setEventSink(sink?: (event: AgentRuntimeEvent) => void, hookSink?: (event: string, payload: Record<string, unknown>) => void): void;
+    updateConfig(config: AgentConfig): void;
+    hasActiveProfile(profile: string): boolean;
+    setInteractivePermissions(enabled: boolean): void;
+    setPermissionMode(mode: string | undefined): void;
+    resolvePermission(agentId: string, requestId: string, response: 'allow' | 'deny' | 'always'): Promise<AgentRecord>;
+    resolveQuestion(agentId: string, response: UserQuestionResponse): Promise<AgentRecord>;
+    recordRoutingTelemetry(event: string, data?: Record<string, unknown>): void;
+    subscribe(listener: (event: AgentRuntimeEvent) => void, options?: SubscribeOptions): () => void;
+    listPendingCompletions(): Promise<AgentCompletionNotification[]>;
+    acknowledgeCompletion(deliveryId: string): Promise<void>;
+    waitForIdle(): Promise<void>;
+    private ensureInitialized;
+    private hydrateAgent;
+    private agentListRecord;
+    dispose(): void;
+    private notifyIdle;
+    private emit;
+    private recordForReturn;
+    private assertMutable;
+    getPersistenceState(): 'healthy' | 'degraded_busy' | 'degraded_unavailable';
+    private handlePersistenceEvent;
+    private requirePersisted;
+    private queueTextDelta;
+    private flushTextDelta;
+    private persist;
+    private completionNotification;
+    private notify;
+    private definitions;
+    createPlan(input: {
+        taskShape: string;
+        issueQuality: IssueQuality;
+        topology: AgentTopology;
+        rationale: string;
+        agentBudget: number;
+        parentSessionId?: string;
+        rootRunId?: string;
+        parentRunId?: string;
+    }): Promise<AgentPlanRecord>;
+    listPlans(): Promise<AgentPlanRecord[]>;
+    private snapshotForPlan;
+    spawn(request: AgentSpawnRequest): Promise<AgentRecord>;
+    list(): Promise<AgentRecord[]>;
+    listProfiles(): Promise<Array<{
+        name: string;
+        description: string;
+        role: AgentRecord['role'];
+        isolation: NonNullable<AgentRecord['isolation']>;
+        resolvedModel: string;
+        configuredModel?: string;
+        color?: string;
+    }>>;
+    get(agentId: string): Promise<AgentRecord | undefined>;
+    dismiss(agentId: string): Promise<void>;
+    send(agentId: string, message: string, evidenceIds?: string[], runContext?: Pick<AgentRunContext, 'rootRunId' | 'runId'>): Promise<AgentRecord>;
+    wait(agentId: string, timeoutMs?: number): Promise<AgentRecord>;
+    stop(agentId: string, reason?: string): Promise<AgentRecord>;
+    publishEvidence(agentId: string, input: PublishEvidenceInput): Promise<EvidenceItem>;
+    listEvidence(options?: {
+        requesterAgentId?: string;
+        includeUnverified?: boolean;
+        ids?: string[];
+    }): Promise<EvidenceItem[]>;
+    reviewEvidence(reviewerAgentId: string, evidenceId: string, verdict: 'pass' | 'fail' | 'inconclusive', notes?: string): Promise<EvidenceItem>;
+    apply(agentId: string, evidenceId?: string): Promise<AgentApplyResult>;
+    private pump;
+    private evidenceContext;
+    private systemPrompt;
+    private run;
+    private telemetry;
+}
+
+type PermissionResult = 'allow' | 'deny' | 'always';
+/**
+ * An `always` answer that names the rule to persist.
+ *
+ * The rule was previously derived from the call alone, which meant a shell
+ * approval could only ever be written as the exact command string. An approver
+ * that lets the user widen the scope has to be able to say which rule they
+ * picked; approvers that do not simply keep returning the bare result.
+ */
+interface PermissionDecision {
+    result: PermissionResult;
+    /** Overrides the derived rule when the result is `always`. */
+    rule?: string;
+}
+/** Why a submitted plan was never applied when the host could not approve it. */
+type PlanNotAppliedReason = 'approval_unavailable' | 'approval_declined' | 'approval_cancelled' | 'invalid_approval_response';
+/**
+ * `stop` is the non-interactive terminal decision: no approver exists (or the
+ * approver refused to decide), so the run ends with the plan as its deliverable
+ * instead of asking the model to revise and resubmit forever.
+ */
+type PlanApprovalResult = 'approve' | 'approve-fresh' | 'reject' | {
+    decision: 'revise';
+    feedback: string;
+} | {
+    decision: 'stop';
+    reason: PlanNotAppliedReason;
+    message: string;
+};
+interface UserQuestionOption {
+    label: string;
+    description: string;
+}
+interface UserQuestion {
+    question: string;
+    header: string;
+    options: UserQuestionOption[];
+    multiSelect: boolean;
+}
+type UserQuestionSource = {
+    kind: 'root';
+    traceId?: string;
+} | {
+    kind: 'subagent';
+    agentPath: string[];
+    traceId?: string;
+};
+interface UserQuestionRequest {
+    id: string;
+    questions: UserQuestion[];
+    source: UserQuestionSource;
+}
+type UserQuestionResponse = {
+    action: 'answer';
+    answers: Record<string, string | string[]>;
+} | {
+    action: 'decline';
+    message?: string;
+} | {
+    action: 'cancel';
+    message?: string;
+};
+type UserQuestionHandler = (request: UserQuestionRequest, context: {
+    signal?: AbortSignal;
+}) => Promise<UserQuestionResponse>;
+/**
+ * One field of an MCP `elicitation/create` form, flattened from the protocol's
+ * restricted JSON Schema subset (top-level primitives only). Enum options come
+ * from either `enum`/`enumNames` or the `oneOf: [{const, title}]` spelling.
+ */
+type ElicitationField = {
+    name: string;
+    title: string;
+    description?: string;
+    required: boolean;
+} & ({
+    kind: 'string';
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    default?: string;
+} | {
+    kind: 'number';
+    integer: boolean;
+    minimum?: number;
+    maximum?: number;
+    default?: number;
+} | {
+    kind: 'boolean';
+    default?: boolean;
+} | {
+    kind: 'enum';
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    default?: string;
+});
+interface ElicitationRequest {
+    id: string;
+    /** Declared name of the MCP server asking, so the user can see who is asking. */
+    server: string;
+    message: string;
+    fields: ElicitationField[];
+}
+type ElicitationValue = string | number | boolean;
+type ElicitationResponse = {
+    action: 'accept';
+    content: Record<string, ElicitationValue>;
+} | {
+    action: 'decline';
+} | {
+    action: 'cancel';
+};
+type ElicitationHandler = (request: ElicitationRequest, context: {
+    signal?: AbortSignal;
+}) => Promise<ElicitationResponse>;
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** Display-only trace for a tool invoked inside a Task subagent. */
+interface NestedToolInvocation {
+    /** Globally unique UI identity. Raw provider tool-call ids may repeat across subagents. */
+    traceId: string;
+    /** Trace id of the Task invocation that directly launched this tool. */
+    parentTraceId: string;
+    call: ToolCall;
+    result?: ToolResult;
+}
+/** Optional observer used by hosts that want live visibility into subagent tools. */
+interface NestedToolObserver {
+    onToolCall: (invocation: NestedToolInvocation) => void;
+    onToolResult: (traceId: string, result: ToolResult) => void;
+}
+interface FileMutationSummary {
+    kind: 'create' | 'update' | 'delete';
+    filePath: string;
+    addedLines: number;
+    removedLines: number;
+}
+type ToolResultStatus = 'success' | 'error' | 'blocked' | 'cancelled' | 'timed_out';
+interface ToolResultError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    remediation?: string;
+    details?: Record<string, unknown>;
+}
+interface ToolResultPresentation {
+    kind: 'text' | 'markdown' | 'diff' | 'file' | 'command' | 'search' | 'task' | 'agent';
+    summary: string;
+    details?: string;
+    metadata?: string[];
+    target?: string;
+}
+interface ToolResultArtifacts {
+    fileMutation?: FileMutationSummary;
+    /** All mutations produced by a transactional multi-file tool call. */
+    fileMutations?: FileMutationSummary[];
+    fileObservations?: FileObservation[];
+    eventRef?: string;
+    /** User-local file containing the complete output when model-facing content is clipped. */
+    outputPath?: string;
+}
+/** V2 result contract shared by runtime, persistence, SDK, and TUI. */
+interface ToolResult<TData = unknown> {
+    version: 2;
+    toolCallId: string;
+    status: ToolResultStatus;
+    /** Concise provider-facing content. */
+    content: string;
+    /** Machine-readable payload for consumers that should not parse content. */
+    data?: TData;
+    structuredError?: ToolResultError;
+    presentation?: ToolResultPresentation;
+    metrics?: {
+        durationMs?: number;
+        retryAttempt?: number;
+    };
+    artifacts?: ToolResultArtifacts;
+    pagination?: {
+        cursor?: string;
+        nextCursor?: string;
+        truncated?: boolean;
+        omittedItems?: number;
+        omittedBytes?: number;
+    };
+}
+/** JSON-schema subset accepted by provider tool definitions. */
+interface JsonSchemaObject extends Record<string, unknown> {
+    type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    title?: string;
+    description?: string;
+    properties?: Record<string, JsonSchemaObject>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchemaObject;
+    items?: JsonSchemaObject;
+    enum?: Array<string | number | boolean | null>;
+    const?: string | number | boolean | null;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+    oneOf?: JsonSchemaObject[];
+    anyOf?: JsonSchemaObject[];
+}
+type ToolCategory = 'filesystem' | 'shell' | 'git' | 'web' | 'planning' | 'tasks' | 'skills' | 'agents' | 'evidence' | 'session' | 'notebook' | 'mcp' | 'other';
+type ToolEffect = 'read' | 'write' | 'execute' | 'network' | 'delegate' | 'interactive';
+interface ToolCatalogMetadata {
+    /** Search terms in addition to the canonical tool name. */
+    aliases?: string[];
+    keywords?: string[];
+    category?: ToolCategory;
+    namespace?: string;
+    /** Tool is always available in the practical core, normally deferred, or runtime-gated. */
+    exposure?: 'core' | 'deferred' | 'runtime';
+    /** Agent roles allowed to discover and invoke this definition. */
+    roles?: Array<'root' | 'child'>;
+    effects?: ToolEffect[];
+    /** Optional runtime predicate for stateful tools such as background shells. */
+    available?: (context: ToolContext) => boolean;
+    /** Short catalog summary; descriptions remain the full provider-facing guidance. */
+    summary?: string;
+}
+interface ToolPolicy {
+    idempotent?: boolean;
+    concurrency?: 'parallel' | 'serial';
+    requiresPermission?: boolean;
+}
+type FileObservationOperation = 'read' | 'mention' | 'edit' | 'write' | 'create' | 'notebook-read';
+interface FileObservation {
+    path: string;
+    workspaceId: string;
+    sha256: string;
+    byteSize: number;
+    lineStart?: number;
+    lineEnd?: number;
+    operation: FileObservationOperation;
+    sourceRef: string;
+    timestamp: number;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /** Typed provider schema. `parameters` remains accepted while tools migrate. */
+    inputSchema?: JsonSchemaObject;
+    /** Cross-harness argument-name aliases (alias → canonical), applied before validation. */
+    argumentAliases?: Record<string, string>;
+    /** Per-item argument aliases for array arguments (argument name → alias → canonical). */
+    arrayItemArgumentAliases?: Record<string, Record<string, string>>;
+    catalog?: ToolCatalogMetadata;
+    policy?: ToolPolicy;
+    /** When true, the tool is safe to retry once on transient failure (Read, Grep, WebFetch, etc.). */
+    idempotent?: boolean;
+    /**
+     * Default deadline in milliseconds, and a declaration that the tool enforces
+     * its own. The registry gives such a tool a grace margin on top so the tool's
+     * report — which carries whatever output it captured — is the one that wins.
+     * A function form lets a tool whose deadline comes from settings (Check) keep
+     * both sides reading the same number.
+     */
+    timeoutMs?: number | ((context: ToolContext) => number | undefined);
+    execute: (args: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
+}
+interface ToolContext {
+    workspaceRoot: string;
+    env: Record<string, string>;
+    /** Explicit environment overrides safe to persist for opt-in persistent jobs. */
+    envOverrides?: Record<string, string>;
+    /** Glob patterns to ignore during file discovery (e.g. from .gitignore). */
+    gitignorePatterns?: string[];
+    /** Resolved sandbox settings for the Bash tool. */
+    sandbox?: ResolvedSettings['sandbox'];
+    /** The shell the Bash tool spawns for unsandboxed commands; resolved on demand when absent. */
+    shell?: ResolvedShell;
+    /** The active AgentConfig, set by the agent loop before tool execution. */
+    agentConfig?: AgentConfig;
+    /** Abort signal shared with nested Task subagents. */
+    signal?: AbortSignal;
+    /** Stable trace identity of the tool currently executing. */
+    currentToolTraceId?: string;
+    /** Current model-loop turn, used for bounded skill activation frames. */
+    currentTurn?: number;
+    /** Observer for display-only tools invoked inside Task subagents. */
+    nestedToolObserver?: NestedToolObserver;
+    /**
+     * Agent todo list — written by TodoWrite, read by the loop for context injection.
+     * Bound to the array `SessionRuntime` owns; TodoWrite mutates it in place rather
+     * than reassigning, so the runtime, the session-state render, and the plan
+     * persistence writer all observe the same list.
+     */
+    todos?: Array<{
+        content: string;
+        status: string;
+        activeForm?: string;
+    }>;
+    /** Agent task list — written by TaskCreate/TaskUpdate and shared across tool calls. */
+    tasks?: AgentTask[];
+    /** Background shells started by Bash(run_in_background), shared across tool calls. */
+    backgroundShells?: BackgroundShellStore;
+    shellManager?: ShellJobManager;
+    /** Runtime-only newest file observation per workspace/path. */
+    fileObservationLedger?: Map<string, FileObservation>;
+    /** Live permission mode for the active agent loop; tools may update this. */
+    currentMode?: PermissionMode;
+    /** Mode to restore after a tool-initiated plan-mode session exits. */
+    previousMode?: PermissionMode;
+    /** Plan text submitted by ExitPlanMode and awaiting host approval. */
+    pendingPlanApproval?: {
+        plan: string;
+    };
+    /** Structured questions submitted by AskUserQuestion and awaiting the host. */
+    pendingUserQuestion?: {
+        questions: UserQuestion[];
+    };
+    /** Host interaction capability propagated into Task subagents. */
+    userQuestionHandler?: UserQuestionHandler;
+    /** Nested agent names from the root agent to this loop. */
+    agentPath?: string[];
+    /** Active definitions used to derive a child's capability intersection. */
+    availableTools?: ToolDefinition[];
+    /** Managed-agent runtime shared by the parent session. */
+    agentManager?: AgentManager;
+    /** Identity set only inside a managed child. */
+    agentId?: string;
+    agentRole?: AgentRole;
+    /** Parent session attribution for managed agents and hooks. */
+    parentSessionId?: string;
+    /** Root/parent execution attribution for managed agents and evidence. */
+    runContext?: AgentRunContext;
+    /** Host sink for managed-agent lifecycle and evidence events. */
+    onAgentEvent?: (event: AgentRuntimeEvent) => void;
+    /** Host sink used by lifecycle hooks started from managed-agent tools. */
+    onHookEvent?: (event: string, payload: Record<string, unknown>) => void;
+    /** Per-session capability/discovery controller installed by the agent loop. */
+    toolDiscovery?: ToolDiscoveryContext;
+    /** Mutable resources owned by the current session, separate from configuration. */
+    runtime?: SessionRuntime;
+}
+interface ToolSearchMatch {
+    name: string;
+    description: string;
+    summary: string;
+    category: ToolCategory;
+    namespace?: string;
+    loaded: boolean;
+}
+interface ToolDiscoveryContext {
+    /** Return authorized catalog matches without exposing their full schemas. */
+    search(query: string, category?: ToolCategory, namespace?: string, limit?: number): ToolSearchMatch[];
+    /** Activate selected definitions for the next provider request. */
+    activate(names: string[]): string[];
+    /** Intersect the current surface with an additional command/skill capability policy. */
+    restrict(rules: string[]): void;
+    /** Add a scoped capability intersection and return a disposer that restores the parent surface. */
+    pushRestriction(rules: string[]): () => void;
+    /** Preview the authorized definitions after an additional scoped intersection. */
+    previewRestriction(rules: string[]): ToolDefinition[];
+    /** Whether a tool is currently visible and executable for this turn. */
+    canExecute(call: ToolCall): boolean;
+    /** Definitions to send to the provider for the current request. */
+    activeDefinitions(): ToolDefinition[];
+    /** Compact catalog text used by the system prompt. */
+    catalogSummary(): string;
+}
+interface ToolDiscoveryState {
+    /** Monotonic access counter used for deterministic LRU eviction. */
+    clock: number;
+    loaded: Map<string, number>;
+}
+
+/**
+ * Resolve settings from all scopes: user → project → local.
+ * Priority: Local > Project > User.
+ *
+ * @param workspace - Project root directory
+ * @param overridePath - Optional path to an ad-hoc settings file (--settings flag)
+ * @returns Fully resolved settings with all defaults filled
+ */
+interface SettingsResolutionPaths {
+    home?: string;
+    userSettingsPath?: string;
+    projectSettingsPath?: string;
+    localSettingsPath?: string;
+    trustStorePath?: string;
+}
+
+interface LoadConfigOptions {
+    /** Path to an ad-hoc settings file (--settings flag); takes highest priority. */
+    settingsOverridePath?: string;
+    /** If true, skip all settings.json layers entirely (use defaults + legacy .bookrc.json). */
+    noSettings?: boolean;
+    /** Run storage migrations after effective settings are validated. */
+    runMigrations?: boolean;
+    /** CLI -m/--model override, applied before provider registry resolution. */
+    modelOverride?: string;
+    /**
+     * CLI --effort override. Passed in rather than assigned after the fact so it
+     * counts as an explicit choice: model metadata must not override a level the
+     * user typed, and providers that gate on `effortExplicit` must see it.
+     */
+    effortOverride?: AgentConfig['effort'];
+    /**
+     * Redirect individual settings layers. Pointing one at a path that does not
+     * exist drops it from the merge, which is how `book doctor` finds the layer a
+     * failure first appears in.
+     */
+    settingsPaths?: SettingsResolutionPaths;
+    /** Let the interactive TUI start before a BYOK credential has been added. */
+    allowMissingApiKey?: boolean;
+    /** Optional store for learned context window ceilings. */
+    modelWindowStore?: ModelWindowStore;
+}
+declare function loadConfig(workspace?: string, options?: LoadConfigOptions): AgentConfig;
+
+type AgentEvent = {
+    type: 'run_started';
+    context: AgentRunContext;
+    ambient: AgentRunAmbientSnapshot;
+} | {
+    type: 'system';
+    model: string;
+    cwd: string;
+} | {
+    type: 'session';
+    sessionId: string;
+} | {
+    type: 'text';
+    content: string;
+} | {
+    type: 'reasoning';
+    content: string;
+} | {
+    type: 'tool_use';
+    toolCall: ToolCall;
+} | {
+    type: 'tool_result';
+    toolResult: ToolResult;
+} | {
+    type: 'user_question';
+    request: UserQuestionRequest;
+    status: 'pending' | 'unavailable';
+} | {
+    type: 'user_question_result';
+    requestId: string;
+    response: UserQuestionResponse;
+} | ShellJobEvent | {
+    type: 'agent_start';
+    agent: AgentRecord;
+} | {
+    type: 'agent_update';
+    agent: AgentRecord;
+} | {
+    type: 'agent_result';
+    agent: AgentRecord;
+} | Extract<AgentRuntimeEvent, {
+    type: 'agent_question' | 'agent_apply' | 'agent_status' | 'agent_activity' | 'agent_text_delta' | 'agent_message' | 'agent_completion' | 'agent_permission' | 'agent_persistence' | 'skill_lifecycle';
+}> | {
+    type: 'evidence_update';
+    evidence: EvidenceItem;
+} | {
+    type: 'attempt_discarded';
+    reason: 'empty_response';
+} | {
+    type: 'error';
+    error: string;
+} | {
+    type: 'result';
+    messages: Message[];
+    usage: Usage | null;
+    sessionId: string;
+    outcome?: AgentTerminalOutcome;
+    runContext?: AgentRunContext;
+    runs?: AgentRunResult[];
+    /**
+     * Slash commands the host performed itself rather than sending to the
+     * model. Present for SDK callers, whose stdout is a discard sink and who
+     * would otherwise have no way to read a `/review` they paid for.
+     */
+    commandResults?: HostCommandResult[];
+} | {
+    type: 'terminal';
+    outcome: AgentTerminalOutcome;
+    runContext?: AgentRunContext;
+} | {
+    type: 'done';
+};
+type AgentSessionStatus = 'idle' | 'running' | 'waiting_for_user' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'interrupted';
+interface AgentSessionSnapshot {
+    status: AgentSessionStatus;
+    sessionId?: string;
+    model?: string;
+    cwd?: string;
+    assistantText: string;
+    toolCalls: ToolCall[];
+    toolResults: ToolResult[];
+    pendingUserQuestion?: UserQuestionRequest;
+    agents: AgentRecord[];
+    evidence: EvidenceItem[];
+    messages: Message[];
+    usage: Usage | null;
+    terminal?: AgentTerminalOutcome;
+    runContext?: AgentRunContext;
+    ambient?: AgentRunAmbientSnapshot;
+    error?: string;
+}
+declare function createAgentSessionSnapshot(): AgentSessionSnapshot;
+declare function reduceAgentSessionSnapshot(snapshot: AgentSessionSnapshot, event: AgentEvent): AgentSessionSnapshot;
+
+interface SurfaceOptions {
+    config: AgentConfig;
+    context: ToolContext;
+    definitions: ToolDefinition[];
+    capabilityRules?: string[];
+    isSubagent?: boolean;
+}
+declare function createToolSurface(options: SurfaceOptions): ToolDiscoveryContext;
+
+interface ToolResultOptions<TData> {
+    toolCallId?: string;
+    data?: TData;
+    presentation?: Partial<ToolResultPresentation>;
+    artifacts?: ToolResultArtifacts;
+    pagination?: ToolResult['pagination'];
+}
+declare function toolSuccess<TData = unknown>(content: string, options?: ToolResultOptions<TData>): ToolResult<TData>;
+declare function toolFailure(message: string, options?: ToolResultOptions<unknown> & {
+    code?: string;
+    status?: Exclude<ToolResultStatus, 'success'>;
+    retryable?: boolean;
+    remediation?: string;
+    details?: Record<string, unknown>;
+    content?: string;
+}): ToolResult;
+
+declare const SKILL_EVALUATION_CATEGORIES: readonly ["direct", "indirect", "negative", "ambiguous", "conflicting", "disabled", "invalid", "missing-body", "missing-resource"];
+type SkillEvaluationCategory = (typeof SKILL_EVALUATION_CATEGORIES)[number];
+interface SkillEvaluationFixture {
+    id: string;
+    category: SkillEvaluationCategory;
+    promptHash: string;
+    expectedSkills: string[];
+    expectedBlockedCodes?: string[];
+}
+interface SkillEvaluationPromptFixture {
+    id: string;
+    category: SkillEvaluationCategory;
+    prompt: string;
+    expectedSkills: string[];
+    expectedBlockedCodes?: string[];
+}
+interface SkillEvaluationOutcome {
+    promptChars?: number;
+    promptTokens?: number;
+    bodyTokens?: number;
+    taskCompleted?: boolean;
+    userCorrections?: number;
+    skillToolFailures?: number;
+    exposure?: 'eager' | 'deferred';
+    activationTurns?: number;
+}
+interface SkillEvaluationObservation extends SkillEvaluationFixture {
+    activatedSkills: string[];
+    blockedCodes: string[];
+    promptChars: number;
+    promptTokens: number;
+    bodyBytes: number;
+    bodyTokens: number;
+    falseActivationBytes: number;
+    activationLatencyMs: number[];
+    consentRequests: number;
+    unnecessaryPermissionPrompts: number;
+    taskCompleted?: boolean;
+    userCorrections: number;
+    skillToolFailures: number;
+    blockingMismatch: boolean;
+    exposure?: 'eager' | 'deferred';
+    activationTurns?: number;
+}
+interface SkillEvaluationThresholds {
+    minimumPrecision: number;
+    minimumRecall: number;
+    maximumFalseActivations: number;
+    maximumUnnecessaryPermissionPrompts: number;
+    maximumSkillToolFailures: number;
+}
+interface SkillEvaluationExecution {
+    evidenceKind: 'offline-observation';
+    providerRunEligibility: 'not-applicable';
+    controls: {
+        evaluationDate: string;
+        randomSeed: string;
+        runtimeRevision: string;
+        fixtureRevision: string;
+        fixtureRevisionStatus: 'captured' | 'incomplete';
+    };
+}
+interface SkillEvaluationReport {
+    generatedAt: string;
+    fixtureCount: number;
+    categoryCounts: Record<SkillEvaluationCategory, number>;
+    truePositives: number;
+    falsePositives: number;
+    falseNegatives: number;
+    precision: number;
+    recall: number;
+    falseActivationBytes: number;
+    promptChars: {
+        total: number;
+        median: number;
+    };
+    promptTokens: {
+        total: number;
+        median: number;
+    };
+    bodyBytes: {
+        total: number;
+        median: number;
+    };
+    bodyTokens: {
+        total: number;
+        median: number;
+    };
+    activationLatencyMs: {
+        median: number;
+        p95: number;
+    };
+    consentRequests: number;
+    unnecessaryPermissionPrompts: number;
+    taskCompletionRate?: number;
+    userCorrections: number;
+    skillToolFailures: number;
+    blockingMismatches: number;
+    exposure: Record<'eager' | 'deferred', {
+        samples: number;
+        activationRate: number;
+        medianActivationTurns: number;
+    }>;
+    thresholds: SkillEvaluationThresholds;
+    rolloutReady: boolean;
+    reasons: string[];
+    observations: SkillEvaluationObservation[];
+    evaluation?: SkillEvaluationExecution;
+}
+declare const DEFAULT_SKILL_EVALUATION_THRESHOLDS: SkillEvaluationThresholds;
+declare const DEFAULT_SKILL_EVALUATION_FIXTURES: readonly SkillEvaluationPromptFixture[];
+/** Convert bounded lifecycle evidence into one prompt-free evaluation observation. */
+declare function observeSkillEvaluation(fixture: SkillEvaluationFixture, events: readonly SkillLifecycleEvent[], outcome?: SkillEvaluationOutcome): SkillEvaluationObservation;
+declare function evaluateSkillActivation(observations: readonly SkillEvaluationObservation[], thresholds?: SkillEvaluationThresholds): SkillEvaluationReport;
+declare function runSkillActivationEvaluation(fixtures: readonly SkillEvaluationPromptFixture[], execute: (fixture: SkillEvaluationPromptFixture) => Promise<{
+    events: readonly SkillLifecycleEvent[];
+    outcome?: SkillEvaluationOutcome;
+}>, thresholds?: SkillEvaluationThresholds): Promise<SkillEvaluationReport>;
+declare function renderSkillEvaluationReport(report: SkillEvaluationReport): string;
+declare function writeSkillEvaluationReport(report: SkillEvaluationReport, jsonPath: string, markdownPath?: string): void;
+
+/** Render a body-free diagnostic report suitable for commands, logs, and SDK consumers. */
+declare function buildSkillReport(snapshot: SkillRegistrySnapshot | undefined): string;
+
+interface EvaluationFixture {
+    id: string;
+    cohort: 'decomposable' | 'ambiguous' | 'sequential';
+    prompt: string;
+}
+interface EvaluationRunResult {
+    passed: boolean;
+    validationCorrect?: boolean;
+    wallTimeMs: number;
+    totalTokens?: number;
+    costUsd?: number;
+    spawnCount?: number;
+    route?: AgentTopology;
+    issueQuality?: IssueQuality;
+    conflicts?: number;
+    interruptions?: number;
+    unvalidatedApplications?: number;
+}
+interface EvaluationMetric extends Omit<EvaluationRunResult, 'route' | 'issueQuality'> {
+    fixtureId: string;
+    promptHash: string;
+    cohort: EvaluationFixture['cohort'];
+    mode: Extract<AgentMode, 'adaptive' | 'off'>;
+    route?: AgentTopology;
+    issueQuality?: IssueQuality;
+}
+/** Run each fixture with the single-agent control and adaptive treatment. */
+declare function runPairedEvaluation(fixtures: EvaluationFixture[], execute: (fixture: EvaluationFixture, mode: Extract<AgentMode, 'adaptive' | 'off'>) => Promise<EvaluationRunResult>, outputPath: string): Promise<EvaluationMetric[]>;
+declare function evaluateSuccess(metrics: EvaluationMetric[]): {
+    successful: boolean;
+    reasons: string[];
+};
+
+/** Book Agent SDK — programmatic API for embedding Book as a library. */
+
+type QueryEvent = AgentEvent;
+interface QueryOptions {
+    workspace?: string;
+    model?: string;
+    permissionMode?: string;
+    maxTurns?: number;
+    settingsPath?: string;
+    noSettings?: boolean;
+    persistSession?: boolean;
+    sessionId?: string;
+    sessionStore?: SessionStoreInterface;
+    signal?: AbortSignal;
+    onUserQuestionRequired?: UserQuestionHandler;
+    /**
+     * Answer MCP form elicitations. Supplying it declares the elicitation
+     * capability to connected servers; without it they fail such requests
+     * themselves rather than blocking on a prompt no one can see.
+     */
+    onElicit?: ElicitationHandler;
+    agents?: 'adaptive' | 'manual' | 'off';
+    /** Forward high-volume managed-agent text deltas. Defaults to false. */
+    forwardSubagentText?: boolean;
+}
+declare function query(prompt: string, options?: QueryOptions): AsyncGenerator<QueryEvent, void, undefined>;
+
+declare function createAgentManager(config: AgentConfig): AgentManager;
+
+export { type AgentActivity, type AgentApplyResult, type AgentCompletion, type AgentCompletionNotification, type AgentEvent, AgentManager, type AgentModelIdentity, type AgentModelIdentityStatus, type AgentPlanRecord, type AgentProfile, type AgentRecord, type AgentRunAccounting, type AgentRunAmbientSnapshot, type AgentRunContext, type AgentRunMetrics, type AgentRunResult, type AgentRunSource, type AgentRuntimeEvent, type AgentSessionSnapshot, type AgentSessionStatus, type AgentSnapshot, type AgentSpawnRequest, type AgentSummary, type AgentTerminalOutcome, type AgentTerminalReason, type AgentTerminalStatus, DEFAULT_SKILL_EVALUATION_FIXTURES, DEFAULT_SKILL_EVALUATION_THRESHOLDS, type DiscoverSkillsOptions, type ElicitationField, type ElicitationHandler, type ElicitationRequest, type ElicitationResponse, type ElicitationValue, type EvaluationFixture, type EvaluationMetric, type EvaluationRunResult, type EvidenceItem, type JsonSchemaObject, type LoadConfigOptions, type LoadedSkillBody, type QueryEvent, type QueryOptions, SKILL_EVALUATION_CATEGORIES, SessionRuntime, type ShadowedSkill, type Skill, type SkillActivationFrame, type SkillActivationFrameSummary, type SkillActivationReason, type SkillEvaluationCategory, type SkillEvaluationFixture, type SkillEvaluationObservation, type SkillEvaluationOutcome, type SkillEvaluationPromptFixture, type SkillEvaluationReport, type SkillEvaluationThresholds, type SkillIssue, type SkillLifecycleEvent, type SkillLifecycleEventType, type SkillListingResult, SkillRegistry, SkillRegistryError, type SkillRegistrySnapshot, type SkillResource, type SkillRoot, type SkillRootKind, type SkillSource, type ToolCatalogMetadata, type ToolCategory, type ToolDefinition, type ToolDiscoveryContext, type ToolDiscoverySettings, type ToolEffect, type ToolPolicy, type ToolResult, type ToolResultArtifacts, type ToolResultError, type ToolResultPresentation, type ToolResultStatus, type ToolSearchMatch, type UserQuestion, type UserQuestionHandler, type UserQuestionOption, type UserQuestionRequest, type UserQuestionResponse, type UserQuestionSource, applySkillOverrides, buildSkillListing, buildSkillReport, createAgentManager, createAgentSessionSnapshot, createDefaultRegistry, createRegistry, createToolSurface, discoverSkills, evaluateSkillActivation, evaluateSuccess, explicitSkillMentions, generateSkillListing, loadConfig, loadSkillBody, observeSkillEvaluation, query, reduceAgentSessionSnapshot, renderSkillEvaluationReport, runPairedEvaluation, runSkillActivationEvaluation, skillRoots, toolFailure, toolSuccess, writeSkillEvaluationReport };