@lucascouts/claude-agent-tui 0.5.2 → 0.6.0

package/dist/engine-lifecycle.js

@@ -21,7 +21,8 @@
 // debounced resize, the cancel primitives, the robust resume, and the single-process binding
 // land in Tasks 2–5.
 import pty from "node-pty";
-import { assertSpawnEnvUntainted, buildSanitizedEnv, resolveShell, spawnClaudePty, } from "./engine-pty.js";
+import { assertSpawnEnvUntainted, buildAddDirFlags, buildSanitizedEnv, resolveShell, spawnClaudePty, } from "./engine-pty.js";
+import { isSafeAgentRef } from "./agent-catalog.js";
 import { attachAnsiMirror } from "./ansi-mirror.js";
 /**
  * Default PTY geometry applied when Zed supplies no terminal size (§5 Spawn defaults). Mirrors
@@ -172,11 +173,45 @@ const RESUME_PTY_NAME = "xterm-256color";
  * launch AND the `|| claude` fresh fallback as `--permission-mode <mode>`, so an in-place re-spawn
  * (a dontAsk/bypass switch) reattaches the SAME sessionId/transcript under the new mode. Still no
  * `-p`/`--print`/`stream-json` — billing stays subscription `cli`.
+ *
+ * Story 056 (R3.3): an optional `agent` persona name is likewise carried via `flags` as the
+ * DOUBLE-QUOTED `--agent "<name>"`. Because `flags` is interpolated into BOTH the `--resume "<id>"`
+ * launch AND the `|| claude` fresh fallback, this single addition reaches both branches (R3.3). It is
+ * the SECOND layer of the command-injection defense — re-asserted via {@link isSafeAgentRef} (which
+ * accepts a namespaced `plugin:name`) so an unsafe name is DROPPED (no flag), never interpolated.
+ * Still no `-p`/`--print`/`stream-json`.
+ *
+ * Story 057 (R1.1/R1.2): an optional `additionalDirectories` list is folded into the SAME `flags`
+ * string as ONE double-quoted `--add-dir "<dir>"` per dir — so, like the agent flag, a single addition
+ * reaches BOTH the `--resume "<id>"` half AND the `|| claude` fallback half. Each dir is re-asserted via
+ * {@link isSafeDir} (absolute + existing + no shell metacharacter); an unsafe dir is DROPPED (logged),
+ * never interpolated. Still no `-p`/`--print`/`stream-json`.
+ *
+ * Story 057 (R2.2): an optional `mcpConfigFile` PATH is likewise folded into the SAME `flags` string as
+ * the DOUBLE-QUOTED `--mcp-config "<file>"` (a file path — the secret-bearing JSON stays off the command
+ * line), so this single addition reaches BOTH the `--resume "<id>"` launch AND the `|| claude` fresh
+ * fallback. R2.2 HARD rule: `--strict-mcp-config` is NEVER emitted, so a resumed turn keeps MERGING the
+ * scratch with the user's own `.mcp.json`/settings MCP servers. Still no `-p`/`--print`/`stream-json`.
  */
-export function buildResumeArgv(sessionId, permissionMode, effortLevel) {
+export function buildResumeArgv(sessionId, permissionMode, effortLevel, agent, additionalDirectories, mcpConfigFile) {
     const pm = permissionMode && permissionMode !== "default" ? ` --permission-mode ${permissionMode}` : "";
     const ef = effortLevel && effortLevel !== "default" ? ` --effort ${effortLevel}` : "";
-    const flags = `${pm}${ef}`;
+    // Story 056 (R3.3): double-quoted agent flag, emitted only for a real persona (the "default"
+    // sentinel = no persona emits nothing, mirroring --effort) and only when it passes the R3.3
+    // allowlist re-assert; folded into `flags` so it carries into both the --resume and || claude halves.
+    const ag = agent && agent !== "default" && isSafeAgentRef(agent) ? ` --agent "${agent}"` : "";
+    // Story 057 (R1.1/R1.2): ONE double-quoted `--add-dir "<dir>"` per safe dir, built by the SAME shared
+    // {@link buildAddDirFlags} the fresh spawn path uses (single source of truth — isSafeDir: absolute +
+    // existing + no shell metachar; unsafe → dropped+logged). Folded into `flags` BELOW so the dirs carry
+    // into BOTH the --resume launch AND the || claude fresh fallback (same single-addition-reaches-both
+    // mechanism as the agent flag). Empty/undefined → "".
+    const dirs = buildAddDirFlags(additionalDirectories);
+    // Story 057 (R2.2): the double-quoted `--mcp-config "<file>"` fragment, emitted only when set; folded
+    // into `flags` BELOW so — like every other flag here — it reaches BOTH the --resume launch AND the
+    // || claude fresh fallback. NEVER `--strict-mcp-config` (R2.2): the resumed turn keeps MERGING the
+    // scratch with the user's own .mcp.json/settings MCP servers. A file path keeps the JSON off the CLI.
+    const mcp = mcpConfigFile ? ` --mcp-config "${mcpConfigFile}"` : "";
+    const flags = `${pm}${ef}${ag}${dirs}${mcp}`;
     return ["-c", `claude --resume "${sessionId}"${flags} || claude${flags}`];
 }
 /**
@@ -190,7 +225,7 @@ export function buildResumeArgv(sessionId, permissionMode, effortLevel) {
 export function spawnResumePty(opts) {
     const { sessionId, cwd, baseEnv = process.env, spawn = pty.spawn } = opts;
     const shell = resolveShell(baseEnv);
-    const argv = buildResumeArgv(sessionId, opts.permissionMode, opts.effortLevel);
+    const argv = buildResumeArgv(sessionId, opts.permissionMode, opts.effortLevel, opts.agent, opts.additionalDirectories, opts.mcpConfigFile);
     const env = buildSanitizedEnv(baseEnv);
     // §10 refuse-to-spawn guard (R4.2): abort if any forbidden billing var survived sanitization,
     // rather than resume a credit-billed run. Checks the SPAWN env, not process.env.
@@ -226,9 +261,13 @@ export function createSessionEngine(opts) {
         cwd: opts.cwd,
         baseEnv: opts.baseEnv,
         spawn: opts.spawn,
+        sessionId: opts.sessionId,
         permissionMode: opts.permissionMode,
         effortLevel: opts.effortLevel,
+        agent: opts.agent,
         settingsFile: opts.settingsFile,
+        additionalDirectories: opts.additionalDirectories,
+        mcpConfigFile: opts.mcpConfigFile,
     });
     // ONE watcher, started by the story 015 factory and bound to that same PTY.
     const watcher = opts.startWatcher?.(handle.sessionId, handle.pty);

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 {

package/dist/engine-pty.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-pty.d.ts","sourceRoot":"","sources":["../src/engine-pty.ts"],"names":[],"mappings":"AAiBA,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAQrC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,8GAKzB,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAWpC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI,CASrF;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAE9F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,GACnB,CAAC,MAAM,EAAE,MAAM,CAAC,CAElB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,CAAC,KAAK,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,eAAe,CAsCrE;AA6BD,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,WAAS,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,IAAI,EACP,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,IAAqC,GAC9E,IAAI,CAON"}
+{"version":3,"file":"engine-pty.d.ts","sourceRoot":"","sources":["../src/engine-pty.ts"],"names":[],"mappings":"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"}

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/gate/settings-writer.d.ts

@@ -144,4 +144,18 @@ export declare function injectHook(opts: {
  *   underlying error so teardown never silently strands the fork hook.
  */
 export declare function restore(backup: Backup): Promise<RestoreResult>;
+/**
+ * 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>;
 //# sourceMappingURL=settings-writer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"settings-writer.d.ts","sourceRoot":"","sources":["../../src/gate/settings-writer.ts"],"names":[],"mappings":"AA6BA,qGAAqG;AACrG,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,qGAAqG;AACrG,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,mFAAmF;IACnF,CAAC,oBAAoB,CAAC,CAAC,EAAE,IAAI,CAAC;CAC/B;AAED,wGAAwG;AACxG,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,aAAa,GAAE,MAAM,GAAG,gBAA+C,GACtE,eAAe,CAuBjB;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAuBvD;AAED,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE;QACN,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;QACvB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;KAC1B,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,KAAK,EAAE,eAAe,GAAG,YAAY,CAsB1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAiB7D;AAYD;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;CAC7B;AA2DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wGAAwG;IACxG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB;AAWD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAkEpE"}
+{"version":3,"file":"settings-writer.d.ts","sourceRoot":"","sources":["../../src/gate/settings-writer.ts"],"names":[],"mappings":"AA6BA,qGAAqG;AACrG,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,oGAAoG;AACpG,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,qGAAqG;AACrG,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,mFAAmF;IACnF,CAAC,oBAAoB,CAAC,CAAC,EAAE,IAAI,CAAC;CAC/B;AAED,wGAAwG;AACxG,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,aAAa,GAAE,MAAM,GAAG,gBAA+C,GACtE,eAAe,CAuBjB;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAuBvD;AAED,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE;QACN,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;QACvB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;KAC1B,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,KAAK,EAAE,eAAe,GAAG,YAAY,CAsB1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAiB7D;AAYD;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,uGAAuG;AACvG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;CAC7B;AA2DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wGAAwG;IACxG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB;AAWD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAkEpE;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBjG"}

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,31 @@
+/** 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;
+//# sourceMappingURL=image-input.d.ts.map

package/dist/image-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-input.d.ts","sourceRoot":"","sources":["../src/image-input.ts"],"names":[],"mappings":"AAoBA,kGAAkG;AAClG,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAelE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAK1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,CASpF"}

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,52 @@
+/**
+ * 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;
+//# sourceMappingURL=image-vision-smoke.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image-vision-smoke.d.ts","sourceRoot":"","sources":["../src/image-vision-smoke.ts"],"names":[],"mappings":"AA8BA;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,YAAY,CAAC;AAEzD,6GAA6G;AAC7G,MAAM,WAAW,iBAAiB;IAChC,uGAAuG;IACvG,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAWxD;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,iBAAiB,CAiBtF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,GAAG,GAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAoB,GAChD,iBAAiB,CAMnB"}