zidane 7.0.31 → 7.1.1

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import { $_ as SessionData, B_ as ToolStateView, Bg as PromptVideoPart, Br as InteractionToolOptions, C as SuccessfulMutationOutcome, C_ as ToolContext, D_ as ReadStateEntry, Dg as McpServerConfig, Dm as TurnResult, Em as ToolSpec, Fg as PromptAudioPart, G_ as SkillConfig, Gg as RetryConfig, Hg as RepeatGuardToolMatcher, I_ as StagedToolState, Ig as PromptDocumentPart, Jg as SessionEndStatus, Ji as AgentHookMap, Kg as RunHookMap, L_ as ToolStateController, Lg as PromptImagePart, Mg as OAuthRefreshHookContext, Ng as ProgressNudgeKind, O_ as ReadStateMap, Og as McpToolHookContext, Pg as ProgressNudgeMessage, Q_ as Session, Qg as SpawnHookContext, R_ as ToolStateOp, Rg as PromptPart, Rm as OpenRouterParams, S as MutationValidationResult, S_ as toolResultToText, Sg as DEFAULT_AGENT_CLOCK, Sm as StreamOptions, T_ as ToolMap, Tm as ToolResult, Ug as ResolveContentRef, Vg as RepeatGuardConfig, Wg as ResolveContentRefBlock, X_ as CreateSessionOptions, Xg as SessionMessage, Xi as AgentOptions, Y_ as SkillsConfig, Yg as SessionHookContext, Yi as AgentHooks, Zg as SessionTurn, Zi as AgentToolState, _ as statsByModel, __ as ToolResultVideoContent, _g as ChildRunStats, a_ as ThinkingLevel, b as MutationValidationHooksOptions, b_ as toolOutputBudgetByteLength, bh as CerebrasParams, c_ as ToolOutcome, ch as OpenAIParams, d_ as ToolResultDocumentContent, dg as AgentClock, f_ as ToolResultDocumentRefContent, fg as AgentRunOptions, fv as RemoteStoreOptions, g_ as ToolResultTextContent, gc as SpawnToolState, h as flattenTurns, h_ as ToolResultMetadata, hc as SpawnToolOptions, kh as AnthropicParams, l_ as ToolResultAudioContent, m_ as ToolResultImageRefContent, nv as SessionStore, p as ModelUsage, p_ as ToolResultImageContent, pg as AgentStats, q_ as SkillResource, qg as SessionContentBlock, qi as Agent, ry as McpConnection, s_ as ToolHookContext, t as Preset, t_ as StreamHookContext, tv as SessionRun, u_ as ToolResultContent, uc as ChildAgent, ug as AgentBehavior, v as MutationValidationBatch, v_ as TurnFinishReason, vm as Provider, vr as ValidationResult, w_ as ToolDef, wm as ToolCall, x as MutationValidationMutation, x_ as toolOutputByteLength, xm as StreamCallbacks, y as MutationValidationFailure, y_ as TurnUsage, ym as ProviderCapabilities, z_ as ToolStateStore, zg as PromptTextPart } from "./index-hd4zLhp8.js";
+import { $_ as SkillsConfig, $g as SessionHookContext, Ah as AnthropicParams, B_ as StagedToolState, Bg as PromptDocumentPart, Br as InteractionToolOptions, C as SuccessfulMutationOutcome, C_ as TurnUsage, Cm as StreamOptions, D_ as ToolContext, Dm as ToolSpec, E_ as toolResultToText, Eg as DEFAULT_AGENT_CLOCK, Em as ToolResult, Gg as RepeatGuardConfig, H_ as ToolStateOp, Hg as PromptPart, Ig as OAuthRefreshHookContext, Jg as ResolveContentRefBlock, Ji as AgentHookMap, Kg as RepeatGuardToolMatcher, Lg as ProgressNudgeKind, M_ as ReadStateMap, Mg as McpToolHookContext, O_ as ToolDef, Om as TurnResult, Qg as SessionEndStatus, Rg as ProgressNudgeMessage, S as MutationValidationResult, S_ as TurnFinishReason, Sm as StreamCallbacks, T_ as toolOutputByteLength, Tm as ToolCall, U_ as ToolStateStore, Ug as PromptTextPart, V_ as ToolStateController, Vg as PromptImagePart, W_ as ToolStateView, Wg as PromptVideoPart, Xg as RunHookMap, Xi as AgentOptions, Y_ as SkillConfig, Yg as RetryConfig, Yi as AgentHooks, Z_ as SkillResource, Zg as SessionContentBlock, Zi as AgentToolState, _ as statsByModel, __ as ToolResultImageContent, _g as AgentStats, a_ as StreamHookContext, av as SessionRun, b as MutationValidationHooksOptions, b_ as ToolResultTextContent, bm as ProviderCapabilities, d_ as ToolHookContext, e_ as SessionMessage, ev as CreateSessionOptions, f_ as ToolOutcome, g_ as ToolResultDocumentRefContent, gc as SpawnToolState, gg as AgentRunOptions, gv as RemoteStoreOptions, h as flattenTurns, h_ as ToolResultDocumentContent, hc as SpawnToolOptions, hg as AgentClock, j_ as ReadStateEntry, jg as McpServerConfig, k_ as ToolMap, l_ as ThinkingLevel, lh as OpenAIParams, m_ as ToolResultContent, mg as AgentBehavior, n_ as SpawnHookContext, nv as Session, ov as SessionStore, p as ModelUsage, p_ as ToolResultAudioContent, qg as ResolveContentRef, qi as Agent, rv as SessionData, sy as McpConnection, t as Preset, t_ as SessionTurn, uc as ChildAgent, v as MutationValidationBatch, v_ as ToolResultImageRefContent, vr as ValidationResult, w_ as toolOutputBudgetByteLength, x as MutationValidationMutation, x_ as ToolResultVideoContent, xg as ChildRunStats, xh as CerebrasParams, y as MutationValidationFailure, y_ as ToolResultMetadata, ym as Provider, zg as PromptAudioPart, zm as OpenRouterParams } from "./index-DZhrTn-v.js";
 import { d as ClassifiedErrorKind, i as AgentContextExceededError, l as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, n as AgentAbortedError, o as AgentProviderError, p as matchesContextExceeded, r as AgentBudgetExceededError, s as AgentToolNotAllowedError, u as ClassifiedError } from "./timeout-DEaqslLO.js";
-import { _ as TaskHandle, a as ContextType, c as ExecutionContext, g as TaskExitInfo, h as TaskEntry, l as ExecutionHandle, n as ContextCapabilities, o as DetachedTasksCapability, p as SpawnConfig, r as ContextHardening, s as ExecResult, t as BackgroundTaskStatus, v as TaskStallInfo } from "./types-U-rIVUDw.js";
-import { t as SandboxProvider } from "./sandbox-CDl9tfTo.js";
+import { C as TaskHandle, S as TaskExitInfo, c as ContextCapabilities, d as ContextType, f as DetachedTasksCapability, h as ExecutionHandle, l as ContextHardening, m as ExecutionContext, p as ExecResult, s as BackgroundTaskStatus, w as TaskStallInfo, x as TaskEntry, y as SpawnConfig } from "./isolation-Kfoof0MM.js";
+import { t as SandboxProvider } from "./sandbox-BH0WQkXn.js";
 export { type Agent, AgentAbortedError, type AgentBehavior, AgentBudgetExceededError, type AgentClock, AgentContextExceededError, type AgentHookMap, type AgentHooks, type AgentOptions, AgentProviderError, type AgentRunOptions, type AgentStats, AgentToolNotAllowedError, type AgentToolState, type AnthropicParams, type BackgroundTaskStatus, CONTEXT_EXCEEDED_MESSAGE_PATTERNS, type CerebrasParams, type ChildAgent, type ChildRunStats, type ClassifiedError, type ClassifiedErrorKind, type ContextCapabilities, type ContextHardening, type ContextType, type CreateSessionOptions, DEFAULT_AGENT_CLOCK, type DetachedTasksCapability, type ExecResult, type ExecutionContext, type ExecutionHandle, type InteractionToolOptions, type McpConnection, type McpServerConfig, type McpToolHookContext, type ModelUsage, type MutationValidationBatch, type MutationValidationFailure, type MutationValidationHooksOptions, type MutationValidationMutation, type MutationValidationResult, type OAuthRefreshHookContext, type OpenAIParams, type OpenRouterParams, type Preset, type ProgressNudgeKind, type ProgressNudgeMessage, type PromptAudioPart, type PromptDocumentPart, type PromptImagePart, type PromptPart, type PromptTextPart, type PromptVideoPart, type Provider, type ProviderCapabilities, type ReadStateEntry, type ReadStateMap, type RemoteStoreOptions, type RepeatGuardConfig, type RepeatGuardToolMatcher, type ResolveContentRef, type ResolveContentRefBlock, type RetryConfig, type RunHookMap, type SandboxProvider, type Session, type SessionContentBlock, type SessionData, type SessionEndStatus, type SessionHookContext, type SessionMessage, type SessionRun, type SessionStore, type SessionTurn, type SkillConfig, type SkillResource, type SkillsConfig, type SpawnConfig, type SpawnHookContext, type SpawnToolOptions, type SpawnToolState, type StagedToolState, type StreamCallbacks, type StreamHookContext, type StreamOptions, type SuccessfulMutationOutcome, type TaskEntry, type TaskExitInfo, type TaskHandle, type TaskStallInfo, type ThinkingLevel, type ToolCall, type ToolContext, type ToolDef, type ToolHookContext, type ToolMap, type ToolOutcome, type ToolResult, type ToolResultAudioContent, type ToolResultContent, type ToolResultDocumentContent, type ToolResultDocumentRefContent, type ToolResultImageContent, type ToolResultImageRefContent, type ToolResultMetadata, type ToolResultTextContent, type ToolResultVideoContent, type ToolSpec, type ToolStateController, type ToolStateOp, type ToolStateStore, type ToolStateView, type TurnFinishReason, type TurnResult, type TurnUsage, type ValidationResult, flattenTurns, matchesContextExceeded, statsByModel, toolOutputBudgetByteLength, toolOutputByteLength, toolResultToText };

package/docs/ARCHITECTURE.md

@@ -312,6 +312,7 @@ A prefix cache breaks at the first differing byte — the wire must be append-on
 | `thinkingDecay` | Step form `{ afterTurn, floor }` | Every distinct budget is one cache loss; step emits one change per run, geometric emits one per halving, a per-turn function disables caching for the rest of the run. |
 | `cacheTtl` | `'1h'` for interactive hosts, `'5m'` for headless back-to-back runs | The 5-minute default TTL is the dominant cache cost for a human-paced session. |
 | `compactStrategy` / `mediaKeepTurns` | Keep windows equal, chunk-aligned (`COMPACT_CHUNK_TURNS`) | A window then costs one invalidation, not two. |
+| `compactThresholdWindowFraction` | `0.25` for interactive hosts | Each tail-compaction frontier step rewrites an early message and re-bills the whole suffix (~50x the cost of keeping the bytes cached). Scaling the byte threshold with the model's window removes the steps on large-context models; ≤128k models keep the byte rule. Live A/B in `test-inference/cache-stability.inference.test.ts` § tail compaction vs context window. |
 | `thinking` level | Constant for the whole run | The thinking config is part of the cache key like the budget; toggling it mid-run forfeits the prefix. |
 | `system:transform` handlers | Byte-stable output only | Per-turn counters/timestamps belong in the transcript, not the system prompt. |
 
@@ -439,16 +440,25 @@ installLazyDisclosureGate                        // tool:gate refuses lazy ∉ u
 
 per turn — buildFormattedTools() emits in two phases:
   1. registry-order walk filtered by initialUnlocked  ← byte-stable cached prefix
-  2. dynamicUnlockOrder, in unlock order              ← append-only tail
+  2. dynamicUnlockOrder, in unlock order              ← append-only tail (omitted in dispatch mode)
 
 tool_search({ names | query | server, limit? }): unlocks matches, returns inlined input_schema JSON
 
+dispatch mode (toolSearch.mode: 'dispatch'):
+  tools.call_tool = createCallToolTool()               ← eager, fixed { name, arguments } envelope
+  model: call_tool({ name: 'mcp_srv_a', arguments })
+  loop (after wire→canonical rewrite): unwrapDispatchCalls()
+    → ToolCall { id, name: 'mcp_srv_a', input: arguments }   for gate / validation / hooks / events
+    persisted assistant turn keeps the call_tool block   ← wire-valid history
+  store.eventsFromTurns: unwrapCallTool() on replay     ← reload matches the live transcript
+
 run end: uninstallLazyDisclosureGate; per-run state GC-eligible on next run()
 ```
 
 - **Aliasing.** `LazyToolEntry.name` is the wire name; `.canonicalName` keys `unlocked` and dispatches `ctx.tools[name]`. `session.turns` / `ToolHookContext.name` stay canonical throughout.
 - **Hard gate vs. provider validation.** Anthropic/OpenAI already refuse `tool_use` blocks for tools absent from the request; the gate exists for lenient/custom/mock providers and makes the lazy boundary observable via `tool:gate`.
-- **Cache-stable injection.** Every `tool_search` call invalidates only the wire tools array's SUFFIX starting at the first new schema — the eager + `tool_search` prefix never moves.
+- **Cache cost of unlock mode.** The eager + `tool_search` prefix of the wire array never moves, but providers hash the request as `tools → system → messages`: a grown tail still re-bills the system prompt and every message on that turn. That is one full prompt-cache rewrite per discovery wave.
+- **Dispatch mode.** `toolSearch.mode: 'dispatch'` keeps the tools array byte-stable: surfaced tools are invoked through `call_tool` (`src/tools/call-tool.ts`). The unwrap happens once, in `runTurn` right after the alias rewrite, so the whole downstream pipeline (lazy gate, MCP gates, `validateToolArgs` against the INNER schema, `tool:before/after`, tracing, run counts, both dispatch paths) is unchanged and sees the inner tool. Only lazy catalog tools are unwrapped: an envelope around an eager tool stays a `call_tool` call and its `execute` says to call the tool directly (history scanners keyed on `block.name`, read-state seeding, task tracking, keep seeing eager tools under their own names). A malformed envelope is left as `call_tool` so its own schema validation reports the shape error. A host-defined `call_tool` disables dispatch mode (the run falls back to unlock). The chat hosts expose this as `Settings.stableToolList`.
 - **Host-defined `tool_search`.** A host tool named `tool_search` shadows auto-injection; it must call `createToolSearchTool({ catalog, unlocked, addUnlock? })` to drive unlocks, or use `toolSearch.tool: false` for a fully custom flow.
 
 ## Hook Firing Order
@@ -661,7 +671,7 @@ Use `agent.hooks.hook(event, fn)` for dynamic post-creation registration (return
 **Defaults:** unlimited turns, model-driven output tokens, level-based thinking, `cache: true`, `dedupReads: true`, `requireReadBeforeEdit: false`, `maxConcurrentTools: 10`, `compactStrategy: 'off'`, `compactThreshold: 128 KiB`, `compactKeepTurns: 4`, `toolDisclosure: 'eager'`, `readLineNumbers: true`, `elideStaleReads: false`, `surfaceMcpInstructions: true`, `maxConsecutivePauseTurns: 0` (unlimited), `persistTurns: true`, `providerStreamStartTimeoutMs: 300000`, `providerStreamTimeoutMs: 1800000`, `mcpConnectTimeoutMs: 120000`. All other knobs below default to `undefined`/off unless noted. The chat-layer profiles (`BUILD_AGENT`/`PLAN_AGENT`) override several — see `docs/CHAT.md` § Agents.
 
 - **`toolOutputBudget`** (off). Sums every result's `outputBytes` after `tool:transform`. On overshoot, appends a synthetic user message (`[Tool output budget exceeded: N bytes … cap: M]`) and fires `budget:exceeded` — the model self-compacts next turn instead of being cut.
-- **`compactStrategy: 'tail' | CompactFunction'`** — client-side, wire-only trim for non-Anthropic providers. `'tail'` stubs `tool_result` blocks older than `compactKeepTurns` past a byte threshold; `session.turns` is untouched. Anthropic should prefer server-side `context-management-2025-06-27` (token-accurate). A custom function must preserve `tool_use ↔ tool_result` adjacency and the trailing user message.
+- **`compactStrategy: 'tail' | CompactFunction'`** — client-side, wire-only trim for non-Anthropic providers. `'tail'` stubs `tool_result` blocks older than `compactKeepTurns` past a byte threshold (`compactThreshold`, raised to `compactThresholdWindowFraction × contextWindow × 4 B` when the run knows its window — `autoCompact.contextWindow`, the active `ModelTarget`, or `provider.meta.contextWindow`); `session.turns` is untouched. Anthropic should prefer server-side `context-management-2025-06-27` (token-accurate). A custom function must preserve `tool_use ↔ tool_result` adjacency and the trailing user message.
 - **`mediaKeepTurns`** — wire-only media age-out. Inline `image`/`document` blocks older than N messages become an `attachment://<hash>` marker on the wire; `session.turns` keeps the bytes, `read_file path="attachment://<hash>"` re-inlines. Chunk-snapped for cache stability; requires `read_file` registered to be actionable.
 - **`autoCompact`** (`boolean | AutoCompactConfig`, off). At each turn boundary, once effective input (`input + cacheRead + cacheCreation`) crosses `threshold` (default `0.85`) of the context window, summarizes older turns and continues. Window source: `autoCompact.contextWindow` → `provider.meta.contextWindow`, else inert. `minGrowthFraction` (default `0.1`) stops post-compact thrashing; `maxFailures` (default `2`) disables it after consecutive summary failures. Chat profiles enable at `{ threshold: 0.85 }`.
 - **`modelCatalog`** — override model metadata keyed `"<provider>:<modelId>"` or via `{ get, list }`. Resolution: run → agent `behavior.modelCatalog` → process-wide `setModelCatalog()` → bundled registry → local fallback tables, merged field-level. `list` returning `[]` empties a provider's picker; `get` returning `undefined` falls through. Unset by default.

package/docs/CHAT.md

@@ -166,6 +166,10 @@ const SHARED_BEHAVIOR: AgentBehavior = {
   // context / token discipline
   compactStrategy: 'tail',
   compactThreshold: 128 * 1024,
+  compactThresholdWindowFraction: 0.25, // effective threshold = max(128 KiB,
+                                    // 0.25 × window × 4 B/tok): 1M-context
+                                    // runs never trip tail compaction on
+                                    // ordinary sessions; ≤128k stays on bytes
   compactKeepTurns: 8,             // floor, not a cap — see below
   elideStaleReads: 'notice',       // append-only staleness note; never rewrites
                                     // cached prefix bytes ('stub' re-bills the
@@ -247,9 +251,14 @@ Both join `[...doctrine, userInstructions]` as the **static** half and `[envSect
 | `showAllProjects` | `boolean` | `false` | Sessions list scope. |
 | `resumeLastSession` | `boolean` | `true` | |
 | `persistToolResults` | `boolean` | `true` | See **Tool-result persistence**. |
+| `stableToolList` | `boolean` | `false` | Lazy MCP tools surfaced by `tool_search` are invoked through `call_tool` instead of growing the model's tool list (`behavior.toolSearch.mode: 'dispatch'`), so discovery never rewrites the prompt cache. Transcript shows the inner tool as with a direct call. Anthropic always uses dispatch (replayed thinking is bound to the tool list — see Preserved thinking in `SKILL.md`); the toggle only affects other providers. |
+| `sandbox` | `boolean` | `false` | Run the model's `shell` commands under the OS sandbox (macOS Seatbelt / Linux bwrap). Writes limited to cwd, temp dirs, a worktree's git dir and `sandboxAllowWrite`; credential dirs unreadable; `write_file`/`edit` follow the same roots. Not covered: `!` commands, MCP servers, `fetch_url`, reads. Fails closed when the backend is missing (a `sandbox` notice explains on activation). Resolved by `chat/sandbox-settings.ts` → `SpawnConfig.isolation`; see `docs/EXECUTION_CONTEXT.md`. Next session activation. |
+| `sandboxNetwork` | `'allow'\|'deny'` | `'allow'` | Network for sandboxed commands. `deny` removes all sockets — the only way to stop exfiltration of readable files, at the cost of `bun install` / `git fetch`. |
+| `sandboxAllowWrite` | `string` | `''` | Extra writable paths, comma/newline separated, `~` expanded, relative to cwd. |
 | `autoCompact` | `boolean` | `true` | See **Auto-compaction**. |
 | `autoCompactThreshold` | `number` | `0.8` | Cycles 0.6/0.7/0.8/0.9 in the settings modal. |
 | `resumeOnMaxTokens`, `maxOutputTokens`, `maxTurns`, `retryMaxAttempts`, `maxCostUsd`, `maxTotalTokens`, `maxWallMinutes` | mixed | off/`0` | Runaway ceilings; all off by default (model-driven, uncapped). |
+| `thinkingBinding` | `'drop_block' \| 'error' \| 'off'` | `'drop_block'` | Anthropic only. What the API does with replayed thinking whose prefix changed: drop server-side and continue, fail the run with the API's 400 (no retry, history untouched — debugging), or account default. Published to `ZIDANE_THINKING_BINDING_SETTING` by the TUI on change and by the chat host per send; the provider reads it per request. Precedence: `anthropic({ thinkingBinding })` > `ZIDANE_THINKING_BINDING` set in the launching shell > this setting > `'drop_block'`. |
 | `showEditDiffs` | `boolean` | `true` | See **Edit-diff rendering**. |
 | `editDiffDisplay` | `'full'\|'compact'` | `'full'` | Approval modal always shows the full diff regardless. |
 | `showCompactionSummary` | `boolean` | `false` | Render the LLM summary text under the compaction card, not just metadata. |

package/docs/EXECUTION_CONTEXT.md

@@ -275,9 +275,70 @@ bun run headless "fix the lint errors" --cwd /tmp/project
 Applicable flags: `--cwd` (defaults to the current directory), `--env`, and
 `--pass-env`. The `--image`, `--pregame`, and `--sandbox` flags don't apply.
 
-Because there's no isolation, the agent's commands can read and modify anything
-your own shell can. Prefer `docker` or `e2b` when you don't fully trust what the
-agent might run.
+Because there's no isolation by default, the agent's commands can read and
+modify anything your own shell can. Prefer `docker` or `e2b` when you don't
+fully trust what the agent might run, or turn on the OS sandbox below for a
+lightweight middle ground.
+
+### OS sandbox (`isolation`)
+
+`createProcessContext({ cwd, isolation })` wraps every shell command in a
+kernel-enforced sandbox — the same primitive Claude Code and Codex use:
+
+| Platform | Backend | Mechanism |
+|---|---|---|
+| macOS | `/usr/bin/sandbox-exec` (Seatbelt) | deny-default SBPL profile derived from Codex's base policy; paths are passed as `-D` params, never inlined |
+| Linux | `bwrap` (bubblewrap) | `--ro-bind / /`, per-root `--bind`, `--tmpfs` over credential dirs, `--unshare-net` when denied |
+| Windows | — | unsupported; requesting isolation fails closed |
+
+```ts
+import { createProcessContext, resolveWritableRoots } from 'zidane'
+
+const execution = createProcessContext({
+  cwd,
+  isolation: {
+    writableRoots: resolveWritableRoots(cwd, { extra: ['~/.cache'] }),
+    network: 'allow', // or 'deny'
+  },
+})
+```
+
+**Policy.** `writableRoots` is where commands may create / modify / delete;
+`resolveWritableRoots` (sync) / `resolveWritableRootsAsync` build the default set: `cwd`, `$TMPDIR`, `/tmp`,
+`/var/tmp` (+ `/private` aliases on macOS), git's common dir when `cwd` is a
+linked worktree (otherwise `git commit` fails there), plus extras — all
+canonicalized and deduped. Reads are allowed everywhere except
+`unreadableDirs` (default: `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.kube`,
+`~/.azure`, `~/.config/gcloud`, `~/.docker/config.json`, `~/.netrc`,
+zidane's `credentials.json` and `mcp-credentials.json`; the chat hosts
+resolve the latter two from the actual data dir). `network` is
+all-or-nothing; per-domain allowlists need a proxy and are not implemented.
+
+**Scope.** Kernel enforcement covers `exec`, `execStream` and
+`execBackground` — i.e. the model's `shell` tool and anything else routed
+through the context (stdio MCP servers bound to it, subagents). `writeFile`
+applies the same `writableRoots` in-process, so `write_file` / `edit` /
+`multi_edit` cannot write where a shell command couldn't. `readFile`, `glob`
+and `listFiles` are unrestricted (persisted tool outputs and skills under
+`~/.zidane` / `~/.agents` must stay reachable). Not covered: MCP servers
+spawned by the host, `fetch_url`, the `!` shell in the TUI, `$EDITOR`.
+
+**Fail closed.** If the backend is missing (`bwrap` not installed,
+non-darwin/linux), every shell call returns exit `127` with the reason and
+`execStream` / `execBackground` throw; nothing runs unsandboxed. Probed once
+at context creation; `capabilities.isolated` is `true` only when isolation is
+actually enforced (requested AND backend available), `false` when it was
+requested but the context is in this fail-closed state.
+
+**Denials.** A failed command whose stderr matches `Operation not permitted`
+/ `Read-only file system` gets one appended `[sandbox] …` line naming the
+writable roots and the settings that widen them, so the model asks instead
+of guessing. Process-group kill semantics are unchanged: `sandbox-exec`
+execs the shell in place and `bwrap` runs without `--new-session`.
+
+In the chat hosts this is `Settings.sandbox` / `sandboxNetwork` /
+`sandboxAllowWrite` (see `docs/CHAT.md`). Docker / e2b / daytona contexts
+ignore it — they are already isolated.
 
 The process context also implements the optional `fileSize` capability — a
 containment-aware size probe that lets whole-file tools (`read_file`, `edit`,

package/docs/INTERACTIONS.md

@@ -87,7 +87,10 @@ user's own selection rather than resetting it.
 Response shape:
 
 ```json
-{ "answers": { "name": "Jane", "notes": "...", "fw": "react", "go": true } }
+{
+  "answers": { "name": "Jane", "notes": "...", "fw": "react", "go": true },
+  "instructions": "Also keep the old endpoint alive until the migration lands."
+}
 ```
 
 Missing keys = question was skipped (only possible when `required:
@@ -95,12 +98,21 @@ false`). Empty-string answers and empty multi-select picks are dropped
 at serialization; a multi-select (`type: 'select'`, `multi: true`)
 answers as an array of choice ids.
 
+`instructions` is free text the user attached to the whole form. Every
+surface offers it unconditionally (the TUI wizard ends on an "additional
+instructions" step, the GUI modal has a permanent textarea under the
+questions), so the user can always refine or override the questions
+instead of being boxed into the model's choices. Omitted when left empty.
+The tool description tells the model it is authoritative.
+
 ## Keyboard
 
 In the question wizard (multi-question batches):
 
 - `↑/↓` (or `j/k`) — navigate options
-- `↵` — submit the active question / pick the focused option
+- `↵` — submit the active question / pick the focused option. The last
+  step is always "additional instructions" (optional textarea): `↵` on an
+  empty box sends the answers as they are.
 - `space` — toggle the focused option (multi-selects only; `↵` submits
   the whole selection, at least one pick required unless `required: false`)
 - `shift+↹` — back one question (preserves your answers, pre-fills the

package/docs/SKILL.md

@@ -49,6 +49,7 @@ const agent = createAgent({
     toolBudgets: { run_query: { max: 20, onExceed: 'steer' } },
     compactStrategy: 'off',          // 'off' | 'tail' (non-Anthropic compaction)
     compactThreshold: 131_072,       // 128 KiB
+    compactThresholdWindowFraction: 0.25, // raise it to 25% of the model's window (large-context runs stop re-billing the prefix)
     compactKeepTurns: 4,
     toolDisclosure: 'eager',         // 'eager' | 'lazy'
     toolSearch: { limit: 20 },
@@ -182,6 +183,32 @@ Flatten via `toolResultToText(result)`. MCP image blocks are auto-normalized via
 
 Cache hits surface on `TurnUsage.cacheRead` / `cacheCreation`. Anthropic + OpenRouter populate them per turn. Live break/drift telemetry is a hook concern — see `cache:break` / `cache:drift` in the [Hook reference](#hook-reference).
 
+### Preserved thinking (Anthropic)
+
+Claude Fable 5.1 and later bind every replayed `thinking` block to the exact prefix it was produced under — `system`, `tools`, and every earlier message. If any of those bytes changed since, that block and every later one are invalid. By default the API rejects the whole request with a 400; on accounts created after 2026-08-31 this is enforced out of the box, on older accounts only when the field below is set. (`platform.claude.com/docs/en/build-with-claude/preserved-thinking`)
+
+Zidane opts into the safe behavior on every thinking-enabled Anthropic request: `thinking.block_binding.prefix_mismatch_behavior: "drop_block"` plus the `thinking-binding-controls-2026-08-01` beta. Invalid blocks are dropped server-side (unbilled), the request succeeds, and history is never mutated. Thinking-off requests and Bedrock are untouched.
+
+```ts
+anthropic({ apiKey: 'sk-ant-...', thinkingBinding: 'drop_block' })  // default
+anthropic({ apiKey: 'sk-ant-...', thinkingBinding: 'error' })       // fail the run on a prefix edit — debugging / CI
+anthropic({ apiKey: 'sk-ant-...', thinkingBinding: 'off' })         // send nothing; pre-feature wire bytes, account default applies
+```
+
+Precedence: `thinkingBinding` param > shell `ZIDANE_THINKING_BINDING` > chat setting `thinkingBinding` (published on `ZIDANE_THINKING_BINDING_SETTING` before each run by the TUI / daemon) > `'drop_block'`. Read per request, so a flip lands on the next call without rebuilding the provider. The setting is labelled "Preserved thinking (Anthropic only)" and is inert on every other provider.
+
+Effect per mode:
+
+| Mode | On a prefix edit | History | Visible as |
+|---|---|---|---|
+| `drop_block` | Stale blocks dropped server-side; model answers without that reasoning; cache restarts at the edit | untouched | `provider:input-transformations` (`prefixMismatches` / `modelMismatches`) |
+| `error` | 400; the run rejects, no retry | untouched | run error `Invalid \`signature\` in \`thinking\` block … bound to a different conversation` |
+| `off` | Account default: old accounts tolerate, new accounts 400 → the signature-scrub ladder strips **all** history thinking and retries | scrubbed on 400 | `history:repair` |
+
+What zidane already keeps prefix-safe: append-only turns, nudges and stale-read notices, tail truncation, compaction (`applyCompactSummaryCutoff` strips thinking from the kept tail), the `__output__` structured-output call, lazy MCP disclosure (defaults to `toolSearch.mode: 'dispatch'` on Anthropic so `tools` stays byte-stable), the TUI `<env> Date:` (pinned per session). What still costs reasoning once per edit: rewriting `system` between turns (cwd change, interaction-mode flip, rules-file edit, skill activation), a run-level `tools` change, `elideStaleReads: 'stub'`, `compactStrategy: 'tail'`, `mediaKeepTurns`. A model downgrade mid-conversation drops the newer model's blocks with `model_binding_mismatch`; that is not an edit and needs no action. Every `cache:break` attributed to `system`, `tools` or `messagePrefix` is also a preserved-thinking drop, so wire the two hooks to the same telemetry.
+
+Live coverage: `test-inference/preserved-thinking.inference.test.ts`.
+
 ### Provider error classification
 
 Provider failures are wrapped via `toTypedError(err)` before leaving `agent.run()` — each provider implements `Provider.classifyError(err): ClassifiedError | null`; unrecognized errors fall back to `AgentProviderError`. Aborts always produce `AgentAbortedError`. Match on `instanceof`, not on `err.message`.
@@ -339,6 +366,7 @@ Every event in `AgentHooks` (`src/agent.ts`), one row each. `child:*` bubble eve
 | `compact:progress` | Throttled, while the compaction summary streams | — | `+ estOutputTokens` |
 | `compact:end` | Exactly once per `compact:start`, on success or failure | — | `+ status: 'success' \| 'error'` (success: replaced/dropped/restored counts + `effectiveTokens`; error: `error`) |
 | `history:repair` | After a provider stream settles when the loop scrubbed provider-rejected reasoning state (e.g. Anthropic signature-400 poisoning) | — | `reason: 'invalid-anthropic-thinking-signature', runId, sessionId?, turnIds, removedBlocks` |
+| `provider:input-transformations` | Provider dropped replayed thinking blocks server-side before sampling (Anthropic preserved-thinking binding, `input_transformations`). History untouched; `prefix_binding_mismatch` entries mean this host edited system/tools/an earlier message | — | `runId, turnId, sessionId?, transformations[{type,path,reason}], prefixMismatches, modelMismatches` |
 | `oauth:refresh` | OAuth token refreshed | — | `provider, providerId, source: 'params'\|'file', previousCredentials, credentials` |
 | `content-ref:resolve` | Wire assembly sees a block carrying `ref`; resolves persisted content refs into provider-bound bytes | **yes** (`data`) | `block, data?, childId?, depth?` |
 | `tool:gate` | Before each tool call | **yes** (`block, reason, result?`) | `turnId, callId, name, displayName, input, runToolCounts` — `block` refuses with `tool_result.content = "Blocked: <reason>"` + `is_error: true`; `result` substitutes and skips execute; `block` wins over `result` |
@@ -688,7 +716,9 @@ createAgent({
 
 The system prompt gains a `<searchable_tools>` block. `tool_search({ query, names, server, limit })` returns matching schemas and unlocks them for the rest of the run. A `tool:gate` middleware refuses un-surfaced lazy tools. Catalog + search results show the **wire** name; the unlock set keys on canonical so dispatch / `session.turns` stay alias-stable.
 
-`behavior.toolSearch` knobs (no-op in eager mode): `tool: false` opts out of auto-injection; `limit: 20` caps default results. Per-server `disclosure: 'eager' | 'lazy'` overrides the agent default; run-level overrides agent-level. Cost: one cache miss per discovery wave; subsequent turns hit cache normally.
+`behavior.toolSearch` knobs (no-op in eager mode): `tool: false` opts out of auto-injection; `limit: 20` caps default results; `mode: 'unlock' | 'dispatch'` picks how a surfaced tool becomes callable. Per-server `disclosure: 'eager' | 'lazy'` overrides the agent default; run-level overrides agent-level.
+
+Cost: in `'unlock'` mode (default) every discovery wave grows the tools array, and since providers hash `tools → system → messages` that is a **full** prompt-cache rewrite each time. `'dispatch'` mode keeps the tools array byte-stable: a fixed `call_tool { name, arguments }` native tool is added, surfaced tools are invoked through it, and the loop unwraps the envelope before dispatch so gating, schema validation (against the inner tool), hooks and transcript events see the inner tool exactly as a direct call. Chat hosts expose it as `Settings.stableToolList`.
 
 ## Skills
 

package/docs/TUI.md

@@ -108,7 +108,7 @@ Not re-exported: the renderer-agnostic engine (settings, theme, safe-mode, store
 Layered slots, in priority order:
 
 1. **Transcript-slot takeover** — a file-edit approval (`edit`/`multi_edit`/`write_file`) renders `FileEditApprovalModal` inline in the transcript slot (`<Transcript visible={!fileEditPending}>` so scroll position and memoized turn anchors survive open→close). See [File-edit approval modal](#file-edit-approval-modal).
-2. **Bottom slot**, one of: non-file-edit `pendingApproval` → `ApprovalBlock` (accept once / for session / + remember / deny, esc aborts the run) · `pendingInteraction` → `InteractionBlock` (plan picker or Q&A wizard; esc aborts if live, exits the form if resumed) · else `PromptBlock` (textarea + history), kept mounted (`Display.None` when hidden) so draft/cursor/attachments survive an approval round-trip.
+2. **Bottom slot**, one of: non-file-edit `pendingApproval` → `ApprovalBlock` (accept once / for session / + remember / deny, `ctrl+esc` aborts the run) · `pendingInteraction` → `InteractionBlock` (plan picker or Q&A wizard; `ctrl+esc` aborts if live, esc leaves for the sessions list) · else `PromptBlock` (textarea + history), kept mounted (`Display.None` when hidden) so draft/cursor/attachments survive an approval round-trip.
 
 When the queue has entries, a `QueuedMessagesBlock` renders between transcript and prompt:
 
@@ -140,7 +140,7 @@ Every action routes through `<userDir>/keybindings.json`, matched via `matchesBi
 | `ctrl+shift+m` | `openMainSession` | any, when `Settings.orchestration` is on | jump to (or lazily create) the pinned Main orchestration session for the cwd; requires the daemon runtime. Silent no-op when the setting/runtime is off |
 | `ctrl+p` | `openUsagePanel` | chat | subscription usage panel; also opens by clicking the footer's `▰ 5h 43%` segment |
 | `ctrl+y` | `openKeybindings` | non-auth | keybindings panel, `↵` opens `keybindings.json` |
-| `ctrl+k` | `cancelToolCall` | chat (busy, ≥1 in-flight call) | cancel-tool picker (`agent.cancelTool(callId)`); distinct from `esc` (whole-run abort) |
+| `ctrl+k` | `cancelToolCall` | chat (busy, ≥1 in-flight call) | cancel-tool picker (`agent.cancelTool(callId)`); distinct from `ctrl+esc` (whole-run abort) |
 | `ctrl+h` | `changeCwd` | non-auth | open the directory picker to change cwd |
 | `ctrl+v` | `attachClipboardImage` | textarea | paste text or an image from the OS clipboard, read by the process itself (bypasses a frozen terminal paste path) |
 | `ctrl+g` | `openExternalEditor` | textarea | edit the prompt draft in `$EDITOR`/`$VISUAL`; gated on `externalEditor` setting |
@@ -151,7 +151,8 @@ Every action routes through `<userDir>/keybindings.json`, matched via `matchesBi
 | — (unbound) | `enterQueueSelection` | textarea | move focus into the queue box |
 | `enter` / `shift+enter` | — | textarea | submit / newline |
 | `↑`/`↓` at buffer edges | — | textarea (popup closed) | cycle prompt history |
-| `esc` | — | popup / run in flight / modal open | dismiss popup, or abort run + drain approval+interaction queues, or close modal |
+| `ctrl+esc` | `abortRun` | chat (busy or pending approval) | abort run + drain approval+interaction queues. Rebind (e.g. `ctrl+x`) if the terminal cannot report ctrl on esc |
+| `esc` | — | popup / chat / modal open | dismiss popup, or leave the chat for the sessions list (busy or not — the run continues), or close modal |
 | `pageup`/`pagedown`, `shift+pageup`/`shift+pagedown` | — | chat, no modal | scroll transcript one page / jump to top-bottom |
 | `ctrl+a` | (textarea built-in) | textarea | select-all |
 
@@ -176,7 +177,7 @@ Every action routes through `<userDir>/keybindings.json`, matched via `matchesBi
 
 `<userDir>/keybindings.json` is JSONC. `ensureKeybindingsFile` never overwrites an existing file. Invalid/unknown entries silently fall back to defaults (`ZIDANE_DEBUG` logs why). Settings → General → "Keybindings" opens the file in `$EDITOR`/`$VISUAL`; changes apply on restart. Full alias/parsing rules: [CHAT.md § Keybindings](./CHAT.md#keybindings).
 
-**Esc semantics.** While busy, `esc` runs `denyAll → interactions.cancelAll → abort → stream.reset → agent.destroy` (shared with session-switching/re-auth teardown). `applyGate` does **not** cascade a single deny through the rest of the queue: denying one approval blocks only that call (`Blocked: …`), other pending approvals stay queued. The global `esc abort` is the only path that denies everything + aborts the run. Esc is consumed by the completion popup first when one is open.
+**Abort semantics.** `abortRun` (`ctrl+esc`) runs `denyAll → interactions.cancelAll → abort → stream.reset → agent.destroy` (shared with session-switching/re-auth teardown). `applyGate` does **not** cascade a single deny through the rest of the queue: denying one approval blocks only that call (`Blocked: …`), other pending approvals stay queued. The global `abortRun` is the only path that denies everything + aborts the run. Plain `esc` never aborts: under the daemon a window can reattach to a session mid-run, and esc must always be able to return to the sessions list. Local runtime only: picking another session (or new) while a run is in flight is refused with a notice under the list — the window's single agent would otherwise be torn down by `activateSession`; abort first, or run under the daemon where runs outlive the window's session choice. Esc is consumed by the completion popup first when one is open.
 
 ## Modals
 
@@ -199,7 +200,7 @@ Inline-mounted in `ChatScreen`'s transcript slot (not stacked); keyed on `reques
 
 ### Tool-call cancellation
 
-`CancelToolModal` lists the in-flight tool registry (`App.tsx` tracks it via `tool:before`/`tool:after`/`tool:error`/`tool:cancelled`, mirrored for `child:*`), opened by `ctrl+k` when `busy && !pendingApproval && inFlightTools.length > 0`. Row: `›` cursor, tool name, truncated `callId`, optional `· child-N`, elapsed time. `↑`/`↓` navigate, `↵` cancels the focused row, `a` cancels every call, `esc` dismisses. Auto-dismisses 500ms after the in-flight list empties. Cancellation resolves that call with `TOOL_USE_CANCELLED_MESSAGE` (`isError: true`); other in-flight tools keep running — distinct from the run-wide `esc abort`.
+`CancelToolModal` lists the in-flight tool registry (`App.tsx` tracks it via `tool:before`/`tool:after`/`tool:error`/`tool:cancelled`, mirrored for `child:*`), opened by `ctrl+k` when `busy && !pendingApproval && inFlightTools.length > 0`. Row: `›` cursor, tool name, truncated `callId`, optional `· child-N`, elapsed time. `↑`/`↓` navigate, `↵` cancels the focused row, `a` cancels every call, `esc` dismisses. Auto-dismisses 500ms after the in-flight list empties. Cancellation resolves that call with `TOOL_USE_CANCELLED_MESSAGE` (`isError: true`); other in-flight tools keep running — distinct from the run-wide `ctrl+esc` abort.
 
 ### TodosModal
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "7.0.31",
+  "version": "7.1.1",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,