@lucascouts/claude-agent-tui 0.5.2 → 0.6.0

package/dist/agent-catalog.d.ts

@@ -0,0 +1,96 @@
+/** A single discoverable main-thread agent persona, as advertised to the Zed `agent` selector. */
+export interface AgentCatalogEntry {
+    /**
+     * The persona reference passed to `claude --agent <value>`. GUARANTEED to match
+     * {@link SAFE_AGENT_REF} (a single safe segment, or a namespaced `plugin:name`) — entries whose
+     * resolved name fails this are dropped at discovery, so this string is always safe to double-quote
+     * into a `-lc` shell command.
+     */
+    value: string;
+    /**
+     * Human-facing label. From the probe path it is the raw reference (e.g. `epic:analyst`); from the
+     * glob path it is the frontmatter `name`, else a humanized form of the filename.
+     */
+    displayName: string;
+    /** The frontmatter `description`, when present (glob path only — the probe lists names, not docs). */
+    description?: string;
+}
+/**
+ * Injectable seams for {@link discoverAgents} — defaults wire the `node:` stdlib. Tests pass fakes so
+ * discovery is exercised against an in-memory fs / canned probe output, never the real disk, the real
+ * `~/.claude`, or the real `claude` binary.
+ */
+export interface DiscoverAgentsDeps {
+    /**
+     * Probe `claude` for its canonical agent list (the PRIMARY source). Returns the raw combined
+     * stdout+stderr of `claude --agent <invalid>` (which contains the `Available agents: …` line), or
+     * `null` when the probe cannot run (missing binary / timeout) so discovery falls back to the glob.
+     * Default: {@link defaultProbeClaudeAgents}. Tests inject a canned string (or `null`) to stay
+     * hermetic — a glob-path test MUST pass `() => null` to force the fallback.
+     */
+    probeClaudeAgents?: () => string | null;
+    /** Resolve the user's home directory (default: `os.homedir`). Glob path only. */
+    homedir?: () => string;
+    /** List the `*.md` filenames in `dir`; MUST return `[]` when `dir` is missing/unreadable. */
+    readdirMd?: (dir: string) => string[];
+    /** Read a file's UTF-8 contents (default: `fs.readFileSync(p, "utf8")`). */
+    readFile?: (path: string) => string;
+}
+/**
+ * The persona-SEGMENT allowlist (R3.3). A single un-namespaced segment: letters/digits/underscore/
+ * hyphen only (no spaces, no shell metacharacters, no path separators, no `:`). Guards the glob path
+ * (on-disk `.md` names) and is the per-segment building block of {@link SAFE_AGENT_REF}.
+ */
+export declare const SAFE_AGENT_NAME: RegExp;
+/** True iff `name` is a non-empty string matching {@link SAFE_AGENT_NAME} (R3.3). */
+export declare function isSafeAgentName(name: unknown): name is string;
+/**
+ * The persona-REFERENCE allowlist (R3.6). A `--agent "<value>"` reference is either a single safe
+ * segment (a built-in like `Explore`, or a user/project `.md` persona) OR a namespaced plugin persona
+ * `plugin:name` — exactly ONE optional `:`-separated second segment, each segment a
+ * {@link SAFE_AGENT_NAME}. The `:` is inert inside the double-quoted shell argument.
+ */
+export declare const SAFE_AGENT_REF: RegExp;
+/** True iff `name` is a non-empty string matching {@link SAFE_AGENT_REF} (R3.6). */
+export declare function isSafeAgentRef(name: unknown): name is string;
+/**
+ * Extract the agent names from a `claude --agent <invalid>` probe output. Matches the
+ * `Available agents: a, b, c` line (tolerant of leading text and a trailing newline — `.` stops at the
+ * newline so only that line is captured), splits on commas, trims, and drops empties. Returns `[]` when
+ * the line is absent (format changed → the caller falls back to the glob).
+ */
+export declare function parseAvailableAgents(probeOutput: string): string[];
+/** Frontmatter fields we extract — only `name`/`description` matter for the catalog. */
+interface Frontmatter {
+    name?: string;
+    description?: string;
+}
+/**
+ * Minimal `---`-fenced frontmatter line-parser (NOT a full YAML dep). Reads the leading
+ * `---\n … \n---` block and pulls `key: value` lines for the keys we care about; surrounding quotes on
+ * a value are stripped. A file without an opening `---` fence yields `{}` (filename-fallback applies).
+ * Tiny + pure on purpose — the persona frontmatter we consume is flat `key: value`.
+ */
+export declare function parseFrontmatter(content: string): Frontmatter;
+/**
+ * Discover the main-thread agent personas selectable via `claude --agent <name>`.
+ *
+ * PRIMARY (Task 7, R3.5): the {@link DiscoverAgentsDeps.probeClaudeAgents} probe asks `claude` for its
+ * canonical list (enabled plugin personas + built-ins, exactly as `claude --agent` resolves them) and
+ * we parse the `Available agents:` line; the bare `claude` default and any name failing the R3.6
+ * reference allowlist are dropped, and the rest are deduped + sorted by `value`. When the probe yields
+ * at least one persona, that is the result.
+ *
+ * FALLBACK (R3.1): when the probe returns `null` (binary missing / timeout) OR its output has no
+ * `Available agents:` line OR every listed name was dropped, discovery degrades to the on-disk glob
+ * ({@link globDiscoverAgents}).
+ *
+ * Never throws: a failed probe, a missing/unreadable dir or file, or an empty/all-unsafe result yields
+ * `[]` (the empty-state that hides the picker in a later sub-task).
+ *
+ * @param cwd  the SESSION cwd (project dir) whose `.claude/agents` takes precedence in the fallback.
+ * @param deps injectable probe/fs/home seams (default: `node:` stdlib + the real `claude` probe).
+ */
+export declare function discoverAgents(cwd: string, deps?: DiscoverAgentsDeps): AgentCatalogEntry[];
+export {};
+//# sourceMappingURL=agent-catalog.d.ts.map

package/dist/agent-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-catalog.d.ts","sourceRoot":"","sources":["../src/agent-catalog.ts"],"names":[],"mappings":"AA4CA,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACxC,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IACvB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAqB,CAAC;AAElD,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAE7D;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAyC,CAAC;AAErE,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,MAAM,CAE5D;AA0CD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAOlE;AAkDD,wFAAwF;AACxF,UAAU,WAAW;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CA0B7D;AAiED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,iBAAiB,EAAE,CAe9F"}

package/dist/agent-catalog.js

@@ -0,0 +1,287 @@
+// Story 056 / Task 3.1 + Task 7 (R3.1, R3.3, R3.5, R3.6) — main-thread agent-persona discovery for
+// the Zed Agent Panel's `agent` selector.
+//
+// HYBRID DISCOVERY (refined in Task 7 — was glob-only):
+//   PRIMARY (R3.5): ask `claude` itself. We spawn `claude --agent <invalid-sentinel>` through a SAFE
+//     args-array child process (NO shell, 8s timeout, EMPTY stdin ⇒ no prompt ⇒ NO tokens/billing).
+//     `claude` rejects the sentinel and prints `Available agents: a, b, c` — listing EXACTLY what
+//     `claude --agent` accepts: enabled plugin personas (namespaced `plugin:name`) AND the built-ins
+//     (Explore, Plan, general-purpose, …). This is the same source the upstream SDK engine uses, so
+//     the panel reaches real parity with the original. LIVE-VERIFIED against 2.1.195 (deterministic,
+//     cwd-independent). The bare `claude` built-in = the no-persona default and is dropped (it maps to
+//     the option's existing "default" sentinel). The spawn mirrors claude-path.ts (execFileSync,
+//     args-list, NEVER a shell — C5); the only argument is a CONSTANT sentinel, never user input.
+//   FALLBACK (R3.1): when the probe cannot run (binary missing / timeout) OR the error format changes
+//     (no `Available agents:` line on a future version), discovery degrades to a glob of the on-disk
+//     persona files: `<cwd>/.claude/agents/*.md` (project — PRECEDENCE) + `~/.claude/agents/*.md`
+//     (user). Both dirs empty (the common case) yields `[]` and a later sub-task's gate hides the
+//     picker entirely.
+//
+// NOTE: `claude agents` (the subcommand) is the *background-agents* manager — it lists dispatched
+// cloud SESSIONS, NOT persona definitions — so we never call it; the persona list comes from the
+// `--agent` rejection message above.
+//
+// SECURITY (R3.3 / R3.6 — the highest-severity item). The `value` we return is interpolated into a
+// `-lc` shell string via `--agent "<name>"` (Task 3.3). A plugin persona is NAMESPACED (`plugin:name`),
+// so the boundary allowlist is {@link SAFE_AGENT_REF} = `/^[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)?$/`: one
+// optional `:`-separated segment, each segment letters/digits/`_`/`-` only (the `:` is inert inside the
+// double-quoted argument). Every resolved name is checked and DROPPED if it fails — a name with spaces,
+// quotes, path separators, command substitution, chaining, … is NEVER returned. The second layer is
+// double-quoting at spawn time. {@link SAFE_AGENT_NAME} (single segment) still guards the glob path,
+// where on-disk `.md` persona names are always un-namespaced.
+//
+// PURE + dependency-injectable (cf. claude-path.ts / usage-env.ts): all fs/home/probe access goes
+// through the {@link DiscoverAgentsDeps} seams so the unit tests inject fakes and never touch the real
+// disk or spawn the real `claude` binary. The only `node:` builtins are os/fs/path/child_process; no
+// shell is ever invoked. Dependency-free: a minimal inline frontmatter line-parser stands in for a YAML
+// dependency (FORK.md pins node-pty + the SDK as the only runtime deps; this adds none).
+//
+// node:test runner: `node --experimental-strip-types --test test/agent-catalog.test.ts`
+import { homedir as osHomedir } from "node:os";
+import { readdirSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+/**
+ * The persona-SEGMENT allowlist (R3.3). A single un-namespaced segment: letters/digits/underscore/
+ * hyphen only (no spaces, no shell metacharacters, no path separators, no `:`). Guards the glob path
+ * (on-disk `.md` names) and is the per-segment building block of {@link SAFE_AGENT_REF}.
+ */
+export const SAFE_AGENT_NAME = /^[A-Za-z0-9_-]+$/;
+/** True iff `name` is a non-empty string matching {@link SAFE_AGENT_NAME} (R3.3). */
+export function isSafeAgentName(name) {
+    return typeof name === "string" && SAFE_AGENT_NAME.test(name);
+}
+/**
+ * The persona-REFERENCE allowlist (R3.6). A `--agent "<value>"` reference is either a single safe
+ * segment (a built-in like `Explore`, or a user/project `.md` persona) OR a namespaced plugin persona
+ * `plugin:name` — exactly ONE optional `:`-separated second segment, each segment a
+ * {@link SAFE_AGENT_NAME}. The `:` is inert inside the double-quoted shell argument.
+ */
+export const SAFE_AGENT_REF = /^[A-Za-z0-9_-]+(?::[A-Za-z0-9_-]+)?$/;
+/** True iff `name` is a non-empty string matching {@link SAFE_AGENT_REF} (R3.6). */
+export function isSafeAgentRef(name) {
+    return typeof name === "string" && SAFE_AGENT_REF.test(name);
+}
+/** A sentinel `--agent` value that can never be a real persona — forces the "not found" + list. */
+const PROBE_SENTINEL = "__acp_agent_probe_sentinel__";
+/** The bare built-in `claude` = the no-persona default (the option's existing "default" sentinel). */
+const DEFAULT_PERSONA = "claude";
+/**
+ * Default {@link DiscoverAgentsDeps.probeClaudeAgents}: spawn `claude --agent <sentinel>` and return
+ * its combined output. `execFileSync` (args-array — NO shell, mirroring claude-path.ts / C5) throws on
+ * the expected non-zero exit; the `Available agents: …` line is carried on the error's stdout/stderr.
+ * Empty stdin + an 8s timeout keep it cheap and tokenless. Any failure (missing binary, timeout,
+ * unexpected shape) → `null`, which routes the caller to the glob fallback. The sole argument is the
+ * CONSTANT {@link PROBE_SENTINEL} — never user input — so there is no injection surface.
+ *
+ * OPT-IN (`FORK_AGENT_PROBE=1`): the spawn runs ONLY when production enables it (the fork entrypoint
+ * `index.ts` sets the flag). Unit tests import this module directly WITHOUT the flag, so the default
+ * probe is a no-op (`null` → glob fallback) — they never spawn the real `claude` and stay hermetic and
+ * fast. Tests that DO exercise the probe path inject {@link DiscoverAgentsDeps.probeClaudeAgents}
+ * directly, bypassing this gate.
+ */
+function defaultProbeClaudeAgents() {
+    if (process.env.FORK_AGENT_PROBE !== "1")
+        return null; // opt-in — production (index.ts) enables it
+    try {
+        // stdio: stdin IGNORED (claude reads EOF → no hang, no prompt → no tokens); stdout+stderr PIPED so
+        // the `Available agents:` line (claude writes it to stderr) is captured, NEVER leaked to the fork's
+        // own stdout (the ACP wire) or stderr (the log). The list lands on the throw's stderr below.
+        const out = execFileSync("claude", ["--agent", PROBE_SENTINEL], {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 8000,
+            encoding: "utf8",
+            maxBuffer: 1024 * 1024,
+        });
+        return out.length > 0 ? out : null;
+    }
+    catch (err) {
+        const e = err;
+        const out = `${e?.stdout ?? ""}${e?.stderr ?? ""}`;
+        return out.length > 0 ? out : null;
+    }
+}
+/**
+ * Extract the agent names from a `claude --agent <invalid>` probe output. Matches the
+ * `Available agents: a, b, c` line (tolerant of leading text and a trailing newline — `.` stops at the
+ * newline so only that line is captured), splits on commas, trims, and drops empties. Returns `[]` when
+ * the line is absent (format changed → the caller falls back to the glob).
+ */
+export function parseAvailableAgents(probeOutput) {
+    const m = /Available agents:\s*(.+)/.exec(probeOutput);
+    if (!m)
+        return [];
+    return m[1]
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Resolve a probe-listed agent name into an entry, or `null` to drop it. The bare `claude` built-in is
+ * the no-persona default (mapped to the option's existing "default" sentinel) so it is dropped; any
+ * name failing the R3.6 reference allowlist is dropped. `displayName` is the raw reference (e.g.
+ * `epic:analyst`), which is what the panel shows.
+ */
+function entryFromProbeName(name) {
+    if (name === DEFAULT_PERSONA)
+        return null;
+    if (!isSafeAgentRef(name))
+        return null;
+    return { value: name, displayName: name };
+}
+/**
+ * Default `readdirMd`: list `*.md` filenames in `dir`, returning `[]` when the directory is missing or
+ * unreadable (the empty-state — never throws). Sorted for a stable first-wins ordering within a dir.
+ */
+function defaultReaddirMd(dir) {
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.toLowerCase().endsWith(".md"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Default `readFile`: UTF-8 file read via the `node:fs` stdlib. */
+function defaultReadFile(path) {
+    return readFileSync(path, "utf8");
+}
+/** The leading `name` (sans `.md`) of a persona file, used as the value/displayName fallback. */
+function baseName(filename) {
+    return filename.replace(/\.md$/i, "");
+}
+/**
+ * Humanize a filename stem into a display label when the frontmatter has no `name`:
+ * `code-reviewer` → `Code Reviewer`, `db_admin` → `Db Admin`. Pure string cosmetics.
+ */
+function humanize(stem) {
+    return stem
+        .split(/[-_]+/)
+        .filter((w) => w.length > 0)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Minimal `---`-fenced frontmatter line-parser (NOT a full YAML dep). Reads the leading
+ * `---\n … \n---` block and pulls `key: value` lines for the keys we care about; surrounding quotes on
+ * a value are stripped. A file without an opening `---` fence yields `{}` (filename-fallback applies).
+ * Tiny + pure on purpose — the persona frontmatter we consume is flat `key: value`.
+ */
+export function parseFrontmatter(content) {
+    // The opening fence must be the very first line (allowing a leading BOM / blank lines is overkill
+    // for this format). Bail to `{}` when there is no fenced block.
+    const lines = content.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return {};
+    const out = {};
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "---")
+            break; // closing fence — stop
+        const m = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(line);
+        if (!m)
+            continue; // not a `key: value` line — skip (lists/comments/blanks)
+        const key = m[1].toLowerCase();
+        if (key !== "name" && key !== "description")
+            continue;
+        let value = m[2].trim();
+        // Strip a single pair of matching surrounding quotes.
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        if (value.length > 0)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Resolve a single persona `*.md` file into an {@link AgentCatalogEntry}, or `null` when it cannot
+ * contribute a SAFE entry. The resolved name is the frontmatter `name` if present, else the filename
+ * stem; it is then run through the R3.3 allowlist and the file is DROPPED (→ `null`) on any failure —
+ * including an unreadable file. `displayName` falls back to a humanized stem.
+ */
+function resolveEntry(dir, filename, readFile) {
+    let fm;
+    try {
+        fm = parseFrontmatter(readFile(join(dir, filename)));
+    }
+    catch {
+        return null; // unreadable file — skip it, never throw (R3.1 graceful)
+    }
+    const stem = baseName(filename);
+    const resolvedName = fm.name ?? stem;
+    // SECURITY (R3.3): drop any entry whose name escapes the single-segment allowlist — never returned.
+    if (!isSafeAgentName(resolvedName))
+        return null;
+    return {
+        value: resolvedName,
+        displayName: fm.name ?? humanize(stem),
+        ...(fm.description ? { description: fm.description } : {}),
+    };
+}
+/** Sort entries by `value` for a stable, scope-independent ordering. */
+function sortByValue(entries) {
+    return entries.sort((a, b) => (a.value < b.value ? -1 : a.value > b.value ? 1 : 0));
+}
+/**
+ * FALLBACK glob discovery (R3.1): scan `<cwd>/.claude/agents/*.md` (project — PRECEDENCE) and
+ * `~/.claude/agents/*.md` (user), parsing frontmatter `name`/`description` (filename stem as the
+ * fallback name), sanitizing against the R3.3 allowlist, deduping by `value` (project beats user;
+ * first-wins within a dir), and sorting by `value`. Never throws.
+ */
+function globDiscoverAgents(cwd, deps) {
+    const homedir = deps.homedir ?? osHomedir;
+    const readdirMd = deps.readdirMd ?? defaultReaddirMd;
+    const readFile = deps.readFile ?? defaultReadFile;
+    const projectDir = join(cwd, ".claude", "agents");
+    const userDir = join(homedir(), ".claude", "agents");
+    const byValue = new Map();
+    for (const dir of [projectDir, userDir]) {
+        for (const filename of readdirMd(dir)) {
+            const entry = resolveEntry(dir, filename, readFile);
+            if (entry && !byValue.has(entry.value)) {
+                byValue.set(entry.value, entry);
+            }
+        }
+    }
+    return sortByValue([...byValue.values()]);
+}
+/**
+ * Discover the main-thread agent personas selectable via `claude --agent <name>`.
+ *
+ * PRIMARY (Task 7, R3.5): the {@link DiscoverAgentsDeps.probeClaudeAgents} probe asks `claude` for its
+ * canonical list (enabled plugin personas + built-ins, exactly as `claude --agent` resolves them) and
+ * we parse the `Available agents:` line; the bare `claude` default and any name failing the R3.6
+ * reference allowlist are dropped, and the rest are deduped + sorted by `value`. When the probe yields
+ * at least one persona, that is the result.
+ *
+ * FALLBACK (R3.1): when the probe returns `null` (binary missing / timeout) OR its output has no
+ * `Available agents:` line OR every listed name was dropped, discovery degrades to the on-disk glob
+ * ({@link globDiscoverAgents}).
+ *
+ * Never throws: a failed probe, a missing/unreadable dir or file, or an empty/all-unsafe result yields
+ * `[]` (the empty-state that hides the picker in a later sub-task).
+ *
+ * @param cwd  the SESSION cwd (project dir) whose `.claude/agents` takes precedence in the fallback.
+ * @param deps injectable probe/fs/home seams (default: `node:` stdlib + the real `claude` probe).
+ */
+export function discoverAgents(cwd, deps = {}) {
+    // PRIMARY: ask `claude` — the source of truth for what `--agent` accepts.
+    const probe = deps.probeClaudeAgents ?? defaultProbeClaudeAgents;
+    const probeOut = probe();
+    if (probeOut) {
+        const byValue = new Map();
+        for (const name of parseAvailableAgents(probeOut)) {
+            const entry = entryFromProbeName(name);
+            if (entry && !byValue.has(entry.value))
+                byValue.set(entry.value, entry);
+        }
+        if (byValue.size > 0)
+            return sortByValue([...byValue.values()]);
+    }
+    // FALLBACK: the probe is unavailable or its format changed — glob the on-disk personas.
+    return globDiscoverAgents(cwd, deps);
+}

package/dist/claude-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-path.d.ts","sourceRoot":"","sources":["../src/claude-path.ts"],"names":[],"mappings":"AA6BA;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAenD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAc/E;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,WAAgC,GACrC,MAAM,GAAG,IAAI,CAMf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAChC,IAAI,CAON;AAED,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,qEAAqE;IACrE,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM,CA6BnE"}
+{"version":3,"file":"claude-path.d.ts","sourceRoot":"","sources":["../src/claude-path.ts"],"names":[],"mappings":"AA+BA;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAenD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAc/E;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,WAAgC,GACrC,MAAM,GAAG,IAAI,CAMf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAChC,IAAI,CAON;AAED,4FAA4F;AAC5F,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,qEAAqE;IACrE,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM,CAiCnE"}

package/dist/claude-path.js

@@ -26,6 +26,8 @@
 import { execFileSync } from "node:child_process";
 import { accessSync, constants } from "node:fs";
 import { delimiter, join } from "node:path";
+// Story 058 R3.2 — version-aware image-vision smoke (observability only; NEVER gates image:true, R3.1).
+import { reportImageVisionSmoke } from "./image-vision-smoke.js";
 /**
  * Provenance pin the live `claude` version is measured against — kept in lockstep
  * with `fork/.fork-provenance.json`'s externalRuntimeDeps `claude` entry. A live
@@ -121,6 +123,10 @@ export function resolveClaudePath(opts = {}) {
                     log(`[claude-path] resolved claude ${candidate} (version ${detected})`);
                 }
                 reportVersionDrift(detected, PROVENANCE_CLAUDE_VERSION, log);
+                // Story 058 R3.2 — version-aware @image vision smoke: warn ONCE (one-liner) when this claude
+                // is NOT a version confirmed to vision-encode @image via Read. Observability only — it never
+                // blocks and never touches promptCapabilities.image (stays `image: true`, R3.1).
+                reportImageVisionSmoke(detected, log);
             }
             catch {
                 // Observability is best-effort; never let it break resolution.

package/dist/end-of-turn.d.ts

@@ -144,6 +144,12 @@ export interface TurnResolverOptions {
     logger?: StopReasonLogger;
     deltaTMs?: number;
     watchdogMs?: number;
+    /**
+     * Story 056 (#812) — fired EXACTLY ONCE, ONLY on a real end-of-turn boundary (NOT on cancel, NOT
+     * on watchdog timeout), AFTER the prompt resolves. Fire-and-forget; the callback MUST NOT
+     * throw/block.
+     */
+    onTurnResolved?: () => void;
 }
 /** A detector paired with the awaitable {@link PromptResponse} the prompt() loop returns. */
 export interface TurnResolver {

package/dist/end-of-turn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"end-of-turn.d.ts","sourceRoot":"","sources":["../src/end-of-turn.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"end-of-turn.d.ts","sourceRoot":"","sources":["../src/end-of-turn.ts"],"names":[],"mappings":"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"}

package/dist/end-of-turn.js

@@ -394,7 +394,14 @@ export function createTurnResolver(opts = {}) {
         action();
     }
     const detector = createEndOfTurnDetector({
-        onEndOfTurn: (boundary) => settle(() => resolveFn({ stopReason: mapStopReason(readStopReason(boundary), opts.logger) })),
+        onEndOfTurn: (boundary) => 
+        // Story 056 (#812): fire onTurnResolved inside the SAME settle, AFTER the prompt resolves, so it
+        // runs EXACTLY ONCE per real end-of-turn. cancel() and onTurnTimeout intentionally do NOT call
+        // it — the settle latch + the detector's firedUuids guarantee a single call per turn.
+        settle(() => {
+            resolveFn({ stopReason: mapStopReason(readStopReason(boundary), opts.logger) });
+            opts.onTurnResolved?.();
+        }),
         onTurnTimeout: (error) => settle(() => rejectFn(error)),
         schedule: opts.schedule,
         sessionId: opts.sessionId,

package/dist/engine-lifecycle.d.ts

@@ -147,8 +147,27 @@ export declare class SessionEngine {
  * 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 declare function buildResumeArgv(sessionId: string, permissionMode?: string, effortLevel?: string): [string, string];
+export declare function buildResumeArgv(sessionId: string, permissionMode?: string, effortLevel?: string, agent?: string, additionalDirectories?: string[], mcpConfigFile?: string): [string, string];
 /** Options for {@link spawnResumePty}. */
 export interface SpawnResumeOptions {
     /** The prior session id to reattach to (== the JSONL transcript basename). */
@@ -166,6 +185,27 @@ export interface SpawnResumeOptions {
     permissionMode?: string;
     /** Story 046 (R2.2): carry `--effort <level>` into the resume argv for an effort re-spawn. */
     effortLevel?: string;
+    /**
+     * Story 056 (R3.3): carry the DOUBLE-QUOTED `--agent "<name>"` into the resume argv (both the
+     * `--resume` and the `|| claude` fallback branches). Injection-safe — re-asserted against the R3.3
+     * allowlist so an unsafe name is dropped. Absent → no flag.
+     */
+    agent?: string;
+    /**
+     * Story 057 (R1.1/R1.2): carry ONE double-quoted `--add-dir "<dir>"` per dir into the resume argv —
+     * folded into the shared `flags`, so the dirs reach BOTH the `--resume` and the `|| claude` fallback
+     * branches. Injection-safe — each dir re-asserted via {@link isSafeDir} so an unsafe dir is dropped.
+     * INTERACTIVE-ONLY: adds no `-p`/`--print`/`stream-json`. Absent/empty → no flag.
+     */
+    additionalDirectories?: string[];
+    /**
+     * Story 057 (R2.2): carry the DOUBLE-QUOTED `--mcp-config "<file>"` into the resume argv — folded into
+     * the shared `flags`, so the scratch-config path reaches BOTH the `--resume` and the `|| claude`
+     * fallback branches. NEVER paired with `--strict-mcp-config`, so the resumed turn keeps MERGING the
+     * scratch with the user's own `.mcp.json`/settings MCP servers (R2.2). A file path keeps the JSON off
+     * the command line. INTERACTIVE-ONLY: adds no `-p`/`--print`/`stream-json`. Absent → no flag.
+     */
+    mcpConfigFile?: string;
 }
 /**
  * Spawn the resume PTY, reusing story 013's sanitized env (R4.2) so the resumed turn keeps the
@@ -180,6 +220,12 @@ export declare function spawnResumePty(opts: SpawnResumeOptions): PtyEngineHandl
 export interface CreateSessionEngineOptions {
     /** Host working directory the spawned TUI runs in (story 013 spawn). */
     cwd: string;
+    /**
+     * Story 056 v4 — OPTIONAL pre-chosen session id for an in-place FRESH re-spawn (a pre-interaction
+     * selector change reuses the session's id). Forwarded to {@link spawnClaudePty}; absent → a fresh
+     * `randomUUID()` (the normal createSession path).
+     */
+    sessionId?: string;
     /** Base environment to sanitize; defaults to the parent process env. */
     baseEnv?: Record<string, string | undefined>;
     /** Injectable spawn function (defaults to node-pty's `spawn`); tests pass a fake. */
@@ -191,6 +237,25 @@ export interface CreateSessionEngineOptions {
     permissionMode?: string;
     /** Story 046 (R2.2): forwarded to {@link spawnClaudePty} as `--effort <level>` for a non-"default" seed. */
     effortLevel?: string;
+    /**
+     * Story 056 (R3.3): forwarded to {@link spawnClaudePty} as the DOUBLE-QUOTED `--agent "<name>"` for a
+     * fresh spawn seeded to a main-thread agent persona. Injection-safe (R3.3 allowlist re-assert).
+     * Absent → no flag.
+     */
+    agent?: string;
+    /**
+     * Story 057 (R1.1/R1.2): forwarded to {@link spawnClaudePty} as ONE double-quoted `--add-dir "<dir>"`
+     * per safe dir for a fresh spawn. Injection-safe (each dir re-asserted via {@link isSafeDir}).
+     * INTERACTIVE-ONLY: adds no `-p`/`--print`/`stream-json`. Absent/empty → no flag.
+     */
+    additionalDirectories?: string[];
+    /**
+     * Story 057 (R2.2): forwarded to {@link spawnClaudePty} as the DOUBLE-QUOTED `--mcp-config "<file>"`
+     * for a fresh spawn (the fork-controlled scratch path from `mcp-config-writer.ts`). NEVER paired with
+     * `--strict-mcp-config`, so claude MERGES the scratch with the user's own `.mcp.json`/settings MCP
+     * servers (R2.2). INTERACTIVE-ONLY: adds no `-p`/`--print`/`stream-json`. Absent → no flag.
+     */
+    mcpConfigFile?: string;
     /**
      * Story 034 (§9 hybrid gate): per-session SCRATCH settings file carrying the fork's
      * `PreToolUse` hook, forwarded to {@link spawnClaudePty} as `--settings "<file>"`. The

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

@@ -1 +1 @@
-{"version":3,"file":"engine-lifecycle.d.ts","sourceRoot":"","sources":["../src/engine-lifecycle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine-lifecycle.d.ts","sourceRoot":"","sources":["../src/engine-lifecycle.ts"],"names":[],"mappings":"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"}