@namzu/cli 18.0.0 → 19.0.0

package/dist/tui/agent.js

@@ -20,18 +20,24 @@
  * `emptySession()` whose `send()` yields a single error event so the UI
  * renders an actionable hint rather than crashing.
  */
-import { BOOT_EVENT_NAMES, DefaultPathBuilder, DiskMemoryStore, DiskTaskStore, EVENT_NAME_ATTRIBUTE, ProviderRegistry, SESSION_GOAL_TOOL_NAMES, SearchToolsTool, ToolRegistry, asProjectId, asRunId, asSessionId, asTenantId, asTopicId, buildMemoryTools, buildSessionGoalTools, compactNow, createComputerUseTool, createMemoryPromoter, createToolPresenter, generateRunId, getBuiltinTools, isTrustedReadOnly, query, resumeRun, withProviderFallback, } from '@namzu/sdk';
+import { BOOT_EVENT_NAMES, BackgroundJobRegistry, DefaultPathBuilder, DiskCheckpointStore, DiskMemoryStore, DiskTaskStore, EVENT_NAME_ATTRIBUTE, GuardedFetchProvider, PromptContributionRegistry, ProviderRegistry, SESSION_GOAL_TOOL_NAMES, SearchToolsTool, ToolRegistry, WebFetchTool, batchNeedsReview, buildAskUserQuestionTool, buildMemoryTools, buildSessionGoalTools, compactNow, createComputerUseTool, createMemoryPromoter, createReviewHandler, createToolPresenter, generateProjectId, generateRunId, generateSessionId, generateTenantId, generateTopicId, getBuiltinTools, isReviewExempt, query, resumeRun, webGuidanceContribution, withProviderFallback, } from '@namzu/sdk';
 import { SubprocessComputerUseHost } from '@namzu/computer-use';
 import { realpath, stat } from 'node:fs/promises';
 import { join, parse, resolve } from 'node:path';
+import { FileCheckpointStore } from '../checkpoints/store.js';
+import { CHECKPOINTED_TOOLS, withCheckpoints } from '../checkpoints/wrap.js';
 import { probeCapabilities } from '../context/capabilities.js';
+import { NAMZU_DELEGATION_DOCTRINE, NAMZU_PLAN_MODE_DOCTRINE, NAMZU_WORKING_DOCTRINE, } from '../context/doctrine.js';
 import { composeEnvironmentPrompt, readEnvironmentFacts } from '../context/environment.js';
 import { ProjectInstructionTracker } from '../context/project-tracker.js';
 import { resolveSandbox, sandboxResolvedSeverity, } from '../context/sandbox.js';
+import { composeTurnSnapshot, readTurnSnapshot } from '../context/turn-snapshot.js';
 import { connectMcpServers, } from '../integrations/mcp/servers.js';
 import { createCliPluginRuntime } from '../integrations/plugins/runtime.js';
 import { CredentialRefreshRejectedError, CredentialWithdrawnError, PROVIDER_REGISTRY, chainCapabilityDisagreements, chainPositionName, describeAcceptedMismatch, describeCapabilityRefusal, discoverProviders, ensureFreshAnthropicToken, ensureFreshStoredCodexCredential, ensureRegistered, findDetected, isAnthropicOAuthToken, isRegistered, missingCredentialMessage, primaryProvider, readCodexCredentialFile, readPreferences, readSubscriptionCredential, resolveChainCapabilities, sameOAuthCredential, unresolvedMembers, unsupportedProviderMessage, } from '../integrations/providers/index.js';
 import { ensurePrivateStateDirectory } from '../integrations/state/private-directory.js';
+import { discoverAgentDefinitions } from '../integrations/subagents/definitions.js';
+import { SubagentPathBuilder, resolveSubagentParent } from '../integrations/subagents/parent.js';
 import { CLI_INTERACTIVE_RUN_TIMEOUT_MS } from '../integrations/subagents/policy.js';
 import { createSubagentRuntime } from '../integrations/subagents/runtime.js';
 import { cliLogger } from '../logging.js';
@@ -238,7 +244,17 @@ async function drainIterator(iterator) {
  */
 export async function probeAgentSession() {
     const read = readPreferences();
+    // Bracketed in the log because this is where a boot has stalled without
+    // a record on either side: it reads credential files, and on WSL it asks
+    // Windows for the paired home. A hang that shows the last line before it
+    // and nothing after is this step.
+    const discoveryStartedAt = Date.now();
+    cliLogger().debug('discovering provider credentials');
     const detected = await discoverProviders();
+    cliLogger().debug('provider credentials discovered', {
+        'namzu.boot.discovery_ms': Date.now() - discoveryStartedAt,
+        'namzu.boot.detected_count': detected.length,
+    });
     switch (read.status) {
         case 'ok':
             return {
@@ -357,9 +373,21 @@ function builtinTools(backgroundJobs) {
         return [tool.name === 'bash' ? foregroundOnlyBash(tool) : tool];
     });
 }
-function buildToolRegistry(cwd, projectStateRoot = join(cwd, '.namzu'), backgroundJobs = true) {
+function buildToolRegistry(cwd, projectStateRoot = join(cwd, '.namzu'), backgroundJobs = true, checkpoints) {
     const registry = new ToolRegistry();
     registry.register(builtinTools(backgroundJobs));
+    // The file tools take a checkpoint before they write, so `/restore` can
+    // put the tree back. Only the session's own registry: a sub-agent's
+    // writes are not checkpointed yet, and the page says so.
+    if (checkpoints) {
+        for (const name of CHECKPOINTED_TOOLS) {
+            const tool = registry.get(name);
+            if (!tool)
+                continue;
+            registry.unregister(name);
+            registry.register(withCheckpoints(tool, checkpoints));
+        }
+    }
     // SDK memory: the agent gets search_memory / read_memory / save_memory over
     // a structured store in this Project's generated-state directory. CLI
     // surfaces inject the central application-home hierarchy; embedded callers
@@ -711,8 +739,46 @@ export async function createAgentSession(prefs, detected, options = {}) {
         [EVENT_NAME_ATTRIBUTE]: BOOT_EVENT_NAMES.SANDBOX_RESOLVED,
         'namzu.sandbox.unconfined': sandbox.unconfined,
     });
-    const backgroundJobs = sandbox.provider === undefined;
-    const { registry, memoryStore } = buildToolRegistry(cwd, projectStateRoot, backgroundJobs);
+    // Always built: the executor hands it to the tools only where it is
+    // safe — on the host, or inside a sandbox that can start a detached
+    // process — so a session under a sandbox that cannot simply has none.
+    const backgroundJobs = true;
+    // One registry per session, and jobs bound to the SESSION: a dev server
+    // started in one turn is still there in the next, and the kernel tells
+    // the model when a job ends. Stopped when the session closes, below.
+    // Withheld under a sandbox for the reason the kernel gives: the registry
+    // runs on the host and must not sit beside a sandbox in one tool context.
+    const jobRegistry = backgroundJobs ? new BackgroundJobRegistry() : undefined;
+    const jobOwner = scope.sessionId;
+    // Session-scoped and mutable: `/add-dir` adds to it, and every turn reads
+    // it fresh — the query, the sandbox binds and the environment prompt.
+    const directories = [];
+    for (const dir of options.additionalDirectories ?? []) {
+        const absolute = resolve(cwd, dir);
+        if (absolute !== resolve(cwd) && !directories.includes(absolute))
+            directories.push(absolute);
+    }
+    const sessionDirectories = {
+        list: () => [...directories],
+        add: async (path) => {
+            const absolute = resolve(cwd, path);
+            if (absolute === resolve(cwd))
+                return {
+                    added: false,
+                    path: absolute,
+                    reason: 'That is the working directory.',
+                };
+            if (directories.includes(absolute))
+                return { added: false, path: absolute, reason: 'Already added.' };
+            const entry = await stat(absolute).catch(() => null);
+            if (!entry?.isDirectory())
+                return { added: false, path: absolute, reason: 'Not a directory.' };
+            directories.push(absolute);
+            return { added: true, path: absolute };
+        },
+    };
+    const checkpoints = new FileCheckpointStore(join(ensurePrivateStateDirectory(projectStateRoot, 'checkpoints'), scope.sessionId), cwd);
+    const { registry, memoryStore } = buildToolRegistry(cwd, projectStateRoot, backgroundJobs, checkpoints);
     // Package presence is not tool reachability. The CLI used to probe and
     // report @namzu/computer-use without ever constructing its host or mounting
     // SDK's computer_use definition, so even an installed, healthy package was
@@ -732,6 +798,28 @@ export async function createAgentSession(prefs, detected, options = {}) {
         catch (error) {
             computerUseError = error instanceof Error ? error : new Error(String(error));
             await candidate.dispose().catch(() => { });
+            // Mounted anyway, with every capability false and the reason on it.
+            // A tool that is absent is a tool the model reasons about from the
+            // wrong premise; a tool that says "this desktop did not answer, and
+            // why" is one call the model reads once and does not repeat.
+            registry.register(createComputerUseTool({
+                id: candidate.id,
+                capabilities: {
+                    ...candidate.capabilities,
+                    screenshot: false,
+                    mouse: false,
+                    keyboard: false,
+                    cursorPosition: false,
+                    clipboard: false,
+                    unavailableReason: describeError(computerUseError),
+                },
+                getDisplayGeometry: async () => {
+                    throw computerUseError;
+                },
+                execute: async () => {
+                    throw computerUseError;
+                },
+            }));
         }
     }
     // Registered only on the main session path. Sub-agents call
@@ -789,10 +877,19 @@ export async function createAgentSession(prefs, detected, options = {}) {
     // This session passes a `taskStore` to query() below, which registers the
     // task tools deferred — so `search_tools` has something to find here.
     registry.register([SearchToolsTool]);
+    // Web reach, opted into in the config file and nowhere else. The parent's
+    // registry only: a child's config carries no provider, and a tool whose
+    // provider is missing is a tool that reports itself unwired — truthful,
+    // and noise. The guarded provider refuses private and loopback addresses
+    // and bounds redirects and body; every fetch is reviewed like a shell
+    // command (see `isPromptExempt`).
+    const webCapability = options.web?.fetch ? { fetch: new GuardedFetchProvider() } : undefined;
+    if (webCapability)
+        registry.register(WebFetchTool);
     // Native sub-agents: register the canonical `Agent` tool so the model can
     // delegate a self-contained task to a fresh sub-agent (own context window).
     // Best-effort — if the runtime can't stand up, the chat still works.
-    let subagentGateway;
+    const delegationScopes = new Map();
     let subagentRuntime;
     // Stays empty when the runtime below throws, which is the honest answer: the
     // catch is non-fatal and the session then genuinely has no delegate to
@@ -800,10 +897,28 @@ export async function createAgentSession(prefs, detected, options = {}) {
     // would name agents that are not there.
     let allowedAgentIds = [];
     try {
+        // Agents the project or user defined in files. A file that cannot be
+        // loaded is named with its reason rather than silently absent: "namzu
+        // ignored my reviewer" and "namzu never saw it" call for opposite fixes.
+        const discovered = await discoverAgentDefinitions({ cwd });
+        for (const skipped of discovered.skipped) {
+            cliLogger().warn('agent definition skipped', {
+                'namzu.agent.definition.path': skipped.path,
+                'namzu.agent.definition.reason': skipped.reason,
+            });
+        }
         const sub = await createSubagentRuntime({
             cwd,
             model,
-            pathBuilder: new DefaultPathBuilder(join(projectStateRoot, 'subagents')),
+            tokenBudget: options.limits?.tokenBudget,
+            definitions: discovered.definitions,
+            pathBuilder: new SubagentPathBuilder(projectStateRoot, scope.projectId),
+            resolveParent: async (runId) => {
+                const parent = delegationScopes.get(runId);
+                if (!parent)
+                    throw new Error(`Run ${runId} no longer owns delegation authority`);
+                return resolveSubagentParent(parent, cwd, options.stateRoot ? hierarchyRoot : undefined);
+            },
             sandboxWorkspace,
             resolveResumeHandler: (runId) => delegatedResumeHandlers.get(runId),
             ...(sandbox.provider ? { sandboxProvider: sandbox.provider } : {}),
@@ -850,7 +965,6 @@ export async function createAgentSession(prefs, detected, options = {}) {
         });
         subagentRuntime = sub;
         registry.register([sub.agentTool]);
-        subagentGateway = sub.gateway;
         allowedAgentIds = sub.allowedAgentIds;
     }
     catch (err) {
@@ -864,24 +978,90 @@ export async function createAgentSession(prefs, detected, options = {}) {
         // and got none had nothing on stderr to say why.
         cliLogger().warn('sub-agent runtime unavailable this session', exceptionAttributes(err));
     }
-    // Task store → query registers task_create / task_update / task_list as
-    // DEFERRED tools and emits task_created/task_updated, so the agent can track
-    // a plan for the current request. Tasks are run-scoped.
+    // `ask_user_question`, where somebody can answer. The SDK tool parks the
+    // run through the handler it was BUILT with, so that handler reads the
+    // turn's answerer through a holder the prelude fills: the tool is per
+    // session, the person answering is per turn. Needs the delegation
+    // gateway the tool builder requires; a session without one has no
+    // question tool either, and says nothing — it also has no `Agent`.
+    let currentOnQuestion;
+    if (options.askUser && subagentRuntime) {
+        const parkQuestion = async (request) => {
+            if (request.type !== 'user_question')
+                return { action: 'continue' };
+            const ask = currentOnQuestion;
+            if (!ask)
+                return { action: 'continue' };
+            const answer = await ask(request.question);
+            switch (answer.kind) {
+                case 'answer':
+                    return {
+                        action: 'answer_question',
+                        selectedOptionIds: [...answer.selectedOptionIds],
+                        ...(answer.freeText !== undefined ? { freeText: answer.freeText } : {}),
+                        questionId: request.question.questionId,
+                    };
+                case 'abort':
+                    return { action: 'abort', reason: 'The user declined to answer.' };
+                default:
+                    return { action: 'continue' };
+            }
+        };
+        // The park request carries the run id of the call that asked; the
+        // handler above routes by the question, not by the run, and no durable
+        // park recorder is supplied.
+        registry.register(buildAskUserQuestionTool({ resumeHandler: parkQuestion }));
+    }
+    // Task store → query registers task_create / task_update / task_list and
+    // emits task_created/task_updated, so the agent can track a plan for the
+    // current request. Tasks are run-scoped. The kernel's default availability
+    // for them is `deferred`; this session overrides that to `active` at the
+    // query call, because the doctrine tells the model to plan with them and a
+    // tool it must search for first is a tool it skips.
     //
-    // "Deferred" is why this session mounts `search_tools` above: these three are
-    // the roster it searches. They are registered inside query(), after this
-    // function returns, which is why the connect line reports no count of them —
-    // counting here would mean restating query's registration order in the CLI.
+    // `search_tools` stays mounted above even so: a tool server or plugin can
+    // still register a deferred roster, and that is what the search is for. The
+    // task tools are registered inside query(), after this function returns,
+    // which is why the connect line reports no count of them — counting here
+    // would mean restating query's registration order in the CLI.
     //
     // It is also why `toolNames` below reads the registry rather than a list
     // captured on this line. The count at connect time is unchanged; what
     // changes is that asking again later gets a later answer.
     ensurePrivateStateDirectory(projectStateRoot, 'tenants');
-    const taskStore = new DiskTaskStore({
+    const taskStoreForRun = (runId, tenantId) => new DiskTaskStore({
         baseDir: projectStateRoot,
-        defaultRunId: asRunId('run_namzu-cli'),
-        tenantId: scope.tenantId,
+        defaultRunId: runId,
+        tenantId,
     });
+    let selectedTaskStore;
+    let taskSelectionGeneration = 0;
+    const resetTaskStore = () => {
+        selectedTaskStore = undefined;
+        taskSelectionGeneration += 1;
+    };
+    const matchesCurrentScope = (candidate) => candidate.sessionId === scope.sessionId &&
+        candidate.projectId === scope.projectId &&
+        candidate.tenantId === scope.tenantId &&
+        candidate.topicId === scope.topicId;
+    const currentTaskStore = () => {
+        if (selectedTaskStore && !matchesCurrentScope(selectedTaskStore.scope))
+            resetTaskStore();
+        return selectedTaskStore?.store;
+    };
+    const beginTaskStoreReadout = () => {
+        // A starting turn must not show its predecessor's plan while credentials
+        // and other asynchronous setup are still being prepared.
+        resetTaskStore();
+        const generation = taskSelectionGeneration;
+        return (runId, runScope) => {
+            const store = taskStoreForRun(runId, runScope.tenantId);
+            if (generation === taskSelectionGeneration && matchesCurrentScope(runScope)) {
+                selectedTaskStore = { scope: { ...runScope }, store };
+            }
+            return store;
+        };
+    };
     // Persists across turns: once the user picks "approve all", later tool
     // batches in this session run without prompting.
     const approval = { all: false };
@@ -903,12 +1083,31 @@ export async function createAgentSession(prefs, detected, options = {}) {
     // registries, so executable plugins remain a top-level-session capability.
     let pluginRuntime;
     try {
-        pluginRuntime = await createCliPluginRuntime(options.plugins, registry, cwd);
+        pluginRuntime = await createCliPluginRuntime(options.plugins, registry, cwd, options.hooks);
     }
     catch (error) {
         await Promise.allSettled([mcp.close(), computerUseHost?.dispose()]);
         return emptySession(describeError(error));
     }
+    // The session's own lifecycle, for hooks that set up or tear down
+    // something per session rather than per run. The run id is minted for
+    // these two calls: they belong to no turn. `session_start` waits for
+    // the first turn rather than firing here, because the conversation id
+    // the scope holds at construction is provisional — it is replaced when
+    // the conversation is first made durable — and a hook given the
+    // provisional id could never match it to a run.
+    const sessionPlugins = pluginRuntime;
+    const sessionHookRunId = generateRunId();
+    let sessionStarted = false;
+    const announceSessionStart = async () => {
+        if (!sessionPlugins || sessionStarted)
+            return;
+        sessionStarted = true;
+        await sessionPlugins.manager.executeHooks('session_start', {
+            runId: sessionHookRunId,
+            sessionId: scope.sessionId,
+        });
+    };
     if (pluginRuntime) {
         cliLogger().info('discovery complete', {
             [EVENT_NAME_ATTRIBUTE]: BOOT_EVENT_NAMES.DISCOVERY_COMPLETED,
@@ -930,9 +1129,19 @@ export async function createAgentSession(prefs, detected, options = {}) {
     const operations = new SessionOperationOwner(async () => {
         const results = await Promise.allSettled([
             subagentRuntime?.close?.(),
-            pluginRuntime?.close(),
+            sessionPlugins
+                ? sessionPlugins.manager
+                    .executeHooks('session_end', {
+                    runId: sessionHookRunId,
+                    sessionId: scope.sessionId,
+                })
+                    .catch(() => [])
+                    .then(() => sessionPlugins.close())
+                : undefined,
             mcp.close(),
             computerUseHost?.dispose(),
+            jobRegistry?.killOwner(jobOwner),
+            checkpoints.close(),
         ]);
         const failures = results
             .filter((result) => result.status === 'rejected')
@@ -972,6 +1181,200 @@ export async function createAgentSession(prefs, detected, options = {}) {
         reasoningEffortDefault = undefined;
         effortNotice = `Reasoning effort levels could not be established for this session: ${describeError(error)}`;
     }
+    /**
+     * The kernel's resume with this session's half of the run attached: the
+     * provider, the tools, the working directory, the doctrine — the part a
+     * checkpoint cannot carry. `resumeDurable` and `resumePaused` differ only
+     * in where the run and its store come from.
+     */
+    const kernelResume = ({ entry, checkpointStore, claimFence, signal, checkpointId, listener, }) => operations.promise(signal, async (ownedSignal) => {
+        const selectTaskStore = beginTaskStoreReadout();
+        // The same prelude a turn runs, and for the same reasons: a lapsed
+        // OAuth token has to be renewed before the provider is used, and the
+        // fallback chain has to be built AFTER that so its members do not
+        // hold a client the refresh just replaced.
+        await prepareProviderCredential(ownedSignal);
+        const pluginSkills = pluginRuntime
+            ? await currentPluginSkills(pluginRuntime.skills)
+            : undefined;
+        const memoryPrompt = composeMemoryPrompt(readMemory(undefined, cwd));
+        const environmentPrompt = composeEnvironmentPrompt({
+            ...(await readEnvironmentFacts(cwd)),
+            additionalDirectories: [...directories],
+        });
+        const systemPrompt = [
+            NAMZU_IDENTITY,
+            NAMZU_WORKING_DOCTRINE,
+            NAMZU_DELEGATION_DOCTRINE,
+            environmentPrompt,
+            memoryPrompt,
+        ]
+            .filter((s) => Boolean(s))
+            .join('\n\n') || undefined;
+        const resumeHandler = makeResumeHandler(approval, undefined, options.permissionMode, (name, input) => isPromptExempt(registry, name, input));
+        if (delegatedResumeHandlers.has(entry.runId)) {
+            throw new Error(`Run ${entry.runId} already owns a delegated review channel.`);
+        }
+        delegatedResumeHandlers.set(entry.runId, resumeHandler);
+        delegationScopes.set(entry.runId, { ...entry, topicId: scope.topicId });
+        try {
+            return await resumeRun({
+                provider,
+                fallbackProviders: fallbackPlan.build(currentToken),
+                tools: registry,
+                pluginManager: pluginRuntime?.manager,
+                skillRegistry: pluginRuntime?.skills,
+                skills: pluginSkills,
+                taskStore: selectTaskStore(entry.runId, { ...entry, topicId: scope.topicId }),
+                // The same availability the original run registered under.
+                // A resumed run re-registers the task tools; leaving them at
+                // the kernel's `deferred` default would hand the model a plan
+                // it started with active tools and can no longer update.
+                runtimeToolOverrides: {
+                    task_create: 'active',
+                    task_update: 'active',
+                    task_list: 'active',
+                },
+                ...(subagentRuntime
+                    ? {
+                        taskScheduler: await subagentRuntime.gatewayForRun(entry.runId),
+                    }
+                    : {}),
+                authorizationGate: gateFor(options.rules),
+                compactionConfig: compactionConfigFor(options.compaction),
+                projectInstructionContext: projectInstructions.createRunContext(),
+                pathBuilder,
+                ...(sandbox.provider ? { sandboxProvider: sandbox.provider } : {}),
+                ...(options.sandbox?.teardownTimeoutMs !== undefined
+                    ? { sandboxTeardownTimeoutMs: options.sandbox.teardownTimeoutMs }
+                    : {}),
+                // NOT `emergencySave`, unlike a turn. The manager is a singleton
+                // whose `attach` detaches whoever held it before, so a caller
+                // resuming several runs in one process would leave only the last
+                // one covered — and would look covered. A turn owns its process
+                // end to end; a drainer does not.
+                runConfig: {
+                    model,
+                    ...(sandbox.provider ? { sandbox: { workspace: sandboxWorkspace } } : {}),
+                    timeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS,
+                    tokenBudget: options.limits?.tokenBudget ?? 1_000_000,
+                    maxIterations: options.limits?.maxIterations ?? 50,
+                    maxResponseTokens: 8192,
+                    permissionMode: 'auto',
+                },
+                agentId: 'namzu',
+                agentName: 'namzu',
+                ...(systemPrompt ? { systemPrompt } : {}),
+                workingDirectory: cwd,
+                ...(directories.length > 0 ? { additionalDirectories: [...directories] } : {}),
+                ...(options.limits ? { limits: options.limits } : {}),
+                // No `onPermission`: there is nobody at a drainer's terminal, so a
+                // prompt would block the pass forever on a run nobody is watching.
+                // The gate's deny rules still apply.
+                // One presenter for the whole stream, built from the registry this
+                // scope already holds. It was the absence of the registry HERE that
+                // forced presentation to be name matching: `toAgentEvent` was pure
+                // over a `RunEvent` and could not ask a tool anything.
+                resumeHandler,
+                signal: ownedSignal,
+                // Attribution comes from the ENTRY, not from this session: the run
+                // belongs to whoever started it, and stamping the drainer's ids onto
+                // it would file another tenant's work under this one.
+                tenantId: entry.tenantId,
+                projectId: entry.projectId,
+                sessionId: entry.sessionId,
+                // …except the topic, which no checkpoint records — see
+                // `RunStateScope`. This one is the drainer's, and honestly so:
+                // supplied here rather than pretended to have been recovered.
+                topicId: scope.topicId,
+                scope: { ...entry, topicId: scope.topicId },
+                checkpointStore,
+                ...(claimFence !== undefined ? { claimFence } : {}),
+                ...(checkpointId !== undefined ? { checkpointId } : {}),
+                ...(listener ? { listener } : {}),
+            });
+        }
+        finally {
+            if (delegatedResumeHandlers.get(entry.runId) === resumeHandler) {
+                delegatedResumeHandlers.delete(entry.runId);
+                delegationScopes.delete(entry.runId);
+                await subagentRuntime?.releaseRun(entry.runId);
+            }
+        }
+    });
+    /**
+     * `resumeRun` drains the loop and returns a settled run; the events go to a
+     * listener. A small queue turns that into the stream `send` gives, so a
+     * headless caller renders a resumed run exactly as it rendered the turn.
+     */
+    const resumePausedStream = ({ runId, checkpointId, signal, }) => {
+        const queue = [];
+        let wake;
+        let settled = false;
+        let failure;
+        const presenter = createToolPresenter(registry);
+        // The store the turn's run manager wrote to, built the same way it
+        // built it (see the kernel's `RunPersistence`): the session directory's
+        // `runs/`, attributed to this tenant and project.
+        const store = new DiskCheckpointStore({
+            baseDir: join(pathBuilder.sessionDir(scope.projectId, scope.sessionId), 'runs'),
+        }, {
+            tenantId: scope.tenantId,
+            projectId: scope.projectId,
+            sessionId: scope.sessionId,
+        });
+        const entry = {
+            tenantId: scope.tenantId,
+            projectId: scope.projectId,
+            sessionId: scope.sessionId,
+            runId: runId,
+        };
+        const outcome = kernelResume({
+            entry,
+            checkpointStore: store,
+            ...(signal ? { signal } : {}),
+            checkpointId: checkpointId,
+            listener: (event) => {
+                queue.push(event);
+                wake?.();
+            },
+        })
+            .then((result) => {
+            if (!result.resumed) {
+                failure = new Error(result.reason === 'no-checkpoint'
+                    ? `no checkpoint ${checkpointId} is recorded for run ${runId}`
+                    : `run ${runId} is parked on a decision only a person can answer`);
+            }
+        })
+            .catch((err) => {
+            failure = err instanceof Error ? err : new Error(String(err));
+        })
+            .finally(() => {
+            settled = true;
+            wake?.();
+        });
+        return (async function* () {
+            for (;;) {
+                while (queue.length > 0) {
+                    const next = queue.shift();
+                    if (!next)
+                        break;
+                    const mapped = toAgentEvent(next, presenter);
+                    if (mapped)
+                        yield mapped;
+                }
+                if (settled)
+                    break;
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
+                wake = undefined;
+            }
+            await outcome;
+            if (failure)
+                yield { kind: 'error', message: failure.message };
+        })();
+    };
     return {
         hasProvider: true,
         sandbox: {
@@ -989,7 +1392,7 @@ export async function createAgentSession(prefs, detected, options = {}) {
             await prepareProviderCredential(signal);
             return compactNow({
                 messages,
-                config: COMPACTION_CONFIG,
+                config: compactionConfigFor(options.compaction),
                 provider,
                 model,
                 signal,
@@ -1003,6 +1406,16 @@ export async function createAgentSession(prefs, detected, options = {}) {
             .map((t) => t.name)
             .filter((name) => !goalToolNames.has(name)),
         agentIds: allowedAgentIds,
+        currentTaskStore,
+        resetTaskStore,
+        jobs: () => jobRegistry?.list(jobOwner) ?? [],
+        ...(options.hooks ? { hooks: options.hooks } : {}),
+        checkpoints,
+        directories: sessionDirectories,
+        onJobExit: (listener) => jobRegistry?.onExit((job) => {
+            if (job.owner === jobOwner)
+                listener(job);
+        }) ?? (() => { }),
         ...(subagentRuntime ? { subagents: subagentRuntime.activity } : {}),
         get instructionFiles() {
             return projectInstructions.instructionFiles;
@@ -1036,6 +1449,7 @@ export async function createAgentSession(prefs, detected, options = {}) {
         },
         promptExemptTools: () => promptExemptToolNames(registry).filter((name) => !goalToolNames.has(name)),
         send: (messages, opts) => operations.stream(opts?.signal, (signal) => (async function* () {
+            const selectTaskStore = beginTaskStoreReadout();
             const runId = opts?.runId ?? generateRunId();
             const turnOpts = { ...opts, runId, signal };
             const resumeHandler = makeResumeHandler(approval, opts?.onPermission, opts?.permissionMode ?? options.permissionMode, (name, input) => isPromptExempt(registry, name, input));
@@ -1043,6 +1457,8 @@ export async function createAgentSession(prefs, detected, options = {}) {
                 throw new Error(`Run ${runId} already owns a delegated review channel.`);
             }
             delegatedResumeHandlers.set(runId, resumeHandler);
+            const turnScope = { ...scope };
+            delegationScopes.set(runId, turnScope);
             try {
                 // Renew a lapsed OAuth token before the turn runs (no-op for valid
                 // tokens and non-subscription credentials).
@@ -1061,11 +1477,52 @@ export async function createAgentSession(prefs, detected, options = {}) {
                 const pluginSkills = pluginRuntime
                     ? await currentPluginSkills(pluginRuntime.skills)
                     : undefined;
-                const memoryPrompt = composeMemoryPrompt(readMemory());
-                const environmentPrompt = composeEnvironmentPrompt(await readEnvironmentFacts(cwd));
-                const systemPrompt = [NAMZU_IDENTITY, environmentPrompt, memoryPrompt, opts?.extraSystem]
+                const memoryPrompt = composeMemoryPrompt(readMemory(undefined, cwd));
+                currentOnQuestion = opts?.onQuestion;
+                const [environmentFacts, turnSnapshot] = await Promise.all([
+                    readEnvironmentFacts(cwd),
+                    readTurnSnapshot(cwd),
+                ]);
+                const environmentPrompt = composeEnvironmentPrompt({
+                    ...environmentFacts,
+                    additionalDirectories: [...directories],
+                });
+                // The repository as it stood when THIS turn began, through the
+                // SDK's `turn` placement — the ephemeral trailing message that is
+                // never cached and never enters history. FIRST iteration only:
+                // later iterations work from state the model itself changed, and
+                // `git status` is the honest source for that. A registry per
+                // turn, closed over this turn's snapshot, rather than one
+                // session-scoped holder every send overwrites: two overlapping
+                // sends would otherwise both render whichever ran second.
+                const turnSnapshotPrompt = turnSnapshot ? composeTurnSnapshot(turnSnapshot) : null;
+                const promptContributions = new PromptContributionRegistry();
+                promptContributions.register({
+                    id: 'namzu.turn-snapshot',
+                    placement: 'turn',
+                    render: ({ iteration }) => (iteration === 1 ? turnSnapshotPrompt : null),
+                });
+                // The citation rules that come with the web tools, only when the
+                // tools are there: guidance about a capability the turn does not
+                // have reads as a capability it should be looking for.
+                if (webCapability)
+                    promptContributions.register(webGuidanceContribution);
+                const systemPrompt = [
+                    NAMZU_IDENTITY,
+                    NAMZU_WORKING_DOCTRINE,
+                    NAMZU_DELEGATION_DOCTRINE,
+                    // Present only while the turn runs under `plan`. A mode change
+                    // is rare, so the cached prefix it re-keys is a price paid once
+                    // per switch rather than once per turn.
+                    opts?.permissionMode === 'plan' ? NAMZU_PLAN_MODE_DOCTRINE : undefined,
+                    environmentPrompt,
+                    memoryPrompt,
+                    opts?.extraSystem,
+                ]
                     .filter((s) => Boolean(s))
                     .join('\n\n') || undefined;
+                await announceSessionStart();
+                checkpoints.beginTurn(lastUserText(messages));
                 let capturedAuthority;
                 if (opts?.goalRound) {
                     if (!opts.runId)
@@ -1095,6 +1552,14 @@ export async function createAgentSession(prefs, detected, options = {}) {
                 try {
                     yield* runTurn({
                         provider,
+                        compactionConfig: compactionConfigFor(options.compaction),
+                        ...(options.compaction?.consolidate ? { consolidateInto: memoryStore } : {}),
+                        ...(jobRegistry
+                            ? {
+                                backgroundJobs: jobRegistry,
+                                backgroundJobOwner: jobOwner,
+                            }
+                            : {}),
                         // Constructed HERE, per turn, and that is not an optimisation to
                         // undo. `refreshTokenIfNeeded` above replaces the head's client
                         // object when an OAuth token rotates, so a member list built once at
@@ -1108,21 +1573,33 @@ export async function createAgentSession(prefs, detected, options = {}) {
                         pluginManager: pluginRuntime?.manager,
                         skillRegistry: pluginRuntime?.skills,
                         skills: pluginSkills,
-                        scope,
+                        scope: turnScope,
                         pathBuilder,
                         workingDirectory: cwd,
+                        ...(directories.length > 0 ? { additionalDirectories: [...directories] } : {}),
+                        ...(options.limits ? { limits: options.limits } : {}),
                         sandboxWorkspace,
                         rules: options.rules,
                         reviewAnswer: options.reviewAnswer,
                         maxAnswerReviews: options.maxAnswerReviews,
                         promoteMemory,
-                        taskStore,
+                        taskStore: selectTaskStore(runId, turnScope),
                         systemPrompt,
                         messages,
                         projectInstructionContext: projectInstructions.createRunContext(),
                         opts: turnOpts,
                         resumeHandler,
-                        taskGateway: subagentGateway,
+                        taskGateway: await subagentRuntime?.gatewayForRun(runId),
+                        promptContributions,
+                        ...(webCapability ? { web: webCapability } : {}),
+                        // Active, not deferred: the doctrine tells the model to open a
+                        // task list for multi-step work, and a tool it has to search
+                        // for first is a tool it will skip.
+                        runtimeToolOverrides: {
+                            task_create: 'active',
+                            task_update: 'active',
+                            task_list: 'active',
+                        },
                         onRunEvent: options.onRunEvent,
                         ...(sandbox.provider ? { sandboxProvider: sandbox.provider } : {}),
                         ...(options.sandbox?.teardownTimeoutMs !== undefined
@@ -1143,94 +1620,18 @@ export async function createAgentSession(prefs, detected, options = {}) {
             finally {
                 if (delegatedResumeHandlers.get(runId) === resumeHandler) {
                     delegatedResumeHandlers.delete(runId);
+                    delegationScopes.delete(runId);
+                    await subagentRuntime?.releaseRun(runId);
                 }
             }
         })()),
-        resumeDurable: ({ entry, checkpointStore, claimFence, signal }) => operations.promise(signal, async (ownedSignal) => {
-            // The same prelude a turn runs, and for the same reasons: a lapsed
-            // OAuth token has to be renewed before the provider is used, and the
-            // fallback chain has to be built AFTER that so its members do not
-            // hold a client the refresh just replaced.
-            await prepareProviderCredential(ownedSignal);
-            const pluginSkills = pluginRuntime
-                ? await currentPluginSkills(pluginRuntime.skills)
-                : undefined;
-            const memoryPrompt = composeMemoryPrompt(readMemory());
-            const environmentPrompt = composeEnvironmentPrompt(await readEnvironmentFacts(cwd));
-            const systemPrompt = [NAMZU_IDENTITY, environmentPrompt, memoryPrompt]
-                .filter((s) => Boolean(s))
-                .join('\n\n') || undefined;
-            const resumeHandler = makeResumeHandler(approval, undefined, options.permissionMode, (name, input) => isPromptExempt(registry, name, input));
-            if (delegatedResumeHandlers.has(entry.runId)) {
-                throw new Error(`Run ${entry.runId} already owns a delegated review channel.`);
-            }
-            delegatedResumeHandlers.set(entry.runId, resumeHandler);
-            try {
-                return await resumeRun({
-                    provider,
-                    fallbackProviders: fallbackPlan.build(currentToken),
-                    tools: registry,
-                    pluginManager: pluginRuntime?.manager,
-                    skillRegistry: pluginRuntime?.skills,
-                    skills: pluginSkills,
-                    taskStore,
-                    ...(subagentGateway ? { taskGateway: subagentGateway } : {}),
-                    authorizationGate: gateFor(options.rules),
-                    compactionConfig: COMPACTION_CONFIG,
-                    projectInstructionContext: projectInstructions.createRunContext(),
-                    pathBuilder,
-                    ...(sandbox.provider ? { sandboxProvider: sandbox.provider } : {}),
-                    ...(options.sandbox?.teardownTimeoutMs !== undefined
-                        ? { sandboxTeardownTimeoutMs: options.sandbox.teardownTimeoutMs }
-                        : {}),
-                    // NOT `emergencySave`, unlike a turn. The manager is a singleton
-                    // whose `attach` detaches whoever held it before, so a caller
-                    // resuming several runs in one process would leave only the last
-                    // one covered — and would look covered. A turn owns its process
-                    // end to end; a drainer does not.
-                    runConfig: {
-                        model,
-                        ...(sandbox.provider ? { sandbox: { workspace: sandboxWorkspace } } : {}),
-                        timeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS,
-                        tokenBudget: 1_000_000,
-                        maxIterations: 50,
-                        maxResponseTokens: 8192,
-                        permissionMode: 'auto',
-                    },
-                    agentId: 'namzu',
-                    agentName: 'namzu',
-                    ...(systemPrompt ? { systemPrompt } : {}),
-                    workingDirectory: cwd,
-                    // No `onPermission`: there is nobody at a drainer's terminal, so a
-                    // prompt would block the pass forever on a run nobody is watching.
-                    // The gate's deny rules still apply.
-                    // One presenter for the whole stream, built from the registry this
-                    // scope already holds. It was the absence of the registry HERE that
-                    // forced presentation to be name matching: `toAgentEvent` was pure
-                    // over a `RunEvent` and could not ask a tool anything.
-                    resumeHandler,
-                    signal: ownedSignal,
-                    // Attribution comes from the ENTRY, not from this session: the run
-                    // belongs to whoever started it, and stamping the drainer's ids onto
-                    // it would file another tenant's work under this one.
-                    tenantId: entry.tenantId,
-                    projectId: entry.projectId,
-                    sessionId: entry.sessionId,
-                    // …except the topic, which no checkpoint records — see
-                    // `RunStateScope`. This one is the drainer's, and honestly so:
-                    // supplied here rather than pretended to have been recovered.
-                    topicId: scope.topicId,
-                    scope: { ...entry, topicId: scope.topicId },
-                    checkpointStore,
-                    ...(claimFence !== undefined ? { claimFence } : {}),
-                });
-            }
-            finally {
-                if (delegatedResumeHandlers.get(entry.runId) === resumeHandler) {
-                    delegatedResumeHandlers.delete(entry.runId);
-                }
-            }
+        resumeDurable: ({ entry, checkpointStore, claimFence, signal }) => kernelResume({
+            entry,
+            checkpointStore,
+            ...(claimFence !== undefined ? { claimFence } : {}),
+            ...(signal ? { signal } : {}),
         }),
+        resumePaused: (params) => resumePausedStream(params),
     };
 }
 function planFallbacks(members, detected) {
@@ -1510,18 +1911,26 @@ export async function listProviderModels(id, det) {
     const listing = await describeProviderModels(id, det);
     return listing.kind === 'ok' ? [...listing.models] : [];
 }
-/** One scope per launched TUI session; runId is minted fresh per turn by the SDK. */
+/** The newest user turn's text, for labels. */
+function lastUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.role === 'user' && typeof m.content === 'string')
+            return m.content;
+    }
+    return '';
+}
+/**
+ * A scope for a session no host supplied one for: four minted ids. Minted
+ * rather than spelled, because a spelled id is a place a typo hides and
+ * these types accept either spelling until they are nominal.
+ */
 function mintScope() {
-    const suffix = `tui-${Date.now().toString(36)}`;
-    // Through the constructors rather than as four bare template literals.
-    // One suffix shared by four ids is exactly the shape a typo hides in —
-    // `top_` and `tnt_` differ by two characters, and the types accept either
-    // spelling for either field while they are still structural.
     return {
-        sessionId: asSessionId(`ses_${suffix}`),
-        topicId: asTopicId(`top_${suffix}`),
-        projectId: asProjectId(`prj_${suffix}`),
-        tenantId: asTenantId(`tnt_${suffix}`),
+        sessionId: generateSessionId(),
+        topicId: generateTopicId(),
+        projectId: generateProjectId(),
+        tenantId: generateTenantId(),
     };
 }
 // Pre-execution safety gate: hard-deny catastrophic shell patterns
@@ -1560,7 +1969,7 @@ function gateFor(rules) {
 // from `runConfig.model`, which is the value the user actually chose. Pinning
 // a number here would fix one window across every model the CLI can talk to.
 const COMPACTION_CONFIG = {
-    strategy: 'structured',
+    strategy: 'salience',
     // On, and this is the CLI making a choice rather than taking a default.
     // A session's transcript is the only record of what was compacted away;
     // the size trade this costs is the operator's to see and turn off.
@@ -1588,7 +1997,17 @@ const COMPACTION_CONFIG = {
     maxCharsPerRequirement: 300,
     maxCharsPerTask: 400,
 };
-async function* runTurn({ provider, fallbackProviders, model, tools, pluginManager, skillRegistry, skills, scope, pathBuilder, workingDirectory, sandboxWorkspace, rules, reviewAnswer, maxAnswerReviews, promoteMemory, resumeHandler, taskStore, systemPrompt, messages, projectInstructionContext, opts, taskGateway, sandboxProvider, sandboxTeardownTimeoutMs, onRunEvent, }) {
+/** The shipped configuration with the strategy the project chose, if it chose one. */
+function compactionConfigFor(compaction) {
+    return {
+        ...COMPACTION_CONFIG,
+        strategy: compaction?.strategy ?? COMPACTION_CONFIG.strategy,
+        ...(compaction?.contextWindowTokens !== undefined
+            ? { contextWindowTokens: compaction.contextWindowTokens }
+            : {}),
+    };
+}
+async function* runTurn({ provider, compactionConfig, consolidateInto, backgroundJobs, backgroundJobOwner, fallbackProviders, model, tools, pluginManager, skillRegistry, skills, scope, pathBuilder, workingDirectory, limits, additionalDirectories, sandboxWorkspace, rules, reviewAnswer, maxAnswerReviews, promoteMemory, resumeHandler, taskStore, systemPrompt, messages, projectInstructionContext, opts, taskGateway, promptContributions, runtimeToolOverrides, web, sandboxProvider, sandboxTeardownTimeoutMs, onRunEvent, }) {
     const signal = opts?.signal;
     // One presenter for the whole stream, built from the registry this scope
     // already holds. Its absence HERE is what forced presentation to be name
@@ -1612,7 +2031,7 @@ async function* runTurn({ provider, fallbackProviders, model, tools, pluginManag
             // turn. An admitted send owns the exact run-scoped authority above.
             ...(!opts?.goalRound ? { deniedTools: SESSION_GOAL_TOOL_NAMES } : {}),
             taskStore,
-            ...(taskGateway ? { taskGateway } : {}),
+            ...(taskGateway ? { taskScheduler: taskGateway } : {}),
             // `gateFor`, not the bare default: the default's `rules` is a hardcoded
             // empty array, so passing it here discarded the operator's rules on the
             // path that runs every top-level turn. The sub-agent path called
@@ -1620,7 +2039,9 @@ async function* runTurn({ provider, fallbackProviders, model, tools, pluginManag
             ...(sandboxProvider ? { sandboxProvider } : {}),
             ...(sandboxTeardownTimeoutMs !== undefined ? { sandboxTeardownTimeoutMs } : {}),
             authorizationGate: gateFor(rules),
-            compactionConfig: COMPACTION_CONFIG,
+            compactionConfig,
+            ...(consolidateInto ? { consolidateInto } : {}),
+            ...(backgroundJobs ? { backgroundJobs, backgroundJobOwner } : {}),
             // The CLI owns its process end to end, so it can safely hand the
             // termination path to the kernel: a Ctrl-C mid-run now leaves a
             // dump under the injected hierarchy's emergency partition instead of
@@ -1631,8 +2052,8 @@ async function* runTurn({ provider, fallbackProviders, model, tools, pluginManag
                 ...(sandboxProvider ? { sandbox: { workspace: sandboxWorkspace } } : {}),
                 ...(opts?.effort !== undefined ? { effort: opts.effort } : {}),
                 timeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS,
-                tokenBudget: 1_000_000,
-                maxIterations: 50,
+                tokenBudget: limits?.tokenBudget ?? 1_000_000,
+                maxIterations: limits?.maxIterations ?? 50,
                 maxResponseTokens: 8192,
                 permissionMode: 'auto',
             },
@@ -1653,10 +2074,14 @@ async function* runTurn({ provider, fallbackProviders, model, tools, pluginManag
             messages: [...messages],
             ...(opts?.inboundMessages ? { inboundMessages: opts.inboundMessages } : {}),
             workingDirectory,
+            ...(additionalDirectories?.length ? { additionalDirectories } : {}),
             // The exemption reads `tools` at decision time, so it sees the task
             // tools `query()` registers deferred below and any tool server that
             // connected after this session was built.
             resumeHandler,
+            ...(promptContributions ? { promptContributions } : {}),
+            ...(runtimeToolOverrides ? { runtimeToolOverrides } : {}),
+            ...(web ? { web } : {}),
             signal,
             ...scope,
         });
@@ -1706,123 +2131,26 @@ async function* runTurn({ provider, fallbackProviders, model, tools, pluginManag
     }
 }
 /**
- * Bridge the SDK's HITL `tool_review` request to the TUI's permission
- * callback. Read-only batches (nothing destructive) run silently; batches
- * with a destructive call prompt the user unless they've already chosen
- * "approve all" for the session. Plans and iteration checkpoints are
- * auto-continued (the TUI doesn't use plan mode).
- */
-export function makeResumeHandler(approval, onPermission, mode = onPermission ? 'prompt' : 'auto', 
-/**
- * Which calls skip the prompt. Injected rather than reached for, so this
- * handler stays testable without a registry — and so the answer comes from
- * the live roster at the moment of the call.
- */
-exempt = () => false) {
-    return async (request) => {
-        if (request.type !== 'tool_review') {
-            return request.type === 'plan_approval' ? { action: 'approve_plan' } : { action: 'continue' };
-        }
-        // Only calls the gate routed to REVIEW arrive here — a rule that denied
-        // one already stopped it, and a rule that allowed one never asked. So the
-        // mode decides what happens to the undecided, and cannot reopen anything
-        // a rule closed. That is the whole precedence story between a flag and a
-        // config file, and it is one sentence on purpose.
-        if (!batchNeedsPrompt(request.toolCalls, exempt)) {
-            return { action: 'approve_tools' };
-        }
-        if (mode === 'strict') {
-            return {
-                action: 'reject_tools',
-                feedback: 'Refused: this run only permits tools an explicit rule allows, and no rule covers this call. Asking again will not change it — either the operator adds a rule, or this has to be done another way.',
-            };
-        }
-        if (mode === 'auto' || !onPermission || approval.all) {
-            return { action: 'approve_tools' };
-        }
-        const decision = await onPermission({
-            toolCalls: request.toolCalls.map((tc) => ({
-                id: tc.id,
-                name: tc.name,
-                input: tc.input,
-                isDestructive: tc.isDestructive,
-            })),
-        });
-        switch (decision.kind) {
-            case 'approve':
-                return { action: 'approve_tools' };
-            case 'approve-all':
-                approval.all = true;
-                return { action: 'approve_tools' };
-            case 'reject':
-                return {
-                    action: 'reject_tools',
-                    feedback: decision.feedback ?? 'User declined to run the proposed tool(s).',
-                };
-        }
-    };
-}
-/**
- * Writes that skip the prompt anyway, in spite of declaring `readOnly: false`.
- *
- * This is an OVERRIDE of the tool's own declaration, and it is named as one.
- * The list it replaced was called `READ_ONLY_TOOLS` and contained three tools
- * that declare `readOnly: false` — a constant asserting the exact property it
- * was getting wrong, which is how the disagreement survived: nothing reading it
- * had reason to doubt the name.
+ * The kernel's review policy with the TUI's prompt behind it.
  *
- * The bar for an entry is that prompting would be unusable AND a bad write
- * cannot reach beyond the agent's own bookkeeping. Each one is justified here,
- * or it does not belong here.
- *
- * - `task_create` / `task_update` — the model's own plan for the current
- *   request, written several times per planning turn; prompting each would put
- *   a consent dialog between the agent and its todo list. What a bad write
- *   costs is a polluted task list, which is visible in the transcript and
- *   grants nothing. Worth knowing while reading that: these DO outlive the
- *   session, because the CLI's task store uses a fixed run id
- *   (`run_namzu-cli`), so "run-scoped" is not the reason they are here — the
- *   blast radius is.
- *
- * `save_memory` was on the list it replaced and is deliberately NOT here. Its
- * effect outlives the run in a way the task tools' does not: content saved now
- * is retrievable by `search_memory` in a later session, so a tool result or
- * fetched page that talks the model into saving something reaches a future
- * run's reasoning. It is not auto-injected into the prompt — that is
- * `MEMORY.md`, a different thing — but retrievable is enough. A write that
- * survives the process, into the user's own repository, is not read-only under
- * any reading, and it now prompts.
+ * The five modes, the exemptions and the batch rule live in `@namzu/sdk`
+ * (`createReviewHandler`); what this application adds is the person to ask
+ * and the session's "approve all" box, which the screen also reads.
  */
-const PROMPT_EXEMPT_WRITES = new Set(['task_create', 'task_update', 'update_goal']);
+export function makeResumeHandler(approval, onPermission, mode = onPermission ? 'prompt' : 'auto', exempt = () => false) {
+    return createReviewHandler({
+        mode,
+        prompt: onPermission,
+        exempt,
+        remembered: approval,
+    });
+}
 /**
- * Whether a call runs without asking: it declares itself read-only, or it is a
- * named exemption above.
- *
- * The read-only half comes from the tool's own `isReadOnly(input)`, never from
- * a list of names kept here. A name list in the consumer is a second source of
- * truth for a property the producer already states: a new read-only tool
- * missing from it merely gets prompted, but a RENAMED tool silently changes
- * posture with nothing to notice.
- *
- * Resolved per call rather than snapshotted, because the roster changes after
- * this module has run — the task tools are registered deferred inside
- * `query()`, and tool servers connect during startup, so anything computed
- * eagerly would be answering about a registry that no longer exists.
- *
- * A tool the registry does not know, or one that declares nothing, prompts.
- * That is the safe-by-default direction the previous comment claimed and this
- * keeps: consent is the answer when the question cannot be established.
+ * Whether a call runs without asking. The kernel's rule: a trusted read-only
+ * declaration or a named bookkeeping write, never a fetch, never a tool the
+ * registry does not know.
  */
-export function isPromptExempt(registry, name, input) {
-    if (PROMPT_EXEMPT_WRITES.has(name.toLowerCase()))
-        return true;
-    const tool = registry.get(name) ?? registry.get(name.toLowerCase());
-    // A connected server's own claim about its own tool cannot skip the
-    // prompt. Same predicate the kernel gate and plan mode use -- three
-    // doors, one rule, because fixing two would close the issue and leave
-    // the boundary open.
-    return isTrustedReadOnly(tool, input);
-}
+export const isPromptExempt = isReviewExempt;
 /** The exempt roster, sorted, for the surface that has to NAME it. */
 export function promptExemptToolNames(registry) {
     return registry
@@ -1831,13 +2159,8 @@ export function promptExemptToolNames(registry) {
         .map((t) => t.name)
         .sort();
 }
-/**
- * A batch needs explicit approval when any call mutates state: flagged
- * destructive by the SDK, or not exempt from the prompt.
- */
-export function batchNeedsPrompt(toolCalls, exempt) {
-    return toolCalls.some((tc) => tc.isDestructive || !exempt(tc.name, tc.input));
-}
+/** A batch needs explicit approval when any call mutates state. */
+export const batchNeedsPrompt = batchNeedsReview;
 /**
  * Translate one SDK `RunEvent` into the TUI's `AgentEvent` vocabulary, or
  * `null` for events the chat surface doesn't render (iteration markers,
@@ -1852,6 +2175,14 @@ export function toAgentEvent(event, presenter) {
                 ...(event.messageId ? { messageId: event.messageId } : {}),
                 ...(event.runId ? { runId: event.runId } : {}),
             };
+        case 'reasoning_started':
+            // A redacted block has no text to show; the empty delta still says
+            // "thinking" so the region does not sit silent for its duration.
+            return { kind: 'reasoning', text: '' };
+        case 'reasoning_delta':
+            return { kind: 'reasoning', text: event.text };
+        case 'reasoning_completed':
+            return { kind: 'reasoning', text: '', done: true };
         case 'tool_executing':
             return {
                 kind: 'tool-start',
@@ -1883,9 +2214,15 @@ export function toAgentEvent(event, presenter) {
                 success: !event.isError,
                 output: event.result,
             });
-            const summary = firstLine(event.result);
             const detail = viewToLines(view);
-            const withoutRepeatedSummary = view.kind === 'terminal' && detail?.[0] === summary ? detail.slice(1) : detail;
+            // For output shown line by line, the summary IS the first rendered
+            // line, so the body can drop it without a second, differently
+            // whitespaced copy of the same text — a `read` used to show its
+            // first line twice, once collapsed and once numbered.
+            const summary = view.kind === 'terminal' && detail && detail.length > 0
+                ? truncate(detail[0], 120)
+                : firstLine(event.result);
+            const withoutRepeatedSummary = view.kind === 'terminal' && detail && detail.length > 0 ? detail.slice(1) : detail;
             return {
                 kind: 'tool-end',
                 runId: event.runId,
@@ -1917,6 +2254,7 @@ export function toAgentEvent(event, presenter) {
             return {
                 kind: 'usage',
                 totalTokens: event.usage.totalTokens,
+                ...(event.budget ? { budget: event.budget } : {}),
                 cost: event.cost,
                 ...(event.contextTokens !== undefined ? { contextTokens: event.contextTokens } : {}),
                 ...(event.contextMeasuredBy !== undefined
@@ -1963,13 +2301,16 @@ export function toAgentEvent(event, presenter) {
             };
         }
         case 'task_created':
-            return { kind: 'task', subject: event.subject, status: event.status };
         case 'task_updated':
-            // Only surface completions — skip pending/in-progress churn so the
-            // transcript shows "todo added" then "todo done", not every flip.
-            return event.status === 'completed'
-                ? { kind: 'task', subject: event.subject, status: event.status }
-                : null;
+            // Every change, not only completions: the live task list needs the
+            // in-progress flips to show which step is current. The transcript
+            // decides for itself which of these it records.
+            return {
+                kind: 'task',
+                taskId: String(event.taskId),
+                subject: event.subject,
+                status: event.status,
+            };
         case 'run_paused':
             // A pause is not an error and not an invisible end. The checkpoint and
             // classification are the recovery surface; dropping this event made a
@@ -1977,6 +2318,8 @@ export function toAgentEvent(event, presenter) {
             // the SDK had explicitly stopped.
             return {
                 kind: 'paused',
+                ...(event.budget ? { budget: event.budget } : {}),
+                runId: String(event.runId),
                 checkpointId: event.checkpointId,
                 reason: event.reason,
                 ...(event.failure ? { failure: event.failure } : {}),
@@ -1991,6 +2334,7 @@ export function toAgentEvent(event, presenter) {
             // answer was refused.
             return {
                 kind: 'done',
+                ...(event.budget ? { budget: event.budget } : {}),
                 ...(event.stopReason ? { stopReason: event.stopReason } : {}),
             };
         case 'run_failed':
@@ -2000,13 +2344,29 @@ export function toAgentEvent(event, presenter) {
             // still forcing every host to parse prose.
             return {
                 kind: 'error',
+                ...(event.budget ? { budget: event.budget } : {}),
                 message: event.error,
                 ...(event.failure ? { failure: event.failure } : {}),
                 ...(event.providerError ? { providerError: event.providerError } : {}),
                 ...(event.explanation ? { explanation: event.explanation } : {}),
             };
+        case 'background_job_exited':
+            return {
+                kind: 'job',
+                jobId: event.jobId,
+                command: event.command,
+                status: event.status,
+                ...(event.exitCode !== undefined ? { exitCode: event.exitCode } : {}),
+                ...(event.signal ? { signal: event.signal } : {}),
+            };
         case 'compaction_completed':
-            return { kind: 'context', text: describeCompaction(event), shed: true };
+            return {
+                kind: 'context',
+                text: describeCompaction(event),
+                shed: true,
+                summarised: true,
+                reclaimedTokens: Math.max(0, event.tokensBefore - event.tokensAfter),
+            };
         case 'compaction_tool_results_cleared':
             // `shed: true` on both branches: the tool-result bodies are gone
             // either way. `reliefWasEnough: false` additionally means a
@@ -2014,8 +2374,11 @@ export function toAgentEvent(event, presenter) {
             // so this one says what IT cost rather than claiming the total.
             return {
                 kind: 'context',
-                text: `cleared ${event.clearedCount} oversized tool result${event.clearedCount === 1 ? '' : 's'} (~${event.reclaimedTokens.toLocaleString()} tokens)${event.reliefWasEnough ? '' : ' — not enough, compacting'}`,
+                text: `cleared ${event.clearedCount} tool result${event.clearedCount === 1 ? '' : 's'}${event.stubbedCount ? `, stubbed ${event.stubbedCount} narration${event.stubbedCount === 1 ? '' : 's'}` : ''} (~${event.reclaimedTokens.toLocaleString()} tokens)${event.reliefWasEnough ? '' : ' — not enough, compacting'}`,
                 shed: true,
+                cleared: event.clearedCount,
+                stubbed: event.stubbedCount ?? 0,
+                reclaimedTokens: event.reclaimedTokens,
             };
         case 'compaction_failed':
             return {
@@ -2355,6 +2718,9 @@ function emptySession(errorHint, errorKind = 'environment') {
         resumeDurable: async () => {
             throw new Error(errorHint);
         },
+        resumePaused: async function* () {
+            yield { kind: 'error', message: 'no provider: nothing to resume' };
+        },
         close: async () => {
             // Nothing was ever connected on this path.
         },