@lucascouts/claude-agent-tui 0.5.1 → 0.6.0

package/dist/acp-agent.js

@@ -1,5 +1,5 @@
 import { AgentSideConnection, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
-import { deleteSession, listSessions, } from "@anthropic-ai/claude-agent-sdk";
+import { deleteSession, getSessionInfo, listSessions, } from "@anthropic-ai/claude-agent-sdk";
 import { randomUUID } from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -24,8 +24,19 @@ import { guardEvent } from "./billing/entrypoint-guard.js";
 import { usageUpdatesFor } from "./usage.js";
 import { createTurnResolver } from "./end-of-turn.js";
 import { sendPrompt } from "./engine-pty.js";
-import { MODEL_CATALOG, DEFAULT_MODEL_INFO } from "./model-catalog.js";
+import { MODEL_CATALOG, DEFAULT_MODEL_INFO, ULTRACODE_EFFORT, ULTRACODE_EFFORT_LEVEL, ULTRACODE_EFFORT_LABEL, } from "./model-catalog.js";
+// Story 060 (R2.2/R2.3/R3.2) — the declarative spawn-time complement to the live ultracode keyword:
+// toggle the {ultracode,ultracodeKeywordTrigger} keys in the gate's per-session scratch settings file
+// (preserving the hook + every other key). Lives in the gate's settings-writer so it reuses durableWrite.
+import { applyUltracodeSettings } from "./gate/settings-writer.js";
+import { discoverAgents } from "./agent-catalog.js";
 import { setupSessionGate } from "./permissions/gate-wiring.js";
+// Story 057 / Task 2.3 — MCP scratch-file lifecycle (translate ACP servers → claude `--mcp-config`
+// JSON, durable 0600 write, idempotent teardown removal). Mirrors the gate's settings-scratch
+// lifecycle: written BEFORE spawn, threaded as a flag, removed on failure + teardown — with the added
+// re-spawn regeneration (R2.4). The module never logs the scratch contents/path-with-secrets (R2.3).
+import { translateMcpServers, writeMcpScratch, removeMcpScratch } from "./mcp-config-writer.js";
+import { materializeImage, cleanupMaterializedImages } from "./image-input.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
 const MAX_TITLE_LENGTH = 256;
 function sanitizeTitle(text) {
@@ -98,6 +109,14 @@ export async function defaultStartEngine(args) {
             // SAME sessionId carrying its mode/effort flags through the resume argv (buildResumeArgv).
             permissionMode: args.permissionMode,
             effortLevel: args.effortLevel,
+            // Story 056 (R3.2): an agent-selecting re-spawn carries the persona through too (--agent).
+            agent: args.agent,
+            // Story 057 (R1.3/R3.1): re-thread the resolved additional-directory list so an in-place
+            // re-spawn keeps the SAME `--add-dir` scope (this resume call also serves respawnSession).
+            additionalDirectories: args.additionalDirectories,
+            // Story 057 (R2.2/R2.4): re-thread the CURRENT MCP scratch path so the re-spawned `claude`
+            // carries `--mcp-config "<file>"`; respawnSession regenerates the scratch before this call.
+            mcpConfigFile: args.mcpConfigFile,
         });
         if (args.inPlaceRespawn) {
             // === SEAM(046 R3.4 LIVE FIX): DEFER discovery for an in-place re-spawn ======================
@@ -169,13 +188,26 @@ export async function defaultStartEngine(args) {
         baseEnv: args.baseEnv,
         sessions: args.sessions,
         spawn: args.spawn,
+        // Story 056 v4: a FRESH in-place re-spawn (a pre-interaction selector change) reuses the session's
+        // existing id; a normal createSession passes none here (inPlaceRespawn absent) → fresh randomUUID.
+        sessionId: args.inPlaceRespawn ? args.sessionId : undefined,
         // Story 046 (R3.2/R2.2): the seeded permission mode + effort → `--permission-mode`/`--effort` on
         // the fresh spawn (non-"default" only; "default"/undefined keep the byte-for-byte pre-046 argv).
         permissionMode: args.permissionMode,
         effortLevel: args.effortLevel,
+        // Story 056 (R3.2): the agent-selecting re-spawn's persona → `--agent "<name>"` (non-"default").
+        agent: args.agent,
         // Story 034 (§9): the per-session gate scratch settings, already on disk — claude reads them at
         // startup, so the hook gates the FIRST tool call (blocker c). Absent → ungated (pre-034) spawn.
         settingsFile: args.settingsFile,
+        // Story 057 (R1.3/R3.1): the resolved additional-directory list → one `--add-dir "<dir>"` per
+        // safe entry on the fresh interactive spawn (always-on; engine sanitizes per-dir). Empty/absent
+        // keeps the pre-057 argv byte-for-byte.
+        additionalDirectories: args.additionalDirectories,
+        // Story 057 (R2.2): the fork's MCP scratch path → `--mcp-config "<file>"` (never `--strict`,
+        // R2.2 merge); written on disk BEFORE this call so claude reads it at startup. Absent (no MCP
+        // servers declared) keeps the pre-057 argv byte-for-byte.
+        mcpConfigFile: args.mcpConfigFile,
     });
     // Hand the engine the cancellation handle for the background poll. STORE-ONLY here — the
     // cleanup→`.abort()` wiring (so tearing a never-interacted session down cancels this dangling poll)
@@ -228,13 +260,31 @@ export async function defaultStartEngine(args) {
         cwd: args.cwd,
     };
 }
+/**
+ * Story 057 (R1.3/R3.1): resolve the session's additional-directory list from the request — the
+ * top-level `additionalDirectories` (the ACP field), else the legacy `_meta.additionalRoots`, else
+ * `[]`. ALWAYS-ON (no `FORK_*` opt-in gate). Both the fingerprint and the spawn must resolve through
+ * THIS single helper so the stored fingerprint and the recomputed one agree for identical inputs
+ * (the compare path in {@link getOrCreateSession} vs the store path in {@link createSession}).
+ */
+function resolveAdditionalDirs(p) {
+    // `_meta` is the loose ACP index-signature bag (`{ [k]: unknown } | null`); the additionalRoots
+    // fallback lives at the `NewSessionMeta` top level, so narrow through that shape (the same cast the
+    // newSession handler uses for `_meta.claudeCode.options`) rather than introducing `any`.
+    const roots = p._meta?.additionalRoots;
+    return p.additionalDirectories ?? roots ?? [];
+}
 /** Compute a stable fingerprint of the session-defining params so we can
  *  detect when a loadSession/resumeSession call requires tearing down and
  *  recreating the underlying Query process.  MCP servers are sorted by name
- *  so that ordering differences don't trigger unnecessary recreations. */
+ *  so that ordering differences don't trigger unnecessary recreations.
+ *  Story 057 (R1.3): the resolved additional-directory set is folded in (SORTED, so input order is
+ *  irrelevant) — a changed `--add-dir` set therefore changes the fingerprint and forces a re-spawn,
+ *  while a reordered-but-equal set does not. */
 function computeSessionFingerprint(params) {
     const servers = [...(params.mcpServers ?? [])].sort((a, b) => a.name.localeCompare(b.name));
-    return JSON.stringify({ cwd: params.cwd, mcpServers: servers });
+    const dirs = [...resolveAdditionalDirs(params)].sort();
+    return JSON.stringify({ cwd: params.cwd, mcpServers: servers, additionalDirectories: dirs });
 }
 // === SEAM(012/023): the engine binary is resolved from the user's PATH. After the 023 rewrite,
 // createSession no longer passes the SDK `pathToClaudeCodeExecutable`; the PTY engine (story 013)
@@ -518,6 +568,12 @@ export class ClaudeAcpAgent {
         // OFF at this seam so directly-constructed test agents spin no gate unless they opt in.
         this.gateEnabled = deps.gate ?? false;
         this.gateOptions = deps.gateOptions;
+        // Story 056 (R3.2): main-thread agent-persona discovery — defaults to the glob-only
+        // discoverAgents; tests inject an in-memory fake so the `agent` surface is hermetic.
+        this.discoverAgents = deps.discoverAgents ?? discoverAgents;
+        // Story 056 (#812): end-of-turn session_info_update title source — defaults to the pure SDK
+        // getSessionInfo; tests inject an in-memory fake so the push is hermetic (no real ~/.claude read).
+        this.getSessionInfo = deps.getSessionInfo ?? getSessionInfo;
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
@@ -746,7 +802,19 @@ export class ClaudeAcpAgent {
         // SYNCHRONOUSLY before the `await promise`, so the PTY write is committed (and the detector is
         // reachable by the live pump and the cancel path) the instant the turn begins.
         // (1) Assemble the PTY text payload from the ContentBlock[] (Task 1 rewrote this to return text).
-        const payload = promptToClaude(params, this.logger);
+        // Story 058 (R2.1/R2.2): pass a fresh sink so every image promptToClaude materializes is recorded
+        // on the session BEFORE the prompt is sent — so the turn-settle + teardown cleanups can unlink it
+        // and leave no orphan temp image.
+        const turnTempImagePaths = [];
+        // Bind the sink to the session BEFORE calling promptToClaude (same array by reference): even if a
+        // future promptToClaude were to throw mid-materialize, the teardown cleanup still reaches the paths.
+        sessionRecord.turnTempImagePaths = turnTempImagePaths;
+        const payload = promptToClaude(params, this.logger, turnTempImagePaths);
+        // Story 060 (R2.2) — while ultracode is active, prefix the OUTGOING prompt with the `ultracode`
+        // keyword (the binary's per-turn Workflow opt-in). This is the LIVE activation that needs no
+        // re-spawn (Option A) and works pre- AND post-first-interaction; the scratch settings keys are the
+        // declarative spawn-time complement. NEVER emitted as a `/effort` value (R1.2).
+        const outgoing = sessionRecord.ultracodeActive ? `${ULTRACODE_EFFORT} ${payload}` : payload;
         // (2) Register the turn with the story-024 resolver: the detector that the live pump feeds, and
         // the awaitable that settles ONCE with { stopReason: mapStopReason(...) } on the terminal
         // boundary (or rejects on the watchdog). One shared `schedule` drives sendPrompt + the resolver.
@@ -754,6 +822,10 @@ export class ClaudeAcpAgent {
             schedule: this.schedule,
             sessionId: params.sessionId,
             logger: this.logger,
+            // Story 056 (#812): on a REAL end-of-turn boundary (never cancel, never watchdog), push the
+            // sanitized session title via session_info_update. `void` = fire-and-forget — the async method
+            // is never awaited, so it cannot delay the `return await promise` below (R5.1).
+            onTurnResolved: () => void this.emitSessionTitleUpdate(params.sessionId),
         });
         sessionRecord.turnDetector = detector;
         sessionRecord.turnCancel = cancel;
@@ -762,12 +834,15 @@ export class ClaudeAcpAgent {
         // On a PTY-write failure, reject the pending prompt via the throw — markCancelled clears the
         // detector's Δt + watchdog timers so nothing is left hung — rather than swallowing the error.
         try {
-            sendPrompt(sessionRecord.pty, payload, this.schedule);
+            sendPrompt(sessionRecord.pty, outgoing, this.schedule);
         }
         catch (e) {
             detector.markCancelled();
             sessionRecord.turnDetector = undefined;
             sessionRecord.turnCancel = undefined;
+            // Story 058 (R2.1): the turn never reached the model — drop its materialized temp images now.
+            cleanupMaterializedImages(sessionRecord.turnTempImagePaths);
+            sessionRecord.turnTempImagePaths = undefined;
             throw e;
         }
         // (4) Resolve ONLY via the detector's terminal boundary. The pump feeds raw JSONL messages to
@@ -778,6 +853,10 @@ export class ClaudeAcpAgent {
         finally {
             sessionRecord.turnDetector = undefined;
             sessionRecord.turnCancel = undefined;
+            // Story 058 (R2.1/R2.2): the turn is over — resolved OR cancelled (both settle this same
+            // promise, per the comment below) — so unlink the temp images materialized for it. No orphans.
+            cleanupMaterializedImages(sessionRecord.turnTempImagePaths);
+            sessionRecord.turnTempImagePaths = undefined;
             // Story 044 (R2.3): the turn is over — resolved OR cancelled, both settle this same promise —
             // so the in-turn sub-agent watcher dies with it (covers turn-resolve AND markCancelled paths).
             sessionRecord.subagentWatcher?.stop();
@@ -786,6 +865,36 @@ export class ClaudeAcpAgent {
             this.flushPendingControlInjections(sessionRecord);
         }
     }
+    /**
+     * Story 056 (#812) — push the sanitized session title to the client via `session_info_update`,
+     * fired (fire-and-forget) by the story-024 end-of-turn boundary ONLY (never on cancel/watchdog,
+     * via {@link TurnResolverOptions.onTurnResolved}). DEDUPED against {@link Session.lastEmittedTitle}
+     * so an unchanged title is not re-emitted, and silent when `getSessionInfo` finds no transcript /
+     * the title is empty. Every error is swallowed and logged — this MUST NEVER reject the turn (it is
+     * never awaited in `prompt()`), and a slow/never-resolving reader cannot delay the PromptResponse.
+     */
+    async emitSessionTitleUpdate(sessionId) {
+        const session = this.sessions[sessionId];
+        if (!session)
+            return;
+        try {
+            const info = await this.getSessionInfo(sessionId, { dir: session.cwd });
+            if (!info)
+                return; // no transcript / not found → nothing to push
+            const title = sanitizeTitle(info.summary);
+            if (!title || title === session.lastEmittedTitle)
+                return; // dedup + never push empty
+            session.lastEmittedTitle = title;
+            await this.client.sessionUpdate({
+                sessionId,
+                update: { sessionUpdate: "session_info_update", title },
+            });
+        }
+        catch (err) {
+            // Swallow — never reject the turn (this method is never awaited from prompt()).
+            this.logger.error("[acp-agent] session title push (#812) failed:", err);
+        }
+    }
     async cancel(params) {
         const sessionRecord = this.sessions[params.sessionId];
         if (!sessionRecord) {
@@ -832,6 +941,12 @@ export class ClaudeAcpAgent {
             return;
         }
         await this.cancel({ sessionId });
+        // Story 058 (R2.1): idempotent backstop — unlink any temp images that survived a turn whose
+        // prompt-finally never ran (e.g. a session torn down between turns or before the finally fired).
+        // The cancel above may have already cleared them; cleanupMaterializedImages never throws on a
+        // gone file, so a double-cleanup is a safe no-op.
+        cleanupMaterializedImages(session.turnTempImagePaths);
+        session.turnTempImagePaths = undefined;
         // Story 044 (R2.3): stop the sub-agent watcher on teardown — idempotent with the prompt-finally stop.
         session.subagentWatcher?.stop();
         session.subagentWatcher = undefined;
@@ -857,6 +972,12 @@ export class ClaudeAcpAgent {
         if (session.gate) {
             await session.gate.teardown();
         }
+        // Story 057 (R2.3): remove the MCP scratch on teardown so no secret-bearing file (auth headers/
+        // env) is orphaned. Idempotent + never throws + never logs the contents; a no-op when the session
+        // declared no MCP servers (mcpConfigFile undefined) or after a re-spawn already swapped/removed it.
+        if (session.mcpConfigFile) {
+            await removeMcpScratch(session.mcpConfigFile);
+        }
         this.engines.delete(sessionId);
         delete this.sessions[sessionId];
     }
@@ -931,17 +1052,29 @@ export class ClaudeAcpAgent {
         const resolvedValue = validValue.value;
         if (params.configId === "mode") {
             await this.applySessionMode(params.sessionId, resolvedValue);
+            // Story 056 v4 (OPTIMISTIC notify) — for a CYCLABLE mode, push `current_mode_update` to the panel
+            // BEFORE driving the (slower) closed-loop Shift+Tab cycle, so the selector reflects the choice
+            // INSTANTLY instead of waiting out the cycle. Safe: the permission gate reads the mode from the
+            // transcript (tail-as-truth), NOT this notification, and a cyclable drive never re-spawns (no R3.7
+            // rollback to honor). dontAsk/bypass (a re-spawn that CAN fail) keep the notify AFTER the drive so
+            // a failed switch does not leave the panel showing a mode that never applied.
+            const cyclable = CYCLABLE_MODES.has(resolvedValue);
+            if (cyclable) {
+                await this.client.sessionUpdate({
+                    sessionId: params.sessionId,
+                    update: { sessionUpdate: "current_mode_update", currentModeId: resolvedValue },
+                });
+            }
             // Bug A fix (Story 046 R3) — Zed sends mode changes via set_config_option(configId:"mode"), so
             // the DRIVE must happen HERE too. This path used to only validate (read-only), leaving claude
             // stuck on its spawn mode — the live permission mode never changed (bypass/acceptEdits no-op'd).
             await this.driveModeIntoTui(params.sessionId, session, resolvedValue);
-            await this.client.sessionUpdate({
-                sessionId: params.sessionId,
-                update: {
-                    sessionUpdate: "current_mode_update",
-                    currentModeId: resolvedValue,
-                },
-            });
+            if (!cyclable) {
+                await this.client.sessionUpdate({
+                    sessionId: params.sessionId,
+                    update: { sessionUpdate: "current_mode_update", currentModeId: resolvedValue },
+                });
+            }
         }
         // === SEAM(023→046) Group 1: the dropped SDK `query.setModel` is replaced by a PTY side-channel.
         // `/model <alias>` is a LOCAL TUI command (no assistant turn, no stop_reason) — inject it as a
@@ -953,10 +1086,19 @@ export class ClaudeAcpAgent {
             this.applyModelSwitch(session, resolvedValue);
         }
         else if (params.configId === "effort") {
-            // Story 046 (R2.2): Probe B verdict — effort has no live mid-session path, so an effort change
-            // re-spawns in place with `--effort <level>` (idle-guarded, R3.7 failure path). On throw, the
-            // applyConfigOptionValue below is skipped so the prior currentValue stays unchanged.
-            await this.applyEffortChange(params.sessionId, session, resolvedValue);
+            // Story 056 v4: effort is now a LIVE `/effort <level>` injection (claude 2.1.195 has the command),
+            // mirroring /model — no re-spawn, works before the first interaction. Mid-turn it defers; it never
+            // throws, so applyConfigOptionValue below always commits the new currentValue (optimistic, like
+            // /model). The flag path stays only to seed/preserve effort across mode/agent re-spawns.
+            // Story 060 (R2/R3.2): route through applyEffortSelection so the `ultracode` sentinel is
+            // special-cased (activate keyword + scratch keys + /effort xhigh) while real levels deselect it.
+            await this.applyEffortSelection(session, resolvedValue);
+        }
+        else if (params.configId === "agent") {
+            // Story 056 (R3.3/R3.4): the agent persona has no live mid-session path either — apply it by an
+            // in-place re-spawn carrying `--agent` (mirrors effort). On throw, applyConfigOptionValue below is
+            // skipped so the prior currentValue stays unchanged (R3.7-style failure path).
+            await this.applyAgentChange(params.sessionId, session, resolvedValue);
         }
         await this.applyConfigOptionValue(params.sessionId, session, params.configId, resolvedValue);
         return { configOptions: session.configOptions };
@@ -1066,6 +1208,12 @@ export class ClaudeAcpAgent {
             session.pendingModelInjection = undefined;
             this.injectModelCommand(session, alias);
         }
+        // Story 056 v4 — flush a deferred effort `/effort <level>` injection too (last-write-wins).
+        const effort = session.pendingEffortInjection;
+        if (effort !== undefined) {
+            session.pendingEffortInjection = undefined;
+            this.injectEffortCommand(session, effort);
+        }
     }
     /**
      * Story 046 (R3.3, design §6b) — drive the TUI to `target` with closed-loop raw Shift+Tab. Writes
@@ -1126,7 +1274,9 @@ export class ClaudeAcpAgent {
      * Order is load-bearing for R3.7: re-spawn FIRST, and swap in + tear down the old PTY ONLY once the new
      * one is live — so a failed re-spawn leaves the prior PTY/currentValue intact (never
      * torn-down-without-replacement). Re-spawn runs only while idle, so the old PTY has no pending turn to
-     * double-resolve. The `respawning` latch defers concurrent selector changes (R3.8).
+     * double-resolve. The `respawning` latch defers concurrent selector changes (R3.8). Re-spawning for
+     * ONE selector preserves the OTHER two (mode / effort / agent — Story 056 added agent) by reading
+     * their current values, so the resume argv always carries all three flags.
      */
     async respawnSession(sessionId, session, change) {
         // Story 046 (R3.4 LIVE FIX guard): a re-spawn reattaches via `claude --resume <id>`, which needs the
@@ -1136,33 +1286,75 @@ export class ClaudeAcpAgent {
         // once. The user/Zed retries after the first prompt; a boot-time default_config_options dontAsk/
         // bypass therefore stays at the fresh spawn's mode (use a fresh-spawn --permission-mode seed for
         // start-in-bypass, a documented follow-up). The OTHER selector's currentValue is left unchanged.
-        if (!session.interacted) {
-            throw new Error("Cannot switch to a re-spawn mode/effort before the first interaction (no transcript to resume yet); send a prompt first, then switch.");
-        }
+        // Story 056 v4 — before the first interaction there is NO transcript to `--resume`, so the re-spawn
+        // is FRESH (reusing the SAME sessionId — LIVE-VERIFIED: claude accepts a reused --session-id once the
+        // prior PTY exits). After the first interaction, `--resume` reattaches the transcript (R3.4). This is
+        // what lets the agent/effort/mode selectors apply BEFORE the first prompt — the live gap the user hit
+        // (previously this threw and the selector silently reverted). NOTE: effort no longer reaches here
+        // (it is a live `/effort` inject now); the fresh path serves agent and the dontAsk/bypass modes.
+        const fresh = !session.interacted;
         session.respawning = true;
         try {
             const oldEngine = session.engine;
-            // Preserve the OTHER selector's current value so re-spawning for one (mode OR effort) does not
-            // reset the other — the resume argv carries both flags.
+            // Preserve the OTHER selectors' current values so re-spawning for one (mode, effort, OR agent)
+            // does not reset the others — the argv carries all three flags. There are three selectors now
+            // (Story 056 added agent): a mode re-spawn keeps effort+agent, an agent re-spawn keeps mode+effort.
             const permissionMode = change.permissionMode ?? session.modes.currentModeId;
-            const effortLevel = change.effortLevel ?? this.currentEffort(session);
+            // Story 060 (R1.2 fix): the preserved currentEffort can be the `ultracode` SENTINEL (it is the
+            // committed configOption value while active). It is NOT a real `--effort` enum value — the binary
+            // rejects `--effort ultracode` (story-060 probe), so a mode/agent re-spawn-while-active would
+            // silently degrade effort to default. Map the sentinel to its real component (xhigh) at THIS spawn
+            // seam (it feeds BOTH buildClaudeCmd and buildResumeArgv); the scratch `ultracode:true` already
+            // carries the orchestration activation declaratively at spawn.
+            const preservedEffort = change.effortLevel ?? this.currentEffort(session);
+            const effortLevel = preservedEffort === ULTRACODE_EFFORT ? ULTRACODE_EFFORT_LEVEL : preservedEffort;
+            const agent = change.agent ?? this.currentAgent(session);
+            // Story 057 (R2.4): REGENERATE the MCP scratch so the re-spawned `claude` reads the CURRENT MCP
+            // config at startup (its `--mcp-config` is bound only at spawn). Re-translate from the stored raw
+            // ACP servers (kept faithful to the original request). Write the NEW scratch BEFORE removing the
+            // OLD so a write failure leaves the prior scratch intact (the still-running old PTY already read
+            // its config at startup, so removing the old file does not disturb it). removeMcpScratch is
+            // idempotent + never throws + never logs the contents (R2.3).
+            if (session.mcpServers && session.mcpServers.length > 0) {
+                const old = session.mcpConfigFile;
+                session.mcpConfigFile = await writeMcpScratch(translateMcpServers(session.mcpServers));
+                if (old)
+                    await removeMcpScratch(old);
+            }
+            // FRESH re-spawn (pre-interaction): retire the old fresh PTY FIRST to free the reused sessionId —
+            // there is no transcript to preserve. RESUME re-spawn: keep the R3.7 order (bring the new PTY up
+            // BEFORE retiring the old, so a failed re-spawn leaves the prior PTY + currentValue intact).
+            if (fresh) {
+                oldEngine?.cleanup();
+                oldEngine?.kill();
+            }
             // Re-spawn through the SAME startEngine seam createSession uses, reusing the sessionId so the
-            // transcript is reattached (R3.4); the flags flow into the flag-carrying resume argv.
+            // transcript is reattached on resume (R3.4) or freshly created on the pre-interaction path; the
+            // flags flow into the flag-carrying spawn argv (fresh `buildClaudeCmd` or `buildResumeArgv`).
             const started = await this.startEngine({
                 sessionId,
                 cwd: session.cwd,
-                resume: true,
-                // Story 046 (R3.4 LIVE FIX): an in-place re-spawn may run before the first interaction (boot
-                // bypass), so DEFER discovery instead of the 2000ms fatal watchdog — see defaultStartEngine.
+                resume: !fresh,
+                // Story 046 (R3.4 LIVE FIX): an in-place re-spawn may run before the first interaction, so DEFER
+                // discovery instead of the 2000ms fatal watchdog — see defaultStartEngine.
                 inPlaceRespawn: true,
                 permissionMode,
                 effortLevel,
+                agent,
+                // Story 057 (R1.3/R3.1): re-thread the SAME `--add-dir` scope into the re-spawn (sub-task 1.2
+                // wired only the fresh createSession path; the in-place re-spawn must preserve it too).
+                additionalDirectories: session.additionalDirectories,
+                // Story 057 (R2.4): the freshly-regenerated MCP scratch path (see above) → `--mcp-config` on
+                // the re-spawned `claude`, so it carries the current MCP config.
+                mcpConfigFile: session.mcpConfigFile,
                 sessions: this.engines,
                 onEvent: (sid) => void this.pumpUpdates(sid),
             });
-            // New PTY is live — only now retire the old one (idle ⇒ no pending turn to double-resolve) and swap.
-            oldEngine?.cleanup();
-            oldEngine?.kill();
+            if (!fresh) {
+                // New PTY is live — only now retire the old one (idle ⇒ no pending turn to double-resolve).
+                oldEngine?.cleanup();
+                oldEngine?.kill();
+            }
             session.pty = started.pty;
             session.engine = started.engine;
             session.watcher = started.watcher;
@@ -1179,20 +1371,102 @@ export class ClaudeAcpAgent {
         const opt = session.configOptions.find((o) => o.id === "effort");
         return typeof opt?.currentValue === "string" ? opt.currentValue : undefined;
     }
+    /** Story 056 — the session's current agent configOption value (undefined when no agent option). */
+    currentAgent(session) {
+        const opt = session.configOptions.find((o) => o.id === "agent");
+        return typeof opt?.currentValue === "string" ? opt.currentValue : undefined;
+    }
+    /**
+     * Story 060 (R2/R3.2) — apply an effort-selector choice, special-casing the `ultracode` sentinel.
+     *
+     * Selecting `ultracode` (Option A — keyword + scratch, NO re-spawn): activate the session flag (which
+     * makes {@link prompt} prefix the OUTGOING prompt with the `ultracode` keyword — the binary's per-turn
+     * Workflow opt-in, the effective live mechanism), write the scratch ultracode keys via
+     * {@link applyUltracodeSettings} (the declarative spawn-time complement), and set the effort to xhigh
+     * through the SAME live `/effort` inject as every other level — NEVER `/effort ultracode` (R1.2). The
+     * `already` guard suppresses a redundant `/effort xhigh` re-inject when ultracode is re-selected while
+     * already active.
+     *
+     * Selecting a real level (or `default`) DEACTIVATES ultracode: clear the flag, remove the scratch keys,
+     * then apply that level through {@link applyEffortChange} (whose own no-op guard handles a same-level
+     * pick). `applyConfigOptionValue` (the caller, after this returns) commits the selector's currentValue,
+     * which for `ultracode` correctly stays `"ultracode"` (the {@link buildConfigOptions} `includes` guard
+     * keeps it valid across rebuilds).
+     */
+    async applyEffortSelection(session, value) {
+        if (value === ULTRACODE_EFFORT) {
+            const already = session.ultracodeActive === true;
+            session.ultracodeActive = true;
+            // The gate's per-session SCRATCH settings file is the spawn's `--settings` target; on a live
+            // Session it is reachable via `session.gate?.settingsPath` (the value createSession also threads
+            // into StartEngineArgs.settingsFile). Absent on a no-gate / resume / replay session → keyword-only.
+            const scratchPath = session.gate?.settingsPath;
+            if (scratchPath) {
+                // Declarative scratch keys for any future (re-)spawn (NOT a re-spawn trigger — Option A).
+                await applyUltracodeSettings(scratchPath, true);
+            }
+            // Effort component is xhigh, applied via the live /effort inject — but only when not already active
+            // (re-selecting ultracode must not re-inject `/effort xhigh`). applyEffortChange's own no-op guard
+            // also short-circuits if xhigh already equals the current effort.
+            if (!already) {
+                this.applyEffortChange(session, ULTRACODE_EFFORT_LEVEL);
+            }
+            return;
+        }
+        // A real level (or `default`) was chosen → deactivate ultracode before applying it.
+        if (session.ultracodeActive) {
+            session.ultracodeActive = false;
+            const scratchPath = session.gate?.settingsPath;
+            if (scratchPath) {
+                await applyUltracodeSettings(scratchPath, false);
+            }
+        }
+        this.applyEffortChange(session, value);
+    }
     /**
-     * Story 046 (R2.2, design §7) — apply a reasoning-effort change. Probe B verdict: effort has no live
-     * mid-session mechanism (`--effort` is a spawn flag), so a change re-spawns in place with the flag
-     * (mirroring the dontAsk/bypass mode path), idle-guarded, with the R3.7 failure path and R3.8 latch.
-     * A no-op change applies nothing. Throwing here leaves the caller's applyConfigOptionValue unrun, so
-     * the prior currentValue is left unchanged on failure (R3.7).
+     * Story 046 (R2.2) + Story 056 v4 — apply a reasoning-effort change LIVE via `/effort <level>`.
+     * SUPERSEDES the 046 Probe-B re-spawn: `claude` 2.1.195 DOES have a live `/effort <level>` local TUI
+     * command (LIVE-VERIFIED — "Set effort level to high…", applied inline, NO "Switch?" dialog unlike
+     * /model). So effort now mirrors {@link applyModelSwitch}: a side-channel write, no re-spawn, no turn —
+     * which means it ALSO works BEFORE the first interaction (the re-spawn's --resume idle-guard was why
+     * effort silently failed pre-first-prompt). Mid-turn it defers (pendingEffortInjection) and flushes
+     * when the turn settles. A no-op change applies nothing; effort stays preserved across mode/agent
+     * re-spawns (currentEffort → --effort flag), so the spawn-flag path remains as the seed/preserve route.
      */
-    async applyEffortChange(sessionId, session, level) {
+    applyEffortChange(session, level) {
         if (level === this.currentEffort(session))
             return; // no value change → no-op
+        if (session.turnDetector !== undefined) {
+            // A turn is in flight — injecting mid-turn corrupts the PTY input. Defer (coalesce, mirrors /model).
+            session.pendingEffortInjection = level;
+            return;
+        }
+        this.injectEffortCommand(session, level);
+    }
+    /**
+     * Side-channel `/effort <level>` write — synchronous, resolves immediately (never a turn). Unlike
+     * `/model`, `/effort` applies INLINE with no blocking "Switch?" dialog (LIVE-VERIFIED 2.1.195), so
+     * sendPrompt's own submit `\r` is sufficient and NO confirm Enter is scheduled.
+     */
+    injectEffortCommand(session, level) {
+        sendPrompt(session.pty, `/effort ${level}`, (fn) => fn());
+    }
+    /**
+     * Story 056 (R3.3/R3.4) — apply a main-thread agent-persona change. Like effort, the persona has no
+     * live mid-session mechanism (`--agent "<name>"` is a spawn flag), so a change re-spawns in place
+     * carrying the flag (mirroring {@link applyEffortChange}), idle-guarded, with the R3.7 failure path
+     * and the R3.8 latch. A no-op change (same persona, with the "default" sentinel as the no-persona
+     * baseline) applies nothing. Throwing here leaves the caller's applyConfigOptionValue unrun, so the
+     * prior currentValue is left unchanged on failure (R3.7). Optimistic-on-apply, like effort: there is
+     * no transcript drift event for the agent persona, so it is NOT reconciled afterward (R4.3).
+     */
+    async applyAgentChange(sessionId, session, agent) {
+        if (agent === (this.currentAgent(session) ?? "default"))
+            return; // no value change → no-op
         if (session.turnDetector !== undefined || session.respawning) {
-            throw new Error("Cannot change effort while the session is busy (a turn is in flight or a re-spawn is underway); retry when idle");
+            throw new Error("Cannot change agent while the session is busy (a turn is in flight or a re-spawn is underway); retry when idle");
         }
-        await this.respawnSession(sessionId, session, { effortLevel: level });
+        await this.respawnSession(sessionId, session, { agent });
     }
     /**
      * Story 046 (R4.1/R4.2/R4.3, design §8) — reconcile the `mode` configOption from the latest
@@ -1708,7 +1982,12 @@ export class ClaudeAcpAgent {
             // Rebuild config options since effort levels depend on the selected model
             const effortOpt = session.configOptions.find((o) => o.id === "effort");
             const currentEffort = typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
-            session.configOptions = buildConfigOptions(session.modes, value, session.modelInfos, currentEffort);
+            // Story 056 (R3.2): preserve the `agent` option across a model switch — re-read its current
+            // value and rebuild from the session's stored catalog (no re-glob). `session.agents ?? []`
+            // keeps the option absent when none were discovered (the gate).
+            const agentOpt = session.configOptions.find((o) => o.id === "agent");
+            const currentAgent = typeof agentOpt?.currentValue === "string" ? agentOpt.currentValue : undefined;
+            session.configOptions = buildConfigOptions(session.modes, value, session.modelInfos, currentEffort, session.agents ?? [], currentAgent);
             // === SEAM(023) Group 1: the SDK effort sync (query.applyFlagSettings) after a model switch is
             // dropped — configOptions already reflects the new effort locally.
             // Degrau 2 (030/032): PTY-backed control. ===
@@ -1791,6 +2070,21 @@ export class ClaudeAcpAgent {
         else {
             requestedSessionId = randomUUID();
         }
+        // Story 057 (R1.3/R3.1): resolve the additional-directory list ONCE (always-on, no env gate) so
+        // the SAME value threads to the spawn AND is stored on the session record (sub-task 2.3's
+        // respawnSession re-threads it). The fingerprint resolves through the same helper — see below.
+        const additionalDirs = resolveAdditionalDirs(params);
+        // Story 057 (R2.2/R2.3, sub-task 2.3): WRITE the MCP scratch BEFORE the spawn when the session
+        // declared ≥1 MCP server. Mirrors the gate's settings-scratch ordering (GATE_FINDINGS blocker c):
+        // the file must be ON DISK before claude starts, because claude reads `--mcp-config` only at
+        // startup. A replay-only load spawns nothing → no scratch. Always-on (no `FORK_*` gate, R3.1);
+        // the ONLY condition is "mcpServers non-empty". The path is threaded into startEngine below and
+        // stored on the session record (teardown removal + re-spawn regeneration). Awaited so a write
+        // failure surfaces here (loudly) rather than racing the spawn. Never logged (R2.3).
+        let mcpConfigFile;
+        if (!creationOpts.replayOnly && params.mcpServers && params.mcpServers.length > 0) {
+            mcpConfigFile = await writeMcpScratch(translateMcpServers(params.mcpServers));
+        }
         // SettingsManager is retained (kept methods read it; teardown disposes it). The PTY TUI reads
         // the user's settings from disk itself — we no longer translate them into SDK `Options`.
         const settingsManager = new SettingsManager(params.cwd, {
@@ -1840,6 +2134,12 @@ export class ClaudeAcpAgent {
                 permissionMode: seededMode,
                 // Story 034: the gate's scratch settings file, consumed as `--settings "<file>"` (fresh path).
                 settingsFile: gate?.settingsPath,
+                // Story 057 (R1.3/R3.1): the resolved additional-directory list → `--add-dir` on the spawn
+                // (always-on; the engine sanitizes per-dir). Same list stored on the session record below.
+                additionalDirectories: additionalDirs,
+                // Story 057 (R2.2): the MCP scratch path (written above) → `--mcp-config "<file>"` on the
+                // spawn. Same path stored on the session record below (teardown removal + re-spawn regen).
+                mcpConfigFile,
             });
         }
         catch (error) {
@@ -1850,6 +2150,12 @@ export class ClaudeAcpAgent {
             // reaches the map, so teardownSession can never dispose it. Dispose it on this path.
             settingsManager.dispose();
             await gate?.teardown();
+            // Story 057 (R2.3): a failed spawn must likewise leave NO MCP scratch behind (it was written
+            // before startEngine). removeMcpScratch is idempotent + never throws, so it cannot mask the
+            // original spawn error rethrown below.
+            if (mcpConfigFile) {
+                await removeMcpScratch(mcpConfigFile);
+            }
             if (creationOpts.resume && error instanceof Error) {
                 throw RequestError.resourceNotFound(requestedSessionId);
             }
@@ -1880,7 +2186,10 @@ export class ClaudeAcpAgent {
                     parentId: entry.parentId,
                     subagentLabel: deriveSubagentLabel(s?.lastMessages ?? [], entry.parentId) ?? "subagent",
                 };
-            });
+            }, 
+            // FIX(watchdog-permission): re-arm the end-of-turn watchdog while a permission dialog is open,
+            // so a slow human decision (JSONL silent meanwhile) is not mistaken for a dead turn.
+            () => this.sessions[startedSessionId]?.turnDetector?.noteActivity());
             boundGate.bindPty(started.pty);
             started.pty.onExit(() => void boundGate.teardown());
         }
@@ -1893,7 +2202,13 @@ export class ClaudeAcpAgent {
             currentModeId: seededMode,
             availableModes,
         };
-        const configOptions = buildConfigOptions(modes, DEFAULT_MODEL_INFO.value, MODEL_CATALOG, settingsManager.getSettings().effortLevel);
+        // Story 056 (R3.2): discover the main-thread agent personas for THIS session's cwd (glob-only via
+        // the injectable seam). When ≥1 is found, buildConfigOptions surfaces the 4th `agent` dropdown
+        // (seeded "default" = no persona at fresh create); when none, the option is omitted. The catalog
+        // is stored on the session record below so the model-change reconcile rebuilds it WITHOUT
+        // re-globbing.
+        const agents = this.discoverAgents(params.cwd);
+        const configOptions = buildConfigOptions(modes, DEFAULT_MODEL_INFO.value, MODEL_CATALOG, settingsManager.getSettings().effortLevel, agents, undefined);
         // Runtime cwd is read from inside the JSONL (story 015); fall back to the requested host cwd
         // until the first transcript line carries `.cwd` (the seam may return cwd === undefined early).
         const runtimeCwd = started.cwd ?? params.cwd;
@@ -1908,6 +2223,13 @@ export class ClaudeAcpAgent {
             engine: started.engine,
             cancelled: false,
             cwd: runtimeCwd,
+            // Story 057 (R1.3): the resolved additional-directory list, stored so sub-task 2.3's
+            // respawnSession can re-thread the SAME `--add-dir` scope into the in-place re-spawn.
+            additionalDirectories: additionalDirs,
+            // Story 057 (R2.3/R2.4): the CURRENT MCP scratch path (for teardown removal + re-spawn regen)
+            // and the RAW ACP server array (so respawnSession can re-translate + regenerate the scratch).
+            mcpConfigFile,
+            mcpServers: params.mcpServers,
             sessionFingerprint: computeSessionFingerprint(params),
             settingsManager,
             accumulatedUsage: {
@@ -1918,6 +2240,7 @@ export class ClaudeAcpAgent {
             },
             modes,
             modelInfos: MODEL_CATALOG,
+            agents,
             configOptions,
             contextWindowSize: inferContextWindowFromModel(DEFAULT_MODEL_INFO.value) ?? DEFAULT_CONTEXT_WINDOW,
             taskState,
@@ -1978,7 +2301,7 @@ function buildAvailableModes(modelInfo) {
 // `applyFlagSettings` in @anthropic-ai/claude-agent-sdk. Mapping both the
 // `"default"` sentinel and `undefined` (effort option absent for the model) to
 // `null` ensures any previously-applied flag is actually cleared.
-function buildConfigOptions(modes, currentModelId, modelInfos, currentEffortLevel) {
+function buildConfigOptions(modes, currentModelId, modelInfos, currentEffortLevel, agents = [], currentAgent) {
     const options = [
         {
             id: "mode",
@@ -2022,8 +2345,13 @@ function buildConfigOptions(modes, currentModelId, modelInfos, currentEffortLeve
                     .map((part) => (part ? part.charAt(0).toUpperCase() + part.slice(1) : part))
                     .join(" "),
             })),
+            // Story 060 (R1.1) — the "ultracode" sentinel, LAST and after the five real levels. NOT a real
+            // `--effort` value (claude rejects `--effort ultracode`); it maps to xhigh + orchestration (Task 3).
+            { value: ULTRACODE_EFFORT, name: ULTRACODE_EFFORT_LABEL },
         ];
-        const includes = (l) => l === "default" || supportedLevels.includes(l);
+        // `ultracode` is a valid current value so a configOptions rebuild (e.g. after a re-spawn) does not
+        // reset a selected ultracode back to "default". It stays OUT of supportedLevels (real --effort enum).
+        const includes = (l) => l === "default" || l === ULTRACODE_EFFORT || supportedLevels.includes(l);
         const validEffort = currentEffortLevel && includes(currentEffortLevel) ? currentEffortLevel : "default";
         options.push({
             id: "effort",
@@ -2035,6 +2363,27 @@ function buildConfigOptions(modes, currentModelId, modelInfos, currentEffortLeve
             options: effortOptions,
         });
     }
+    // Story 056 (R3.2) — the `agent` (main-thread persona) selector, mirroring the effort option but
+    // with a "default" no-persona sentinel. GATED on `agents.length > 0` (upstream #794): when nothing
+    // is discovered the option is OMITTED entirely. The "default" entry = no persona (the spawn layer
+    // already drops the literal "default", exactly like --effort/--permission-mode). The current value
+    // is validated against the discovered set and falls back to "default".
+    if (agents.length > 0) {
+        const agentValues = new Set(agents.map((a) => a.value));
+        const validAgent = currentAgent && agentValues.has(currentAgent) ? currentAgent : "default";
+        options.push({
+            id: "agent",
+            name: "Agent",
+            description: "Main-thread agent persona",
+            category: "model",
+            type: "select",
+            currentValue: validAgent,
+            options: [
+                { value: "default", name: "Default" },
+                ...agents.map((a) => ({ value: a.value, name: a.displayName, description: a.description })),
+            ],
+        });
+    }
     return options;
 }
 // Claude Code CLI persists display strings like "opus[1m]" in settings,
@@ -2164,14 +2513,27 @@ function filePathFromUri(uri) {
  *                     anything below the threshold — or large but path-less — is
  *                     inlined directly so the context is not lost.
  *
- * `resource` (blob) / `image` / `audio` blocks are SILENT no-ops here (R4.1): they
- * emit no PTY bytes and are NOT logged — they are expected-but-unsupported media in
- * v1, not errors. An UNKNOWN block `type` (the `default` branch) and any block whose
- * mapping THROWS are treated as malformed: skipped, recorded via the `logger`, and the
- * remaining valid blocks still map — one bad block never aborts the whole prompt (R1.3).
+ *   - image → materialize the base64 to a uuid-named temp file (extension from mimeType)
+ *             and emit `@<temp-path>` (Story 058 / R1.1). Once at least one image is
+ *             materialized, a single Read-inducing directive is appended after the loop so
+ *             the TUI's Read tool fires and vision-encodes it (R1.2). Each temp path is
+ *             pushed into `materializedSink` (when provided) so the caller can clean it up.
+ *
+ * `resource` (blob) / `audio` blocks are SILENT no-ops here (R4.1): they emit no PTY bytes
+ * and are NOT logged — they are expected-but-unsupported media in v1, not errors. An UNKNOWN
+ * block `type` (the `default` branch) and any block whose mapping THROWS are treated as
+ * malformed: skipped, recorded via the `logger`, and the remaining valid blocks still map —
+ * one bad block never aborts the whole prompt (R1.3). A `materializeImage` failure is caught
+ * by that same per-block isolation, so a broken image is skipped, never aborting the prompt.
+ *
+ * `materializedSink`, when passed, receives every materialized temp path (in order) so the
+ * caller owns their lifecycle (cleanup is a later task). The return type stays `string`.
  */
-export function promptToClaude(prompt, logger = console) {
+export function promptToClaude(prompt, logger = console, materializedSink) {
     const fragments = [];
+    // Set once any image block is materialized, so exactly ONE Read-inducing directive is
+    // appended after the loop regardless of how many images the prompt carries (R1.2).
+    let materializedAnyImage = false;
     for (const chunk of prompt.prompt) {
         // R1.3: isolate every block. A malformed block — even one whose `type` getter
         // throws — is SKIPPED and RECORDED, never allowed to abort the remaining blocks.
@@ -2221,9 +2583,25 @@ export function promptToClaude(prompt, logger = console) {
                     }
                     break;
                 }
-                // image / audio → SILENT no-ops (R4.1): expected-but-unsupported media in v1.
-                // They emit no PTY bytes and are NOT logged (they are not errors).
-                case "image":
+                case "image": {
+                    // R1.1: an ACP image carries base64 `data` + `mimeType` (NOT `source`/`media_type`).
+                    // Materialize it to a uuid-named temp file and reference it with `@<path>` so the TUI
+                    // re-reads (and vision-encodes) it — mirroring the `resource_link` @<path> idiom. A
+                    // single Read-inducing directive is appended AFTER the loop (R1.2). If materialize
+                    // throws, the surrounding per-block try/catch isolates it (R1.3): this image is skipped.
+                    //
+                    // R1.3 (shell-safety): the path is uuid-named + fork-controlled and the prompt body reaches
+                    // the PTY via bracketed-paste (engine-pty `sendPrompt` → `p.write`), NOT the `bash -lc` spawn
+                    // string — so no shell ever parses `@<path>` and the prompt has no injection surface. extFor
+                    // maps mimeType to a CLOSED extension set, so a hostile mimeType cannot reach the filename.
+                    const tempPath = materializeImage(chunk.data, chunk.mimeType);
+                    materializedSink?.push(tempPath);
+                    fragments.push(`@${tempPath}`);
+                    materializedAnyImage = true;
+                    break;
+                }
+                // audio → SILENT no-op (R4.1): expected-but-unsupported media in v1. It emits no PTY
+                // bytes and is NOT logged (it is not an error).
                 case "audio":
                     break;
                 default:
@@ -2240,6 +2618,11 @@ export function promptToClaude(prompt, logger = console) {
             continue;
         }
     }
+    // R1.2: exactly one Read-inducing directive per prompt when ≥1 image was materialized, so the
+    // TUI's Read tool fires on the @<path>(s) above and vision-encodes them (the proven 2.1.195 path).
+    if (materializedAnyImage) {
+        fragments.push("Read the attached image(s) above and use them to answer.");
+    }
     return fragments.filter((fragment) => fragment.length > 0).join(" ");
 }
 /**
@@ -2297,13 +2680,18 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 break;
             case "thinking":
             case "thinking_delta":
-                update = {
-                    sessionUpdate: "agent_thought_chunk",
-                    content: {
-                        type: "text",
-                        text: chunk.thinking,
-                    },
-                };
+                // Story 056 (#793): a signature-only thinking block (thinking.display "omitted") carries empty
+                // text — suppress the agent_thought_chunk rather than emit an empty one (update stays null → no
+                // push at the `if (update)` guard). A non-empty thinking block emits exactly as before.
+                if (chunk.thinking.length > 0) {
+                    update = {
+                        sessionUpdate: "agent_thought_chunk",
+                        content: {
+                            type: "text",
+                            text: chunk.thinking,
+                        },
+                    };
+                }
                 break;
             case "tool_use":
             case "server_tool_use":