@calliopelabs/cli 3.1.0 → 3.2.1

package/README.md

@@ -7,20 +7,34 @@ npm install -g @calliopelabs/cli
 calliope
 ```
 
-Single-binary installs (Homebrew and a `curl` installer, no Node.js required) are
-coming with the v3.0.0 stable release — see
+Single-binary installs are available through Homebrew and a `curl` installer,
+with no Node.js required — see
 [Install as a single binary](docs/getting-started.md#install-as-a-single-binary).
 
 ## Why Calliope
 
-- **Any backend, live-discovered.** 13 providers — Anthropic, OpenAI, Google, AWS Bedrock, Ollama, OpenRouter, Together, Groq, Fireworks, Mistral, AI21, Hugging Face, LiteLLM, plus any OpenAI-compatible server. No hardcoded model lists: models and capabilities are discovered from each provider's API, so new models work the day they ship.
+- **Any backend, live-discovered.** Hosted providers, local runtimes, and OpenAI-compatible servers share the same workflow. Models and capabilities are discovered from provider APIs; unsupported or unknown behavior stays explicit. See the [provider matrix and real-wire evidence](docs/provider-conformance.md).
 - **Built for models you run yourself.** Ollama and self-hosted OpenAI-compatible servers are first-class targets, not checkboxes. Run fully air-gapped.
 - **Sandbox-first execution.** Shell and code tools run inside macOS Seatbelt or Docker sandboxes (`auto`/`native`/`docker`/`off`). Blocklists are advisory; the sandbox is the boundary.
 - **Safety rails that survive long sessions.** Circuit breakers, iteration budgets, git-based checkpoints with `/restore`, and automatic context compaction.
 - **Governance built in.** Tamper-evident audit run logs (on by default), a `replay` command to inspect and verify them, budget caps that halt a run before it overspends, and a pre-tool policy hook for an external allow/deny engine. See [docs/governance.md](docs/governance.md).
-- **Small on purpose.** 22 commands. 16 config keys. 11 flags. v3 removed more code than it kept — the changelog lists everything that went and why.
+- **Focused command surface.** 23 commands, plus optional fleet mode. The [command reference](docs/commands.md) documents the available workflows and subcommands.
 - **Tested like infrastructure.** 3,500 tests, 93%+ line coverage with an enforced 90% floor.
 
+## What's new in 3.2
+
+3.2 turns the provider foundation into a project workbench: live provider health and
+model discovery, `/doctor` diagnostics, health-aware routing, resumable sessions,
+stream-safe retries, and the `auto` permission mode are available from the same
+terminal and headless interfaces. It also adds reviewed orchestration with planner,
+worker and verifier roles, isolated execution, bounded retry/replan supervision,
+auditable artifacts, and a local Brain/KG for provenance-aware project memory.
+
+The release includes native Bedrock reasoning preservation, Google's `@google/genai`
+adapter, expanded DeepSeek/Cerebras and OpenAI-compatible coverage, and real-wire
+provider evidence. See the [3.2.0 release notes](docs/releases/3.2.0.md) for the
+complete feature and validation details.
+
 ## Quick start
 
 ```bash
@@ -32,7 +46,9 @@ Inside a session:
 
 ```
 /mode plan              think first — the agent proposes, you approve
+/mode auto              execute without per-tool approval prompts this session
 /model list             see live-discovered models for your provider
+/defaults save          save the current provider/model for this project
 /scope add ../lib       widen file access deliberately
 /compact                compress context when it grows
 /restore                list git checkpoints; /restore <path> to roll back
@@ -45,6 +61,49 @@ Headless, for CI and scripts:
 calliope --headless --json "run the tests and summarize failures"
 ```
 
+Plan a project goal within a fixed budget, then approve the returned proposal hash:
+
+```bash
+calliope orchestrate "Inspect the parser and propose a focused fix" --cost 1 --json
+calliope orchestrate approve GOAL_ID PROPOSAL_HASH --allow-mutations --json
+```
+
+Planning exits 5 for review; the [goal workflow](docs/goal-planning.md) documents
+scope limits, approval, recovery and the JSON contract. `/orchestrate` presents
+the proposed plan and approval dialog in the REPL.
+
+Add [`--supervise --isolation-image sha256:ID`](docs/continuous-supervision.md#start-from-a-goal)
+to propose an isolated work → verify → review → retry/replan loop. Choose separate
+controller, worker and optional execution-reviewer models; the existing HUD shows
+roles, task attempts and bounded supervision rounds. Planning remains read-only
+and execution requires approval of the exact plan.
+
+Execute a reviewed project task graph with bounded agents:
+
+```bash
+calliope run plan.json --dry-run --json
+calliope run plan.json --allow-mutations --json
+```
+
+Independent tasks run concurrently with per-agent permissions and shared budgets.
+Recorded artifact checks determine completion; unverified criteria require human
+acceptance. See [coordinator execution](docs/coordinator-execution.md) for plan
+contracts, provider requirements, cancellation and recovery.
+
+Record and query project knowledge locally, without model requests:
+
+```bash
+calliope brain init --allow-mutations
+calliope brain ingest docs/design.md --allow-mutations
+calliope brain search "storage decision" --json
+calliope kg graph
+```
+
+The [project brain](docs/project-brain.md) preserves source provenance, supports
+human review and reversal, tracks stale documents, and links verified run evidence.
+Use `/brain` and `/kg` for the same controls in the REPL.
+
+
 ## Configuration
 
 One file, 16 keys. Credentials live in a per-provider map with environment-variable fallbacks:
@@ -63,7 +122,7 @@ One file, 16 keys. Credentials live in a per-provider map with environment-varia
 
 `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OLLAMA_BASE_URL`, and friends work as before. v2 configs migrate automatically on first run.
 
-Docs: [getting started](docs/getting-started.md) · [commands](docs/commands.md) · [configuration](docs/configuration.md) · [providers](docs/providers.md) · [features](docs/features.md) · [fleet mode](docs/fleet.md)
+Docs: [getting started](docs/getting-started.md) · [commands](docs/commands.md) · [configuration](docs/configuration.md) · [model preferences](docs/model-preferences.md) · [providers](docs/providers.md) · [features](docs/features.md) · [fleet mode](docs/fleet.md)
 
 ## Editors
 
@@ -75,13 +134,15 @@ Coordinate a fleet of agents and human operators over a self-hosted IRC channel
 
 ## Project memory
 
-Drop a `CALLIOPE.md` in your repo and every session starts knowing your conventions. `/memory` manages it.
+Use `AGENTS.md` for portable repository instructions and `CALLIOPE.md` for project memory. Trusted instructions load from the checkout root to your working directory, with source paths and directory precedence. `/memory sources` shows applicable files; `/memory reload` refreshes them. See [repository instructions](docs/instructions.md).
 
 ## v3.0
 
 v3 is a deliberate reduction: 84 commands, 40 config keys, and ~20k lines of speculative features (theme packs, companions, multi-agent orchestration, an embedded API server, and more) were removed to make the core fast, predictable, and maintainable. The full list and rationale live in [CHANGELOG.md](CHANGELOG.md) and the [v3.0 roadmap](https://github.com/calliopeai/calliope-cli/issues/195).
 
-Coming in v3.0 stable: single-binary installs (brew/curl, no Node required) and enforced performance budgets. Governance primitives — replayable audit run logs, budget caps, and a policy hook — have landed; see [docs/governance.md](docs/governance.md). Coming after: local-model edit-reliability hardening.
+Single-binary installs, enforced performance budgets, governance, ACP editor integration, and local-model edit repair shipped in v3.0. See [docs/governance.md](docs/governance.md) and [docs/local-models.md](docs/local-models.md).
+
+The [next-version roadmap](https://github.com/calliopeai/calliope-cli/issues/254) prioritizes consistent execution across providers, portable sessions and instructions, and measured task reliability. The [first implementation](https://github.com/calliopeai/calliope-cli/issues/255) adds cancellation through provider requests, retries and local processes, plus scoped `AGENTS.md` support. See [cancellation behavior](docs/features.md#cancellation).
 
 ## Contributing
 

package/dist/acp.d.ts

@@ -22,6 +22,7 @@
 import { AgentSideConnection, type Agent, type Stream, type InitializeRequest, type InitializeResponse, type NewSessionRequest, type NewSessionResponse, type AuthenticateResponse, type PromptRequest, type PromptResponse, type CancelNotification } from '@zed-industries/agent-client-protocol';
 declare class CalliopeAgent implements Agent {
     private readonly conn;
+    private readonly approvals;
     private clientCapabilities;
     private readonly sessions;
     /** Tail of the outgoing write chain; awaited to flush notifications. */
@@ -33,12 +34,8 @@ declare class CalliopeAgent implements Agent {
     prompt(params: PromptRequest): Promise<PromptResponse>;
     cancel(params: CancelNotification): Promise<void>;
     private runTurn;
-    /** Flush pending notifications and return the cancelled stop reason. */
-    private finishCancelled;
-    private runToolCall;
     /** Send a terminal (completed/failed) tool_call_update to the client. */
     private reportToolResult;
-    private gateToolCall;
     /**
      * Ask the client to authorize a tool call. Returns the user's decision, or
      * falls back to Calliope's non-interactive default (deny) when the client does

package/dist/acp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acp.d.ts","sourceRoot":"","sources":["../src/acp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EACL,mBAAmB,EAInB,KAAK,KAAK,EACV,KAAK,MAAM,EAKX,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAwK/C,cAAM,aAAc,YAAW,KAAK;IAMtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,kBAAkB,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,wEAAwE;IACxE,OAAO,CAAC,SAAS,CAAoC;IAErD,YAA6B,IAAI,EAAE,mBAAmB,EAAI;IAIpD,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoBvE;IAIK,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAElD;IAIK,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAiDvE;IAIK,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB3D;IAIK,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMtD;YAIa,OAAO;IAyErB,wEAAwE;YAC1D,eAAe;YAQf,WAAW;IA6DzB,yEAAyE;IACzE,OAAO,CAAC,gBAAgB;YAkBV,YAAY;IAkC1B;;;;OAIG;YACW,iBAAiB;IAiC/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAQZ,gDAAgD;IAChD,OAAO,CAAC,KAAK;IAIb,iEAAiE;IAC3D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAc9B;CACF;AAMD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAQtD;AAED;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAkBnD"}
+{"version":3,"file":"acp.d.ts","sourceRoot":"","sources":["../src/acp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,EACL,mBAAmB,EAInB,KAAK,KAAK,EACV,KAAK,MAAM,EAKX,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAuJ/C,cAAM,aAAc,YAAW,KAAK;IAOtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,kBAAkB,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,wEAAwE;IACxE,OAAO,CAAC,SAAS,CAAoC;IAErD,YAA6B,IAAI,EAAE,mBAAmB,EAAI;IAIpD,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoBvE;IAIK,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAElD;IAIK,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0CvE;IAIK,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA0B3D;IAIK,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtD;YAIa,OAAO;IAsDrB,yEAAyE;IACzE,OAAO,CAAC,gBAAgB;IAkBxB;;;;OAIG;YACW,iBAAiB;IAkC/B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAQZ,gDAAgD;IAChD,OAAO,CAAC,KAAK;IAIb,iEAAiE;IAC3D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAM9B;CACF;AAMD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAQtD;AAED;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAkBnD"}

package/dist/acp.js

@@ -19,20 +19,24 @@
  * lazy-loaded from bin.ts only for the `acp` subcommand, so it adds nothing to the
  * default cold-start path.
  */
+import { ApprovalStore } from './approvals/index.js';
 import * as path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import { AgentSideConnection, ndJsonStream, RequestError, PROTOCOL_VERSION, } from '@zed-industries/agent-client-protocol';
 import * as config from './config.js';
-import { chat, selectProvider } from './providers/index.js';
-import { TOOLS, executeTool } from './tools.js';
-import { DEFAULT_MODELS, calculateCost } from './types.js';
-import { getSystemPromptForProvider, isLocalBackend } from './local-model.js';
+import { selectProvider } from './providers/index.js';
+import { runTurn } from './runtime/index.js';
+import { createSession, saveSessionConversation } from './storage.js';
+import { SessionRecoveryError } from './sessions/index.js';
+import { resolvePreferences } from './preferences/index.js';
+import { cancellable, isCancellation } from './cancellation.js';
+import { TOOLS } from './tools.js';
+import { DEFAULT_MODELS } from './types.js';
+import { getSystemPromptForProvider } from './local-model.js';
 import * as memory from './memory.js';
 import { resolveIterationLimit } from './iteration-limit.js';
+import { formatBudgetHalt } from './budget.js';
 import { RunLog } from './runlog.js';
-import { evaluatePolicy, isPolicyEnabled } from './policy.js';
-import { assessToolRisk } from './risk.js';
-import { checkHooksAllow } from './hooks.js';
 // ============================================================================
 // Diagnostics — stderr only (stdout carries the protocol).
 // ============================================================================
@@ -61,23 +65,6 @@ function errMessage(err) {
 // ============================================================================
 // Tool → permission / presentation mapping
 // ============================================================================
-/**
- * Tools with side effects. These always route through the permission flow (and
- * are denied under the non-interactive fallback), matching the headless runner's
- * notion of a mutating tool.
- */
-const MUTATING_TOOLS = new Set(['shell', 'write_file', 'edit_file', 'git', 'execute_code', 'configure']);
-/**
- * Whether a tool call must ask the client for permission before running.
- * Read-only tools (read_file, list_files, think, glob, grep, web_search) run
- * silently; anything that mutates state or that Calliope's risk model flags for
- * confirmation asks first.
- */
-function toolNeedsPermission(toolCall) {
-    if (MUTATING_TOOLS.has(toolCall.name))
-        return true;
-    return assessToolRisk(toolCall).requiresConfirmation;
-}
 /** Map a Calliope tool name to the ACP tool kind (drives client icons/UX). */
 function toolKind(name) {
     switch (name) {
@@ -156,6 +143,7 @@ function promptToText(blocks) {
 // ============================================================================
 class CalliopeAgent {
     conn;
+    approvals = new ApprovalStore();
     clientCapabilities = {};
     sessions = new Map();
     /** Tail of the outgoing write chain; awaited to flush notifications. */
@@ -190,8 +178,14 @@ class CalliopeAgent {
     // ---- ACP: session/new -------------------------------------------------
     async newSession(params) {
         const cwd = params.cwd || process.cwd();
-        const provider = process.env.CALLIOPE_PROVIDER || config.get('defaultProvider');
-        const model = process.env.CALLIOPE_MODEL || config.get('defaultModel') || '';
+        let preference;
+        try {
+            preference = resolvePreferences(cwd);
+        }
+        catch (error) {
+            throw RequestError.invalidParams({ error: error instanceof Error ? error.message : String(error) });
+        }
+        const { provider } = preference, model = preference.model || '';
         // Resolve the provider so 'auto' picks a real backend for the system prompt,
         // cost model, and local-backend flag (mirrors the headless runner). Fall back
         // to the raw provider if selection throws (chat() surfaces the real error).
@@ -202,18 +196,9 @@ class CalliopeAgent {
         catch {
             resolvedProvider = provider;
         }
-        const localBackend = isLocalBackend(resolvedProvider);
         const costModel = model || DEFAULT_MODELS[resolvedProvider];
-        const sessionId = `acp_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const sessionId = createSession(cwd, { activate: false, prefix: 'acp' }).id;
         const runlog = RunLog.open(sessionId);
-        runlog.runStart({
-            session: sessionId,
-            cwd,
-            provider: resolvedProvider,
-            model: costModel,
-            config: config.getConfig(),
-            mode: 'acp',
-        });
         const systemPrompt = getSystemPromptForProvider(resolvedProvider);
         const memoryContext = memory.buildMemoryContext(cwd);
         const fullPrompt = memoryContext.trim()
@@ -225,12 +210,11 @@ class CalliopeAgent {
             provider,
             resolvedProvider,
             model,
-            localBackend,
+            preference,
+            revision: null,
             messages: [{ role: 'system', content: fullPrompt }],
             runlog,
             cancelled: false,
-            totals: { inputTokens: 0, outputTokens: 0, cost: 0, toolCalls: 0 },
-            startedAt: Date.now(),
         });
         debug(`session/new: ${sessionId} cwd=${cwd} provider=${resolvedProvider} model=${costModel}`);
         return { sessionId };
@@ -241,156 +225,108 @@ class CalliopeAgent {
         if (!session) {
             throw RequestError.invalidParams({ error: `unknown session: ${params.sessionId}` });
         }
+        if (session.controller)
+            throw RequestError.invalidParams({ error: 'A prompt is already running in this session' });
+        session.controller = new AbortController();
         // Each prompt is a fresh turn; clear any stale cancel from a prior turn.
         session.cancelled = false;
         const text = promptToText(params.prompt);
         session.messages.push({ role: 'user', content: text });
-        session.runlog.userPrompt(text);
         debug(`session/prompt: ${session.id} (${text.length} chars)`);
-        const stopReason = await this.runTurn(session);
-        await session.runlog.flush();
-        return { stopReason };
+        try {
+            session.activeTurn = this.runTurn(session, text);
+            const stopReason = await session.activeTurn;
+            return { stopReason };
+        }
+        catch (error) {
+            if (!(error instanceof SessionRecoveryError) && (session.cancelled || isCancellation(error)))
+                return { stopReason: 'cancelled' };
+            throw RequestError.internalError({ error: errMessage(error) });
+        }
+        finally {
+            try {
+                await session.runlog.flush();
+            }
+            finally {
+                session.controller = undefined;
+                session.activeTurn = undefined;
+            }
+        }
     }
     // ---- ACP: session/cancel (notification) -------------------------------
     async cancel(params) {
         const session = this.sessions.get(params.sessionId);
         if (session) {
             session.cancelled = true;
+            session.controller?.abort();
             debug(`session/cancel: ${params.sessionId}`);
         }
     }
     // ---- The agent loop (ACP-flavoured mirror of the headless loop) --------
-    async runTurn(session) {
-        const maxIterations = resolveIterationLimit(config.get('maxIterations'));
-        const costModel = session.model || DEFAULT_MODELS[session.resolvedProvider];
-        let iteration = 0;
-        while (iteration < maxIterations) {
-            if (session.cancelled)
-                return this.finishCancelled(session);
-            iteration++;
-            // Stream assistant text as agent_message_chunk deltas via the chat seam.
-            let streamedChars = 0;
-            const onToken = (token) => {
-                if (!token)
-                    return;
-                streamedChars += token.length;
-                this.emit(session.id, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: token } });
-            };
-            let response;
-            try {
-                response = await chat(session.provider, session.messages, TOOLS, session.model || undefined, onToken);
-            }
-            catch (err) {
-                const msg = errMessage(err);
-                log(`chat error: ${msg}`);
-                session.runlog.assistantMessage({ content: `[error: ${msg}]`, tokens: { input: 0, output: 0 }, cost: 0 });
-                await session.runlog.flush();
-                throw RequestError.internalError({ error: msg });
-            }
-            // Audit + spend accounting (mirrors headless).
-            if (response.usage) {
-                const cost = calculateCost(costModel, response.usage.inputTokens, response.usage.outputTokens);
-                session.totals.inputTokens += response.usage.inputTokens;
-                session.totals.outputTokens += response.usage.outputTokens;
-                session.totals.cost += cost;
-                session.runlog.assistantMessage({
-                    content: response.content,
-                    tokens: { input: response.usage.inputTokens, output: response.usage.outputTokens },
-                    cost,
-                });
-            }
-            else {
-                session.runlog.assistantMessage({ content: response.content, tokens: { input: 0, output: 0 }, cost: 0 });
-            }
-            // Providers that don't stream: emit the assembled content once so the
-            // client still sees the assistant message.
-            if (streamedChars === 0 && response.content) {
-                this.emit(session.id, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: response.content } });
-            }
-            if (session.cancelled)
-                return this.finishCancelled(session);
-            if (response.toolCalls && response.toolCalls.length > 0) {
-                session.messages.push({ role: 'assistant', content: response.content, toolCalls: response.toolCalls });
-                for (const toolCall of response.toolCalls) {
-                    if (session.cancelled)
-                        return this.finishCancelled(session);
-                    const outcome = await this.runToolCall(session, toolCall);
-                    if (outcome === 'cancelled')
-                        return this.finishCancelled(session);
-                }
-                continue; // next model turn
-            }
-            // No tool calls: this is the final assistant message → end of turn.
-            session.messages.push({ role: 'assistant', content: response.content });
-            await this.flush();
-            return response.finishReason === 'length' ? 'max_tokens' : 'end_turn';
-        }
-        // Exhausted the iteration budget.
-        await this.flush();
-        return 'max_turn_requests';
-    }
-    /** Flush pending notifications and return the cancelled stop reason. */
-    async finishCancelled(session) {
-        debug(`turn cancelled: ${session.id}`);
-        await this.flush();
-        return 'cancelled';
-    }
-    // ---- One tool call: announce → gate → execute → report ----------------
-    async runToolCall(session, toolCall) {
-        session.runlog.toolCall({ id: toolCall.id, name: toolCall.name, args: toolCall.arguments });
-        session.totals.toolCalls++;
-        // Announce the pending tool call.
-        await this.emit(session.id, {
-            sessionUpdate: 'tool_call',
-            toolCallId: toolCall.id,
-            title: toolTitle(toolCall),
-            kind: toolKind(toolCall.name),
-            status: 'pending',
-            rawInput: toolCall.arguments,
-            locations: toolLocations(toolCall, session.cwd),
-        });
-        // Permission + hard governance gates.
-        const gate = await this.gateToolCall(session, toolCall);
-        if (gate.decision === 'cancelled') {
-            await this.reportToolResult(session, toolCall.id, '[cancelled]', true);
-            session.runlog.toolResult({ id: toolCall.id, result: '[cancelled]', isError: true, durationMs: 0 });
-            session.messages.push({ role: 'tool', content: '[cancelled]', toolCallId: toolCall.id });
-            return 'cancelled';
-        }
-        if (gate.decision === 'deny') {
-            await this.reportToolResult(session, toolCall.id, gate.reason, true);
-            session.runlog.toolResult({ id: toolCall.id, result: gate.reason, isError: true, durationMs: 0 });
-            session.messages.push({ role: 'tool', content: gate.reason, toolCallId: toolCall.id });
-            return 'ok';
-        }
-        // Allowed: mark in-progress and execute through the shared tool runtime,
-        // preferring the client's filesystem when it advertised fs capabilities.
-        await this.emit(session.id, { sessionUpdate: 'tool_call_update', toolCallId: toolCall.id, status: 'in_progress' });
-        const started = Date.now();
-        let result;
+    async runTurn(session, prompt) {
+        const messages = { current: session.messages };
+        let streamedChars = 0;
         try {
-            result = await executeTool(toolCall, session.cwd, 60000, undefined, {
-                appendAnchorHash: session.localBackend,
-                fs: this.clientFsDelegate(session.id),
+            for (const warning of session.preference.warnings)
+                await this.emit(session.id, { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: `[Warning: ${warning}]\n` } });
+            const result = await runTurn({
+                captureToolOutput: true,
+                client: 'acp',
+                onSafetyBranch: async () => {
+                    const { branchSession } = await import('./session-management/index.js');
+                    const branch = await branchSession(session.id, { kind: 'safety', signal: session.controller?.signal, runlog: session.runlog });
+                    await this.emit(session.id, { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: `Recovery conversation branch: ${branch.session.id}\n` } });
+                },
+                onCheckpoint: (history, status) => {
+                    const saved = saveSessionConversation(session.id, history, { expectedRevision: session.revision, status });
+                    session.revision = saved.revision;
+                    session.runlog.sessionCheckpoint({ revision: saved.revision, status, messageCount: saved.messages.length, checksum: saved.checksum });
+                },
+                sessionId: session.id, cwd: session.cwd, provider: session.provider,
+                model: session.model || undefined, prompt, messages, signal: session.controller?.signal,
+                preferenceSources: session.preference.sources,
+                runlog: session.runlog, maxIterations: resolveIterationLimit(config.get('maxIterations')),
+                confirmation: 'mutating', approvals: this.approvals, tools: () => TOOLS, toolOptions: { fs: this.clientFsDelegate(session.id) },
+                prepare: async (request) => { streamedChars = 0; return request; },
+                approve: (call, decision) => this.requestPermission(session, call, decision.request?.reusable ?? false),
+                onToken: token => {
+                    if (!token || session.cancelled)
+                        return;
+                    streamedChars += token.length;
+                    void this.emit(session.id, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: token } });
+                },
+                onResponse: async (response) => {
+                    if (!streamedChars && response.content)
+                        await this.emit(session.id, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: response.content } });
+                },
+                onToolStart: async (call) => {
+                    await this.emit(session.id, { sessionUpdate: 'tool_call', toolCallId: call.id, title: toolTitle(call), kind: toolKind(call.name), status: 'pending', rawInput: call.arguments });
+                },
+                beforeTool: async (call) => { await this.emit(session.id, { sessionUpdate: 'tool_call_update', toolCallId: call.id, status: 'in_progress' }); },
+                onToolResult: async (call, value) => { await this.reportToolResult(session, call.id, value.displayResult || value.result, !!value.isError, value.result); },
+                onWarning: warning => { void this.emit(session.id, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: `\n[Warning: ${warning}]\n` } }); },
+                onRoute: decision => {
+                    if (decision.selected)
+                        session.resolvedProvider = decision.selected.provider;
+                    void this.emit(session.id, { sessionUpdate: 'agent_thought_chunk', content: { type: 'text', text: `\n[Route: ${decision.selected ? `${decision.selected.provider}/${decision.selected.model}` : 'unavailable'}; ${decision.reason}]\n` } });
+                },
             });
+            if (result.budget?.exceeded)
+                await this.emit(session.id, { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: formatBudgetHalt(result.budget) } });
+            await this.flush();
+            if (result.reason === 'cancelled')
+                return 'cancelled';
+            if (result.reason === 'budget')
+                return 'refusal';
+            if (result.reason === 'iteration_limit')
+                return 'max_turn_requests';
+            if (result.reason === 'length')
+                return 'max_tokens';
+            return 'end_turn';
         }
-        catch (err) {
-            result = {
-                toolCallId: toolCall.id,
-                result: `Error: ${errMessage(err)}`,
-                isError: true,
-            };
+        finally {
+            session.messages = messages.current;
         }
-        const durationMs = Date.now() - started;
-        session.runlog.toolResult({
-            id: toolCall.id,
-            result: result.result,
-            isError: result.isError || false,
-            durationMs,
-        });
-        await this.reportToolResult(session, toolCall.id, result.displayResult || result.result, result.isError || false, result.result);
-        session.messages.push({ role: 'tool', content: result.result, toolCallId: toolCall.id });
-        return 'ok';
     }
     /** Send a terminal (completed/failed) tool_call_update to the client. */
     reportToolResult(session, toolCallId, text, isError, rawResult) {
@@ -403,46 +339,14 @@ class CalliopeAgent {
         });
     }
     // ---- Gates: permission, then the hard hooks -------------------------
-    async gateToolCall(session, toolCall) {
-        // 1. Permission via the client (only for mutating / confirm-worthy tools).
-        if (toolNeedsPermission(toolCall)) {
-            const permission = await this.requestPermission(session, toolCall);
-            if (permission === 'cancelled')
-                return { decision: 'cancelled' };
-            if (permission === 'reject')
-                return { decision: 'deny', reason: '[Permission denied by user]' };
-            // 'allow' falls through to the hard gates below.
-        }
-        // 2. Pre-tool hooks — the hard gate, runs regardless of permission (exit-42
-        //    veto contract; see hooks.ts / docs/governance.md).
-        const hookGate = await checkHooksAllow('pre-tool', { tool: toolCall.name, toolArgs: toolCall.arguments });
-        if (!hookGate.allowed) {
-            return { decision: 'deny', reason: `[Blocked by hook: ${hookGate.reason || 'no reason given'}]` };
-        }
-        // 3. Policy hook — the Zentinelle integration point (fail closed).
-        if (isPolicyEnabled()) {
-            const verdict = await evaluatePolicy(toolCall);
-            session.runlog.policyEvent({
-                tool: toolCall.name,
-                decision: verdict.decision,
-                source: verdict.source,
-                reason: verdict.reason,
-                durationMs: verdict.durationMs,
-            });
-            if (verdict.decision === 'deny') {
-                return { decision: 'deny', reason: `[Policy denied: ${verdict.reason || 'no reason given'}]` };
-            }
-        }
-        return { decision: 'allow' };
-    }
     /**
      * Ask the client to authorize a tool call. Returns the user's decision, or
      * falls back to Calliope's non-interactive default (deny) when the client does
      * not support the permission request at all.
      */
-    async requestPermission(session, toolCall) {
+    async requestPermission(session, toolCall, reusable) {
         try {
-            const res = await this.conn.requestPermission({
+            const res = await cancellable(this.conn.requestPermission({
                 sessionId: session.id,
                 toolCall: {
                     toolCallId: toolCall.id,
@@ -452,18 +356,20 @@ class CalliopeAgent {
                 },
                 options: [
                     { optionId: 'allow', name: 'Allow', kind: 'allow_once' },
-                    { optionId: 'allow_always', name: 'Always allow', kind: 'allow_always' },
+                    ...(reusable ? [{ optionId: 'allow_always', name: 'Allow this exact operation for this session', kind: 'allow_always' }] : []),
                     { optionId: 'reject', name: 'Reject', kind: 'reject_once' },
                 ],
-            });
+            }), session.controller?.signal);
             const outcome = res.outcome;
             if (outcome.outcome === 'cancelled')
                 return 'cancelled';
             if (outcome.outcome === 'selected')
-                return outcome.optionId.startsWith('allow') ? 'allow' : 'reject';
+                return outcome.optionId === 'allow' ? 'allow' : outcome.optionId === 'allow_always' && reusable ? 'allow_session' : 'reject';
             return 'reject';
         }
         catch (err) {
+            if (session.cancelled || isCancellation(err))
+                return 'cancelled';
             // Client can't handle permission requests: non-interactive default is to
             // deny anything that needed asking (read-only tools never reach here).
             log(`requestPermission unavailable (${errMessage(err)}); ` +
@@ -517,16 +423,11 @@ class CalliopeAgent {
     /** Close every session's audit log (best-effort) on shutdown. */
     async shutdown() {
         for (const session of this.sessions.values()) {
-            session.runlog.runEnd({
-                totals: {
-                    inputTokens: session.totals.inputTokens,
-                    outputTokens: session.totals.outputTokens,
-                    cost: session.totals.cost,
-                    toolCalls: session.totals.toolCalls,
-                    durationMs: Date.now() - session.startedAt,
-                },
-                exitReason: session.cancelled ? 'cancelled' : 'completed',
-            });
+            if (session.controller) {
+                session.cancelled = true;
+                session.controller.abort();
+            }
+            await session.activeTurn?.catch(() => { });
             await session.runlog.close();
         }
     }