@letrquan/book 0.3.0 → 0.4.0-beta.0

package/dist/sdk.d.ts

@@ -56,6 +56,7 @@ interface Clock {
 declare const providerModelSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodString>;
     contextWindow: z.ZodOptional<z.ZodNumber>;
+    reportedContextWindow: z.ZodOptional<z.ZodNumber>;
     maxOutputTokens: z.ZodOptional<z.ZodNumber>;
     vision: z.ZodOptional<z.ZodBoolean>;
     manual: z.ZodOptional<z.ZodBoolean>;
@@ -81,6 +82,44 @@ declare const providerModelSchema: z.ZodObject<{
         }>>>;
     }, z.core.$strip>]>>;
 }, z.core.$strip>;
+declare const providerConfigSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodEnum<{
+        openai: "openai";
+        anthropic: "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>;
+        reportedContextWindow: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        vision: z.ZodOptional<z.ZodBoolean>;
+        manual: z.ZodOptional<z.ZodBoolean>;
+        editFormat: z.ZodOptional<z.ZodEnum<{
+            patch: "patch";
+            replace: "replace";
+            whole: "whole";
+        }>>;
+        effort: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            default: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                max: "max";
+            }>>;
+            levels: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+                max: "max";
+            }>>>;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 declare const toolDiscoverySettingsSchema: z.ZodObject<{
     mode: z.ZodDefault<z.ZodEnum<{
         auto: "auto";
@@ -122,6 +161,7 @@ declare const skillSettingsSchema: z.ZodObject<{
 }, z.core.$strip>;
 type SkillSettings = z.infer<typeof skillSettingsSchema>;
 type ProviderModelConfig = z.infer<typeof providerModelSchema>;
+type ProviderConfig = z.infer<typeof providerConfigSchema>;
 /** The supported production strategy. */
 declare const compactStrategySchema: z.ZodLiteral<"summary">;
 type CompactStrategy = z.infer<typeof compactStrategySchema>;
@@ -140,6 +180,7 @@ declare const bookSettingsSchema: z.ZodObject<{
         xhigh: "xhigh";
         max: "max";
     }>>;
+    advisorModel: z.ZodOptional<z.ZodString>;
     maxTurns: z.ZodOptional<z.ZodNumber>;
     maxTokens: z.ZodOptional<z.ZodNumber>;
     effort: z.ZodOptional<z.ZodEnum<{
@@ -184,6 +225,13 @@ declare const bookSettingsSchema: z.ZodObject<{
         approved: "approved";
         rejected: "rejected";
     }>>>;
+    workspaceProviders: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        fingerprint: z.ZodString;
+        choice: z.ZodEnum<{
+            approved: "approved";
+            rejected: "rejected";
+        }>;
+    }, z.core.$strip>>>;
     env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     provider: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         type: z.ZodDefault<z.ZodEnum<{
@@ -196,6 +244,7 @@ declare const bookSettingsSchema: z.ZodObject<{
         models: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
             label: z.ZodOptional<z.ZodString>;
             contextWindow: z.ZodOptional<z.ZodNumber>;
+            reportedContextWindow: z.ZodOptional<z.ZodNumber>;
             maxOutputTokens: z.ZodOptional<z.ZodNumber>;
             vision: z.ZodOptional<z.ZodBoolean>;
             manual: z.ZodOptional<z.ZodBoolean>;
@@ -241,6 +290,7 @@ declare const bookSettingsSchema: z.ZodObject<{
             allowWrite: z.ZodDefault<z.ZodArray<z.ZodString>>;
             denyWrite: z.ZodDefault<z.ZodArray<z.ZodString>>;
             denyRead: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            allowGitWrites: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>;
         network: z.ZodPrefault<z.ZodObject<{
             allowedDomains: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -316,6 +366,7 @@ declare const bookSettingsSchema: z.ZodObject<{
         requestTimeoutMs: z.ZodDefault<z.ZodNumber>;
         streamStallTimeoutMs: z.ZodDefault<z.ZodNumber>;
         thinkingStallTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        firstDeltaStallTimeoutMs: z.ZodDefault<z.ZodNumber>;
         toolRetries: z.ZodDefault<z.ZodNumber>;
         watchdog: z.ZodDefault<z.ZodBoolean>;
         streamReissueAttempts: z.ZodDefault<z.ZodNumber>;
@@ -324,15 +375,6 @@ declare const bookSettingsSchema: z.ZodObject<{
     memory: z.ZodPrefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         autoSave: z.ZodDefault<z.ZodBoolean>;
-        requireApproval: z.ZodDefault<z.ZodBoolean>;
-        quarantineExternal: z.ZodDefault<z.ZodBoolean>;
-        extraction: z.ZodPrefault<z.ZodObject<{
-            enabled: z.ZodDefault<z.ZodBoolean>;
-            idleHours: z.ZodDefault<z.ZodNumber>;
-            minMessages: z.ZodDefault<z.ZodNumber>;
-            maxPerSession: z.ZodDefault<z.ZodNumber>;
-            maxSessionsPerRun: z.ZodDefault<z.ZodNumber>;
-        }, z.core.$strip>>;
     }, z.core.$strip>>;
     continuation: z.ZodPrefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -345,8 +387,8 @@ declare const bookSettingsSchema: z.ZodObject<{
     agents: z.ZodPrefault<z.ZodObject<{
         mode: z.ZodDefault<z.ZodEnum<{
             manual: "manual";
-            adaptive: "adaptive";
             off: "off";
+            adaptive: "adaptive";
         }>>;
         maxConcurrent: z.ZodDefault<z.ZodNumber>;
         maxSpawned: z.ZodDefault<z.ZodNumber>;
@@ -423,31 +465,43 @@ type BookSettings = z.infer<typeof bookSettingsSchema>;
 /**
  * Resolved settings after layering (all defaults filled).
  */
-type ResolvedSettings = Required<Omit<BookSettings, 'model' | 'compactModel' | 'compactEffort' | 'maxTurns' | 'maxTokens' | 'effort' | 'theme' | 'shell' | 'autoCompactEnabled' | 'defaultMode' | 'disableBypassPermissionsMode'>> & Pick<BookSettings, 'model' | 'compactModel' | 'compactEffort' | 'maxTurns' | 'maxTokens' | 'effort' | 'theme' | 'shell' | 'autoCompactEnabled' | 'defaultMode' | 'disableBypassPermissionsMode'>;
+type ResolvedSettings = Required<Omit<BookSettings, 'model' | 'compactModel' | 'compactEffort' | 'advisorModel' | 'maxTurns' | 'maxTokens' | 'effort' | 'theme' | 'shell' | 'autoCompactEnabled' | 'defaultMode' | 'disableBypassPermissionsMode'>> & Pick<BookSettings, 'model' | 'compactModel' | 'compactEffort' | 'advisorModel' | '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' | 'superseded';
 interface MemoryFileSummary {
     name: string;
     path: string;
     type?: MemoryType;
-    status?: MemoryStatus;
     title?: string;
-    created?: string;
-    updated?: string;
+    /** The frontmatter `description`: what the memory is for, in a line. */
+    description?: string;
     size: number;
     driver?: SessionDriver;
+    /**
+     * The file still carries the retired `status: superseded` frontmatter of the old save tool. It
+     * is no longer retired by anything, so it loads like any other file; `/memory status` lists it
+     * as legacy.
+     */
+    legacySuperseded?: boolean;
 }
 interface LoadedMemoryContext {
     dir: string;
     indexFile: string | null;
     indexLoaded: boolean;
+    /** Non-empty lines in MEMORY.md (the whole file, not only what loaded). */
     indexLineCount: number;
+    /** Non-empty lines that loaded, the cut marker excluded. */
     loadedLineCount: number;
+    /** UTF-8 size of the trimmed MEMORY.md. */
+    indexByteCount: number;
+    /** The index was cut at the line limit. */
+    wasLineTruncated: boolean;
+    /** The index was cut at the byte limit. */
+    wasByteTruncated: boolean;
+    /** The loaded index; ends with a warning marker when it was cut. */
     indexText: string;
     files: MemoryFileSummary[];
-    candidates: MemoryFileSummary[];
 }
 
 interface LearnedModelWindowEntry {
@@ -461,6 +515,89 @@ interface ModelWindowStore {
     all(): Record<string, LearnedModelWindowEntry>;
 }
 
+/** A provider entry as a settings file wrote it: every key optional, nothing defaulted. */
+type ProviderDeclaration = Partial<ProviderConfig>;
+type WorkspaceProviderState = 'approved' | 'rejected' | 'pending';
+/** Override keys one workspace layer wrote for a provider a trusted layer defines. */
+interface DroppedProviderOverride {
+    path: string;
+    providerId: string;
+    /** Which of `baseURL`, `baseUrl`, `apiKey` and `type` the layer wrote. */
+    keys: string[];
+}
+/** A provider only workspace layers declare, merged across them, with what the user decides on. */
+interface WorkspaceProviderEntry {
+    id: string;
+    /** The merged declaration, later layers over earlier ones. */
+    declaration: ProviderDeclaration;
+    fingerprint: string;
+    /** Every layer that declared it, in merge order. */
+    layers: string[];
+}
+interface WorkspaceProviderPartition {
+    /** The user approved this exact declaration: it joins the resolved providers. */
+    approved: WorkspaceProviderEntry[];
+    /** No decision recorded for this declaration: withheld until the user makes one. */
+    pending: WorkspaceProviderEntry[];
+    /** Explicitly refused: withheld, and not re-offered. */
+    rejected: WorkspaceProviderEntry[];
+    /**
+     * A provider named {@link LEGACY_BASE_URL_ID}: that id is where the decision about a legacy
+     * `baseUrl` lives, so a decision recorded under it could not tell the two apart. Withheld
+     * whatever the trust store holds, and never offered for approval.
+     */
+    reserved: WorkspaceProviderEntry[];
+}
+/** A model selection a workspace layer made that names a withheld workspace provider. */
+interface WithheldModelSelection {
+    /** The slot: `model`, `compactModel`, `advisorModel` or `agents.profiles.<name>.model`. */
+    key: string;
+    value: string;
+    providerId: string;
+    /** The workspace layer the value came from. */
+    path: string;
+    /** What applies instead: the trusted layers' own value, or `undefined` when they set none. */
+    fallback: string | undefined;
+}
+/**
+ * A model selection the user's own settings, `--model` or the environment made, whose prefix
+ * names only a withheld workspace provider. It is unaffected: it resolves as it would had the
+ * workspace not declared that provider. Approving the provider is what would change that.
+ */
+interface UnaffectedModelSelection {
+    key: string;
+    value: string;
+    providerId: string;
+    /** Where it came from: a settings path, `--model` or an environment variable. */
+    source: string;
+}
+/** The legacy `.bookrc.json` `baseUrl`, and whether the user approved it. */
+interface LegacyBaseUrlGate {
+    baseUrl: string;
+    state: WorkspaceProviderState;
+}
+/**
+ * What the provider gate did to one resolution (#418), for the config that carries it and for the
+ * hosts that report it. Computed from the layer files themselves, never read back from a settings
+ * key a workspace layer could write. Build one with {@link createWorkspaceProviderGate}.
+ */
+interface WorkspaceProviderGate {
+    /** Provider ids only workspace layers define: they never inherit a key. */
+    declared: string[];
+    /** The subset of {@link declared} that is withheld (pending, rejected or reserved). */
+    withheld: string[];
+    /** The same ids sorted by the user's decision on the declaration as written. */
+    partition: WorkspaceProviderPartition;
+    /** Origin, key and protocol overrides a workspace layer wrote for a trusted provider; dropped. */
+    droppedOverrides: DroppedProviderOverride[];
+    /** Model selections that fell back to the trusted layers' value. */
+    withheldSelections: WithheldModelSelection[];
+    /** The user's own selections that name only a withheld provider, and so are unaffected. */
+    unaffectedSelections: UnaffectedModelSelection[];
+    /** The legacy `.bookrc.json` `baseUrl`, when the workspace has one. */
+    legacyBaseUrl?: LegacyBaseUrlGate;
+}
+
 type PermissionMode = 'default' | 'auto' | 'plan' | 'accept-edits' | 'dontAsk' | 'bypassPermissions';
 /**
  * A command resolved to a direct argv spawn — no intermediate shell parses it.
@@ -472,10 +609,16 @@ type PermissionMode = 'default' | 'auto' | 'plan' | 'accept-edits' | 'dontAsk' |
  * 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`).
+ *
+ * `env` holds variables the spawn must add to the child's environment, merged
+ * last over everything else. Git Bash and a POSIX-named sh on Windows receive
+ * their command there rather than in `args` (see `shellExecution`), so every
+ * site that spawns an `exec` must apply it to that spawn alone.
  */
 interface CommandExecution {
     file: string;
     args: string[];
+    env?: Record<string, string>;
 }
 /** The program that interprets a Bash tool command string. */
 type ShellKind = 'bash' | 'pwsh' | 'powershell' | 'cmd' | 'sh';
@@ -498,6 +641,17 @@ interface ResolvedShell {
     source: ShellSource;
     /** Set when a requested shell could not be honoured and the automatic ladder was used instead. */
     warning?: string;
+    /**
+     * Set on Windows for a `kind: 'bash'` or `kind: 'sh'` executable that runs on the MSYS runtime
+     * (Git for Windows' `bin\bash.exe`, `usr\bin\bash.exe` and `sh.exe`; MSYS2's `bash.exe`,
+     * `dash.exe`, `zsh.exe` and other POSIX shells), detected at resolution by `msys-2.0.dll` beside
+     * it, or in `..\usr\bin` for one in a `bin` directory (#532, #548). It does not decide delivery: every non-WSL bash and every
+     * POSIX-named sh gets its command out of band, flagged or not (`receivesCommandOutOfBand`). It
+     * only lets the permission scanner read `'` as on Linux (`readsSingleQuoteAsPosix`), because
+     * Windows CI proves this runtime's delivery. Never set off Windows, in a WSL launcher directory,
+     * or for a non-POSIX shell, a Cygwin shell or a shim or copy with no DLL beside it.
+     */
+    msys?: true;
 }
 /**
  * What phase of retry is currently active (drives the TUI spinner label).
@@ -538,6 +692,16 @@ interface RetryConfig {
     outputCapContinuations?: number;
     /** Stall ceiling while the model is thinking; absent falls back to the chat one. */
     thinkingStallTimeoutMs?: number;
+    /**
+     * First-delta ceiling for a model that may think silently (#379): how long a
+     * stream may stay quiet before its first content, tool-call or reasoning
+     * delta when the request sends no `reasoning_effort` and the model's catalog
+     * entry does not settle the question. A router that buffers the whole
+     * thinking block sends a role-only chunk and then nothing for up to about
+     * 80 s, past the chat ceiling. Optional, and absent falls back to the chat
+     * one, so a hand-built RetryConfig keeps the behavior it was written for.
+     */
+    firstDeltaStallTimeoutMs?: number;
 }
 type AgentTaskStatus = 'pending' | 'in_progress' | 'completed' | 'deleted';
 interface AgentTask {
@@ -592,6 +756,8 @@ interface BackgroundShellRecord {
     timer?: NodeJS.Timeout;
     retentionTimer?: NodeJS.Timeout;
     sandboxed?: boolean;
+    /** The sandbox's git-dir mode (issue 373): true = every git dir of the workspace read-only. */
+    gitDirReadOnly?: boolean;
 }
 interface BackgroundShellStore {
     nextId: number;
@@ -619,6 +785,8 @@ interface AgentConfig {
     modelProviderWarning?: string;
     /** Optional provider/model used only for historical conversation compaction. */
     compactModel?: string;
+    /** Optional stronger provider/model the `Advisor` tool consults (`/advisor`). */
+    advisorModel?: string;
     compactEffort?: AgentConfig['effort'];
     /** Supported production context-reduction strategy. */
     compactStrategy: CompactStrategy;
@@ -648,6 +816,24 @@ interface AgentConfig {
     /** Plain-model fallback values used after provider/model switches. */
     defaultApiKey?: string;
     defaultBaseUrl?: string;
+    /**
+     * Whether `defaultBaseUrl` was chosen with BOOK_BASE_URL rather than being the built-in OpenAI
+     * default or a legacy `.bookrc.json` `baseUrl` (a repository can ship that file, so it is no
+     * proof of the user's choice). Recorded at load, never inferred from the URL.
+     */
+    defaultBaseUrlExplicit?: boolean;
+    /**
+     * Provider ids only a workspace layer declares, computed by the loader from the layer files
+     * themselves (#418) -- never from a settings key, which a workspace layer could write. A
+     * declared provider never inherits a key, `BOOK_API_KEY` and the session key included; and a
+     * withheld one (pending, rejected or reserved) is absent from `settings.provider`, so a model id
+     * a workspace controls that names it is refused instead of falling through to the default
+     * endpoint, while the user's own selection with that prefix resolves as the plain fallback. The
+     * rest of the gate (what was dropped, which selections fell back or were left alone, the legacy
+     * `baseUrl`) is what the hosts report. It describes one resolution of the settings: whoever
+     * re-resolves them in a session replaces the gate with the one computed alongside.
+     */
+    workspaceProviderGate?: WorkspaceProviderGate;
     defaultProvider?: 'anthropic' | 'openai' | 'auto';
     autoCompactEnabled: boolean;
     /**
@@ -715,16 +901,29 @@ interface ShellStartOptions {
     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`.
+     * (on Windows Git Bash, a POSIX sh or PowerShell, where Git Bash and a POSIX
+     * sh carry the command in `env`); absent means Node's `shell: true`.
      */
     exec?: CommandExecution;
     workdir: string;
     env: NodeJS.ProcessEnv;
     sandboxed: boolean;
+    /**
+     * The sandbox's git-dir mode (issue 373): true binds every git directory of the
+     * workspace read-only, which is what the failed `git` command's note describes.
+     * Persisted with the spec so a restored job still reports its own note.
+     */
+    gitDirReadOnly?: boolean;
     title?: string;
     notify?: BackgroundShellNotify;
     timeoutMs?: number;
     lifetime?: 'session' | 'persistent';
+    /**
+     * Ends a persistent start that is still waiting for its runner: the runner is killed and the job
+     * forgotten, as for a start that outran its budget. Read only by a persistent start; a session
+     * shell is spawned at once and has nothing to wait for.
+     */
+    signal?: AbortSignal;
     workspace?: string;
     envOverrides?: Record<string, string>;
     parentSessionId?: string;
@@ -745,6 +944,7 @@ interface ShellAdoptOptions {
     effectiveCommand: string;
     workdir: string;
     sandboxed: boolean;
+    gitDirReadOnly?: boolean;
     title?: string;
     /** When the command really started, not when it was adopted. */
     startedAt?: number;
@@ -790,8 +990,12 @@ declare class ShellJobManager {
     private readonly unwrittenLost;
     /** Set by `dispose()`: a disposed manager takes on no new work. */
     private disposed;
+    /** Secrets the buffer trim must not cut (#411); the Bash tools hand over the session's set. */
+    private providerSecrets;
     constructor(store: BackgroundShellStore, options?: ShellJobManagerOptions);
     private readonly clock;
+    /** The provider secrets the 5 MB buffer trim keeps whole (#411). */
+    setProviderSecrets(secrets: readonly string[] | undefined): void;
     subscribe(listener: (event: ShellJobEvent) => void): () => void;
     configureWorkspace(workspace: string): void;
     list(): BackgroundShellRecord[];
@@ -821,8 +1025,30 @@ declare class ShellJobManager {
      * between.
      */
     adopt(options: ShellAdoptOptions): BackgroundShellRecord | undefined;
-    readOutput(shellId: string, limit?: number): ShellOutputResult | undefined;
-    readTail(shellId: string, limit?: number): string | undefined;
+    /**
+     * The next unread chunk. `secrets` are values the caller will redact from what it gets back
+     * (#411): the chunk never ends inside one, so a key cut in half across two reads cannot slip past
+     * an exact-match redactor. `readOffset` and `remaining` follow the adjusted cut.
+     */
+    readOutput(shellId: string, limit?: number, secrets?: readonly string[]): ShellOutputResult | undefined;
+    /**
+     * Cut the next chunk out of `unread` and advance the cursor past it.
+     *
+     * With secrets configured, a running job's read stops after the last line break, so a key being
+     * written is not returned in halves: the unterminated trailing line waits until it ends or the
+     * job does. The rule looks at line breaks and length only, never at the secrets' values: a
+     * rule that held back "text that starts a key" would let a command probe the key by printing
+     * candidates and seeing which BashOutput comes back empty. A line with no break at all is
+     * returned in {@link UNTERMINATED_READ_CAP}-character pieces so a prompt or a long line is not
+     * held forever. The chunk never ends inside a whole key (`secretSafeCut`), and a finished job
+     * returns everything.
+     */
+    private takeUnread;
+    /**
+     * The last `limit` characters of the output. With `secrets`, a window whose front edge falls
+     * inside a key starts where that key starts, so the redactor the caller applies sees it whole.
+     */
+    readTail(shellId: string, limit?: number, secrets?: readonly string[]): string | undefined;
     stop(shellId: string, reason?: 'killed' | 'timed_out'): Promise<boolean>;
     dismiss(shellId: string): void;
     acknowledgeCompletion(shellId: string, sequence?: number, consumer?: 'ui' | 'agent'): void;
@@ -884,7 +1110,22 @@ declare class ShellJobManager {
 }
 
 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';
+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'
+/**
+ * A usage or plan limit is spent, or the provider stated a wait longer than the
+ * retry layer can sit out (provider codes `usage_limit` and `rate_limit_wait`).
+ * Not a rejected key: nothing needs rotating, the run waits for the reset or an
+ * operator picks another model. A 402 and `insufficient_quota` stay
+ * `credentials_rejected`.
+ */
+ | 'quota_exhausted' | 'model_unavailable' | 'objective_complete' | 'continuation_limit' | 'blocked_plan' | 'no_progress'
+/** The run's `/goal` was judged impossible, or was still unmet at the check cap. */
+ | 'goal_unmet'
+/**
+ * The run's `/goal` check could not run (provider error, timeout, unreadable
+ * answer). The run was let end rather than trapped, but nothing confirmed the goal.
+ */
+ | 'goal_unverified' | 'all_tools_blocked' | 'plan_stop' | 'handoff_requested' | 'missing_terminal';
 interface AgentTerminalOutcome {
     readonly status: AgentTerminalStatus;
     readonly reason: AgentTerminalReason;
@@ -893,6 +1134,52 @@ interface AgentTerminalOutcome {
     readonly providerCode?: string;
 }
 
+/**
+ * A session goal set with `/goal <condition>`: the host keeps the agent working
+ * until a separate evaluator judges, from the transcript, that the condition
+ * holds. Lives on the session runtime and survives a resume through `goal`
+ * session records.
+ */
+interface ActiveGoal {
+    /** The condition as the user wrote it; also the agent's directive. */
+    condition: string;
+    /** Evaluations that found the condition unmet. */
+    iterations: number;
+    /** Epoch milliseconds when the goal was set. */
+    setAt: number;
+    /** `restored` when a resume brought back a goal set in an earlier process. */
+    origin: 'user' | 'restored';
+    /** Output tokens the root agent and the goal checks have spent while the goal was set. */
+    outputTokens: number;
+    /** The evaluator's reason from the most recent unmet check. */
+    lastReason?: string;
+}
+/** One change in a goal's state, reported to the host as it happens. */
+type GoalStatusEvent = {
+    state: 'set';
+    condition: string;
+} | {
+    state: 'cleared';
+    condition: string;
+} | {
+    state: 'unmet';
+    condition: string;
+    reason: string;
+    iterations: number;
+} | {
+    state: 'met' | 'failed';
+    condition: string;
+    reason: string;
+    iterations: number;
+    durationMs: number;
+    tokens: number;
+} | {
+    state: 'paused';
+    condition: string;
+    cause: 'block_cap' | 'check_failed' | 'max_turns';
+    detail?: string;
+};
+
 /** What triggered a compaction attempt. */
 type CompactTrigger = 'manual' | 'auto';
 /**
@@ -1007,6 +1294,13 @@ interface CompactBoundary {
     timestamp: number;
     /** Earlier user turns kept verbatim ahead of the checkpoint; absent on records written before Carried Turns. */
     carriedCount?: number;
+    /**
+     * The compaction used reduced-fidelity coverage. Live only: the host shows it on the boundary's
+     * row, it is not written to the session record, and a resumed session's boundaries lack it.
+     */
+    degraded?: boolean;
+    /** The compaction's warning, for the same live row as `degraded`; not persisted either. */
+    warning?: string;
 }
 interface RewindCheckpointMetadata {
     snapshotId?: string;
@@ -1019,12 +1313,18 @@ interface RewindTarget extends RewindCheckpointMetadata {
     id: string;
     userEventId: string;
     prompt: string;
+    /**
+     * `prompt` is what the user typed: their text, or the command line that ran a command. Only such
+     * a prompt goes back in the composer on a rewind. Absent for any other turn (a command's body, a
+     * notification) and for one recorded before this was, whose prompt may be a command's body.
+     */
+    promptTyped?: boolean;
     attachments?: ImageAttachment[];
     timestamp: number;
     codeAvailable: boolean;
 }
 interface SessionRecord {
-    type: 'user' | 'assistant' | 'local' | 'tool_call' | 'tool_result' | 'usage' | 'session_meta' | 'compact' | 'turn_checkpoint' | 'rewind' | 'plan';
+    type: 'user' | 'assistant' | 'local' | 'tool_call' | 'tool_result' | 'usage' | 'session_meta' | 'compact' | 'turn_checkpoint' | 'rewind' | 'plan' | 'goal';
     eventId?: string;
     timestamp: number;
     data: unknown;
@@ -1044,6 +1344,17 @@ interface PlanRecordData {
     todos?: PersistedTodo[];
     tasks?: AgentTask[];
 }
+/**
+ * Payload stored in a SessionRecord of type `goal` — last record wins.
+ *
+ * Written whenever the session's `/goal` changes: set, checked unmet, met, failed
+ * or cleared. `goal: null` is a cleared goal, so a resume after a goal was met
+ * does not bring it back. Readers must tolerate absence, as for `plan`.
+ */
+interface GoalRecordData {
+    version: 1;
+    goal: ActiveGoal | null;
+}
 interface PersistedTodo {
     content: string;
     status: string;
@@ -1293,6 +1604,8 @@ interface LoadedSession {
      * not survive the restart".
      */
     plan?: PlanRecordData;
+    /** The newest `goal` record; `goal: null` inside it is a goal that was cleared or reached. */
+    goal?: GoalRecordData;
     /**
      * Token totals recorded by earlier processes of this session, summed from the
      * `usage` records. USD is deliberately not stored: pricing changes between
@@ -1342,13 +1655,22 @@ interface SessionStoreInterface {
     list(): SessionMeta[];
     findByName(name: string): SessionMeta | undefined;
     findById(id: string): SessionMeta | undefined;
-    mostRecentInCwd(cwd: string): SessionMeta | undefined;
+    /**
+     * The newest session in `cwd` with at least one message, or the newest one `accept` approves
+     * when given; empty sessions are skipped by default.
+     */
+    mostRecentInCwd(cwd: string, accept?: (meta: SessionMeta) => boolean): SessionMeta | undefined;
     saveImageAttachment?(sessionId: string, image: {
         bytes: Uint8Array;
         mediaType: ImageAttachment['mediaType'];
         displayName?: string;
     }): ImageAttachment;
     readImageAttachment?(sessionId: string, attachment: ImageAttachment): Uint8Array;
+    /**
+     * Remove a session nothing was ever recorded in (a bare header, no name), file and index
+     * entry together. Returns whether it was removed. A store that omits it keeps every session.
+     */
+    removeUntouched?(id: string): boolean;
     cleanup(days: number, preserveIds?: ReadonlySet<string>): number;
 }
 
@@ -1393,7 +1715,7 @@ interface ConfigCommandDisplay {
         workspace: string;
     };
 }
-type ContextWindowSource = 'declared' | 'learned' | 'family' | 'default';
+type ContextWindowSource = 'declared' | 'learned' | 'reported' | 'family' | 'default';
 interface ContextCommandDisplay {
     kind: 'context';
     model: string;
@@ -1432,6 +1754,11 @@ interface UsageCommandDisplay {
     rate?: {
         inputPerMillion: number;
         outputPerMillion: number;
+        longPrompt?: {
+            overPromptTokens: number;
+            inputPerMillion: number;
+            outputPerMillion: number;
+        };
     };
     estimatedCostUsd?: number;
     /** Delegated agents inside `usage`, so the sheet can say so (#370). */
@@ -1660,6 +1987,9 @@ interface AgentRunResult {
     readonly ambient?: AgentRunAmbientSnapshot;
 }
 
+/** {@link reachesUncPath} for one top-level call, answering from what it already probed. */
+type UncGuard = (path: string) => boolean;
+
 type SkillSource = 'user' | 'project';
 type SkillRootKind = 'book' | 'agents' | 'claude' | 'opencode';
 type SkillIssueSeverity = 'error' | 'warning';
@@ -1730,8 +2060,16 @@ interface DiscoverSkillsOptions {
     enabled?: boolean;
     executionOverrides?: Readonly<Record<string, SkillExecution>>;
 }
-/** Roots are ordered from lowest to highest precedence. */
-declare function skillRoots(workspace: string, options?: DiscoverSkillsOptions): SkillRoot[];
+/**
+ * Roots are ordered from lowest to highest precedence.
+ *
+ * A project root is a path a repository can commit as a link, and on Windows resolving a link to
+ * a network share opens the share, which can send the user's credentials to the host it names
+ * (#567, #579). A project root that reaches one is therefore not a root at all, so nothing that
+ * takes its roots from here resolves it. The user's own roots are theirs to keep on a share.
+ * `reachesUnc` is the UNC guard of the discovery this is part of, so the two share what it probed.
+ */
+declare function skillRoots(workspace: string, options?: DiscoverSkillsOptions, reachesUnc?: UncGuard): 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;
@@ -2135,11 +2473,12 @@ type AgentRuntimeEvent = {
 /**
  * A line the child's own run raised for the operator, such as a read it was refused (#305
  * item 4). A child's transcript is summarised into a handoff, so a refusal inside it is
- * otherwise invisible to whoever delegated it.
+ * otherwise invisible to whoever delegated it. Without an `agentId` it is the manager's own
+ * one-time line (#579).
  */
  | {
     type: 'agent_notice';
-    agentId: string;
+    agentId?: string;
     message: string;
 } | {
     type: 'agent_persistence';
@@ -2216,6 +2555,19 @@ interface AgentApplyResult {
     commit?: string;
     error?: string;
 }
+/**
+ * Who started an apply: the user (`/agent apply`, `/review --fix`) or the model (`AgentApply`).
+ * The model's `AgentStop` stops only the applies the model started (#527).
+ */
+type AgentApplyStarter = 'user' | 'model';
+/** What a stop that kept the user's applies running did with the agent's applies. */
+interface AgentStopOutcome {
+    agent: AgentRecord;
+    /** The evidence id of each model-started apply it stopped, which has ended. */
+    stoppedApplies: string[];
+    /** The evidence id of each user-started apply it left running. */
+    keptUserApplies: string[];
+}
 
 /**
  * A small, always-current file saying what a run is doing right now.
@@ -2549,6 +2901,14 @@ interface AgentLoopCallbacks {
     onAgentEvent?: (event: AgentRuntimeEvent) => void;
     /** Called when a host or system notice should be surfaced (e.g. memory candidate saved). */
     onNotice?: (notice: string) => void;
+    /** Called when the session's `/goal` changes state at a stop (checked, met, failed, paused). */
+    onGoalStatus?: (event: GoalStatusEvent) => void;
+    /**
+     * Spend on a side request the loop or a tool made on another model -- a goal check, an
+     * `Advisor` consultation. Not the turn's own usage, so a host must not feed it to the
+     * context meter; it belongs on the session's bill, priced at `metadata`'s model.
+     */
+    onAuxiliaryUsage?: (usage: Usage, metadata: ProviderResponseMetadata, source: string) => void;
 }
 
 interface ProviderStreamOptions {
@@ -2850,10 +3210,80 @@ interface Sandbox {
      *
      * Returns null if the sandbox is unavailable.
      */
-    wrap(command: string, workspaceRoot: string): CommandExecution | null;
+    wrap(command: string, workspaceRoot: string, protectedPaths?: ProtectedWorkspacePaths): CommandExecution | null;
     /** One-line description of the policy actually enforced, for diagnostics. */
     describe(): string;
 }
+/**
+ * One workspace path the namespace must shield, and how.
+ *
+ * - `directory` — a directory the host reads after the command exits. Bound
+ *   read-only when it exists, masked with an empty read-only tmpfs when it does
+ *   not, which both hides any contents the host grows there later and makes
+ *   creating it fail.
+ * - `file` — a file the host reads after the command exits. Bound read-only
+ *   when it exists: bubblewrap aborts the whole invocation on a tmpfs mounted
+ *   over a file path ("Not a directory"), so an absent file cannot be masked at
+ *   all.
+ * - `hidden-file` — a file whose *contents* must not reach the command, bound
+ *   over with `/dev/null`. A read-only bind of `.book/` still serves what is in
+ *   it, and the namespace shares the host network, so a key the user stored
+ *   there would be one `cat` away from a sandboxed command.
+ */
+type ProtectedMountKind = 'directory' | 'file' | 'hidden-file';
+interface ProtectedMount {
+    /**
+     * The path the namespace mounts at, in the workspace's own spelling;
+     * containment is decided on canonical paths.
+     */
+    path: string;
+    kind: ProtectedMountKind;
+    /** False when nothing exists at it, which for a directory becomes a mask. */
+    present: boolean;
+}
+interface ProtectedWorkspacePaths {
+    /**
+     * Directories the namespace must pin as mount points in their own right.
+     *
+     * A read-only child mount is not enough: the directory that holds it can still
+     * be renamed away and replaced, and rename(2) on a path that is not a mount
+     * point succeeds. `--bind <dir> <dir>` pins it, which is what makes
+     * `mv .git .git.old` fail with EBUSY instead of redirecting the host's git.
+     *
+     * Only the workspace's own top-level `.git` is pinned, and only in the opt-out
+     * mode (`allowGitWrites: true`) where git directories stay writable. Read-only
+     * mode has no pin because the git directory is already a mount point through
+     * its own `--ro-bind`, and the half-done `git worktree remove` it describes
+     * (deleting the work tree and failing on the read-only admin directory) now
+     * happens by design in read-only mode.
+     */
+    pinnedDirectories: string[];
+    mounts: ProtectedMount[];
+    /**
+     * Control paths this namespace cannot protect at all. A refusal rather than a
+     * mount: bwrap aborts the whole invocation on the shapes that could be
+     * mistaken for one, and guessing would leave a control file writable while
+     * reporting a sandbox.
+     */
+    refusals: ControlPathRefusal[];
+    /**
+     * Control mounts inside read-only git dirs (hooks, config, etc.), preserved in
+     * read-only mode so an allowWrite opt-in on a git dir can re-apply them.
+     */
+    gitDirControlMounts: ProtectedMount[];
+}
+/**
+ * Why a workspace cannot be sandboxed, and which path says so.
+ *
+ * Both are shapes a repository controls and no mount can cover. The run is
+ * refused with the path named, because the fix — replace the link, trim the
+ * config — is a change to the workspace, not to a Book setting.
+ */
+type ControlPathRefusalReason = 'symlinked-control-path' | 'oversized-git-config' | 'workspace-root-is-git-dir';
+interface ControlPathRefusal {
+    path: string;
+    reason: ControlPathRefusalReason;
+}
 
 interface SessionRuntimeOptions {
     tasks?: AgentTask[];
@@ -2869,18 +3299,17 @@ interface SessionRuntimeOptions {
     skillRegistry?: SkillRegistry;
     /** Skill root discovery options, shared by the registry and the watcher so they agree. */
     skillDiscoveryOptions?: DiscoverSkillsOptions;
-    /**
-     * The conversation this runtime is being built for. Its tool calls seed
-     * `usedToolNames`, so every runtime built for a loaded, resumed, or rewound
-     * conversation knows what that conversation already read.
-     */
-    history?: Message[];
     /**
      * Whether this runtime is the session's long-lived one. `false` marks a runtime that is disposed
      * when one run ends — a Task subagent's, a managed agent's — and so may not adopt a timed-out
      * command as a background shell it would then destroy. Defaults to `true`.
      */
     ownsSessionShells?: boolean;
+    /**
+     * The store instances of every agent manager this session has disposed. Hand on the outgoing
+     * runtime's set to its replacement; see {@link SessionRuntime.disposedAgentInstanceIds}.
+     */
+    disposedAgentInstanceIds?: Set<string>;
 }
 /** Mutable resources owned by one logical agent session. */
 declare class SessionRuntime {
@@ -2897,6 +3326,18 @@ declare class SessionRuntime {
      * Surfaced once in `<session-state>` so a dropped plan is a visible event.
      */
     planUnrestored: boolean;
+    /**
+     * The session's `/goal`, if one is set. Read by the root loop each time the agent
+     * stops without calling a tool; mutated there and by the host's `/goal` command.
+     * A runtime is replaced on `/clear`, which is what clears the goal with it.
+     */
+    activeGoal?: ActiveGoal;
+    /**
+     * The loaded memory snapshot whose `MEMORY.md` was last seeded into the observation ledger, so
+     * the seed happens once per snapshot: a later turn must not claim the model has seen a file that
+     * changed since. A reloaded snapshot (a new object) is seeded again, as a resumed session is.
+     */
+    memoryIndexSeededFor?: object;
     readonly backgroundShells: BackgroundShellStore;
     readonly fileObservationLedger: Map<string, FileObservation>;
     readonly toolDiscoveryState: ToolDiscoveryState;
@@ -2937,13 +3378,6 @@ declare class SessionRuntime {
      * there, as it was before #302.
      */
     readonly ownsSessionShells: boolean;
-    /**
-     * Canonical names of tools executed in this conversation, seeded from the
-     * conversation it was built for. A runtime is replaced rather than cleared
-     * when the host projects a different conversation, so this only ever grows
-     * within one conversation.
-     */
-    readonly usedToolNames: Set<string>;
     /**
      * Files this session's tool output was clipped into, as absolute paths.
      *
@@ -2954,6 +3388,15 @@ declare class SessionRuntime {
      */
     readonly clippedOutputPaths: Set<string>;
     agentManager?: AgentManager;
+    /**
+     * The store instances of the agent managers this session has disposed, its earlier runtimes'
+     * included: one set, handed from each runtime to the next by `AgentSession.replaceRuntime`.
+     * Every manager built on this runtime gives it to its store, which adds its own instance when it
+     * is disposed and reads each instance in it as gone, whatever its lease file says (#568). A lease
+     * outlives its dispose when the unlink fails (a Windows scanner holding the file), and would read
+     * as a live owner of the records that manager wrote for up to 15 s.
+     */
+    readonly disposedAgentInstanceIds: Set<string>;
     private readonly abortControllers;
     private readonly timers;
     private readonly childProcesses;
@@ -3025,6 +3468,13 @@ declare function runAgentLoop(config: AgentConfig, registry: ToolRegistry, userM
     userMessageKind?: Message['kind'];
     /** The prompt was resolved from a command or delegated, not typed by the user. */
     userMessageDerived?: boolean;
+    /**
+     * The text the user typed for this turn, when the turn comes from their typing: what they sent,
+     * or the command line that ran a command. Only its `$name` tokens invoke a skill by name; a
+     * token anywhere else in the prompt (a command's body, an inlined file, a notification, a
+     * delegated task) is plain text. Absent, no skill is invoked by name.
+     */
+    typedText?: string;
     /** Synthetic host notifications bypass user-authored prompt hooks and memory capture. */
     skipUserPromptHooks?: boolean;
     /** Host identity for each streamed assistant turn. */
@@ -3118,9 +3568,34 @@ declare function createAgentWorktree(snapshot: AgentSnapshot, agentId: string, w
 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, signal?: AbortSignal): Promise<AgentApplyResult>;
+/**
+ * What a caller can say about how an apply may be stopped, beyond the `signal` it is given.
+ *
+ * `signal` stops the apply's **reads**: the candidate resolution, the pending-pick check, the
+ * fingerprint, the delta, the pre-check and the signing configuration read. Those are where an
+ * operator's slow `gpg.ssh.defaultKeyCommand` can hold an apply for up to 30 s per call (#491), and
+ * none of them has written anything, so a stop there leaves nothing behind.
+ *
+ * `mutationSignal` stops the **mutation step**: the `cherry-pick`, or the `git apply -` of a dirty
+ * workspace. It is separate because stopping that step is not free: a stop SIGTERMs the pick and
+ * relies on the unsignalled `cherry-pick --abort` that follows to put the operator's repository
+ * back, and a caller whose process exits right after it aborts (`dispose()`) never lets that
+ * cleanup run. A caller that wants the reads stopped and nothing after them passes a signal here
+ * that it never aborts. Absent, the mutation step uses `signal`, so a caller that passes one signal
+ * gets one behaviour for all of it.
+ */
+interface ApplyCandidateOptions {
+    mutationSignal?: AbortSignal;
+}
+declare function applyVerifiedCandidate(snapshot: AgentSnapshot, candidate: PatchCandidate, signal?: AbortSignal, options?: ApplyCandidateOptions): Promise<AgentApplyResult>;
 
 type AtomicWriteOperation = 'lock' | 'serialize' | 'write' | 'fsync' | 'rename';
+/**
+ * Outcome of an atomic JSON write.
+ *
+ * `attempts` counts how many times this write tried: 1 for a clean write, plus 1 for each contended
+ * retry of either the lock step or the rename step. A stale-lock reclaim is not a retry.
+ */
 type AtomicWriteResult = {
     status: 'ok';
     target: string;
@@ -3155,6 +3630,11 @@ type AtomicWriteResult = {
 };
 /** What one {@link AtomicJsonWriter.writeAsync} call is allowed to decide for itself. */
 interface AtomicAsyncWriteOptions {
+    /**
+     * A complete temp file an earlier write left behind, renamed over the target instead of writing a
+     * new one: the `preparedTemp` of {@link AtomicJsonWriter.write}.
+     */
+    preparedTemp?: string;
     /**
      * Asked immediately before the rename, which is the only step of the write that changes the
      * target.
@@ -3178,6 +3658,17 @@ interface AtomicJsonWriterOptions {
     instanceId: string;
     pid?: number;
     hostname: string;
+    /**
+     * The budget of one write, counted on `now` from before the lock is taken: the lock, the
+     * fsyncs of the lock and temp files, and the rename retries all spend it, so on a slow disk the
+     * fsyncs alone can use it up. The budget bounds the back-off ladder, not the work already done,
+     * so a rename that hits contention is always retried once after its back-off, even when the
+     * budget is gone by then; after that retry the deadline applies and the write returns `busy`.
+     * That back-off is the clamped ladder step while the budget lasts, and with little or none left
+     * it is the first rename step at least and the current step at most. A write whose rename
+     * fails every time therefore ends within the budget plus one such back-off. The lock phase has no such retry: a lock still contended at the
+     * deadline is `busy`.
+     */
     deadlineMs?: number;
     now?: () => number;
     randomId?: () => string;
@@ -3261,8 +3752,30 @@ declare class AtomicJsonWriter {
      *
      * {@link AtomicAsyncWriteOptions.canCommit} is the one thing this path has that the synchronous
      * one does not, and it exists because this path is the one a caller can no longer wait for.
+     * Without it the write cannot be withdrawn, so the result is never `cancelled`.
      */
-    writeAsync(target: string, value: unknown, options?: AtomicAsyncWriteOptions): Promise<AtomicWriteResult>;
+    writeAsync(target: string, value: unknown, options?: Omit<AtomicAsyncWriteOptions, 'canCommit'>): Promise<Exclude<AtomicWriteResult, {
+        status: 'cancelled';
+    }>>;
+    writeAsync(target: string, value: unknown, options: AtomicAsyncWriteOptions): Promise<AtomicWriteResult>;
+    /** What both write paths record in a lock file they take: who holds it, and since when. */
+    private lockOwnerDocument;
+    /** A temp file name unique to this writer, which recovery parses back to its target and owner. */
+    private tempPathFor;
+    /**
+     * Whether a contended lock may be taken from its holder, given what its file said: a lock with a
+     * valid owner only when that owner is gone, one without once it is older than the stale window.
+     */
+    private mayReclaim;
+    /**
+     * How long to back off before `attempt`: the ladder step, cut short by the time left to the
+     * deadline. `guaranteed` is the one retry past the deadline, after the first contended rename.
+     * Cut to nothing, that retry would hit the same contention again; so it waits at least the first
+     * rename step, whatever is left, and never more than the ladder step: the ladder is shared with
+     * the lock phase, and a step it has climbed to could block the main thread for a long time past
+     * the deadline.
+     */
+    private backoffMs;
     private pause;
     private pauseAsync;
     private reclaimStaleLockAsync;
@@ -3297,6 +3810,12 @@ interface AgentStoreOptions {
     eventSink?: (event: AgentStorePersistenceEvent) => void;
     writer?: AtomicJsonWriter;
     writerOptions?: Omit<AtomicJsonWriterOptions, 'instanceId' | 'hostname'>;
+    /**
+     * The instances of the stores the session this one belongs to has disposed, shared rather than
+     * copied: this store adds its own when it is disposed, and reads each one in it as gone, whatever
+     * its lease says (#568). See {@link AgentStore.aliveByLease}.
+     */
+    disposedInstanceIds?: Set<string>;
 }
 declare class AgentStore {
     readonly directory: string;
@@ -3320,8 +3839,14 @@ declare class AgentStore {
     private readonly processAlive;
     private readonly eventSink?;
     private readonly writer;
+    private readonly disposedInstanceIds?;
     private enabled;
     private disposed;
+    /**
+     * Set while {@link open} loads the store. The writes `load` finds it needs are queued rather than
+     * made, and `open` flushes them on the thread pool once loading is done.
+     */
+    private opening;
     private heartbeatTimer?;
     /**
      * The heartbeat write in flight, if any. See {@link refreshLease}: a tick that arrives while one
@@ -3337,13 +3862,53 @@ declare class AgentStore {
     private readonly evidence;
     private readonly snapshots;
     private readonly pendingWrites;
-    constructor(repoHash: string, root?: string, enabled?: boolean, options?: AgentStoreOptions);
+    /**
+     * A store that has not touched the disk yet, and is not usable until it has: {@link open} is the
+     * way to get one.
+     */
+    private constructor();
+    /**
+     * Open the store for `repoHash` under `root`: create its directories, take this instance's lease
+     * and start the heartbeat, then recover the temp files a crashed write left behind, load what is
+     * persisted, and make the writes loading found it needed.
+     *
+     * All of that is on the thread pool. It is the first thing the TUI does after its first frame, and
+     * done synchronously on a slow disk its `open`s and `fsync`s held the event loop for hundreds of
+     * milliseconds: keys typed in that window arrived in one read and were taken for a paste (#516).
+     *
+     * The lease comes before the first read, because on the thread pool the reads no longer run in
+     * one piece: a disposed manager's {@link recordLateApplication} can land between them. It
+     * writes only when no other instance holds a live lease, so with the lease already on disk it
+     * stands down; taken after loading, it found none, wrote a record this store had already read,
+     * and this store's next save of that stale copy undid it.
+     *
+     * The promise resolves only once the lease is on disk, so no caller ever holds a store without one
+     * (#357). A store whose directories cannot be created, or whose contents cannot be read, is not an
+     * error: it resolves disabled, and runs in memory only.
+     */
+    static open(repoHash: string, root?: string, enabled?: boolean, options?: AgentStoreOptions): Promise<AgentStore>;
+    private initialize;
+    /**
+     * Turn an opening store whose contents could not be read into a disabled one: nothing of what it
+     * read is kept, nothing it queued is written, and the lease it took is removed with its heartbeat,
+     * since a disabled store writes nothing that a lease would speak for.
+     */
+    private disableAfterFailedLoad;
     private ensureDirectories;
     private safeLog;
+    private quarantinePath;
     private quarantine;
+    /** {@link quarantine}, on the thread pool, for what {@link open} reads. */
+    private quarantineAsync;
     private readJson;
+    /** {@link readJson}, on the thread pool, for what {@link open} reads. */
+    private readJsonAsync;
     private targetMatchesId;
     private loadDirectory;
+    /**
+     * Read what is persisted into memory. Runs only inside {@link open}, so the writes it finds it
+     * needs are queued, and `open` makes them once it is done.
+     */
     private load;
     private migrateAgent;
     private agentPath;
@@ -3358,6 +3923,11 @@ declare class AgentStore {
     private cancelPendingWrite;
     private queueWrite;
     private flushPending;
+    /** {@link flushPending} on the thread pool: the writes {@link open} makes. */
+    private flushPendingAsync;
+    private beginFlush;
+    /** What both flushes do with the result: settle the pending write, or schedule its retry. */
+    private finishFlush;
     private schedulePending;
     private enterDegraded;
     private maybeRecover;
@@ -3371,6 +3941,45 @@ declare class AgentStore {
         defer?: boolean;
         required?: boolean;
     }): AtomicWriteResult;
+    /**
+     * Record on disk how an apply that outlived its manager ended: the one fact that can only be
+     * known after this store was disposed. A pick that finished after `dispose()` is on the
+     * operator's branch, and nothing else records that.
+     *
+     * The session's next manager may have opened this store's directory by then and written the
+     * same record (#518), so this is a field-level update rather than a save of the disposed
+     * manager's copy: the record is re-read from disk and only its `applicationStatus` changes, with
+     * the owner and `updatedAt` stamped as every write stamps them. Written to disk only, since the
+     * disposed store's cache has no reader left.
+     *
+     * Nothing is written, and the record is left as it is, when another instance holds a live lease
+     * here (the record is its to write now), when the record on disk is newer than `seenUpdatedAt`,
+     * the `updatedAt` of the copy the disposed manager last had (someone wrote it since), or when
+     * the record is not on disk.
+     *
+     * That is decided twice: once before the write, and again immediately before each rename, which
+     * is the step that changes the file. Between the two are a lock, a temp file and its fsync, and a
+     * save by the next manager or another process can land in that window (its writer reclaims the
+     * lock of a store that is gone); the copy read before it would otherwise be renamed over it.
+     */
+    recordLateApplication(agentId: string, status: AgentRecord['applicationStatus'], seenUpdatedAt: number): Promise<'recorded' | 'skipped' | 'failed'>;
+    /**
+     * What one write of {@link recordLateApplication} not landing makes of it, logged without any of
+     * the record's content; `undefined` when the write landed.
+     */
+    private lateWriteSetback;
+    /**
+     * Why a late write to the record at `path` must not land now, or `undefined` if it may: the skip
+     * rule of {@link recordLateApplication}, with `newestAllowed` the `updatedAt` the record on disk
+     * may have. Synchronous, because it is asked as the `canCommit` of a write, and an answer that
+     * waited for the thread pool would be one the rename no longer immediately follows. It is a
+     * directory listing and a few small reads, once per late apply.
+     */
+    private lateWriteConflict;
+    /** Whether an instance other than this one holds a live lease in `instances/`. */
+    private anotherInstanceIsLive;
+    /** Whether `lease`, as read from `instances/`, is another instance's, and live. */
+    private isLiveForeignLease;
     removeAgent(agentId: string): void;
     removePlan(planId: string): void;
     removeEvidence(evidenceId: string): void;
@@ -3383,6 +3992,11 @@ declare class AgentStore {
     recoverAbandonedAgents(): AgentRecord[];
     markActiveInterrupted(): AgentRecord[];
     isOwnedByCurrent(agentId: string): boolean;
+    /**
+     * The instance that wrote the newest copy of the record this store knows, as
+     * {@link isOwnedByLiveForeign} reads it.
+     */
+    ownerInstanceId(agentId: string): string | undefined;
     isOwnedByLiveForeign(agentId: string): boolean;
     hasPendingAgent(agentId: string): boolean;
     getPersistenceState(): 'healthy' | 'degraded_busy' | 'degraded_unavailable';
@@ -3392,13 +4006,16 @@ declare class AgentStore {
     dispose(): void;
     private refreshForeignSummaries;
     /**
-     * Take the lease for this instance, before anything else reads it.
+     * Take the lease for this instance, before this store reads anything and before anything else
+     * reads it.
      *
-     * This first lease is written synchronously where the heartbeats below are not, because it is the
-     * one a caller depends on the moment the constructor returns: a store that has just been built is
-     * asked whether its own instance is alive, and answered from this file. Deferring it to the thread
-     * pool leaves a window in which a brand new store has no lease at all, which is what a manager
-     * reading a just-created store sees when its first agent looks abandoned (#357).
+     * {@link open} waits for this write before it resolves, and that order is the guarantee: a store
+     * that has just been opened is asked whether its own instance is alive, and answered from this
+     * file. A store handed out before its lease landed would have a window with no lease at all, which
+     * is what a manager reading a just-created store saw when its first agent looked abandoned (#357).
+     * The write itself is on the thread pool like the heartbeat's, because on a slow disk its lock,
+     * fsyncs and rename are what held the TUI's event loop after its first frame (#516): the caller
+     * waits for it, the event loop does not.
      *
      * A failure is not fatal here either, for the reason it is not fatal on the heartbeat: what is
      * written is this instance's own ownership record, and every other write carries the same metadata.
@@ -3412,7 +4029,7 @@ declare class AgentStore {
      * every one of them a disk round trip, all of it on whichever thread scheduled the timer — for the
      * TUI, the event loop the keystrokes and the model stream are on. On a busy disk that is hundreds
      * of milliseconds every five seconds, and it lands on the user rather than on the heartbeat
-     * (#357). {@link takeLease} is the exception, and says why.
+     * (#357). {@link takeLease} is on the thread pool too, but awaited: see there.
      *
      * Two properties come with moving it off the thread and are the reason this is not simply a
      * fire-and-forget:
@@ -3433,11 +4050,55 @@ declare class AgentStore {
     private refreshLease;
     private leaseDocument;
     private removeLease;
+    /**
+     * {@link removeLease}, for a store that is done with its lease. A lease the unlink leaves behind
+     * (a Windows scanner holding the file, say) reads as fresh for up to {@link LEASE_FRESH_MS}, so
+     * it is overwritten with a dead one, best effort (#568). This session's own later stores read the
+     * instance as gone either way: see {@link aliveByLease}.
+     */
+    private releaseLease;
+    /**
+     * Overwrite this instance's lease with one that reads as dead to every store: a heartbeat stale on
+     * any clock, and no process, so that a store of another process on this host does not fall back
+     * to this one's pid, which is still alive (see {@link isLiveForeignLease}). In place, not by temp
+     * file and rename like every other lease write: a file whose unlink was refused refuses a rename
+     * onto it the same way, but may still take a write. A reader that catches the write half done
+     * reads no lease, which is no fresher than a dead one.
+     */
+    private markLeaseStale;
     private scheduleHeartbeat;
     private defaultProcessAlive;
     private isInstanceAlive;
+    /** {@link isInstanceAlive}, reading the lease on the thread pool, for {@link open}. */
+    private isInstanceAliveAsync;
+    private instanceLeasePath;
+    /**
+     * Whether an instance other than this one is alive, given its lease as read and the owner a
+     * record names. Every caller has already answered for this store's own instance.
+     *
+     * A fresh lease is alive. Without one, an owner on this host is alive while its process is (a
+     * Book from before leases, or one whose heartbeat is late), except when that process is this one
+     * (#544). Every live store takes its lease before anything else and keeps it fresh until
+     * `dispose()` removes it, so an instance of this process without one is taken for a disposed
+     * sibling: the manager a `/clear`, `/resume` or `/rewind` replaced. Its records are the next
+     * manager's to write and recover, and its locks are left over. No registry of disposed instances
+     * is needed for that, and an earlier process whose pid this one now has reads as gone too, which
+     * it is. The cost is a live sibling whose lease is missing or late: its first lease write failed,
+     * or its heartbeat stalled past {@link LEASE_FRESH_MS}. It reads as gone until its next
+     * heartbeat lands. Two live stores on one repository in one process come only from an SDK host
+     * running sessions side by side; the TUI and print mode dispose a runtime before replacing it.
+     *
+     * What that rule misses is a disposed sibling whose lease outlived its dispose: the unlink failed
+     * (a Windows scanner holding the file), and the lease reads as fresh for up to
+     * {@link LEASE_FRESH_MS}. So an instance the session has disposed, one in
+     * {@link AgentStoreOptions.disposedInstanceIds}, is gone whatever its lease says (#568). The set
+     * holds only this session's own instances, so a live instance of another process, or one another
+     * session in this process has not disposed, is judged as before.
+     */
+    private aliveByLease;
     private isLockOwnerAlive;
     private parseTemp;
+    /** Promote or discard the temp files crashed writes left behind. Runs only inside {@link open}. */
     private recoverTemps;
 }
 
@@ -3459,7 +4120,9 @@ interface ManagerOptions {
     runtime?: SessionRuntime;
     permissionMode?: string;
     persistPermissionRule?: (rule: string) => void;
-    createStore?: (repoHash: string, root: string | undefined, enabled: boolean) => AgentStore;
+    createStore?: (repoHash: string, root: string | undefined, enabled: boolean, 
+    /** What the manager hands every store it opens: its session's disposed instances (#568). */
+    options: Pick<AgentStoreOptions, 'disposedInstanceIds'>) => AgentStore | Promise<AgentStore>;
 }
 interface SubscribeOptions {
     snapshot?: boolean;
@@ -3486,23 +4149,40 @@ declare class AgentManager {
     private readonly snapshotPromises;
     private readonly queue;
     private readonly controllers;
+    /**
+     * Applies in flight, per agent. An apply runs after its agent has finished, so no run controller
+     * covers it; `stop` and `dispose` abort these instead. A set because one agent can be applied
+     * more than once at a time.
+     *
+     * Two controllers because the two ways in are not the same stop. `stop` ends the whole apply,
+     * including a cherry-pick that is running, whose rollback it then waits for (`settled`).
+     * `dispose` ends only the reads: it is synchronous and the process usually exits right after it,
+     * so a pick it killed would never be rolled back and the operator's repository would be left
+     * mid-pick. The pick that is running finishes, bounded by its own timeout.
+     */
+    private readonly applies;
     private readonly questionResolvers;
     private readonly permissionResolvers;
     private readonly permissionRules;
     private readonly activities;
     private readonly waiters;
     private readonly idleWaiters;
+    /** Settles each `wait` still pending, so a disposed manager leaves none of their timers armed. */
+    private readonly pendingWaits;
     private active;
     private interactivePermissions;
     private permissionMode;
     private permissionModeOverride?;
     private readonly subscribers;
+    private readonly heldNotices;
     private legacyEventSink?;
     private readonly textBuffers;
     private readonly textTimers;
     private hookEventSink?;
     private exitHandler?;
     private disposed;
+    /** The session's current manager, asked when an apply lands after dispose (#540). */
+    private lateApplicationReceiver?;
     private persistenceState;
     constructor(config: AgentConfig, parentDefinitions: ToolDefinition[], options?: ManagerOptions);
     setEventSink(sink?: (event: AgentRuntimeEvent) => void, hookSink?: (event: string, payload: Record<string, unknown>) => void): void;
@@ -3535,6 +4215,27 @@ declare class AgentManager {
     private recordForReturn;
     private assertMutable;
     getPersistenceState(): 'healthy' | 'degraded_busy' | 'degraded_unavailable';
+    /**
+     * The user's home directory when this workspace is strictly below it, has no repository of its
+     * own, and home holds a `.git`: the dotfiles repository Book has ignored since #572.
+     */
+    private homeDotfilesAbove;
+    /**
+     * A project below the user's home with no repository of its own used to resolve to the home
+     * directory's, so its records, worktrees and snapshot refs were keyed by it (#579). Since #572
+     * that `.git` is a dotfiles repository Book ignores, and that state is no longer found. Say so
+     * once, with the way to clear it; never read it back, and never move or delete it. Records carry
+     * no workspace, so every record under the home key is counted, the home repository's own
+     * included.
+     */
+    private reportOrphanedHomeState;
+    /**
+     * The manager's own one-time line for the operator. Held until a host is listening, because the
+     * first initialization can run before the TUI subscribes (or between its resubscribes), and a
+     * notice nobody saw was not reported.
+     */
+    private emitManagerNotice;
+    private flushHeldNotices;
     private handlePersistenceEvent;
     /**
      * Turn a write's result into either "it is on disk" or the error an operator sees, and report the
@@ -3593,8 +4294,20 @@ declare class AgentManager {
     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>;
+    wait(agentId: string, timeoutMs?: number, signal?: AbortSignal): Promise<AgentRecord>;
+    /**
+     * Stop an agent's run, and every apply of its result that is running.
+     *
+     * `keepUserApplies` is the model's `AgentStop` (#527): it stops only the applies the model
+     * started with `AgentApply`, leaves running the ones the user started (`/agent apply`,
+     * `/review --fix`), and says which it did with each. Every other caller is the user's own stop,
+     * or a host's, and stops them all.
+     */
     stop(agentId: string, reason?: string): Promise<AgentRecord>;
+    stop(agentId: string, reason: string | undefined, options: {
+        keepUserApplies: true;
+    }): Promise<AgentStopOutcome>;
+    private stopAgent;
     publishEvidence(agentId: string, input: PublishEvidenceInput): Promise<EvidenceItem>;
     listEvidence(options?: {
         requesterAgentId?: string;
@@ -3602,7 +4315,63 @@ declare class AgentManager {
         ids?: string[];
     }): Promise<EvidenceItem[]>;
     reviewEvidence(reviewerAgentId: string, evidenceId: string, verdict: 'pass' | 'fail' | 'inconclusive', notes?: string): Promise<EvidenceItem>;
-    apply(agentId: string, evidenceId?: string): Promise<AgentApplyResult>;
+    apply(agentId: string, evidenceId?: string, options?: {
+        signal?: AbortSignal;
+        startedBy?: AgentApplyStarter;
+    }): Promise<AgentApplyResult>;
+    /** Record how an apply of `record`'s candidate ended: on the record, to subscribers, in telemetry. */
+    private recordApplication;
+    /**
+     * Name the manager an apply that outlives this one hands its outcome to: the session's current
+     * manager, asked when the pick lands rather than now, since a session can switch again in the
+     * meantime and creates its manager lazily. Called where a session's runtime is replaced.
+     */
+    handOffLateApplications(current: () => AgentManager | undefined): void;
+    /**
+     * Hand the outcome of an apply that outlived this manager to the session's current manager
+     * (#540). True when that manager took it: it recorded the outcome, or left the record alone on
+     * purpose. False when there is no such manager or the hand-off failed, and the caller's own late
+     * write is what is left. A failure is logged with its code only, and never fails the apply,
+     * whose pick is on the operator's branch either way.
+     */
+    private handOverLateApplication;
+    /**
+     * Record the outcome of an apply that a disposed manager of this session started (#540).
+     *
+     * Only `applicationStatus` changes, on the record as this manager has it now, so its own later
+     * saves keep it. The record is left alone when it is gone, when its candidate is no longer the
+     * one applied (a re-run replaced it: `applied` would be false of the new one), or when another
+     * live owner holds it (#518, {@link heldByLiveOwner}). A skip is logged rather than thrown,
+     * because the pick is on the branch either way and nobody is waiting on this to fail.
+     *
+     * False when this manager was disposed before it could open its store, and took nothing.
+     */
+    private receiveLateApplication;
+    /**
+     * Whether a live instance other than this one holds the record a late application is for, so
+     * the application must leave it alone. Asked once the record has been read again. The owner it
+     * compares is the one {@link AgentStore.isOwnedByLiveForeign} judges: the writer of the newest
+     * copy the store knows, which is the one on disk unless the store holds a newer one. Two paths:
+     *
+     * - **Main (#544, #568):** an instance of this process without a fresh lease is a disposed one
+     *   and owns nothing, and so does one this session has disposed, whatever its lease file says.
+     *   That covers the manager handing the pick over, and any manager of this session disposed
+     *   after it that wrote the record in between, even when `dispose()` could not remove its lease
+     *   (a scanner holding the file) and the lease reads as fresh for up to 15 s.
+     * - **Fallback, the handing-over instance:** it is disposed, whatever its lease file says. This
+     *   manager may not know the session's disposed instances: a host can build it by hand rather
+     *   than on the session's runtime. A pick landing while that lease reads as fresh would then be
+     *   skipped and the record say `not_applied` for good. So a record whose owner is
+     *   {@link LateApplication.fromInstanceId} is this manager's to write. No other instance is
+     *   exempt: a live owner keeps the record.
+     */
+    private heldByLiveOwner;
+    /**
+     * One record as it is on disk now, read on its own rather than by listing the store: the copy
+     * `get()` would take (this manager has none, another live instance owns it, or it is newer), or
+     * else this manager's own, hydrated. `undefined` when the record is not on disk.
+     */
+    private reloadAgent;
     private pump;
     private evidenceContext;
     private systemPrompt;
@@ -3748,6 +4517,13 @@ interface ToolCall {
         raw: string;
         error: string;
     };
+    /**
+     * Set when the call's arguments, joined across every streamed fragment, were empty or
+     * whitespace on the wire: the name and id arrived and no argument text followed. `arguments`
+     * is `{}` as for a literal `{}`, which this does not mark. The registry rejects such a call
+     * as a route's wire shape when the tool has required arguments, and runs it with `{}` otherwise.
+     */
+    emptyOnWire?: true;
 }
 /** Display-only trace for a tool invoked inside a Task subagent. */
 interface NestedToolInvocation {
@@ -3765,7 +4541,10 @@ interface NestedToolObserver {
 }
 interface FileMutationSummary {
     kind: 'create' | 'update' | 'delete';
+    /** Workspace-relative; a memory file is `memory/<name>.md`, relative to the memory directory. */
     filePath: string;
+    /** The file is in the project memory directory (`ToolContext.memoryWrite`). */
+    memory?: true;
     addedLines: number;
     removedLines: number;
 }
@@ -3894,6 +4673,11 @@ interface ToolDefinition {
     argumentAliases?: Record<string, string>;
     /** Per-item argument aliases for array arguments (argument name → alias → canonical). */
     arrayItemArgumentAliases?: Record<string, Record<string, string>>;
+    /**
+     * Cross-harness arguments with no effect here, dropped before validation rather than refused:
+     * another harness's spelling for something this tool always does (Grep's `-n`).
+     */
+    ignoredArguments?: readonly string[];
     catalog?: ToolCatalogMetadata;
     policy?: ToolPolicy;
     /** When true, the tool is safe to retry once on transient failure (Read, Grep, WebFetch, etc.). */
@@ -3908,18 +4692,20 @@ interface ToolDefinition {
     timeoutMs?: number | ((context: ToolContext) => number | undefined);
     execute: (args: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
 }
-interface ReadOnlyRoot {
-    root: string;
-    /** Subpaths relative to root that must not be read (e.g. ['.inbox']). */
-    exclude?: readonly string[];
-}
 interface ToolContext {
     workspaceRoot: string;
     /**
-     * Directories outside the workspace that the Read tool may read;
-     * today only the project memory directory.
+     * Paths outside the workspace that the Read tool may read: the project memory directory and
+     * the files this session clipped a result into.
+     */
+    readOnlyRoots?: readonly string[];
+    /**
+     * The project memory directory as a *search* root: Glob and Grep reach the files in it (an
+     * absolute pattern or `path`), as Read does through `readOnlyRoots`. Set for every agent that
+     * can read memory, a subagent included. A dot-entry below it (`.format`, a backup) stays out of
+     * a search's results.
      */
-    readOnlyRoots?: readonly (string | ReadOnlyRoot)[];
+    memorySearchRoot?: string;
     /**
      * Honored `additionalDirectories`, as resolved real roots the file tools may serve alongside
      * the workspace: Read, Glob and Grep reach them, and so do the write tools' root check. A read
@@ -3928,6 +4714,25 @@ interface ToolContext {
      * managed child and a subagent see the same roots as their parent.
      */
     additionalRoots?: readonly string[];
+    /**
+     * The project memory directory as a *write* root, for the root agent only. Set by the agent loop
+     * when memory is enabled with `autoSave` on, and never copied into a subagent or managed child:
+     * a Task subagent runs in `bypassPermissions`, so the field's absence is what keeps it out of
+     * memory. Write, Edit, MultiEdit and ApplyPatch then reach `*.md` files in `root` (see
+     * `resolveMutationPath`), through the guard in `memory-write-guard.ts`.
+     *
+     * `scope` is `learnings` when another agent drives the session. `sessionId` stamps provenance.
+     */
+    memoryWrite?: {
+        root: string;
+        scope: 'learnings' | 'full';
+        sessionId?: string;
+    };
+    /**
+     * The provider secrets the agent loop redacts from every tool result (#411), longest first.
+     * `BashOutput` reads with them so a chunk never ends inside one. Populated by the agent loop.
+     */
+    providerSecrets?: readonly string[];
     env: Record<string, string>;
     /** Explicit environment overrides safe to persist for opt-in persistent jobs. */
     envOverrides?: Record<string, string>;
@@ -4000,12 +4805,16 @@ interface ToolContext {
     onHookEvent?: (event: string, payload: Record<string, unknown>) => void;
     /** Host sink for one-line informational notices (e.g. memory saved). */
     onNotice?: (notice: string) => void;
-    /** Canonical tool names invoked so far in this session. */
-    usedToolNames?: Set<string>;
     /** Per-session capability/discovery controller installed by the agent loop. */
     toolDiscovery?: ToolDiscoveryContext;
     /** Mutable resources owned by the current session, separate from configuration. */
     runtime?: SessionRuntime;
+    /** The conversation as the running loop holds it, for a tool that reads it whole (`Advisor`). */
+    conversation?: () => readonly Message[];
+    /** The system prompt of the request the running loop last sent, for the same tool. */
+    systemPrompt?: () => string;
+    /** Spend on a model the tool called itself (`AgentLoopCallbacks.onAuxiliaryUsage`). */
+    onAuxiliaryUsage?: (usage: Usage, metadata: ProviderResponseMetadata, source: string) => void;
 }
 interface ToolSearchMatch {
     name: string;
@@ -4160,6 +4969,9 @@ type AgentEvent = {
     type: 'notice';
     message: string;
     title?: string;
+} | {
+    type: 'goal_status';
+    event: GoalStatusEvent;
 } | {
     type: 'error';
     error: string;