@lucascouts/claude-agent-tui 0.5.2 → 0.7.0

package/dist/engine-pty.d.ts

@@ -49,19 +49,63 @@ export declare function resolveShell(baseEnv?: Record<string, string | undefined
  * non-"default" mode is emitted as `--permission-mode <mode>`; "default"/undefined emit nothing;
  * `permissionMode: "plan"` reproduces the old planMode=true path. Still interactive-only — adds no
  * `-p`/`stream-json`, billing stays subscription `cli`.
+ *
+ * Story 056 (R3.3): an optional `agent` persona name is emitted as `--agent "<name>"` (DOUBLE-QUOTED,
+ * grouped with the other behavior flags). This is the SECOND layer of the two-layer command-injection
+ * defense — `agent-catalog.ts` already drops any name outside `SAFE_AGENT_REF`
+ * (`/^[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)?$/`, allowing a namespaced `plugin:name`) at discovery, and
+ * here we re-assert via {@link isSafeAgentRef} so an unsafe name is silently DROPPED (no flag), never
+ * interpolated into the `-lc` shell string. Interactive-only — adds no `-p`/`stream-json`.
+ *
+ * Story 057 (R1.1/R1.2): an optional `additionalDirectories` list is emitted as ONE double-quoted
+ * `--add-dir "<dir>"` flag PER directory (never a single space-joined value — each dir is its own flag,
+ * matching the upstream/CLI shape). Each dir is re-asserted via {@link isSafeDir} (absolute + existing +
+ * free of shell metacharacters); an unsafe dir is DROPPED and a one-line warning is logged, never
+ * interpolated into the `-lc` shell string. Interactive-only — adds no `-p`/`stream-json`.
+ *
+ * Story 057 (R2.2): an optional `mcpConfigFile` PATH is emitted as the DOUBLE-QUOTED `--mcp-config
+ * "<file>"` flag (same style as `--settings` — a file path, so the secret-bearing JSON stays OFF the
+ * command line and survives the `-lc` shell word-splitting). The file is the fork-controlled
+ * uuid-named scratch from `mcp-config-writer.ts`. R2.2 is a HARD rule: `--strict-mcp-config` is NEVER
+ * emitted, so claude MERGES the scratch with the user's own `.mcp.json`/settings MCP servers (the
+ * parity target) instead of discarding them. Interactive-only — adds no `-p`/`stream-json`.
+ */
+export declare function buildClaudeCmd(sessionId: string, permissionMode?: string, settingsFile?: string, effortLevel?: string, agent?: string, additionalDirectories?: string[], mcpConfigFile?: string): string;
+/**
+ * Story 057 (R1.2). The directory-allowlist predicate, mirroring the discipline of
+ * {@link isSafeAgentRef}: a directory is safe to interpolate into a double-quoted `--add-dir "<dir>"`
+ * flag ONLY when it is an ABSOLUTE path, currently EXISTS on disk, and is FREE of the shell
+ * metacharacters that could break out of (or inject into) the `-lc` double-quoted argument — `"`, `$`,
+ * a backtick, or a newline/CR. Single source of truth — exported so engine-lifecycle.ts's resume path
+ * reuses it rather than re-implementing the rule.
+ */
+export declare function isSafeDir(p: string): boolean;
+/**
+ * Story 057 (R1.1/R1.2). Build the trailing ` --add-dir "<dir>"` fragment for a list of additional
+ * directories: ONE double-quoted flag per dir that passes {@link isSafeDir}. An unsafe dir (relative,
+ * non-existent, or containing a shell metacharacter) is DROPPED — never interpolated — and a one-line
+ * warning is logged to stderr (the fork's diagnostic channel, never the ACP stdout wire). An
+ * empty/undefined list emits the empty string (no flags). Shared by the fresh and resume spawn paths.
  */
-export declare function buildClaudeCmd(sessionId: string, permissionMode?: string, settingsFile?: string, effortLevel?: string): string;
+export declare function buildAddDirFlags(additionalDirectories?: string[]): string;
 /**
  * Login-shell argv (§5, R1.3). The `-lc` flag is MANDATORY: node-pty's `posix_spawnp`
  * does not execute the `claude` npm launcher's `#!/usr/bin/env node` shebang, so the
  * launcher must run *through* a login shell. (The compiled native-binary is the only
  * thing that could be spawned directly — §5 / IMPLEMENTACAO-FORK-ACP.md §17.)
  */
-export declare function buildSpawnArgv(sessionId: string, permissionMode?: string, settingsFile?: string, effortLevel?: string): [string, string];
+export declare function buildSpawnArgv(sessionId: string, permissionMode?: string, settingsFile?: string, effortLevel?: string, agent?: string, additionalDirectories?: string[], mcpConfigFile?: string): [string, string];
 /** Options for {@link spawnClaudePty}. */
 export interface SpawnPtyOptions {
     /** Host working directory the TUI runs in; passed straight through to the PTY (§5). */
     cwd: string;
+    /**
+     * Story 056 v4 — an OPTIONAL pre-chosen session id for an in-place FRESH re-spawn (a selector change
+     * before the first interaction reuses the session's existing id). Absent → a new `randomUUID()` is
+     * generated (the normal createSession path). claude accepts a reused `--session-id` once the prior
+     * PTY for that id has exited (LIVE-VERIFIED).
+     */
+    sessionId?: string;
     /** Base environment to sanitize; defaults to the parent process env. */
     baseEnv?: Record<string, string | undefined>;
     /**
@@ -88,6 +132,30 @@ export interface SpawnPtyOptions {
      * Absent → no flag (the ungated/`FORK_GATE=off` spawn is byte-for-byte pre-034).
      */
     settingsFile?: string;
+    /**
+     * Story 056 (R3.3): a main-thread agent persona name (from `agent-catalog.ts`) emitted as the
+     * interactive-only `--agent "<name>"` spawn flag. DOUBLE-QUOTED and injection-safe — re-asserted
+     * against the R3.3 allowlist (`/^[A-Za-z0-9_-]+$/`) so an unsafe name is dropped, never interpolated.
+     * Absent → no flag. Adds no `-p`/`stream-json`; billing stays subscription `cli`.
+     */
+    agent?: string;
+    /**
+     * Story 057 (R1.1/R1.2): extra workspace directories surfaced as ONE double-quoted
+     * `--add-dir "<dir>"` flag per dir. Each dir is re-asserted via {@link isSafeDir} (absolute +
+     * existing + no shell metacharacter) — an unsafe dir is dropped (logged), never interpolated.
+     * INTERACTIVE-ONLY: adds no `-p`/`--print`/`stream-json`, so billing stays subscription `cli`.
+     * Absent/empty → no flag.
+     */
+    additionalDirectories?: string[];
+    /**
+     * Story 057 (R2.2): the fork-controlled uuid-named scratch MCP-config PATH (written by
+     * `mcp-config-writer.ts`), surfaced as the DOUBLE-QUOTED `--mcp-config "<file>"` flag. A file path —
+     * the secret-bearing JSON lives in the file, OFF the command line. NEVER paired with
+     * `--strict-mcp-config`, so claude MERGES it with the user's own `.mcp.json`/settings MCP servers
+     * (the R2.2 parity target) rather than discarding them. INTERACTIVE-ONLY: adds no
+     * `-p`/`--print`/`stream-json`, so billing stays subscription `cli`. Absent → no flag.
+     */
+    mcpConfigFile?: string;
 }
 /** Handle returned by {@link spawnClaudePty}; story 014 manages its lifecycle. */
 export interface PtyEngineHandle {
@@ -150,4 +218,3 @@ export declare const CLEAR_INPUT_DELAY_MS = 60;
  * try/catch); the payload and `\r` writes are scheduled and post-exit-safe.
  */
 export declare function sendPrompt(p: IPty, text: string, schedule?: (fn: () => void, ms: number) => void): void;
-//# sourceMappingURL=engine-pty.d.ts.map

package/dist/engine-pty.js

@@ -16,6 +16,9 @@
 // the ACP createSession rewrite that wires this engine in is story 023.
 import pty from "node-pty";
 import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+import { isSafeAgentRef } from "./agent-catalog.js";
 // PTY geometry pinned by §5.
 const PTY_NAME = "xterm-256color";
 const PTY_COLS = 120;
@@ -94,8 +97,28 @@ export function resolveShell(baseEnv = process.env) {
  * non-"default" mode is emitted as `--permission-mode <mode>`; "default"/undefined emit nothing;
  * `permissionMode: "plan"` reproduces the old planMode=true path. Still interactive-only — adds no
  * `-p`/`stream-json`, billing stays subscription `cli`.
+ *
+ * Story 056 (R3.3): an optional `agent` persona name is emitted as `--agent "<name>"` (DOUBLE-QUOTED,
+ * grouped with the other behavior flags). This is the SECOND layer of the two-layer command-injection
+ * defense — `agent-catalog.ts` already drops any name outside `SAFE_AGENT_REF`
+ * (`/^[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)?$/`, allowing a namespaced `plugin:name`) at discovery, and
+ * here we re-assert via {@link isSafeAgentRef} so an unsafe name is silently DROPPED (no flag), never
+ * interpolated into the `-lc` shell string. Interactive-only — adds no `-p`/`stream-json`.
+ *
+ * Story 057 (R1.1/R1.2): an optional `additionalDirectories` list is emitted as ONE double-quoted
+ * `--add-dir "<dir>"` flag PER directory (never a single space-joined value — each dir is its own flag,
+ * matching the upstream/CLI shape). Each dir is re-asserted via {@link isSafeDir} (absolute + existing +
+ * free of shell metacharacters); an unsafe dir is DROPPED and a one-line warning is logged, never
+ * interpolated into the `-lc` shell string. Interactive-only — adds no `-p`/`stream-json`.
+ *
+ * Story 057 (R2.2): an optional `mcpConfigFile` PATH is emitted as the DOUBLE-QUOTED `--mcp-config
+ * "<file>"` flag (same style as `--settings` — a file path, so the secret-bearing JSON stays OFF the
+ * command line and survives the `-lc` shell word-splitting). The file is the fork-controlled
+ * uuid-named scratch from `mcp-config-writer.ts`. R2.2 is a HARD rule: `--strict-mcp-config` is NEVER
+ * emitted, so claude MERGES the scratch with the user's own `.mcp.json`/settings MCP servers (the
+ * parity target) instead of discarding them. Interactive-only — adds no `-p`/`stream-json`.
  */
-export function buildClaudeCmd(sessionId, permissionMode, settingsFile, effortLevel) {
+export function buildClaudeCmd(sessionId, permissionMode, settingsFile, effortLevel, agent, additionalDirectories, mcpConfigFile) {
     let cmd = `claude --session-id ${sessionId}`;
     if (permissionMode && permissionMode !== "default")
         cmd += ` --permission-mode ${permissionMode}`;
@@ -103,18 +126,69 @@ export function buildClaudeCmd(sessionId, permissionMode, settingsFile, effortLe
     // non-"default" level is seeded/re-spawned with `--effort <level>`. Interactive-only — no credit path.
     if (effortLevel && effortLevel !== "default")
         cmd += ` --effort ${effortLevel}`;
+    // Story 056 (R3.3): the agent persona, double-quoted, emitted ONLY for a real persona — the "default"
+    // sentinel (= no persona, mirrors --effort/--permission-mode) emits nothing — and only when it passes
+    // the R3.3 allowlist re-assert (defense-in-depth — an unsafe name is dropped, never interpolated).
+    if (agent && agent !== "default" && isSafeAgentRef(agent))
+        cmd += ` --agent "${agent}"`;
     if (settingsFile)
         cmd += ` --settings "${settingsFile}"`;
+    // Story 057 (R1.1/R1.2): ONE double-quoted `--add-dir "<dir>"` per safe dir (never a space-joined
+    // value). Each dir is re-asserted via isSafeDir (absolute + existing + no shell metachar) — an unsafe
+    // dir is DROPPED with a one-line warning, never interpolated into the `-lc` shell string.
+    cmd += buildAddDirFlags(additionalDirectories);
+    // Story 057 (R2.2): the DOUBLE-QUOTED `--mcp-config "<file>"` (mirrors `--settings` above — a file path,
+    // so the secret-bearing JSON stays off the command line). Emitted ONLY when set. R2.2 HARD rule: NEVER
+    // `--strict-mcp-config` — without it claude MERGES the scratch with the user's own .mcp.json/settings
+    // MCP servers (the parity target) instead of discarding them.
+    if (mcpConfigFile)
+        cmd += ` --mcp-config "${mcpConfigFile}"`;
     return cmd;
 }
+/**
+ * Story 057 (R1.2). The directory-allowlist predicate, mirroring the discipline of
+ * {@link isSafeAgentRef}: a directory is safe to interpolate into a double-quoted `--add-dir "<dir>"`
+ * flag ONLY when it is an ABSOLUTE path, currently EXISTS on disk, and is FREE of the shell
+ * metacharacters that could break out of (or inject into) the `-lc` double-quoted argument — `"`, `$`,
+ * a backtick, or a newline/CR. Single source of truth — exported so engine-lifecycle.ts's resume path
+ * reuses it rather than re-implementing the rule.
+ */
+export function isSafeDir(p) {
+    return path.isAbsolute(p) && existsSync(p) && !/["$`\n\r]/.test(p);
+}
+/**
+ * Story 057 (R1.1/R1.2). Build the trailing ` --add-dir "<dir>"` fragment for a list of additional
+ * directories: ONE double-quoted flag per dir that passes {@link isSafeDir}. An unsafe dir (relative,
+ * non-existent, or containing a shell metacharacter) is DROPPED — never interpolated — and a one-line
+ * warning is logged to stderr (the fork's diagnostic channel, never the ACP stdout wire). An
+ * empty/undefined list emits the empty string (no flags). Shared by the fresh and resume spawn paths.
+ */
+export function buildAddDirFlags(additionalDirectories) {
+    if (!additionalDirectories || additionalDirectories.length === 0)
+        return "";
+    let fragment = "";
+    for (const dir of additionalDirectories) {
+        if (isSafeDir(dir)) {
+            fragment += ` --add-dir "${dir}"`;
+        }
+        else {
+            console.error(`engine-pty: dropping unsafe --add-dir entry (not absolute+existing, or contains a shell ` +
+                `metacharacter): ${JSON.stringify(dir)}`);
+        }
+    }
+    return fragment;
+}
 /**
  * Login-shell argv (§5, R1.3). The `-lc` flag is MANDATORY: node-pty's `posix_spawnp`
  * does not execute the `claude` npm launcher's `#!/usr/bin/env node` shebang, so the
  * launcher must run *through* a login shell. (The compiled native-binary is the only
  * thing that could be spawned directly — §5 / IMPLEMENTACAO-FORK-ACP.md §17.)
  */
-export function buildSpawnArgv(sessionId, permissionMode, settingsFile, effortLevel) {
-    return ["-lc", buildClaudeCmd(sessionId, permissionMode, settingsFile, effortLevel)];
+export function buildSpawnArgv(sessionId, permissionMode, settingsFile, effortLevel, agent, additionalDirectories, mcpConfigFile) {
+    return [
+        "-lc",
+        buildClaudeCmd(sessionId, permissionMode, settingsFile, effortLevel, agent, additionalDirectories, mcpConfigFile),
+    ];
 }
 /**
  * Spawn the interactive `claude` TUI under a real PTY with the §5 dimensions and a
@@ -133,10 +207,10 @@ export function buildSpawnArgv(sessionId, permissionMode, settingsFile, effortLe
  * process-supervisor or non-PTY spawn variant is introduced.
  */
 export function spawnClaudePty(opts) {
-    const { cwd, baseEnv = process.env, spawn = pty.spawn, permissionMode, settingsFile, effortLevel, } = opts;
-    const sessionId = randomUUID(); // pre-generated → correlates to the JSONL transcript
+    const { cwd, baseEnv = process.env, spawn = pty.spawn, permissionMode, settingsFile, effortLevel, agent, additionalDirectories, mcpConfigFile, } = opts;
+    const sessionId = opts.sessionId ?? randomUUID(); // pre-generated → correlates to the JSONL transcript (v4: reused on a fresh re-spawn)
     const shell = resolveShell(baseEnv);
-    const argv = buildSpawnArgv(sessionId, permissionMode, settingsFile, effortLevel);
+    const argv = buildSpawnArgv(sessionId, permissionMode, settingsFile, effortLevel, agent, additionalDirectories, mcpConfigFile);
     // Sanitized, subscription-billing env (§5/§10) via the single shared definition.
     const env = buildSanitizedEnv(baseEnv);
     // §10 no-spoof contract (R3.1/R3.3): the 'cli' entrypoint label MUST be produced

package/dist/engine-watcher.d.ts

@@ -80,4 +80,3 @@ export interface JsonlWatcher extends SessionWatcher {
  * @returns a {@link JsonlWatcher} (a {@link SessionWatcher} plus `notifyEndOfTurn`).
  */
 export declare function createJsonlWatcher(opts: JsonlWatcherOptions): JsonlWatcher;
-//# sourceMappingURL=engine-watcher.d.ts.map

package/dist/engine.d.ts

@@ -27,4 +27,3 @@ export declare class StubEngine implements Engine {
 }
 /** Factory for the default story-011 engine (the no-op stub). */
 export declare function createStubEngine(): Engine;
-//# sourceMappingURL=engine.d.ts.map

package/dist/event-switch.d.ts

@@ -161,4 +161,3 @@ export type EventClassification = ContentClassification | LifecycleClassificatio
  */
 export declare function classifyEvent(event: JsonlEvent, opts?: ClassifyOptions): EventClassification;
 export {};
-//# sourceMappingURL=event-switch.d.ts.map

package/dist/gate/port.d.ts

@@ -35,4 +35,3 @@ export type ServerFactory = () => PortServer;
  *   the last bind error.
  */
 export declare function findFreePort(attempts?: number, makeServer?: ServerFactory): Promise<number>;
-//# sourceMappingURL=port.d.ts.map

package/dist/gate/settings-writer.d.ts

@@ -144,4 +144,17 @@ export declare function injectHook(opts: {
  *   underlying error so teardown never silently strands the fork hook.
  */
 export declare function restore(backup: Backup): Promise<RestoreResult>;
-//# sourceMappingURL=settings-writer.d.ts.map
+/**
+ * Story 060 (R2.2/R2.3/R3.2) — toggle the ultracode keys in the per-session SCRATCH settings file the
+ * gate wrote (preserving the hook + EVERY other key). `active` → set `ultracode:true` (the per-session
+ * ACTIVATOR) + `ultracodeKeywordTrigger:true` (defensively ENABLE the keyword even if the user disabled
+ * it). `!active` → remove BOTH keys. Read tolerantly (JSONC) + written durably (temp+fsync+rename),
+ * mirroring {@link injectHook}. A missing/empty file is treated as an empty object. No-op-safe and
+ * idempotent: re-applying the same `active` produces a byte-equivalent document.
+ *
+ * @param settingsPath absolute path to the per-session scratch `settings.local.json` (the gate's file).
+ * @param active whether ultracode is selected (set the keys) or de-selected (remove them).
+ * @throws {Error} only on a genuine read/parse/write failure — NEVER on the benign absence of the file
+ *   (ENOENT → treated as `{}`), mirroring the rest of the module's discipline.
+ */
+export declare function applyUltracodeSettings(settingsPath: string, active: boolean): Promise<void>;

package/dist/gate/settings-writer.js

@@ -353,3 +353,52 @@ export async function restore(backup) {
         }
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Story 060 (R2.2 / R2.3 / R3.2) — toggle the ultracode keys in the per-session SCRATCH settings file.
+//
+// The "ultracode" effort-selector sentinel (story 060) activates the binary's Workflow keyword-trigger.
+// Its LIVE activation is a keyword prefix on the outgoing prompt (acp-agent.ts); THIS function is the
+// declarative spawn-time complement — the keys `claude` reads only at (re-)spawn, so the scratch stays
+// in sync for any (re-)spawn that DOES happen. It is NOT itself a re-spawn trigger (Option A).
+// ─────────────────────────────────────────────────────────────────────────────
+/** The two settings keys that opt a session into the ultracode keyword-trigger (story 060). */
+const ULTRACODE_SETTINGS_KEY = "ultracode";
+const ULTRACODE_KEYWORD_TRIGGER_KEY = "ultracodeKeywordTrigger";
+/**
+ * Story 060 (R2.2/R2.3/R3.2) — toggle the ultracode keys in the per-session SCRATCH settings file the
+ * gate wrote (preserving the hook + EVERY other key). `active` → set `ultracode:true` (the per-session
+ * ACTIVATOR) + `ultracodeKeywordTrigger:true` (defensively ENABLE the keyword even if the user disabled
+ * it). `!active` → remove BOTH keys. Read tolerantly (JSONC) + written durably (temp+fsync+rename),
+ * mirroring {@link injectHook}. A missing/empty file is treated as an empty object. No-op-safe and
+ * idempotent: re-applying the same `active` produces a byte-equivalent document.
+ *
+ * @param settingsPath absolute path to the per-session scratch `settings.local.json` (the gate's file).
+ * @param active whether ultracode is selected (set the keys) or de-selected (remove them).
+ * @throws {Error} only on a genuine read/parse/write failure — NEVER on the benign absence of the file
+ *   (ENOENT → treated as `{}`), mirroring the rest of the module's discipline.
+ */
+export async function applyUltracodeSettings(settingsPath, active) {
+    // 1) Read the current bytes; a missing file (ENOENT) is treated as "no prior settings" (→ `{}`).
+    const priorBytes = await readPriorBytes(settingsPath);
+    let current = {};
+    if (priorBytes !== null) {
+        const text = priorBytes.toString("utf8").trim();
+        // An empty existing file is treated as an empty object rather than a parse error (mirrors inject).
+        if (text.length > 0) {
+            current = parsePriorSettings(text);
+        }
+    }
+    // 2) Clone (never mutate the parsed prior) and toggle ONLY the two ultracode keys — every other key
+    //    (the gate hook, the user's own config) is preserved verbatim.
+    const next = structuredClone(current);
+    if (active) {
+        next[ULTRACODE_SETTINGS_KEY] = true;
+        next[ULTRACODE_KEYWORD_TRIGGER_KEY] = true;
+    }
+    else {
+        delete next[ULTRACODE_SETTINGS_KEY];
+        delete next[ULTRACODE_KEYWORD_TRIGGER_KEY];
+    }
+    // 3) Durably write (temp+fsync+rename) so a concurrent (re-)spawn read never sees a half-written file.
+    await durableWrite(settingsPath, `${JSON.stringify(next, null, 2)}\n`);
+}

package/dist/image-input.d.ts

@@ -0,0 +1,30 @@
+/** Filename prefix for every materialized image — shared so a later cleanup task can match it. */
+export declare const MATERIALIZED_IMAGE_PREFIX = "fork-acp-img-";
+/**
+ * Map an ACP `image` block `mimeType` to a file extension the TUI's Read tool recognizes.
+ *
+ * Tolerant of a `;`-parameterized mimeType (e.g. `image/png; charset=binary`): only the media type
+ * before the first `;` is matched. Anything unrecognized — including `undefined`/`null` — falls back
+ * to `.img` so a path is still produced (the Read tool sniffs the bytes regardless of extension).
+ * Never throws.
+ */
+export declare function extFor(mimeType: string | undefined | null): string;
+/**
+ * Decode a base64 `image` payload to a uniquely-named temp file and return its absolute path.
+ *
+ * The file lives under {@link os.tmpdir} with a uuid name (no user-controlled characters) and an
+ * extension derived from `mimeType` via {@link extFor}. The write is SYNCHRONOUS on purpose — the
+ * caller (`promptToClaude`) is sync. May throw if the decode or write fails; the caller isolates that
+ * in its per-block try/catch (R1.3), so a bad image is skipped rather than aborting the whole prompt.
+ */
+export declare function materializeImage(data: string, mimeType: string | undefined | null): string;
+/**
+ * Story 058 / Task 2.1 (R2.1/R2.2) — best-effort unlink of every materialized temp image.
+ *
+ * The single unlink path shared by the turn-settle cleanup (prompt()'s catch + finally) and the
+ * session-teardown backstop, kept here so it stays OFFLINE-testable. NEVER throws: each unlink is
+ * isolated so a missing file (already removed, or a torn-down/raced turn) is a no-op rather than an
+ * error — which makes the teardown backstop idempotent with the prompt-finally cleanup. `undefined`
+ * (no image materialized this turn) returns immediately.
+ */
+export declare function cleanupMaterializedImages(paths: readonly string[] | undefined): void;

package/dist/image-input.js

@@ -0,0 +1,79 @@
+// Story 058 / Task 1.1 — materialize an ACP `image` block to a temp file for the @path vision path.
+//
+// The fork drives the real `claude` TUI over a PTY; it has no API surface to push raw image bytes.
+// The proven claude-2.1.195 path to get an image vision-encoded is to write the bytes to a file and
+// reference it with `@<path>` in the prompt text, then ask the model to Read it — the TUI's Read tool
+// then vision-encodes the file. This module is the standalone, OFFLINE-testable materialize seam:
+//
+//   extFor(mimeType)            → ".png" | ".jpg" | ".gif" | ".webp" | ".img"   (PURE — mime → ext)
+//   materializeImage(data, mt)  → <abs temp path>   (DURABLE — base64 → temp file, returns the path)
+//
+// `promptToClaude` (acp-agent.ts) is SYNCHRONOUS and runs before the `await` at its call site, so the
+// write here is synchronous (`writeFileSync`) by design — do NOT make it async. The temp path is
+// uuid-named and fork-controlled (no user input in the filename), which is what lets a later cleanup
+// task (Task 2) treat it as shell-safe. The decoded bytes are not logged.
+import { writeFileSync, unlinkSync } from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+/** Filename prefix for every materialized image — shared so a later cleanup task can match it. */
+export const MATERIALIZED_IMAGE_PREFIX = "fork-acp-img-";
+/**
+ * Map an ACP `image` block `mimeType` to a file extension the TUI's Read tool recognizes.
+ *
+ * Tolerant of a `;`-parameterized mimeType (e.g. `image/png; charset=binary`): only the media type
+ * before the first `;` is matched. Anything unrecognized — including `undefined`/`null` — falls back
+ * to `.img` so a path is still produced (the Read tool sniffs the bytes regardless of extension).
+ * Never throws.
+ */
+export function extFor(mimeType) {
+    // Strip any `;`-delimited parameters and normalize, so `image/JPEG; q=…` still matches.
+    const media = (mimeType ?? "").split(";", 1)[0].trim().toLowerCase();
+    switch (media) {
+        case "image/png":
+            return ".png";
+        case "image/jpeg":
+            return ".jpg";
+        case "image/gif":
+            return ".gif";
+        case "image/webp":
+            return ".webp";
+        default:
+            return ".img";
+    }
+}
+/**
+ * Decode a base64 `image` payload to a uniquely-named temp file and return its absolute path.
+ *
+ * The file lives under {@link os.tmpdir} with a uuid name (no user-controlled characters) and an
+ * extension derived from `mimeType` via {@link extFor}. The write is SYNCHRONOUS on purpose — the
+ * caller (`promptToClaude`) is sync. May throw if the decode or write fails; the caller isolates that
+ * in its per-block try/catch (R1.3), so a bad image is skipped rather than aborting the whole prompt.
+ */
+export function materializeImage(data, mimeType) {
+    const bytes = Buffer.from(data, "base64");
+    const tempPath = path.join(os.tmpdir(), MATERIALIZED_IMAGE_PREFIX + randomUUID() + extFor(mimeType));
+    writeFileSync(tempPath, bytes);
+    return tempPath;
+}
+/**
+ * Story 058 / Task 2.1 (R2.1/R2.2) — best-effort unlink of every materialized temp image.
+ *
+ * The single unlink path shared by the turn-settle cleanup (prompt()'s catch + finally) and the
+ * session-teardown backstop, kept here so it stays OFFLINE-testable. NEVER throws: each unlink is
+ * isolated so a missing file (already removed, or a torn-down/raced turn) is a no-op rather than an
+ * error — which makes the teardown backstop idempotent with the prompt-finally cleanup. `undefined`
+ * (no image materialized this turn) returns immediately.
+ */
+export function cleanupMaterializedImages(paths) {
+    if (!paths)
+        return;
+    for (const p of paths) {
+        try {
+            unlinkSync(p);
+        }
+        catch {
+            /* best-effort: the file is already gone, or a raced teardown removed it first */
+        }
+    }
+}

package/dist/image-vision-smoke.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The claude version where `@<path>` → Read-vision was PROVEN to work (story 058 research).
+ *
+ * WHY this exact anchor: on claude 2.1.170 a `@path` image prompt did NOT vision-encode the picture —
+ * the TUI did not turn it into a Read the model could see (story 030). On claude 2.1.195 it DOES: the
+ * two-arm proof (a blue vs a green image under the same uuid filename, each described correctly) showed
+ * `@path` → Read vision-encodes. So 2.1.195 is the earliest version we are willing to call "confirmed";
+ * anything below is treated as unconfirmed and warned about.
+ */
+export declare const VISION_CONFIRMED_CLAUDE_VERSION = "2.1.195";
+/** The verdict {@link imageVisionSmoke} returns. Observability only — there is NO capability toggle here. */
+export interface VisionSmokeResult {
+    /** True iff the running `claude` version is one we have CONFIRMED vision-encodes `@image` via Read. */
+    confirmed: boolean;
+    /**
+     * Human-readable one-liner. On `confirmed=true` it is a positive note. On `confirmed=false` it is the
+     * fail-loud WARNING text and NAMES the detected version (or "undetected") plus the confirmed anchor
+     * (mirrors drift-checks.ts's "name the offending value" habit).
+     */
+    detail: string;
+}
+/**
+ * Compare two `x.y.z` semver strings: `true` iff `a >= b` componentwise (major, then minor, then patch).
+ *
+ * Splits on `.`, parses the three leading numeric components; a missing/non-numeric component counts as
+ * `0` (so `"2.1"` reads as `2.1.0`). Private to this module — exported only so the unit test can pin the
+ * ordering directly. Pure.
+ */
+export declare function versionGte(a: string, b: string): boolean;
+/**
+ * PURE verdict: is the running `claude` `version` one we have CONFIRMED vision-encodes `@image` via Read?
+ *
+ * `confirmed: true` IFF `version` is a parseable leading `x.y.z` that is `>= {@link
+ * VISION_CONFIRMED_CLAUDE_VERSION}`. In that case `detail` is a positive one-liner.
+ *
+ * Otherwise (`null` / `undefined` / unparseable, OR a parseable version BELOW the anchor) `confirmed:
+ * false` and `detail` is the fail-loud WARNING text — it NAMES the detected version (or "undetected")
+ * and the confirmed anchor, and states that the image is NOT blocked (R3.1). No I/O; depends only on
+ * its argument.
+ */
+export declare function imageVisionSmoke(version: string | null | undefined): VisionSmokeResult;
+/**
+ * Best-effort fail-loud reporter: compute {@link imageVisionSmoke} and, WHEN unconfirmed, log the
+ * verdict's `detail` EXACTLY ONCE via `log` with an `[image-vision]` prefix (mirrors claude-path.ts's
+ * reportVersionDrift `[claude-path] …` style). Returns the verdict.
+ *
+ * Logs NOTHING on a confirmed version (a confirmed `claude` is the expected case — no news is good news,
+ * matching reportVersionDrift which is silent when there is no drift). NEVER blocks and NEVER throws out
+ * of the caller's intent — it is pure aside from the single conditional `log` call (R3.1, R3.2).
+ */
+export declare function reportImageVisionSmoke(version: string | null | undefined, log?: (...args: unknown[]) => void): VisionSmokeResult;

package/dist/image-vision-smoke.js

@@ -0,0 +1,111 @@
+// === Story 058 / Task 3.1 (R3.1, R3.2) — version-aware image-vision smoke (pure verdict + fail-loud) ==
+//
+// The whole "image input via @path" feature rests on a VERSION-FRAGILE claude behavior: a prompt
+// containing `@<path>` makes the native TUI invoke the Read tool, and Read vision-encodes the image so
+// the model can see it. This was PROVEN on claude 2.1.195 (story 058 research — two-arm proof: a blue
+// image vs a green image under the same filename, each correctly described). It did NOT work on claude
+// 2.1.170 (story 030): there, `@path` did not vision-encode, so an image prompt silently dropped its
+// picture.
+//
+// Because the behavior is version-fragile, this module makes a too-old / unknown `claude` LOUD instead
+// of silently dropping the image. It mirrors story 049's drift discipline:
+//   - the VERDICT is PURE (no I/O — like src/drift-checks.ts's `{surface, ok, detail}` checks), and
+//   - the REPORTER is best-effort + fail-loud one-liner (like src/claude-path.ts's reportVersionDrift,
+//     `[claude-path] …`); here the prefix is `[image-vision]`.
+//
+// CRITICAL — OBSERVABILITY ONLY, NEVER A GATE (R3.1): this smoke NEVER blocks the prompt and NEVER
+// touches `promptCapabilities.image`, which stays literally `image: true` (acp-agent.ts:1413),
+// UNCONDITIONALLY. The verdict's only output is `{confirmed, detail}` — there is deliberately NO field
+// or return shape here that could disable a capability. A too-old `claude` produces a WARNING, not a
+// degraded capability: the image still rides the @path delivery; we just warn that this `claude` is not
+// a version we have confirmed vision-encodes it.
+//
+// LIMITATION (documented honestly): this is an OFFLINE `>= anchor` version-gate. It catches too-old and
+// undetected/unparseable versions, but it CANNOT catch a *future regression* — a hypothetical 2.1.300
+// that re-breaks @path-vision would still parse as `>= 2.1.195` and report confirmed. Catching a future
+// regression needs the LIVE smoke (opt-in — story 058 R4 probe: actually send @image and check the
+// model saw it), which this offline gate intentionally does NOT implement.
+//
+// node:test runner: `node --experimental-strip-types --test test/image-vision-smoke.test.ts`
+/**
+ * The claude version where `@<path>` → Read-vision was PROVEN to work (story 058 research).
+ *
+ * WHY this exact anchor: on claude 2.1.170 a `@path` image prompt did NOT vision-encode the picture —
+ * the TUI did not turn it into a Read the model could see (story 030). On claude 2.1.195 it DOES: the
+ * two-arm proof (a blue vs a green image under the same uuid filename, each described correctly) showed
+ * `@path` → Read vision-encodes. So 2.1.195 is the earliest version we are willing to call "confirmed";
+ * anything below is treated as unconfirmed and warned about.
+ */
+export const VISION_CONFIRMED_CLAUDE_VERSION = "2.1.195";
+/**
+ * Compare two `x.y.z` semver strings: `true` iff `a >= b` componentwise (major, then minor, then patch).
+ *
+ * Splits on `.`, parses the three leading numeric components; a missing/non-numeric component counts as
+ * `0` (so `"2.1"` reads as `2.1.0`). Private to this module — exported only so the unit test can pin the
+ * ordering directly. Pure.
+ */
+export function versionGte(a, b) {
+    const partsA = a.split(".");
+    const partsB = b.split(".");
+    for (let i = 0; i < 3; i++) {
+        const na = toComponent(partsA[i]);
+        const nb = toComponent(partsB[i]);
+        if (na !== nb) {
+            return na > nb;
+        }
+    }
+    return true; // all three components equal → a >= b holds
+}
+/** Parse one semver component to a non-negative integer; missing / non-numeric → 0. */
+function toComponent(part) {
+    if (part === undefined) {
+        return 0;
+    }
+    const n = Number.parseInt(part, 10);
+    return Number.isNaN(n) ? 0 : n;
+}
+/** Matches a leading `x.y.z` triple — same shape parseClaudeVersion extracts (claude-path.ts:58). */
+const SEMVER_RE = /^(\d+\.\d+\.\d+)/;
+/**
+ * PURE verdict: is the running `claude` `version` one we have CONFIRMED vision-encodes `@image` via Read?
+ *
+ * `confirmed: true` IFF `version` is a parseable leading `x.y.z` that is `>= {@link
+ * VISION_CONFIRMED_CLAUDE_VERSION}`. In that case `detail` is a positive one-liner.
+ *
+ * Otherwise (`null` / `undefined` / unparseable, OR a parseable version BELOW the anchor) `confirmed:
+ * false` and `detail` is the fail-loud WARNING text — it NAMES the detected version (or "undetected")
+ * and the confirmed anchor, and states that the image is NOT blocked (R3.1). No I/O; depends only on
+ * its argument.
+ */
+export function imageVisionSmoke(version) {
+    const parsed = typeof version === "string" ? SEMVER_RE.exec(version) : null;
+    if (parsed && versionGte(parsed[1], VISION_CONFIRMED_CLAUDE_VERSION)) {
+        return {
+            confirmed: true,
+            detail: `claude ${parsed[1]} >= ${VISION_CONFIRMED_CLAUDE_VERSION} — @image is confirmed to vision-encode via Read`,
+        };
+    }
+    const named = parsed ? parsed[1] : "undetected";
+    return {
+        confirmed: false,
+        detail: `@image vision-encoding is UNCONFIRMED on this claude (detected ${named}; confirmed at ` +
+            `${VISION_CONFIRMED_CLAUDE_VERSION}+). Sending images anyway — image input is NOT blocked — but ` +
+            `if the picture is ignored, upgrade claude to ${VISION_CONFIRMED_CLAUDE_VERSION} or newer`,
+    };
+}
+/**
+ * Best-effort fail-loud reporter: compute {@link imageVisionSmoke} and, WHEN unconfirmed, log the
+ * verdict's `detail` EXACTLY ONCE via `log` with an `[image-vision]` prefix (mirrors claude-path.ts's
+ * reportVersionDrift `[claude-path] …` style). Returns the verdict.
+ *
+ * Logs NOTHING on a confirmed version (a confirmed `claude` is the expected case — no news is good news,
+ * matching reportVersionDrift which is silent when there is no drift). NEVER blocks and NEVER throws out
+ * of the caller's intent — it is pure aside from the single conditional `log` call (R3.1, R3.2).
+ */
+export function reportImageVisionSmoke(version, log = console.error) {
+    const result = imageVisionSmoke(version);
+    if (!result.confirmed) {
+        log(`[image-vision] ${result.detail}`);
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -88,6 +88,12 @@ else {
     // (src/live-subagent-env.ts) so the truth table is unit-checkable; threaded through
     // runAcp → AgentDeps → the agent.
     const liveSubagentWatch = liveSubagentWatchEnabled();
+    // Story 056 / Task 7 (R3.5): enable the live agent-discovery probe in PRODUCTION only. The probe
+    // (agent-catalog.ts) spawns `claude --agent <sentinel>` once per createSession to read `claude`'s
+    // canonical persona list (enabled plugins + built-ins) for the 4th `agent` selector. Gated opt-in so
+    // the unit suite — which imports modules directly without this flag — stays on the hermetic glob
+    // fallback and never spawns the real binary. `??=` keeps a user opt-out (`FORK_AGENT_PROBE=0`).
+    process.env.FORK_AGENT_PROBE ??= "1";
     const { connection, agent } = runAcp({ usageUpdate, gate, liveDiff, liveSubagentWatch });
     async function shutdown() {
         await agent.dispose().catch((err) => {

package/dist/jsonl.d.ts

@@ -264,4 +264,3 @@ export declare function stripHeavyImages(message: unknown, imageSkipBytes?: numb
  * @returns the typed {@link JsonlEvent}.
  */
 export declare function projectEvent(message: unknown, opts?: ProjectOptions): JsonlEvent;
-//# sourceMappingURL=jsonl.d.ts.map

package/dist/lib.d.ts

@@ -3,4 +3,3 @@ export { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./u
 export { toolInfoFromToolUse, toDisplayPath, planEntries, toolUpdateFromToolResult, } from "./tools.js";
 export { SettingsManager, type SettingsManagerOptions } from "./settings.js";
 export type { ClaudePlanEntry } from "./tools.js";
-//# sourceMappingURL=lib.d.ts.map