zidane 4.1.4 → 4.1.6

package/dist/tui.js

@@ -1,12 +1,15 @@
-import { d as createAgent } from "./tools-DpeWKzP1.js";
+import { d as createAgent } from "./tools-C8kDot0H.js";
 import { n as toolResultToText } from "./types-Bx_F8jet.js";
-import { r as basic_default } from "./presets-Cs7_CsMk.js";
-import { i as anthropic, n as openai, r as cerebras, t as openrouter } from "./providers-CX-R-Oy-.js";
+import { n as formatTokenUsage } from "./stats-BT9l57RS.js";
+import { r as basic_default } from "./presets-BzkJDW1K.js";
+import { i as anthropic, n as openai, r as cerebras, t as openrouter } from "./providers-CCDvIXGJ.js";
 import { n as loadSession, t as createSession } from "./session-Cn68UASv.js";
 import { createSqliteStore } from "./session/sqlite.js";
+import { spawn } from "node:child_process";
 import { dirname, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { anthropicOAuthProvider, openaiCodexOAuthProvider } from "@mariozechner/pi-ai/oauth";
 import { getModel, getModels } from "@mariozechner/pi-ai";
 import { RGBA, SyntaxStyle, createCliRenderer, defaultTextareaKeyBindings } from "@opentui/core";
 import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
@@ -115,6 +118,27 @@ const MD_STYLE = SyntaxStyle.fromStyles({
 });
 //#endregion
 //#region src/tui/components.tsx
+init().catch(() => {});
+/**
+* Heal incomplete streaming markdown, surviving any md4x failure.
+*
+* `md4x/wasm` can throw "WASM not initialized" in two cases we've seen:
+*   1. A host mounted `<App>` directly without calling `runTui()`/`init()`.
+*   2. A `bun build --compile` binary where the inlined `md4x.wasm` default
+*      export resolved to `undefined` — `init()` silently calls
+*      `_setInstance(undefined)` and every subsequent `heal()` throws.
+*
+* In both cases we'd rather render the raw streaming text (OpenTUI's
+* `<markdown streaming>` tolerates unclosed delimiters) than crash the
+* transcript.
+*/
+function safeHeal(text) {
+	try {
+		return heal(text);
+	} catch {
+		return text;
+	}
+}
 /**
 * Memoized so a flush that mutates only the trailing event doesn't force the
 * entire transcript to re-render. Each event holds a stable reference until
@@ -123,9 +147,17 @@ const MD_STYLE = SyntaxStyle.fromStyles({
 * The outer wrapper handles top-margin per kind (and per neighbor) so spacing
 * is the single source of truth for inter-event breathing room.
 */
-const EventLine = memo(({ event, previous }) => /* @__PURE__ */ jsx("box", {
-	style: { marginTop: marginTopFor(event, previous) },
-	children: /* @__PURE__ */ jsx(EventLineImpl, { event })
+const EventLine = memo(({ event, previous, depthOffset = 0 }) => /* @__PURE__ */ jsx("box", {
+	style: {
+		marginTop: marginTopFor(event, previous),
+		alignSelf: "stretch",
+		flexShrink: 0,
+		flexDirection: "column"
+	},
+	children: /* @__PURE__ */ jsx(EventLineImpl, {
+		event,
+		depthOffset
+	})
 }));
 /**
 * `@opentui/react` extends `React.JSX.IntrinsicElements`, so `onSubmit` on `<input>`
@@ -254,8 +286,8 @@ function Spinner({ label }) {
 	});
 }
 function Transcript({ events, settings }) {
-	const visible = events.filter((e) => isVisible(e, settings));
-	if (visible.length === 0) return /* @__PURE__ */ jsx(EmptyState$1, {});
+	const items = useMemo(() => partitionTranscript(events, settings), [events, settings]);
+	if (items.length === 0) return /* @__PURE__ */ jsx(EmptyState$1, {});
 	return /* @__PURE__ */ jsx("scrollbox", {
 		focusable: false,
 		style: {
@@ -265,13 +297,33 @@ function Transcript({ events, settings }) {
 		},
 		stickyScroll: true,
 		stickyStart: "bottom",
-		children: visible.map((evt, i) => /* @__PURE__ */ jsx(EventLine, {
-			event: evt,
-			previous: visible[i - 1]
+		children: items.map((item, i) => item.kind === "event" ? /* @__PURE__ */ jsx(EventLine, {
+			event: item.event,
+			previous: item.previous
+		}, i) : /* @__PURE__ */ jsx(SubagentBlock, {
+			events: item.events,
+			previous: item.previous
 		}, i))
 	});
 }
+/**
+* Per-event visibility — filters honor user toggles and the
+* `hideSubagentOutput` setting. When subagent output is hidden:
+*   - Child-agent events are filtered down to the `spawn-start` /
+*     `spawn-end` markers so the user still sees "🌱 working… 🌳 done".
+*   - The parent's `tool-result` for `spawn` is hidden too. Its body
+*     duplicates `spawn-end`'s stats line *and* the parent's next markdown
+*     turn ("Here's what the sub-agent found: …"). Showing it again
+*     produced an extra `┃ [sub-agent child-1] Completed …` block that
+*     the user just wanted gone.
+*
+* Exported so the visibility matrix can be unit-tested without rendering.
+*/
 function isVisible(event, settings) {
+	if (settings.hideSubagentOutput) {
+		if (isChild(event)) return event.kind === "spawn-start" || event.kind === "spawn-end";
+		if (event.kind === "tool-result" && event.tool === "spawn") return false;
+	}
 	switch (event.kind) {
 		case "thinking": return settings.showThinking;
 		case "tool": return settings.showToolCalls;
@@ -279,6 +331,91 @@ function isVisible(event, settings) {
 		default: return true;
 	}
 }
+/**
+* Walk the visible-event list once and group consecutive child events
+* (`depth > 0`) into runs so we can wrap each run in a single bordered
+* subagent box.
+*
+* When `hideSubagentOutput` is on, `isVisible` already filters most child
+* events out; the surviving `spawn-start` / `spawn-end` markers render as
+* plain entries (no boxing) — there's nothing meaningful to box.
+*/
+function partitionTranscript(events, settings) {
+	const visible = events.filter((e) => isVisible(e, settings));
+	if (visible.length === 0) return [];
+	if (settings.hideSubagentOutput) return visible.map((event, i) => ({
+		kind: "event",
+		event,
+		previous: visible[i - 1]
+	}));
+	const items = [];
+	let run = [];
+	let runPrevious;
+	const flush = () => {
+		if (run.length > 0) {
+			items.push({
+				kind: "child-run",
+				events: run,
+				previous: runPrevious
+			});
+			run = [];
+			runPrevious = void 0;
+		}
+	};
+	for (let i = 0; i < visible.length; i++) {
+		const event = visible[i];
+		if (isChild(event)) {
+			if (run.length === 0) runPrevious = visible[i - 1];
+			run.push(event);
+		} else {
+			flush();
+			items.push({
+				kind: "event",
+				event,
+				previous: visible[i - 1]
+			});
+		}
+	}
+	flush();
+	return items;
+}
+/**
+* Bordered container for one run of subagent events. The box's border +
+* left padding give the visual "this is a subagent" affordance, so events
+* inside render with `depthOffset: 1` — a direct child of the parent
+* (depth 1) sits flush against the box's inner padding rather than being
+* indented twice. Grandchildren (depth ≥ 2) still indent further, so
+* nested subagents remain visually distinct.
+*/
+function SubagentBlock({ events, previous }) {
+	const childIds = useMemo(() => {
+		const set = /* @__PURE__ */ new Set();
+		for (const e of events) if (e.childId) set.add(e.childId);
+		return Array.from(set);
+	}, [events]);
+	const title = childIds.length === 0 ? " subagent " : childIds.length === 1 ? ` ${childIds[0]} ` : ` subagents · ${childIds.join(", ")} `;
+	const marginTop = previous ? 1 : 0;
+	return /* @__PURE__ */ jsx("box", {
+		title,
+		style: {
+			border: true,
+			borderColor: COLOR.mute,
+			paddingLeft: 1,
+			paddingRight: 1,
+			paddingTop: 0,
+			paddingBottom: 0,
+			marginTop,
+			flexDirection: "column",
+			flexShrink: 0,
+			alignSelf: "stretch"
+		},
+		children: events.map((evt, i) => /* @__PURE__ */ jsx(EventLine, {
+			event: evt,
+			previous: events[i - 1],
+			depthOffset: 1
+		}, i))
+	});
+}
 function EmptyState$1() {
 	return /* @__PURE__ */ jsx("box", {
 		style: {
@@ -301,6 +438,23 @@ function isChild(event) {
 	return (event.depth ?? 0) > 0;
 }
 /**
+* Shared row geometry for every transcript event.
+*
+* `alignSelf: 'stretch'` + `flexShrink: 0` together pin each row to the
+* scrollbox's content width and prevent flex re-negotiation when neighboring
+* rows grow or shrink (streaming markdown, late-arriving tool results, etc.).
+* Without this, Yoga is free to re-compute widths every render and the
+* visible text appears to "wiggle" between columns as the stream advances.
+*/
+function rowStyle(paddingLeft) {
+	return {
+		paddingLeft,
+		flexDirection: "column",
+		flexShrink: 0,
+		alignSelf: "stretch"
+	};
+}
+/**
 * Default top-margin per kind. Spacing intent:
 *   - `info` / `markdown` / `tool` / `error` / `spawn-start` open a new block
 *     so they each get one row of breathing room above.
@@ -325,33 +479,44 @@ const TOOL_KINDS = new Set(["tool", "tool-result"]);
 /**
 * Resolve the top margin for an event given the one rendered just before it.
 *
-* The only context-aware rule today: a tool/tool-result event that follows
-* another tool/tool-result event collapses its margin to zero, so a chain of
-* tool calls reads as a tight list — whether the user has hidden tool outputs
-* or not, and whether the agent emits back-to-back calls or call→result pairs.
+* Context-aware rules:
+*
+*   - A `tool` / `tool-result` event right after another `tool` / `tool-result`
+*     collapses to a tight list — call→result pairs and back-to-back calls
+*     read as one logical block.
+*   - A parent-level event (`depth === 0`) right after a subagent event
+*     (`depth > 0`) collapses too. The subagent's `🌳` end marker (and, in
+*     show mode, the subagent box's bottom border) already provides the
+*     separation; adding the event's default `marginTop` on top would
+*     produce the visible "line jump" between a subagent's outcome and the
+*     parent's follow-up. Either form of marker is enough — we don't want
+*     both.
 *
 * Exported so the spacing matrix can be unit-tested without rendering.
 */
 function marginTopFor(event, previous) {
 	if (TOOL_KINDS.has(event.kind) && previous && TOOL_KINDS.has(previous.kind)) return 0;
+	const eventDepth = event.depth ?? 0;
+	const previousDepth = previous?.depth ?? 0;
+	if (eventDepth === 0 && previousDepth > 0) return 0;
 	return MARGIN_TOP[event.kind] ?? 0;
 }
-function EventLineImpl({ event }) {
+function EventLineImpl({ event, depthOffset = 0 }) {
 	const safeText = event.text === "" ? " " : event.text;
-	const paddingLeft = indentFor(event.depth);
+	const row = rowStyle(indentFor(Math.max(0, (event.depth ?? 0) - depthOffset)));
 	const child = isChild(event);
 	switch (event.kind) {
 		case "separator": return /* @__PURE__ */ jsx("text", { children: " " });
 		case "info": return /* @__PURE__ */ jsx(UserPromptBlock, { text: safeText });
 		case "thinking": return /* @__PURE__ */ jsx("box", {
-			style: { paddingLeft },
+			style: row,
 			children: /* @__PURE__ */ jsx("text", {
 				fg: COLOR.dim,
 				children: safeText
 			})
 		});
 		case "tool": return /* @__PURE__ */ jsx("box", {
-			style: { paddingLeft },
+			style: row,
 			children: /* @__PURE__ */ jsxs("text", {
 				fg: child ? COLOR.dim : COLOR.model,
 				children: [/* @__PURE__ */ jsx("span", {
@@ -362,10 +527,10 @@ function EventLineImpl({ event }) {
 		});
 		case "tool-result": return /* @__PURE__ */ jsx(ToolResultBlock, {
 			text: event.text,
-			indent: paddingLeft
+			indent: row.paddingLeft
 		});
 		case "error": return /* @__PURE__ */ jsx("box", {
-			style: { paddingLeft },
+			style: row,
 			children: /* @__PURE__ */ jsxs("text", {
 				fg: COLOR.error,
 				children: [/* @__PURE__ */ jsx("span", {
@@ -375,7 +540,7 @@ function EventLineImpl({ event }) {
 			})
 		});
 		case "markdown": return /* @__PURE__ */ jsx("box", {
-			style: { paddingLeft },
+			style: row,
 			children: /* @__PURE__ */ jsx(MarkdownBlock, {
 				text: event.text,
 				streaming: event.streaming ?? false,
@@ -383,7 +548,7 @@ function EventLineImpl({ event }) {
 			})
 		});
 		case "spawn-start": return /* @__PURE__ */ jsx("box", {
-			style: { paddingLeft },
+			style: row,
 			children: /* @__PURE__ */ jsxs("text", {
 				fg: COLOR.dim,
 				children: [
@@ -403,13 +568,13 @@ function EventLineImpl({ event }) {
 			})
 		});
 		case "spawn-end": return /* @__PURE__ */ jsx("box", {
-			style: { paddingLeft },
+			style: row,
 			children: /* @__PURE__ */ jsxs("text", {
 				fg: COLOR.dim,
 				children: [
 					/* @__PURE__ */ jsx("span", {
 						fg: COLOR.accent,
-						children: "✓ "
+						children: "🌳 "
 					}),
 					/* @__PURE__ */ jsx("span", {
 						fg: COLOR.dim,
@@ -445,13 +610,27 @@ function UserPromptBlock({ text }) {
 * `md4x.heal()` so unclosed delimiters (bold, italic, code, link, table) render
 * as if already complete. OpenTUI's `streaming` prop keeps its parser from
 * committing to the final layout for the trailing block.
+*
+* `internalBlockMode: "top-level"` is the load-bearing knob for streaming
+* stability: in the default `"coalesced"` mode, OpenTUI fuses adjacent
+* top-level markdown blocks into one render block, so when a token streams
+* in the *entire* coalesced block re-flows and earlier paragraphs visibly
+* jump. With `"top-level"`, each top-level block (paragraph, heading, list,
+* code fence) is its own render block — they finalize as soon as the parser
+* moves past them, leaving only the trailing block reflowable.
+*
+* `alignSelf: 'stretch'` pins the markdown to the parent box's content
+* width so its wrap column doesn't drift between renders.
 */
 function MarkdownBlock({ text, streaming, dim }) {
 	return /* @__PURE__ */ jsx("markdown", {
-		content: useMemo(() => streaming ? heal(text) : text, [text, streaming]),
+		content: useMemo(() => streaming ? safeHeal(text) : text, [text, streaming]),
 		syntaxStyle: MD_STYLE,
 		streaming,
-		fg: dim ? COLOR.dim : void 0
+		internalBlockMode: "top-level",
+		fg: dim ? COLOR.dim : void 0,
+		alignSelf: "stretch",
+		flexShrink: 0
 	});
 }
 const TOOL_RESULT_MAX_LINES = 6;
@@ -480,107 +659,281 @@ function ToolResultBlock({ text, indent }) {
 	});
 }
 //#endregion
-//#region src/tui/auth.ts
-const ENV_KEYS = {
-	anthropic: "ANTHROPIC_API_KEY",
-	openai: "OPENAI_CODEX_API_KEY",
-	openrouter: "OPENROUTER_API_KEY",
-	cerebras: "CEREBRAS_API_KEY"
+//#region src/tui/providers.ts
+/** Convenience accessor — returns `credentialFileKey ?? key`. */
+function credKeyOf(desc) {
+	return desc.credentialFileKey ?? desc.key;
+}
+/** Convenience accessor — returns `piProviderId ?? key`. */
+function piIdOf(desc) {
+	return desc.piProviderId ?? desc.key;
+}
+const anthropicDescriptor = {
+	key: "anthropic",
+	label: "Anthropic",
+	factory: anthropic,
+	defaultModel: "claude-opus-4-7",
+	envKey: "ANTHROPIC_API_KEY",
+	apiKeyPlaceholder: "sk-ant-…",
+	oauthProvider: anthropicOAuthProvider,
+	oauthHint: "Claude Pro/Max subscription"
+};
+const openaiDescriptor = {
+	key: "openai",
+	label: "OpenAI Codex",
+	factory: openai,
+	defaultModel: "gpt-5.4",
+	envKey: "OPENAI_CODEX_API_KEY",
+	credentialFileKey: "openai-codex",
+	piProviderId: "openai-codex",
+	apiKeyPlaceholder: "sk-… or eyJ… (Codex)",
+	oauthProvider: openaiCodexOAuthProvider
+};
+const openrouterDescriptor = {
+	key: "openrouter",
+	label: "OpenRouter",
+	factory: openrouter,
+	defaultModel: "anthropic/claude-sonnet-4-6",
+	envKey: "OPENROUTER_API_KEY",
+	apiKeyPlaceholder: "sk-or-…"
 };
-/** Maps a provider to the credentials.json key written by `bun run auth`. */
-const OAUTH_KEYS = {
-	anthropic: "anthropic",
-	openai: "openai-codex"
+const cerebrasDescriptor = {
+	key: "cerebras",
+	label: "Cerebras",
+	factory: cerebras,
+	defaultModel: "zai-glm-4.7",
+	envKey: "CEREBRAS_API_KEY",
+	apiKeyPlaceholder: "csk-…"
 };
-const LABELS = {
-	anthropic: "Anthropic",
-	openai: "OpenAI Codex",
-	openrouter: "OpenRouter",
-	cerebras: "Cerebras"
+/**
+* Default provider registry. Passed verbatim when `runTui` is invoked without
+* an explicit `providers` option. Hosts that want to override per-provider
+* metadata can spread this and replace specific entries:
+*
+* ```ts
+* runTui({ providers: { ...BUILTIN_PROVIDERS, anthropic: myOwnAnthropicDescriptor } })
+* ```
+*/
+const BUILTIN_PROVIDERS = {
+	anthropic: anthropicDescriptor,
+	openai: openaiDescriptor,
+	openrouter: openrouterDescriptor,
+	cerebras: cerebrasDescriptor
 };
-function envKeyFor(key) {
-	return ENV_KEYS[key];
+/**
+* Resolve the model list for a given provider. Honors `descriptor.models`
+* when set; otherwise queries pi-ai via `descriptor.piProviderId`. Returns
+* `[]` for descriptors with no known mapping (custom providers without a
+* model list) — callers should hide the model picker in that case.
+*/
+function modelsForDescriptor(descriptor) {
+	if (descriptor.models) return descriptor.models;
+	try {
+		return getModels(piIdOf(descriptor));
+	} catch {
+		return [];
+	}
+}
+/**
+* Look up the model's max context window via the descriptor's model source.
+* Returns `null` when the model isn't known (custom slugs, providers without
+* a registry); callers should hide the context indicator in that case.
+*/
+function getContextWindow(descriptor, modelId) {
+	if (descriptor.models) return descriptor.models.find((m) => m.id === modelId)?.contextWindow ?? null;
+	try {
+		return getModel(piIdOf(descriptor), modelId)?.contextWindow ?? null;
+	} catch {
+		return null;
+	}
 }
+//#endregion
+//#region src/tui/credentials.ts
+/** POSIX mode for the credentials file. Ignored on Windows. */
+const FILE_MODE = 384;
 /**
-* Detect available auth across the providers the harness ships with.
+* Resolve the credentials file path given the resolved TUI data directory
+* (typically `~/.zidane`, i.e. `config.paths.dir`).
 *
-* Mirrors the resolution order used by the providers at runtime:
-*   - explicit env var (highest)
-*   - OAuth credentials in `.credentials.json` (anthropic + openai-codex only)
+* Matches the convention used elsewhere in the TUI (sessions.db, state.json)
+* so a single `ZIDANE_STORAGE_DIR` override moves the entire data root.
+*/
+function credentialsPath(dataDir) {
+	return resolve(dataDir, "credentials.json");
+}
+/**
+* Read credentials from disk.
 *
-* Pure read — never refreshes or rewrites the credentials file.
+* Returns `{}` when the file is missing or corrupt (last-ditch tolerance —
+* a hand-edit gone wrong shouldn't lock the user out of re-authing). On first
+* call with no file present, attempts a migration from `cwd/.credentials.json`
+* (the legacy location used by `bun run auth`).
 */
-function detectAuth(env = process.env) {
-	const credsPath = resolve(process.cwd(), ".credentials.json");
-	let creds = {};
-	if (existsSync(credsPath)) try {
-		const parsed = JSON.parse(readFileSync(credsPath, "utf-8"));
-		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) creds = parsed;
-	} catch {}
-	return Object.keys(LABELS).map((key) => {
-		const methods = [];
-		const envKey = ENV_KEYS[key];
-		if (env[envKey]) methods.push({
-			source: "env",
-			detail: envKey
-		});
-		const oauthKey = OAUTH_KEYS[key];
-		if (oauthKey) {
-			const entry = creds[oauthKey];
-			if (entry?.access && entry.refresh) {
-				const detail = entry.expires ? `oauth · expires ${new Date(entry.expires).toLocaleString()}` : "oauth · .credentials.json";
-				methods.push({
-					source: "oauth",
-					detail
-				});
-			}
-		}
-		return {
-			key,
-			label: LABELS[key],
-			available: methods.length > 0,
-			methods
-		};
-	});
+function readCredentials(dataDir) {
+	const path = credentialsPath(dataDir);
+	if (!existsSync(path)) {
+		const migrated = migrateLegacyFile(path);
+		if (migrated) return migrated;
+		return {};
+	}
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+/** Read a single provider's credential (translating via the descriptor). */
+function readProviderCredential(dataDir, descriptor) {
+	return readCredentials(dataDir)[credKeyOf(descriptor)];
 }
-//#endregion
-//#region src/tui/providers.ts
 /**
-* Construct a fresh provider instance for a given key.
+* Write credentials atomically (write-then-rename) with mode 0o600.
 *
-* Providers are cheap to build — credentials are resolved lazily at first
-* stream call — so we instantiate on demand rather than caching a singleton.
-* This also avoids leaking state across session/provider switches.
+* Atomic on the same filesystem — readers either see the previous file or the
+* new one, never a half-written intermediate. Creates the parent dir if needed
+* (first launch on a fresh machine: `~/.zidane/` may not exist yet).
 */
-const FACTORIES = {
-	anthropic,
-	openai,
-	openrouter,
-	cerebras
-};
-/** zidane provider key → pi-ai provider id (some don't match 1:1). */
-const PI_PROVIDER_ID = {
-	anthropic: "anthropic",
-	openai: "openai-codex",
-	openrouter: "openrouter",
-	cerebras: "cerebras"
-};
+function writeCredentials(dataDir, creds) {
+	const path = credentialsPath(dataDir);
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(creds, null, 2)}\n`, { mode: FILE_MODE });
+	renameSync(tmp, path);
+}
+function setProviderCredential(dataDir, descriptor, cred) {
+	const all = readCredentials(dataDir);
+	all[credKeyOf(descriptor)] = cred;
+	writeCredentials(dataDir, all);
+}
+function removeProviderCredential(dataDir, descriptor) {
+	const all = readCredentials(dataDir);
+	const fileKey = credKeyOf(descriptor);
+	if (!(fileKey in all)) return;
+	delete all[fileKey];
+	writeCredentials(dataDir, all);
+}
 /**
-* Look up the model's max context window via pi-ai's model registry.
-* Returns `null` when the model isn't known (e.g. a custom openrouter slug);
-* callers should hide the context indicator in that case.
+* Inject API-key credentials into `process.env` so the harness providers pick
+* them up via their existing env-var resolution. Called once at TUI launch
+* after the credentials file has been resolved. OAuth credentials are NOT
+* injected — those reach providers via `ZIDANE_CREDENTIALS_PATH` + the file
+* reader in `src/providers/oauth.ts`.
+*
+* Does not overwrite env vars that are already set — explicit user-provided
+* env values win over stored API keys.
+*
+* Descriptors without an `envKey` (OAuth-only providers, custom providers
+* that bypass env-var resolution) are skipped silently.
 */
-function getContextWindow(key, modelId) {
+function applyApiKeyEnv(dataDir, registry) {
+	const creds = readCredentials(dataDir);
+	for (const descriptor of Object.values(registry)) {
+		if (!descriptor.envKey || process.env[descriptor.envKey]) continue;
+		const cred = creds[credKeyOf(descriptor)];
+		if (cred?.kind === "apikey" && cred.value) process.env[descriptor.envKey] = cred.value;
+	}
+}
+/**
+* `bun run auth` (pre-TUI) wrote `cwd/.credentials.json` with an entry per
+* provider mapping directly to an OAuthCredentials payload, e.g.:
+*
+*   {
+*     "anthropic":    { "access": "...", "refresh": "...", "expires": 123 },
+*     "openai-codex": { "access": "...", "refresh": "...", "expires": 123, "accountId": "..." }
+*   }
+*
+* We don't delete the legacy file — it might still be used by a host that
+* imports the harness directly. We just copy its contents into the new
+* location under the kind-tagged shape so the TUI picks them up.
+*
+* Migration is provider-agnostic: any top-level entry with an `access` field
+* is preserved verbatim (extras included), under the same key. The TUI's
+* detection then looks them up via the matching descriptor's `credentialFileKey`.
+*
+* Returns the migrated credentials when the migration ran, or `null` when
+* there's no legacy file to migrate.
+*/
+function migrateLegacyFile(targetPath) {
+	const legacyPath = resolve(process.cwd(), ".credentials.json");
+	if (!existsSync(legacyPath)) return null;
+	let legacy;
 	try {
-		const providerId = PI_PROVIDER_ID[key];
-		return getModel(providerId, modelId)?.contextWindow ?? null;
+		legacy = JSON.parse(readFileSync(legacyPath, "utf-8"));
 	} catch {
 		return null;
 	}
+	if (!legacy || typeof legacy !== "object" || Array.isArray(legacy)) return null;
+	const migrated = {};
+	for (const [fileKey, value] of Object.entries(legacy)) {
+		if (!isOAuthLegacy(value)) continue;
+		const { access, refresh, expires, ...extras } = value;
+		migrated[fileKey] = {
+			kind: "oauth",
+			access,
+			...typeof refresh === "string" ? { refresh } : {},
+			...typeof expires === "number" ? { expires } : {},
+			...extras
+		};
+	}
+	if (Object.keys(migrated).length === 0) return null;
+	mkdirSync(dirname(targetPath), { recursive: true });
+	const tmp = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(migrated, null, 2)}\n`, { mode: FILE_MODE });
+	renameSync(tmp, targetPath);
+	return migrated;
+}
+function isOAuthLegacy(value) {
+	return typeof value === "object" && value !== null && "access" in value && typeof value.access === "string";
+}
+//#endregion
+//#region src/tui/auth.ts
+/**
+* Detect available auth for every registered provider.
+*
+* Resolution order per provider (a method appears in `methods` for each
+* layer that has a credential — the agent itself resolves them in the same
+* order via its provider factories):
+*
+*   1. `kind: 'apikey'` from `credentials.json` (injected into env at TUI launch)
+*   2. explicit env var (descriptor's `envKey`)
+*   3. `kind: 'oauth'` from `credentials.json` (or legacy `cwd/.credentials.json`)
+*
+* Pure read — never refreshes or rewrites the credentials file.
+*/
+function detectAuth(dataDir, registry, env = process.env) {
+	const creds = readCredentials(dataDir);
+	return Object.values(registry).map((descriptor) => {
+		const methods = [];
+		const fileEntry = creds[credKeyOf(descriptor)];
+		if (fileEntry?.kind === "apikey" && fileEntry.value) methods.push({
+			source: "apikey",
+			detail: "credentials.json"
+		});
+		if (descriptor.envKey && env[descriptor.envKey]) methods.push({
+			source: "env",
+			detail: descriptor.envKey
+		});
+		if (fileEntry?.kind === "oauth" && fileEntry.access) {
+			const detail = typeof fileEntry.expires === "number" ? `oauth · expires ${new Date(fileEntry.expires).toLocaleString()}` : "oauth · credentials.json";
+			methods.push({
+				source: "oauth",
+				detail
+			});
+		}
+		return {
+			key: descriptor.key,
+			label: descriptor.label,
+			available: methods.length > 0,
+			methods
+		};
+	});
 }
 //#endregion
 //#region src/tui/store.ts
-function ensureDir(path) {
+function ensureDir$1(path) {
 	const dir = dirname(path);
 	if (existsSync(dir)) return;
 	try {
@@ -591,7 +944,7 @@ function ensureDir(path) {
 	}
 }
 function createTuiStore(dbPath) {
-	ensureDir(dbPath);
+	ensureDir$1(dbPath);
 	return createSqliteStore({ path: dbPath });
 }
 function createStateStore(path) {
@@ -609,7 +962,7 @@ function loadState(path) {
 	return {};
 }
 function saveState(path, state) {
-	ensureDir(path);
+	ensureDir$1(path);
 	const tmp = `${path}.${process.pid}.tmp`;
 	writeFileSync(tmp, JSON.stringify(state, null, 2));
 	renameSync(tmp, path);
@@ -643,43 +996,122 @@ function titleFromTurns(turns) {
 	return null;
 }
 /**
-* Replay persisted turns as a viewable transcript. Mirrors the event shape produced
-* live by the agent hooks so loaded and streaming history render identically.
+* Replay persisted turns as a viewable transcript. Mirrors the event shape
+* produced live by the agent hooks so loaded and streaming history render
+* identically — including subagent ancestry when `runs` is supplied.
+*
+* Subagent reconstruction:
+*   - Every turn carries a `runId`. We look that up in `runs` to get the
+*     run's `depth` and tag the resulting events with `{ depth, childId }`
+*     — the same shape the live `child:*` bubble hooks produce.
+*   - We synthesize `spawn-start` / `spawn-end` markers at each child-run
+*     boundary so the transcript reads the same as a live run did
+*     (`🌱 [run-id] task` … child events … `🌳 [run-id] done · tokens`).
+*   - For child runs (`depth > 0`), the user-role "task" text is suppressed
+*     because `spawn-start` already shows it.
 *
-* Skips `tool_result` blocks (they're not user-visible by default), and inserts a
-* `separator` event between turn groups so the eye can parse turn boundaries.
+* Without `runs` (legacy callers / tests), the function falls back to the
+* old behavior: depth-0 events with no subagent grouping.
 */
-function eventsFromTurns(turns) {
+function eventsFromTurns(turns, runs = []) {
+	const runById = /* @__PURE__ */ new Map();
+	for (const run of runs) runById.set(run.id, run);
+	const childLabelByRunId = /* @__PURE__ */ new Map();
+	runs.filter((r) => (r.depth ?? 0) > 0).slice().sort((a, b) => a.startedAt - b.startedAt).forEach((r, i) => childLabelByRunId.set(r.id, `child-${i + 1}`));
+	const labelFor = (runId) => childLabelByRunId.get(runId) ?? runId;
+	const toolByCallId = /* @__PURE__ */ new Map();
+	for (const turn of turns) {
+		if (turn.role !== "assistant") continue;
+		for (const block of turn.content) if (block.type === "tool_call") toolByCallId.set(block.id, block.name);
+	}
 	const events = [];
+	let lastRunId;
+	let lastDepth = 0;
+	const closeRun = (runId, depth) => {
+		if (!runId || depth <= 0) return;
+		const run = runById.get(runId);
+		if (!run) return;
+		const tag = run.status === "aborted" || run.status === "error" ? run.status : "done";
+		const usage = formatTokenUsage({
+			totalIn: run.tokensIn ?? run.totalUsage?.input ?? 0,
+			totalOut: run.tokensOut ?? run.totalUsage?.output ?? 0,
+			totalCacheRead: run.totalUsage?.cacheRead ?? 0,
+			totalCacheCreation: run.totalUsage?.cacheCreation ?? 0
+		});
+		events.push({
+			kind: "spawn-end",
+			text: `${tag} ${usage}`,
+			childId: labelFor(runId),
+			depth
+		});
+	};
+	const openRun = (runId, depth) => {
+		if (depth <= 0) return;
+		const run = runById.get(runId);
+		if (!run) return;
+		const taskPreview = run.prompt.length > 80 ? `${run.prompt.slice(0, 80)}…` : run.prompt;
+		events.push({
+			kind: "spawn-start",
+			text: taskPreview,
+			childId: labelFor(runId),
+			depth
+		});
+	};
 	for (let i = 0; i < turns.length; i++) {
 		const turn = turns[i];
-		if (i > 0) events.push({
+		const depth = (turn.runId ? runById.get(turn.runId) : void 0)?.depth ?? 0;
+		const tag = depth > 0 && turn.runId ? {
+			childId: labelFor(turn.runId),
+			depth
+		} : void 0;
+		if (turn.runId !== lastRunId) {
+			closeRun(lastRunId, lastDepth);
+			if (depth === 0 && lastDepth === 0 && i > 0) events.push({
+				kind: "separator",
+				text: ""
+			});
+			if (turn.runId) openRun(turn.runId, depth);
+			lastRunId = turn.runId;
+			lastDepth = depth;
+		} else if (i > 0 && depth === 0) events.push({
 			kind: "separator",
 			text: ""
 		});
 		if (turn.role === "user") {
-			for (const block of turn.content) if (block.type === "text" && block.text.trim()) events.push({
-				kind: "info",
-				text: `❯ ${block.text}`
-			});
-			else if (block.type === "tool_result") events.push({
-				kind: "tool-result",
-				text: toolResultText(block.output)
-			});
+			for (const block of turn.content) if (block.type === "text" && block.text.trim()) {
+				if (depth === 0) events.push({
+					kind: "info",
+					text: `❯ ${block.text}`
+				});
+			} else if (block.type === "tool_result") {
+				const tool = toolByCallId.get(block.callId);
+				const raw = toolResultText(block.output);
+				const text = tool === "spawn" ? stripSpawnTokensLine(raw) : raw;
+				events.push({
+					kind: "tool-result",
+					text,
+					...tool ? { tool } : {},
+					...tag
+				});
+			}
 			continue;
 		}
 		if (turn.role === "assistant") {
 			for (const block of turn.content) if (block.type === "text" && block.text.trim()) events.push({
 				kind: "markdown",
 				text: block.text,
-				streaming: false
+				streaming: false,
+				...tag
 			});
 			else if (block.type === "tool_call") events.push({
 				kind: "tool",
-				text: toolCallPreview(block.name, block.input)
+				text: toolCallPreview(block.name, block.input),
+				tool: block.name,
+				...tag
 			});
 		}
 	}
+	closeRun(lastRunId, lastDepth);
 	return events;
 }
 /** Shared formatter for the `↳ name(args)` line shown on tool calls. */
@@ -691,6 +1123,22 @@ function toolCallPreview(name, input) {
 function toolResultText(output) {
 	return typeof output === "string" ? output : toolResultToText(output);
 }
+/**
+* Strip the `Tokens: …` line from a spawn tool-result. The spawn-end marker
+* displayed right above already shows the same stats; keeping the line in the
+* rendered tool-result body just produces a visible duplicate (and, on
+* reloaded pre-fix sessions, an *inconsistent* duplicate — the persisted line
+* uses the old `13 in / 4075 out` shape while the freshly synthesized
+* spawn-end uses the cache-aware `in 92615 (cache 92602) / 4075 out` shape).
+*
+* Display-only: the persisted tool_result content is untouched, so the LLM
+* still sees the full string in its context window. Anchored to start-of-line
+* and matches both `Tokens: 13 in / 4075 out` (legacy) and `Tokens: in 13 …`
+* (post-`formatTokenUsage`) shapes.
+*/
+function stripSpawnTokensLine(text) {
+	return text.replace(/^Tokens:[^\n]*\n?/m, "");
+}
 /** Effective context size of the most recent assistant turn — drives the footer indicator. */
 function lastContextSizeFromTurns(turns) {
 	for (let i = turns.length - 1; i >= 0; i--) {
@@ -714,13 +1162,12 @@ function resolveConfig(options = {}) {
 	const store = options.store ?? createTuiStore(paths.db);
 	const stateStore = createStateStore(paths.state);
 	const initialState = stateStore.load();
-	const providers = {
-		...FACTORIES,
-		...options.providers ?? {}
-	};
+	const providers = options.providers ?? BUILTIN_PROVIDERS;
 	const preset = options.preset ?? basic_default;
-	const modelsFor = makeModelsResolver(options.models);
-	const resumeProvider = resolveResumeProvider(initialState, providers);
+	process.env.ZIDANE_CREDENTIALS_PATH = credentialsPath(dir);
+	applyApiKeyEnv(dir, providers);
+	const modelsFor = makeModelsResolver(providers);
+	const resumeProvider = resolveResumeProvider(initialState, providers, dir);
 	const initialPicked = resumeProvider ? pickInitial(resumeProvider, providers, initialState) : null;
 	return {
 		prefix,
@@ -737,31 +1184,32 @@ function resolveConfig(options = {}) {
 		initialPicked
 	};
 }
-function makeModelsResolver(custom) {
+function makeModelsResolver(registry) {
 	return (key) => {
-		const overridden = custom?.[key];
-		if (overridden) return overridden;
-		try {
-			const piId = PI_PROVIDER_ID[key];
-			return getModels(piId);
-		} catch {
-			return [];
-		}
+		const descriptor = registry[key];
+		return descriptor ? modelsForDescriptor(descriptor) : [];
 	};
 }
-function resolveResumeProvider(state, providers) {
+function resolveResumeProvider(state, providers, storageDir) {
 	if (!state.lastProvider) return null;
 	if (!providers[state.lastProvider]) return null;
-	return detectAuth().find((p) => p.key === state.lastProvider && p.available) ?? null;
+	return detectAuth(storageDir, providers).find((p) => p.key === state.lastProvider && p.available) ?? null;
 }
 function pickInitial(auth, providers, state) {
-	const factory = providers[auth.key];
-	if (!factory) return null;
-	const provider = factory();
-	return {
+	const descriptor = providers[auth.key];
+	if (!descriptor) return null;
+	const model = state.lastModelByProvider?.[auth.key] ?? descriptor.defaultModel ?? safeFactoryDefault(descriptor);
+	return model ? {
 		provider: auth,
-		model: state.lastModelByProvider?.[auth.key] ?? provider.meta.defaultModel
-	};
+		model
+	} : null;
+}
+function safeFactoryDefault(descriptor) {
+	try {
+		return descriptor.factory().meta.defaultModel;
+	} catch {
+		return;
+	}
 }
 const ConfigContext = createContext(null);
 function ConfigProvider({ config, children }) {
@@ -868,9 +1316,10 @@ function Modal({ title, onClose, children, maxWidth = 92, minWidth = 44, horizon
 /** Cap the visible scroll window so a 30-model list doesn't push the modal off-screen. */
 const VISIBLE_ROW_CAP = 12;
 /**
-* Modal that lists the available models for the current provider and lets the
-* user pick one. Options come from `runTui({ models })` if supplied, otherwise
-* from pi-ai's built-in registry.
+* Modal that lists the available models for the current provider and lets
+* the user pick one. Options come from the active `ProviderDescriptor` —
+* either its declared `models` list or, when absent, pi-ai's built-in
+* registry looked up via `piProviderId`.
 *
 * Each row shows: `● selected · name (ctx N · reasoning · vision)`.
 */
@@ -933,9 +1382,21 @@ function EmptyState() {
 		children: [/* @__PURE__ */ jsx("text", {
 			fg: COLOR.dim,
 			children: "No models available for this provider."
-		}), /* @__PURE__ */ jsx("text", {
+		}), /* @__PURE__ */ jsxs("text", {
 			fg: COLOR.mute,
-			children: "Pass a `models` registry to `runTui()` to populate this list."
+			children: [
+				"Set",
+				/* @__PURE__ */ jsx("span", {
+					fg: COLOR.model,
+					children: " models "
+				}),
+				"on the provider descriptor (or a",
+				/* @__PURE__ */ jsx("span", {
+					fg: COLOR.model,
+					children: " piProviderId "
+				}),
+				"that pi-ai recognizes) to populate this list."
+			]
 		})]
 	});
 }
@@ -947,35 +1408,361 @@ function describeModel(m) {
 	return parts.join(" · ");
 }
 //#endregion
+//#region src/tui/safe-mode.ts
+/**
+* Safe-mode storage + matching for the TUI.
+*
+* Lives at `<dataDir>/projects.json` (default `~/.zidane/projects.json`). Each
+* top-level key is an absolute project directory; the value carries that
+* project's persisted tool-call `safelist`.
+*
+* ```json
+* {
+*   "/Users/me/proj-a": { "safelist": ["read_file", "shell:git:*"] }
+* }
+* ```
+*
+* Two granularities for safelist entries:
+*   - **bare tool name** — `"read_file"` matches every `read_file` call.
+*   - **tool + first-arg token + wildcard** — `"shell:git:*"` matches `shell`
+*     calls whose primary string argument starts with the token `git`
+*     (followed by whitespace or end-of-string). Modelled on Claude Code's
+*     `Bash(git:*)` syntax.
+*
+* A short list of read-only tools is **implicitly safe** without being
+* persisted — see {@link IMPLICITLY_SAFE_TOOLS}.
+*/
+/** Resolve `projects.json`'s on-disk path given the TUI data directory. */
+function projectsFilePath(dataDir) {
+	return resolve(dataDir, "projects.json");
+}
+function readProjects(dataDir) {
+	const path = projectsFilePath(dataDir);
+	if (!existsSync(path)) return {};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8"));
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+	} catch {}
+	return {};
+}
+function ensureDir(path) {
+	const dir = dirname(path);
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+/** Atomic write — tmp + rename so a crash never leaves a half-file. */
+function writeProjects(dataDir, file) {
+	const path = projectsFilePath(dataDir);
+	ensureDir(path);
+	const tmp = `${path}.${process.pid}.tmp`;
+	writeFileSync(tmp, JSON.stringify(file, null, 2));
+	renameSync(tmp, path);
+}
+/**
+* Append `entry` to the safelist for `projectDir`, dedup-aware. Returns the
+* updated entry list (post-write) so callers can render it without re-reading.
+*/
+function addToSafelist(dataDir, projectDir, entry) {
+	const file = readProjects(dataDir);
+	const existing = file[projectDir]?.safelist ?? [];
+	if (existing.includes(entry)) return existing;
+	const next = [...existing, entry];
+	file[projectDir] = {
+		...file[projectDir],
+		safelist: next
+	};
+	writeProjects(dataDir, file);
+	return next;
+}
+/** Read the safelist for one project. Returns `[]` for unknown projects. */
+function getSafelist(dataDir, projectDir) {
+	return readProjects(dataDir)[projectDir]?.safelist ?? [];
+}
+/**
+* Tools that always pass without prompting — pure file/dir reads with no
+* side effects. Users who want to gate them must disable safe-mode entirely
+* (or fork this list in their own embedding).
+*/
+const IMPLICITLY_SAFE_TOOLS = [
+	"read_file",
+	"list_files",
+	"glob",
+	"grep"
+];
+/** Common input keys carrying the "primary argument" we scope safelists on. */
+const PRIMARY_ARG_KEYS = [
+	"command",
+	"path",
+	"pattern",
+	"query"
+];
+function primaryArgValue(input) {
+	for (const key of PRIMARY_ARG_KEYS) {
+		const v = input[key];
+		if (typeof v === "string" && v.length > 0) return v;
+	}
+	return "";
+}
+/** Extract the first whitespace-delimited token of the primary arg. */
+function primaryArgToken(input) {
+	return primaryArgValue(input).split(/\s+/)[0] ?? "";
+}
+/**
+* Shell metacharacters that turn a single command into a compound: pipes,
+* sequencing, redirects, substitutions, line breaks, subshells. A `shell:git:*`
+* entry is meant to greenlight "any git invocation" — without this guard,
+* `git status && rm -rf /` would tokenize to `git` and pass the safelist
+* unchallenged. Reject any command that's not a single program call.
+*
+* The regex is intentionally generous: false positives (e.g. `echo "hi & bye"`)
+* just prompt the user again, which is the safe failure mode.
+*/
+const SHELL_COMPOUND_RE = /[;&|<>`$\n\r()]/;
+function isCompoundShellCommand(command) {
+	return SHELL_COMPOUND_RE.test(command);
+}
+/**
+* Test whether a `{ tool, input }` pair is covered by one safelist entry.
+*
+* Supported entry shapes:
+*   - `"<tool>"` — broad match on tool name. For `shell` this still requires
+*     a single-program command (compound forms always prompt).
+*   - `"<tool>:<token>:*"` — match when the primary arg's first token equals
+*     `<token>`. For `shell`, also requires the command to be free of
+*     metacharacters (`;`, `&&`, `||`, `|`, `$(`, backticks, `>`, `<`,
+*     newlines, subshells) — otherwise a `shell:git:*` entry would silently
+*     greenlight `git status && rm -rf /`.
+*
+* Entries that don't fit either shape are ignored (forward-compat for future
+* pattern syntax — readers shouldn't choke on entries written by a newer
+* version of the TUI).
+*/
+function matchesSafelistEntry(entry, tool, input) {
+	if (tool === "shell") {
+		if (isCompoundShellCommand(typeof input.command === "string" ? input.command : "")) return false;
+	}
+	if (entry === tool) return true;
+	const sep = entry.indexOf(":");
+	if (sep <= 0) return false;
+	if (entry.slice(0, sep) !== tool) return false;
+	const scope = entry.slice(sep + 1);
+	if (scope.endsWith(":*")) return primaryArgToken(input) === scope.slice(0, -2);
+	return false;
+}
+/** True when a call matches ANY entry in the project's safelist (or is implicitly safe). */
+function isOnSafelist(entries, tool, input) {
+	if (IMPLICITLY_SAFE_TOOLS.includes(tool)) return true;
+	return entries.some((e) => matchesSafelistEntry(e, tool, input));
+}
+/**
+* Suggest the safelist entry to write when the user picks "accept and
+* remember" for a `{ tool, input }`. Heuristic:
+*
+*   - `shell` → scope by first command token (`shell:git:*`).
+*   - anything else → bare tool name (broad).
+*
+* Returning a string ensures the UI always has a concrete entry to display
+* as the button label.
+*/
+function suggestSafelistEntry(tool, input) {
+	if (tool === "shell") {
+		const token = primaryArgToken(input);
+		if (token) return `${tool}:${token}:*`;
+	}
+	return tool;
+}
+//#endregion
+//#region src/tui/safe-mode-context.tsx
+const SafeModeQueueContext = createContext([]);
+const SafeModeActionsContext = createContext(null);
+let approvalIdCounter = 0;
+function nextApprovalId() {
+	approvalIdCounter += 1;
+	return `approval-${approvalIdCounter}`;
+}
+/**
+* Owns the queue + actions. Splits the value across two contexts so a queue
+* change doesn't invalidate every callback memo that closes over the actions.
+*/
+function SafeModeProvider({ children }) {
+	const [queue, setQueue] = useState([]);
+	const requestApproval = useCallback((tool, input) => new Promise((resolve) => {
+		setQueue((prev) => [...prev, {
+			id: nextApprovalId(),
+			tool,
+			input,
+			resolve
+		}]);
+	}), []);
+	const resolveHead = useCallback((decision) => {
+		setQueue((prev) => {
+			const [head, ...rest] = prev;
+			if (head) head.resolve(decision);
+			return rest;
+		});
+	}, []);
+	const denyAll = useCallback(() => {
+		setQueue((prev) => {
+			for (const p of prev) p.resolve("deny");
+			return [];
+		});
+	}, []);
+	const actionsRef = useRef(null);
+	if (!actionsRef.current) actionsRef.current = {
+		requestApproval,
+		resolveHead,
+		denyAll
+	};
+	return /* @__PURE__ */ jsx(SafeModeActionsContext.Provider, {
+		value: actionsRef.current,
+		children: /* @__PURE__ */ jsx(SafeModeQueueContext.Provider, {
+			value: queue,
+			children
+		})
+	});
+}
+function useSafeModeQueue() {
+	return useContext(SafeModeQueueContext);
+}
+function useSafeModeActions() {
+	const ctx = useContext(SafeModeActionsContext);
+	if (!ctx) throw new Error("useSafeModeActions must be used inside <SafeModeProvider>");
+	return ctx;
+}
+//#endregion
+//#region src/tui/oauth.ts
+function supportsOAuth(descriptor) {
+	return descriptor.oauthProvider !== void 0;
+}
+/**
+* Run the OAuth login flow for a provider.
+*
+* Returns the OAuth credentials on success; caller persists them via
+* `setProviderCredential(dataDir, descriptor, { kind: 'oauth', ...credentials })`.
+* Throws when the descriptor has no `oauthProvider` configured.
+*/
+async function runOAuthLogin(descriptor, options) {
+	if (!descriptor.oauthProvider) throw new Error(`OAuth not supported for ${descriptor.label} (${descriptor.key}) — use an API key instead.`);
+	const callbacks = {
+		onAuth: (info) => {
+			options.onUrl(info.url, info.instructions);
+			tryOpenBrowser(info.url);
+		},
+		onPrompt: async () => {
+			if (!options.onCodeRequest) throw new Error("OAuth flow requires manual code input but no handler is wired.");
+			return options.onCodeRequest();
+		},
+		onProgress: options.onProgress,
+		signal: options.signal
+	};
+	return descriptor.oauthProvider.login(callbacks);
+}
+/**
+* Best-effort cross-platform browser open. macOS uses `open`, Linux uses
+* `xdg-open`, Windows uses `start`. Failures are swallowed — the callback
+* server is already listening, and the URL is displayed in the TUI for
+* manual click.
+*
+* Uses `spawn` (not `exec`) so the URL is passed as an argv element rather
+* than interpolated into a shell command — no need to think about quoting
+* URLs that contain `&`, `?`, `"` or other shell metacharacters.
+*/
+function tryOpenBrowser(url) {
+	const [cmd, ...args] = (() => {
+		if (process.platform === "darwin") return ["open", url];
+		if (process.platform === "win32") return [
+			"cmd",
+			"/c",
+			"start",
+			"",
+			url
+		];
+		return ["xdg-open", url];
+	})();
+	try {
+		const child = spawn(cmd, args, {
+			stdio: "ignore",
+			detached: true
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+//#endregion
 //#region src/tui/screens.tsx
 /**
-* Textarea bindings: plain `enter` submits; `shift+enter` inserts a newline.
-* All `return` defaults are stripped and replaced so the user's preferred
-* binding wins regardless of modifier state.
+* Build a key-binding set for the prompt textarea / API-key input. Strips the
+* default `return` action and reinstalls it with our preferred meaning, so the
+* binding wins regardless of modifier state. Pass `allowShiftReturnNewline`
+* to enable `shift+enter` → newline (multi-line input).
 */
-const TEXTAREA_BINDINGS = [
-	...defaultTextareaKeyBindings.filter((b) => b.name !== "return"),
-	{
+function makeSubmitBindings(allowShiftReturnNewline) {
+	const base = defaultTextareaKeyBindings.filter((b) => b.name !== "return");
+	return allowShiftReturnNewline ? [
+		...base,
+		{
+			name: "return",
+			action: "submit"
+		},
+		{
+			name: "return",
+			shift: true,
+			action: "newline"
+		}
+	] : [...base, {
 		name: "return",
 		action: "submit"
-	},
-	{
-		name: "return",
-		shift: true,
-		action: "newline"
-	}
-];
+	}];
+}
+const TEXTAREA_BINDINGS = makeSubmitBindings(true);
+const API_KEY_INPUT_BINDINGS = makeSubmitBindings(false);
+/**
+* Look up a `{ key }` item by the value of a `<select>` option. Used by every
+* screen that mixes keyed-entry rows with sentinel "+ new" / "← back" rows —
+* sentinel handling stays explicit at the call site, this helper just trims
+* the boilerplate `.find(i => i.key === ...)` typing.
+*/
+function findByKey(items, value) {
+	return typeof value === "string" ? items.find((i) => i.key === value) : void 0;
+}
+/**
+* Sentinel value used by the picker's "+ add / re-configure" option. Lives
+* outside the provider key namespace (key strings are at least one char, no
+* leading `__`) so we can't collide with a real registry entry.
+*/
+const WIZARD_OPTION_VALUE = "__wizard__";
 function AuthScreen({ onPick }) {
-	const { providers: registry } = useConfig();
+	const config = useConfig();
+	const { providers: registry } = config;
 	const focused = useModalAwareFocus();
-	const providers = useMemo(() => detectAuth().filter((p) => p.key in registry), [registry]);
+	const [providers, setProviders] = useState([]);
+	const refresh = useCallback(() => setProviders(detectAuth(config.paths.dir, registry)), [config.paths.dir, registry]);
+	useEffect(() => {
+		refresh();
+	}, [refresh]);
+	const [forceWizard, setForceWizard] = useState(false);
 	const available = useMemo(() => providers.filter((p) => p.available), [providers]);
-	if (available.length === 0) return /* @__PURE__ */ jsx(NoAuthScreen, { providers });
-	const options = available.map((p) => ({
+	const onWizardDone = useCallback(() => {
+		setForceWizard(false);
+		refresh();
+	}, [refresh]);
+	if (available.length === 0 || forceWizard) {
+		const canCancel = forceWizard && available.length > 0;
+		return /* @__PURE__ */ jsx(SetupWizard, {
+			registry,
+			dataDir: config.paths.dir,
+			onConfigured: onWizardDone,
+			onCancel: canCancel ? () => setForceWizard(false) : void 0
+		});
+	}
+	const options = [...available.map((p) => ({
 		name: p.label,
 		description: p.methods.map((m) => m.detail).join(" · "),
 		value: p.key
-	}));
+	})), {
+		name: "+ add or re-configure a provider",
+		description: "launch the setup wizard",
+		value: WIZARD_OPTION_VALUE
+	}];
 	return /* @__PURE__ */ jsx("box", {
 		title: " pick a provider ",
 		style: {
@@ -992,48 +1779,318 @@ function AuthScreen({ onPick }) {
 			wrapSelection: true,
 			onSelect: (_idx, option) => {
 				if (!option) return;
-				const provider = available.find((p) => p.key === option.value);
+				if (option.value === WIZARD_OPTION_VALUE) {
+					setForceWizard(true);
+					return;
+				}
+				const provider = findByKey(available, option.value);
 				if (provider) onPick(provider);
 			},
 			style: { flexGrow: 1 }
 		})
 	});
 }
-function NoAuthScreen({ providers }) {
+function SetupWizard({ registry, dataDir, onConfigured, onCancel }) {
+	const [step, setStep] = useState({ kind: "pick-provider" });
+	const [error, setError] = useState(null);
+	const descriptors = useMemo(() => Object.values(registry), [registry]);
+	const onPickProvider = useCallback((descriptor) => {
+		setError(null);
+		setStep({
+			kind: "pick-method",
+			descriptor
+		});
+	}, []);
+	const onPickMethod = useCallback((descriptor, method) => {
+		setError(null);
+		if (method === "apikey") setStep({
+			kind: "enter-apikey",
+			descriptor
+		});
+		else setStep({
+			kind: "oauth-running",
+			descriptor
+		});
+	}, []);
+	const onApiKeySubmit = useCallback((descriptor, value) => {
+		const trimmed = value.trim();
+		if (!trimmed) {
+			setError("API key cannot be empty.");
+			return;
+		}
+		try {
+			setProviderCredential(dataDir, descriptor, {
+				kind: "apikey",
+				value: trimmed
+			});
+			if (descriptor.envKey) process.env[descriptor.envKey] = trimmed;
+			onConfigured();
+		} catch (err) {
+			setError(err instanceof Error ? err.message : String(err));
+		}
+	}, [dataDir, onConfigured]);
+	if (descriptors.length === 0) return /* @__PURE__ */ jsx(EmptyRegistryNotice, {});
+	if (step.kind === "pick-provider") return /* @__PURE__ */ jsx(PickProviderStep, {
+		descriptors,
+		error,
+		onPick: onPickProvider,
+		onCancel
+	});
+	if (step.kind === "pick-method") return /* @__PURE__ */ jsx(PickMethodStep, {
+		descriptor: step.descriptor,
+		error,
+		onPick: onPickMethod
+	});
+	if (step.kind === "enter-apikey") return /* @__PURE__ */ jsx(EnterApiKeyStep, {
+		descriptor: step.descriptor,
+		error,
+		onSubmit: onApiKeySubmit
+	});
+	return /* @__PURE__ */ jsx(OAuthRunningStep, {
+		descriptor: step.descriptor,
+		dataDir,
+		onSuccess: onConfigured,
+		onError: (msg) => {
+			setError(msg);
+			setStep({
+				kind: "pick-method",
+				descriptor: step.descriptor
+			});
+		}
+	});
+}
+/**
+* Shared wrapper for every wizard step — same border + padding + flex layout
+* with a customizable title and accent color. Footnote slot at the bottom for
+* an error banner.
+*/
+function WizardPanel({ title, accent = COLOR.border, error, children }) {
 	return /* @__PURE__ */ jsxs("box", {
-		title: " no authentication detected ",
+		title,
 		style: {
 			border: true,
-			borderColor: COLOR.error,
+			borderColor: accent,
 			padding: 1,
-			flexDirection: "column",
 			gap: 1,
+			flexDirection: "column",
 			flexGrow: 1
 		},
+		children: [children, error && /* @__PURE__ */ jsx("text", {
+			fg: COLOR.error,
+			children: error
+		})]
+	});
+}
+/** "esc to exit" footer hint shared by every wizard step that doesn't offer a "← back" affordance. */
+function WizardEscHint() {
+	return /* @__PURE__ */ jsx("text", {
+		fg: COLOR.dim,
+		children: "esc to exit"
+	});
+}
+function EmptyRegistryNotice() {
+	return /* @__PURE__ */ jsxs(WizardPanel, {
+		title: " no providers configured ",
+		accent: COLOR.error,
+		children: [/* @__PURE__ */ jsx("text", {
+			fg: COLOR.error,
+			children: "This TUI has no providers registered."
+		}), /* @__PURE__ */ jsxs("text", {
+			fg: COLOR.dim,
+			children: [
+				"Pass providers via",
+				/* @__PURE__ */ jsx("span", {
+					fg: COLOR.model,
+					children: " runTui({ providers }) "
+				}),
+				"or use the built-ins via",
+				/* @__PURE__ */ jsx("span", {
+					fg: COLOR.model,
+					children: " BUILTIN_PROVIDERS "
+				}),
+				"."
+			]
+		})]
+	});
+}
+/** Sentinel option value used for the wizard's "← back to picker" entry. */
+const WIZARD_BACK_VALUE = "__back__";
+function PickProviderStep({ descriptors, error, onPick, onCancel }) {
+	const focused = useModalAwareFocus();
+	const options = [...descriptors.map((d) => {
+		const methods = supportsOAuth(d) ? ["API key", "OAuth"] : ["API key"];
+		return {
+			name: d.label,
+			description: methods.join(" · "),
+			value: d.key
+		};
+	}), ...onCancel ? [{
+		name: "← back",
+		description: "return to the provider list",
+		value: WIZARD_BACK_VALUE
+	}] : []];
+	return /* @__PURE__ */ jsxs(WizardPanel, {
+		title: onCancel ? " add or re-configure a provider " : " welcome to zidane · pick a provider ",
+		error,
+		children: [!onCancel && /* @__PURE__ */ jsxs("text", {
+			fg: COLOR.dim,
+			children: [
+				"No provider credentials yet. Pick a provider to configure — keys are stored in",
+				/* @__PURE__ */ jsx("span", {
+					fg: COLOR.model,
+					children: " ~/.zidane/credentials.json "
+				}),
+				"(owner-only)."
+			]
+		}), /* @__PURE__ */ jsx("select", {
+			...SELECT_THEME,
+			focused,
+			options,
+			wrapSelection: true,
+			onSelect: (_idx, option) => {
+				if (!option) return;
+				if (option.value === WIZARD_BACK_VALUE) {
+					onCancel?.();
+					return;
+				}
+				const descriptor = findByKey(descriptors, option.value);
+				if (descriptor) onPick(descriptor);
+			},
+			style: { flexGrow: 1 }
+		})]
+	});
+}
+function PickMethodStep({ descriptor, error, onPick }) {
+	const focused = useModalAwareFocus();
+	const options = useMemo(() => {
+		const items = [{
+			name: "API key",
+			description: `paste your ${descriptor.label} API key`,
+			value: "apikey"
+		}];
+		if (supportsOAuth(descriptor)) {
+			const hint = descriptor.oauthHint ? ` (${descriptor.oauthHint})` : "";
+			items.push({
+				name: "OAuth",
+				description: `browser-based sign-in${hint}`,
+				value: "oauth"
+			});
+		}
+		return items;
+	}, [descriptor]);
+	return /* @__PURE__ */ jsxs(WizardPanel, {
+		title: ` configure ${descriptor.label} — pick auth method `,
+		error,
+		children: [/* @__PURE__ */ jsx(WizardEscHint, {}), /* @__PURE__ */ jsx("select", {
+			...SELECT_THEME,
+			focused,
+			options,
+			wrapSelection: true,
+			onSelect: (_idx, option) => {
+				if (option) onPick(descriptor, option.value);
+			},
+			style: { flexGrow: 1 }
+		})]
+	});
+}
+function EnterApiKeyStep({ descriptor, error, onSubmit }) {
+	const focused = useModalAwareFocus();
+	const inputRef = useRef(null);
+	const submit = useCallback(() => {
+		onSubmit(descriptor, inputRef.current?.value ?? "");
+	}, [descriptor, onSubmit]);
+	return /* @__PURE__ */ jsxs(WizardPanel, {
+		title: ` configure ${descriptor.label} — paste API key `,
+		error,
+		children: [/* @__PURE__ */ jsxs("text", {
+			fg: COLOR.dim,
+			children: [
+				"Paste your",
+				` ${descriptor.label} `,
+				"API key and press",
+				/* @__PURE__ */ jsx("span", {
+					fg: COLOR.model,
+					children: " enter "
+				}),
+				"to save. Esc to exit."
+			]
+		}), /* @__PURE__ */ jsx("box", {
+			style: {
+				border: true,
+				borderColor: COLOR.borderActive,
+				paddingLeft: 1,
+				paddingRight: 1,
+				height: 3
+			},
+			children: /* @__PURE__ */ jsx("input", {
+				ref: inputRef,
+				focused,
+				keyBindings: API_KEY_INPUT_BINDINGS,
+				placeholder: descriptor.apiKeyPlaceholder ?? "API key…",
+				onSubmit: submit,
+				style: { flexGrow: 1 }
+			})
+		})]
+	});
+}
+function OAuthRunningStep({ descriptor, dataDir, onSuccess, onError }) {
+	const [url, setUrl] = useState(null);
+	const [status, setStatus] = useState("starting browser…");
+	useEffect(() => {
+		const ac = new AbortController();
+		let cancelled = false;
+		(async () => {
+			try {
+				const creds = await runOAuthLogin(descriptor, {
+					onUrl: (loginUrl) => {
+						if (cancelled) return;
+						setUrl(loginUrl);
+						setStatus("waiting for browser callback…");
+					},
+					onProgress: (message) => {
+						if (!cancelled) setStatus(message);
+					},
+					signal: ac.signal
+				});
+				if (cancelled) return;
+				setProviderCredential(dataDir, descriptor, {
+					kind: "oauth",
+					...creds
+				});
+				onSuccess();
+			} catch (err) {
+				if (cancelled) return;
+				onError(err instanceof Error ? err.message : String(err));
+			}
+		})();
+		return () => {
+			cancelled = true;
+			ac.abort();
+		};
+	}, [
+		descriptor,
+		dataDir,
+		onSuccess,
+		onError
+	]);
+	return /* @__PURE__ */ jsxs(WizardPanel, {
+		title: ` configure ${descriptor.label} — OAuth `,
 		children: [
-			/* @__PURE__ */ jsx("text", {
-				fg: COLOR.error,
-				children: "No provider credentials found."
-			}),
-			/* @__PURE__ */ jsx("text", {
-				fg: COLOR.dim,
-				children: "Set one of these env vars (or run `bun run auth` for OAuth):"
-			}),
-			providers.map((p) => /* @__PURE__ */ jsxs("text", {
-				fg: COLOR.dim,
-				children: [
-					"  · ",
-					/* @__PURE__ */ jsx("span", {
-						fg: COLOR.brand,
-						children: p.label
-					}),
-					" → ",
-					/* @__PURE__ */ jsx("span", {
-						fg: COLOR.model,
-						children: envKeyFor(p.key)
-					})
-				]
-			}, p.key))
+			/* @__PURE__ */ jsx(WizardEscHint, {}),
+			/* @__PURE__ */ jsx(Spinner, { label: status }),
+			url && /* @__PURE__ */ jsxs("box", {
+				style: {
+					flexDirection: "column",
+					gap: 0
+				},
+				children: [/* @__PURE__ */ jsx("text", {
+					fg: COLOR.dim,
+					children: "If the browser didn't open, visit:"
+				}), /* @__PURE__ */ jsx("text", {
+					fg: COLOR.model,
+					children: url
+				})]
+			})
 		]
 	});
 }
@@ -1074,7 +2131,7 @@ function SessionsScreen({ sessions, currentId, onPick, onCreate }) {
 			onSelect: (_idx, option) => {
 				if (!option) return;
 				if (option.value === NEW_VALUE) onCreate();
-				else onPick(option.value);
+				else if (typeof option.value === "string") onPick(option.value);
 			},
 			style: { flexGrow: 1 }
 		})
@@ -1083,11 +2140,11 @@ function SessionsScreen({ sessions, currentId, onPick, onCreate }) {
 /** Visible content lines: 1 minimum, 5 maximum (textarea scrolls past 5). */
 const MIN_CONTENT_LINES = 1;
 const MAX_CONTENT_LINES = 5;
-function ChatScreen({ events, busy, settings, onSubmit, session }) {
+function ChatScreen({ events, busy, settings, onSubmit, session, pending, onApproval }) {
 	const title = useMemo(() => {
 		if (!session) return " untitled ";
 		const turns = `${session.turnCount} turn${session.turnCount === 1 ? "" : "s"}`;
-		return ` ${session.title}  ·  #${shortId(session.id)} · ${turns} `;
+		return ` ${session.title} · #${shortId(session.id)} · ${turns} `;
 	}, [session]);
 	const userPrompts = useMemo(() => events.filter((e) => e.kind === "info").map((e) => e.text.replace(/^❯ /, "")), [events]);
 	return /* @__PURE__ */ jsxs("box", {
@@ -1107,12 +2164,130 @@ function ChatScreen({ events, busy, settings, onSubmit, session }) {
 				events,
 				settings
 			})
-		}), busy ? /* @__PURE__ */ jsx(BusyBlock, {}) : /* @__PURE__ */ jsx(PromptBlock, {
+		}), pending ? /* @__PURE__ */ jsx(ApprovalBlock, {
+			request: pending,
+			onPick: onApproval
+		}) : busy ? /* @__PURE__ */ jsx(BusyBlock, {}) : /* @__PURE__ */ jsx(PromptBlock, {
 			userPrompts,
 			onSubmit
 		})]
 	});
 }
+/** Max chars per scalar argument in the approval preview. */
+const APPROVAL_ARG_MAX = 80;
+/**
+* Render `{ path: 'x.ts', contents: 'long string' }` as
+* `path: "x.ts", contents: "long string…"` — readable, per-key, truncated
+* per value rather than dumping `JSON.stringify(input)` (which produces an
+* illegible 50KB blob for `write_file` etc.).
+*/
+function formatApprovalArgs(input) {
+	const parts = [];
+	for (const [key, raw] of Object.entries(input)) {
+		let value;
+		if (typeof raw === "string") {
+			const escaped = raw.replace(/\n/g, "\\n");
+			value = escaped.length > APPROVAL_ARG_MAX ? `"${escaped.slice(0, APPROVAL_ARG_MAX)}…"` : `"${escaped}"`;
+		} else {
+			const json = JSON.stringify(raw);
+			value = json.length > APPROVAL_ARG_MAX ? `${json.slice(0, APPROVAL_ARG_MAX)}…` : json;
+		}
+		parts.push(`${key}: ${value}`);
+	}
+	return parts.join(", ");
+}
+/**
+* Inline approval picker — replaces the chat input while a tool call is
+* pending. Three options:
+*   - **accept once** — let this call execute, don't persist anything.
+*   - **accept + remember** — execute + add a `projects.json` entry so the
+*     same shape doesn't prompt again in this directory.
+*   - **deny** — refuse the call. The model gets `Blocked: …` and adapts.
+*
+* Esc aborts the whole run via the parent keyboard handler; per-call
+* accept/deny only happens through the select below.
+*
+* Layout is fully pinned so the picker never overlaps with itself or the
+* transcript above:
+*
+*   - Outer `<box>` has an explicit `height`. The slot below the transcript
+*     adapts (the chat container is column-flex), so we control exactly how
+*     many rows we occupy.
+*   - Summary row is a `<box height: 1, overflow: hidden>` wrapping a
+*     `<text wrapMode="none">` — a 500-char tool-call preview can never
+*     wrap to row 2 and push the select off-screen.
+*   - `<select showDescription={false}>` keeps each option to exactly one
+*     row. Hints live in the `name` string after a `·` separator. Without
+*     this, the default `showDescription: true` makes every option take 2
+*     rows, and a `height: options.length` select would overdraw into the
+*     summary above (the original bug).
+*/
+function ApprovalBlock({ request, onPick }) {
+	const focused = useModalAwareFocus();
+	const summary = useMemo(() => `${request.tool}(${formatApprovalArgs(request.input)})`, [request.tool, request.input]);
+	const options = useMemo(() => {
+		return [
+			{
+				name: "accept once  ·  allow this call only",
+				description: "",
+				value: "accept-once"
+			},
+			{
+				name: `accept + remember  ·  add "${suggestSafelistEntry(request.tool, request.input)}" to projects.json`,
+				description: "",
+				value: "accept-safelist"
+			},
+			{
+				name: "deny  ·  refuse — the model will see Blocked",
+				description: "",
+				value: "deny"
+			}
+		];
+	}, [request.tool, request.input]);
+	const height = 3 + options.length;
+	return /* @__PURE__ */ jsxs("box", {
+		title: " approve tool call · esc to abort run ",
+		style: {
+			border: true,
+			borderColor: COLOR.warn,
+			paddingLeft: 1,
+			paddingRight: 1,
+			paddingTop: 0,
+			paddingBottom: 0,
+			height,
+			flexDirection: "column",
+			flexShrink: 0
+		},
+		children: [/* @__PURE__ */ jsx("box", {
+			style: {
+				height: 1,
+				overflow: "hidden",
+				flexShrink: 0
+			},
+			children: /* @__PURE__ */ jsxs("text", {
+				fg: COLOR.model,
+				wrapMode: "none",
+				children: [/* @__PURE__ */ jsx("span", {
+					fg: COLOR.warn,
+					children: "↳ "
+				}), summary]
+			})
+		}), /* @__PURE__ */ jsx("select", {
+			...SELECT_THEME,
+			focused,
+			options,
+			showDescription: false,
+			wrapSelection: true,
+			onSelect: (_idx, option) => {
+				if (option) onPick(option.value);
+			},
+			style: {
+				height: options.length,
+				flexShrink: 0
+			}
+		})]
+	});
+}
 function BusyBlock() {
 	return /* @__PURE__ */ jsx("box", {
 		style: {
@@ -1210,7 +2385,9 @@ function PromptBlock({ userPrompts, onSubmit }) {
 const DEFAULT_SETTINGS = {
 	showThinking: true,
 	showToolCalls: true,
-	showToolResults: true
+	showToolResults: true,
+	safeMode: true,
+	hideSubagentOutput: true
 };
 const SettingsContext = createContext(null);
 function SettingsProvider({ initial, onChange, children }) {
@@ -1239,40 +2416,88 @@ function useSettings() {
 	if (!ctx) throw new Error("useSettings must be used inside <SettingsProvider>");
 	return ctx;
 }
-const ROWS = [
+const TOGGLES = [
+	{
+		kind: "toggle",
+		key: "safeMode",
+		label: "Safe mode",
+		description: "prompt before each tool call (unless safelisted)"
+	},
+	{
+		kind: "toggle",
+		key: "hideSubagentOutput",
+		label: "Hide subagent output",
+		description: "collapse subagent runs to start/done markers"
+	},
 	{
+		kind: "toggle",
 		key: "showThinking",
 		label: "Thinking blocks",
 		description: "agent reasoning shown inline"
 	},
 	{
+		kind: "toggle",
 		key: "showToolCalls",
 		label: "Tool calls",
 		description: "the ↳ name(args) lines"
 	},
 	{
+		kind: "toggle",
 		key: "showToolResults",
 		label: "Tool outputs",
 		description: "the ┃ result blocks under tool calls"
 	}
 ];
-function SettingsModal() {
+function SettingsModal({ actions } = {}) {
 	const { settings, toggle } = useSettings();
-	const [cursor, setCursor] = useState(0);
+	const [cursor, setCursorRaw] = useState(0);
+	const items = useMemo(() => {
+		const actionItems = [];
+		if (actions?.onReauth) actionItems.push({
+			kind: "action",
+			id: "reauth",
+			label: "Authentication",
+			description: "switch provider, add another, or re-authenticate",
+			onPick: actions.onReauth
+		});
+		return [...TOGGLES, ...actionItems];
+	}, [actions]);
+	const safeCursor = Math.min(cursor, items.length - 1);
+	const setCursor = useCallback((update) => setCursorRaw((prev) => Math.min(Math.max(0, update(prev)), items.length - 1)), [items.length]);
 	useKeyboard((key) => {
-		if (key.name === "up" || key.ctrl && key.name === "p") setCursor((c) => Math.max(0, c - 1));
-		else if (key.name === "down" || key.ctrl && key.name === "n") setCursor((c) => Math.min(ROWS.length - 1, c + 1));
-		else if (key.name === "return" || key.name === "space") toggle(ROWS[cursor].key);
+		if (key.name === "up" || key.ctrl && key.name === "p") setCursor((c) => c - 1);
+		else if (key.name === "down" || key.ctrl && key.name === "n") setCursor((c) => c + 1);
+		else if (key.name === "return" || key.name === "space") {
+			const item = items[safeCursor];
+			if (!item) return;
+			if (item.kind === "toggle") toggle(item.key);
+			else item.onPick();
+		}
 	});
+	const firstActionIndex = items.findIndex((i) => i.kind === "action");
 	return /* @__PURE__ */ jsxs(Modal, {
 		title: "settings",
 		children: [/* @__PURE__ */ jsx("box", {
 			style: { flexDirection: "column" },
-			children: ROWS.map((row, i) => /* @__PURE__ */ jsx(SettingRowView, {
-				row,
-				enabled: settings[row.key],
-				focused: i === cursor
-			}, row.key))
+			children: items.map((item, i) => /* @__PURE__ */ jsxs("box", {
+				style: { flexDirection: "column" },
+				children: [i === firstActionIndex && i > 0 && /* @__PURE__ */ jsx("box", { style: {
+					border: ["top"],
+					borderColor: COLOR.mute,
+					height: 1,
+					marginTop: 1,
+					marginBottom: 1
+				} }), item.kind === "toggle" ? /* @__PURE__ */ jsx(ToggleRow, {
+					label: item.label,
+					description: item.description,
+					enabled: settings[item.key],
+					focused: i === safeCursor
+				}) : /* @__PURE__ */ jsx(ActionRow, {
+					label: item.label,
+					description: item.description,
+					focused: i === safeCursor
+				})]
+			}, item.kind === "toggle" ? item.key : item.id))
 		}), /* @__PURE__ */ jsxs("text", {
 			fg: COLOR.mute,
 			children: [
@@ -1285,7 +2510,7 @@ function SettingsModal() {
 					fg: COLOR.warn,
 					children: "↵"
 				}),
-				" toggle · ",
+				firstActionIndex >= 0 ? " toggle/select · " : " toggle · ",
 				/* @__PURE__ */ jsx("span", {
 					fg: COLOR.warn,
 					children: "esc"
@@ -1296,14 +2521,13 @@ function SettingsModal() {
 	});
 }
 /**
-* A single setting row — `▶` marker · checkbox · label · description.
+* Toggle row — `▶` marker · checkbox · label · description.
 *
 * Rendered as one `<text>` so OpenTUI's word-wrap handles narrow terminals
 * automatically: on wide screens everything sits on one line; on narrow ones
-* the trailing description wraps under the label without breaking the row's
-* structure.
+* the trailing description wraps under the label without breaking the row.
 */
-function SettingRowView({ row, enabled, focused }) {
+function ToggleRow({ label, description, enabled, focused }) {
 	return /* @__PURE__ */ jsxs("text", {
 		fg: focused ? COLOR.brand : COLOR.dim,
 		children: [
@@ -1317,11 +2541,42 @@ function SettingRowView({ row, enabled, focused }) {
 			}),
 			/* @__PURE__ */ jsx("span", {
 				fg: focused ? COLOR.brand : COLOR.dim,
-				children: row.label
+				children: label
+			}),
+			/* @__PURE__ */ jsx("span", {
+				fg: COLOR.mute,
+				children: `  ${description}`
+			})
+		]
+	});
+}
+/**
+* Action row — cursor marker · label · description · (focus-only) trailing arrow.
+*
+* The label sits in the same column as a toggle row's `[✓]` checkbox (right
+* after the 2-col cursor slot). The trailing `›` only renders when focused
+* so it reads as a "this row runs" affordance, not a static decoration on
+* every action.
+*/
+function ActionRow({ label, description, focused }) {
+	return /* @__PURE__ */ jsxs("text", {
+		fg: focused ? COLOR.brand : COLOR.dim,
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				fg: focused ? COLOR.brand : COLOR.mute,
+				children: focused ? "▶ " : "  "
+			}),
+			/* @__PURE__ */ jsx("span", {
+				fg: focused ? COLOR.brand : COLOR.accent,
+				children: label
 			}),
 			/* @__PURE__ */ jsx("span", {
 				fg: COLOR.mute,
-				children: `  ${row.description}`
+				children: `  ${description}`
+			}),
+			focused && /* @__PURE__ */ jsx("span", {
+				fg: COLOR.brand,
+				children: " ›"
 			})
 		]
 	});
@@ -1518,7 +2773,7 @@ function App({ config }) {
 				...config.stateStore.load(),
 				settings
 			}), [config.stateStore]),
-			children: /* @__PURE__ */ jsx(ModalRoot, { children: /* @__PURE__ */ jsx(AppShell, {}) })
+			children: /* @__PURE__ */ jsx(SafeModeProvider, { children: /* @__PURE__ */ jsx(ModalRoot, { children: /* @__PURE__ */ jsx(AppShell, {}) }) })
 		})
 	});
 }
@@ -1527,8 +2782,54 @@ function AppShell() {
 	const modal = useModal();
 	const config = useConfig();
 	const { settings } = useSettings();
+	const queue = useSafeModeQueue();
+	const { requestApproval, resolveHead, denyAll } = useSafeModeActions();
 	const { providers: providerRegistry, preset, store, stateStore, modelsFor, resumeProvider, initialPicked, initialState } = config;
 	const lastResumedSessionId = initialState.lastSessionId;
+	const dataDir = config.paths.dir;
+	const safeModeEnabledRef = useRef(settings.safeMode);
+	useEffect(() => {
+		safeModeEnabledRef.current = settings.safeMode;
+	}, [settings.safeMode]);
+	const [projectDir] = useState(() => process.cwd());
+	const safelistRef = useRef(null);
+	const readSafelist = useCallback(() => {
+		if (safelistRef.current === null) safelistRef.current = getSafelist(dataDir, projectDir);
+		return safelistRef.current;
+	}, [dataDir, projectDir]);
+	useEffect(() => {
+		safelistRef.current = null;
+	}, [dataDir, projectDir]);
+	/**
+	* Single source of truth for "should this call execute?". Returns true to
+	* let the call through, false to refuse it. Handles three short-circuits:
+	*
+	*   - Safe-mode globally off → always allow.
+	*   - Call covered by the project safelist or the implicit read-only set
+	*     → always allow without prompting.
+	*   - Otherwise → prompt the user and act on their decision (including
+	*     persisting a new safelist entry on "accept + safelist").
+	*
+	* Wired into the parent agent via `tool:gate` / `mcp:tool:gate`, and to
+	* every subagent (transitively, for free) via `child:tool:gate` /
+	* `child:mcp:tool:gate` — see the bubble in `src/tools/spawn.ts`.
+	*/
+	const gateDecision = useCallback(async (tool, input) => {
+		if (!safeModeEnabledRef.current) return true;
+		if (isOnSafelist(readSafelist(), tool, input)) return true;
+		const decision = await requestApproval(tool, input);
+		if (decision === "deny") return false;
+		if (decision === "accept-safelist") {
+			addToSafelist(dataDir, projectDir, suggestSafelistEntry(tool, input));
+			safelistRef.current = null;
+		}
+		return true;
+	}, [
+		dataDir,
+		projectDir,
+		requestApproval,
+		readSafelist
+	]);
 	const [screen, setScreen] = useState(() => {
 		if (!resumeProvider) return "auth";
 		return lastResumedSessionId ? "chat" : "sessions";
@@ -1544,40 +2845,56 @@ function AppShell() {
 	const sessionRef = useRef(null);
 	const stream = useStreamBuffer(setEvents);
 	const makePicked = useCallback((provider, modelId) => {
-		const factory = providerRegistry[provider.key];
-		if (!factory) return null;
+		const descriptor = providerRegistry[provider.key];
+		if (!descriptor) return null;
 		const remembered = initialState.lastModelByProvider?.[provider.key];
 		return {
 			provider,
-			model: modelId ?? remembered ?? factory().meta.defaultModel
+			model: modelId ?? remembered ?? descriptor.defaultModel ?? descriptor.factory().meta.defaultModel
 		};
 	}, [providerRegistry, initialState]);
 	const buildAgent = useCallback((session, key) => {
-		const factory = providerRegistry[key];
-		if (!factory) throw new Error(`No provider registered for key "${key}"`);
+		const descriptor = providerRegistry[key];
+		if (!descriptor) throw new Error(`No provider registered for key "${key}"`);
 		const agent = createAgent({
 			...preset,
-			provider: factory(),
+			provider: descriptor.factory(),
 			session
 		});
+		const applyGate = async (name, input, ctx) => {
+			if (ctx.block) return;
+			if (!await gateDecision(name, input)) {
+				ctx.block = true;
+				ctx.reason = "User denied this tool call";
+			}
+		};
+		agent.hooks.hook("tool:gate", (ctx) => applyGate(ctx.name, ctx.input, ctx));
+		agent.hooks.hook("child:tool:gate", (ctx) => applyGate(ctx.name, ctx.input, ctx));
+		agent.hooks.hook("mcp:tool:gate", (ctx) => applyGate(ctx.displayName, ctx.input, ctx));
+		agent.hooks.hook("child:mcp:tool:gate", (ctx) => applyGate(ctx.displayName, ctx.input, ctx));
 		agent.hooks.hook("stream:thinking", ({ delta }) => stream.queueStreamDelta("thinking", delta));
 		agent.hooks.hook("stream:text", ({ delta }) => stream.queueStreamDelta("markdown", delta));
 		agent.hooks.hook("tool:before", ({ name, input }) => {
 			stream.appendImmediate({
 				kind: "tool",
-				text: toolCallPreview(name, input)
+				text: toolCallPreview(name, input),
+				tool: name
 			});
 		});
-		agent.hooks.hook("tool:after", ({ result }) => {
+		agent.hooks.hook("tool:after", ({ name, result }) => {
+			const raw = toolResultText(result);
+			const text = name === "spawn" ? stripSpawnTokensLine(raw) : raw;
 			stream.appendImmediate({
 				kind: "tool-result",
-				text: toolResultText(result)
+				text,
+				tool: name
 			});
 		});
-		agent.hooks.hook("mcp:tool:after", ({ result }) => {
+		agent.hooks.hook("mcp:tool:after", ({ displayName, result }) => {
 			stream.appendImmediate({
 				kind: "tool-result",
-				text: toolResultText(result)
+				text: toolResultText(result),
+				tool: displayName
 			});
 		});
 		agent.hooks.hook("turn:after", ({ usage }) => {
@@ -1597,7 +2914,7 @@ function AppShell() {
 			const tag = status === "aborted" ? "aborted" : status === "error" ? "error" : "done";
 			stream.appendImmediate({
 				kind: "spawn-end",
-				text: `${tag} · ${stats.totalIn} in / ${stats.totalOut} out`,
+				text: `${tag} ${formatTokenUsage(stats)}`,
 				childId: id,
 				depth: depth ?? 1
 			});
@@ -1626,14 +2943,16 @@ function AppShell() {
 			stream.appendImmediate({
 				kind: "tool",
 				text: toolCallPreview(name, input),
+				tool: name,
 				childId,
 				depth
 			});
 		});
-		agent.hooks.hook("child:tool:after", ({ result, childId, depth }) => {
+		agent.hooks.hook("child:tool:after", ({ name, result, childId, depth }) => {
 			stream.appendImmediate({
 				kind: "tool-result",
 				text: toolResultText(result),
+				tool: name,
 				childId,
 				depth
 			});
@@ -1645,7 +2964,8 @@ function AppShell() {
 	}, [
 		providerRegistry,
 		preset,
-		stream
+		stream,
+		gateDecision
 	]);
 	const refreshSessions = useCallback(async () => {
 		const list = await listSessionMeta(store);
@@ -1666,7 +2986,7 @@ function AppShell() {
 		});
 		sessionRef.current = session;
 		agentRef.current = buildAgent(session, key);
-		setEvents(eventsFromTurns(session.turns));
+		setEvents(eventsFromTurns(session.turns, session.runs));
 		setLastInputTokens(lastContextSizeFromTurns(session.turns));
 		setCurrentSession({
 			id: session.id,
@@ -1740,8 +3060,9 @@ function AppShell() {
 		setScreen("sessions");
 	}, [refreshSessions]);
 	const onAbort = useCallback(() => {
+		denyAll();
 		agentRef.current?.abort();
-	}, []);
+	}, [denyAll]);
 	const onPickModel = useCallback((modelId) => {
 		setPicked((prev) => {
 			if (!prev) return prev;
@@ -1799,10 +3120,15 @@ function AppShell() {
 		events.length,
 		stream
 	]);
+	const onReauth = useCallback(() => {
+		modal.close();
+		setScreen("auth");
+	}, [modal]);
+	const pendingApproval = queue[0] ?? null;
 	useKeyboard((key) => {
 		if (modal.isOpen) return;
 		if (key.ctrl && key.name === "," && screen !== "auth") {
-			modal.open(/* @__PURE__ */ jsx(SettingsModal, {}));
+			modal.open(/* @__PURE__ */ jsx(SettingsModal, { actions: { onReauth } }));
 			return;
 		}
 		if (key.ctrl && key.name === "m" && screen === "chat" && picked && !busy) {
@@ -1814,23 +3140,30 @@ function AppShell() {
 			return;
 		}
 		if (key.name !== "escape") return;
-		if (busy) return onAbort();
+		if (busy || pendingApproval) return onAbort();
 		if (screen === "chat") return onOpenSessions();
 		if (screen === "sessions") {
 			if (currentSession) setScreen("chat");
 			else renderer.destroy();
 			return;
 		}
+		if (picked) {
+			setScreen(currentSession ? "chat" : "sessions");
+			return;
+		}
 		renderer.destroy();
 	});
-	const hints = useMemo(() => buildHints(screen, busy, currentSession), [
+	const hints = useMemo(() => buildHints(screen, busy, !!pendingApproval, currentSession), [
 		screen,
 		busy,
+		pendingApproval,
 		currentSession
 	]);
 	const contextUsage = useMemo(() => {
 		if (screen !== "chat" || !picked) return null;
-		const max = modelsFor(picked.provider.key).find((m) => m.id === picked.model)?.contextWindow ?? getContextWindow(picked.provider.key, picked.model);
+		const descriptor = providerRegistry[picked.provider.key];
+		if (!descriptor) return null;
+		const max = getContextWindow(descriptor, picked.model);
 		return max ? {
 			used: lastInputTokens,
 			max
@@ -1839,7 +3172,7 @@ function AppShell() {
 		screen,
 		picked,
 		lastInputTokens,
-		modelsFor
+		providerRegistry
 	]);
 	useEffect(() => () => {
 		teardown();
@@ -1869,7 +3202,9 @@ function AppShell() {
 					busy,
 					settings,
 					onSubmit: onSubmitPrompt,
-					session: currentSession
+					session: currentSession,
+					pending: pendingApproval,
+					onApproval: resolveHead
 				})
 			]
 		}), /* @__PURE__ */ jsx(Footer, {
@@ -1879,7 +3214,21 @@ function AppShell() {
 		})]
 	});
 }
-function buildHints(screen, busy, currentSession) {
+function buildHints(screen, busy, pending, currentSession) {
+	if (pending) return [
+		{
+			key: "↑↓",
+			label: "navigate"
+		},
+		{
+			key: "↵",
+			label: "select"
+		},
+		{
+			key: "esc",
+			label: "abort run"
+		}
+	];
 	if (busy) return [{
 		key: "esc",
 		label: "abort"
@@ -1971,21 +3320,26 @@ let runTuiInvoked = false;
 * to `runTui({ storageDir, prefix })`.
 *
 * ```ts
-* import { runTui } from 'zidane/tui'
+* import { BUILTIN_PROVIDERS, runTui } from 'zidane/tui'
 * import { createRemoteStore } from 'zidane/session'  // for the `store` option
 *
 * await runTui()                                       // ~/.zidane/sessions.db + state.json
 * await runTui({ prefix: '.myapp' })                   // ~/.myapp/...
 * await runTui({ storageDir: '/data', prefix: 'myapp' })
-* await runTui({ providers: { custom: () => myProvider() } })
+* await runTui({ providers: { ...BUILTIN_PROVIDERS, mine: myDescriptor } })
 * await runTui({ store: createRemoteStore({ url: '…' }) })
-* await runTui({ models: { anthropic: [{ id: 'claude-foo', contextWindow: 200_000 }] } })
 * ```
 */
 async function runTui(options = {}) {
 	if (runTuiInvoked) throw new Error("runTui() can only be invoked once per process. Compose `<App config={resolveConfig(...)} />` against your own renderer if you need to run multiple TUIs in the same lifetime.");
 	runTuiInvoked = true;
 	await init();
+	try {
+		heal("");
+	} catch (err) {
+		const cause = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`[zidane/tui] md4x WASM probe failed: ${cause}\n`);
+	}
 	const config = resolveConfig(options);
 	let done = () => {};
 	const exited = new Promise((resolve) => {
@@ -1999,6 +3353,6 @@ async function runTui(options = {}) {
 	process.exit(0);
 }
 //#endregion
-export { App, AuthScreen, COLOR, ChatScreen, ConfigProvider, DEFAULT_SETTINGS, FACTORIES, Footer, MD_STYLE, Modal, ModalRoot, ModelPickerModal, PI_PROVIDER_ID, SELECT_THEME, SessionsScreen, SettingsModal, SettingsProvider, Spinner, Transcript, ageString, createStateStore, createTuiStore, detectAuth, envKeyFor, eventsFromTurns, finalizeStreamingMarkdown, finalizeStreamingMarkdownForOwner, fmtTokens, getContextWindow, lastContextSizeFromTurns, listSessionMeta, loadState, marginTopFor, onInputSubmit, resolveConfig, runTui, saveState, shortId, titleFromTurns, toolCallPreview, toolResultText, turnContextSize, useConfig, useModal, useModalAwareFocus, useSettings, useStreamBuffer };
+export { App, AuthScreen, BUILTIN_PROVIDERS, COLOR, ChatScreen, ConfigProvider, DEFAULT_SETTINGS, Footer, IMPLICITLY_SAFE_TOOLS, MD_STYLE, Modal, ModalRoot, ModelPickerModal, SELECT_THEME, SafeModeProvider, SessionsScreen, SettingsModal, SettingsProvider, Spinner, Transcript, addToSafelist, ageString, anthropicDescriptor, applyApiKeyEnv, cerebrasDescriptor, createStateStore, createTuiStore, credKeyOf, credentialsPath, detectAuth, eventsFromTurns, finalizeStreamingMarkdown, finalizeStreamingMarkdownForOwner, fmtTokens, getContextWindow, getSafelist, isOnSafelist, lastContextSizeFromTurns, listSessionMeta, loadState, marginTopFor, matchesSafelistEntry, modelsForDescriptor, onInputSubmit, openaiDescriptor, openrouterDescriptor, piIdOf, projectsFilePath, readCredentials, readProjects, readProviderCredential, removeProviderCredential, resolveConfig, runOAuthLogin, runTui, saveState, setProviderCredential, shortId, suggestSafelistEntry, supportsOAuth, titleFromTurns, toolCallPreview, toolResultText, turnContextSize, useConfig, useModal, useModalAwareFocus, useSafeModeActions, useSafeModeQueue, useSettings, useStreamBuffer, writeCredentials, writeProjects };
 
 //# sourceMappingURL=tui.js.map