@lucascouts/claude-agent-tui 0.5.2 → 0.7.0

package/dist/command-catalog.js

@@ -0,0 +1,339 @@
+// Story 063 / Task 1.2 (R1.1, R2, R3, R5) — OFFLINE discovery of custom slash-commands for the ACP
+// fork's `available_commands` advertisement.
+//
+// The command analog of {@link file://./agent-catalog.ts}: PURE + dependency-injectable, sharing the
+// exact style — a minimal inline frontmatter line-parser (NO YAML dep), graceful `readdirMd`/`readFile`
+// seams (try/catch → the empty-state, NEVER a throw), an ordered `Map<name, entry>` first-wins dedup,
+// and an alphabetical sort. Unlike `agent-catalog.ts` this surface is FULLY OFFLINE — no subprocess,
+// no probe, no network: slash-commands live on disk (`<cwd>/.claude/commands/*.md`, `~/.claude/commands/
+// *.md`) plus a curated built-in tier. The only `node:` builtins are os/fs/path; the single non-`node:`
+// import is TYPE-ONLY (`AvailableCommand`), so it is erased at runtime and adds no runtime dependency
+// (FORK.md pins node-pty + the SDK as the only runtime deps; this file adds none).
+//
+// PRECEDENCE (R1.1 / R7 / R8.1). Four disk surfaces are consulted, highest precedence first — commands
+// out-scope skills at the SAME scope, and any cwd surface out-scopes any user surface:
+//   1. `<cwd>/.claude/commands/*.md`    (cwd commands)
+//   2. `<cwd>/.claude/skills/*/SKILL.md` (cwd skills — R7)
+//   3. `~/.claude/commands/*.md`         (user commands)
+//   4. `~/.claude/skills/*/SKILL.md`      (user skills — R7)
+// then the built-in tier (R9, populated in Task 1.5) is the LOWEST precedence: a built-in whose name
+// collides with a disk entry loses. One entry per name (first-wins across the ordered surfaces). The
+// visible result is FLAT ALPHABETICAL by `name` — tiers govern collision dedup ONLY, not grouping
+// (determinism + parity with `agent-catalog.ts`'s `sortByValue`).
+//
+// SKILLS (R7 / R7.1): a skill lives at `<scope>/.claude/skills/<name>/SKILL.md`; the command `name` is
+// the DIRECTORY name (same R3 allowlist as a command) and `description` comes from the `SKILL.md`
+// frontmatter. A skills subdir WITHOUT a `SKILL.md` is NOT a command (the `readFile` throw skips it).
+// Skills carry no `argument-hint`, so a skill entry is `{ name, description }` with no `input`.
+//
+// SECURITY (R3): a command `name` is the file's basename sans `.md`; it is checked against
+// {@link SAFE_COMMAND_NAME} = `/^[a-z0-9_-]+$/` and the entry is DROPPED on any failure (a name with
+// spaces, quotes, path separators, uppercase, … never renders). A missing/unreadable dir or file yields
+// `[]` for that surface — discovery NEVER throws or crashes the session (R3 / R5).
+//
+// PURE + dependency-injectable (R5): all fs/home access goes through the {@link DiscoverCommandsDeps}
+// seams so the unit tests inject an in-memory fs and never touch the real `~/.claude`; the built-in tier
+// is likewise an injectable seam (`builtins`) defaulting to {@link BUILTIN_COMMANDS}.
+//
+// node:test runner: `node --experimental-strip-types --test test/command-catalog.test.ts`
+import { homedir as osHomedir } from "node:os";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The curated built-in slash-command tier (R9) — the interactive `claude` TUI's own built-ins, which are
+ * baked into the binary and therefore NOT disk-discoverable. This is a CURATED APPROXIMATION (C1), NOT a
+ * live probe: it stands beside the same static-curation idea as `MODEL_CATALOG`. It is the LOWEST-
+ * precedence tier, so any disk command/skill of the same name shadows a built-in (R1/R9). Names are
+ * lowercase (R3) and every entry carries a non-empty `description` (the SDK requires it). The list is
+ * intentionally small and conservative — a documented approximation, not an exhaustive enumeration.
+ */
+export const BUILTIN_COMMANDS = [
+    { name: "clear", description: "Clear the conversation history and free up context" },
+    { name: "compact", description: "Summarize and compact the current conversation" },
+    { name: "config", description: "Open the settings / configuration panel" },
+    { name: "cost", description: "Show token usage and cost for the current session" },
+    { name: "help", description: "List available slash commands and usage help" },
+    { name: "init", description: "Initialize a CLAUDE.md with codebase documentation" },
+    { name: "memory", description: "Edit the project or user memory (CLAUDE.md) files" },
+    { name: "model", description: "Switch the active model for the session" },
+    { name: "resume", description: "Resume a previous conversation" },
+    { name: "review", description: "Review a pull request or the pending changes" },
+];
+/**
+ * The command-name allowlist (R3). A single un-namespaced segment: LOWERCASE letters/digits/underscore/
+ * hyphen only (no spaces, no uppercase, no shell metacharacters, no path separators). Slash-command
+ * names are conventionally lowercase, so — unlike `agent-catalog.ts`'s {@link SAFE_AGENT_NAME} — this
+ * allowlist excludes uppercase.
+ */
+export const SAFE_COMMAND_NAME = /^[a-z0-9_-]+$/;
+/** True iff `name` is a non-empty string matching {@link SAFE_COMMAND_NAME} (R3). */
+export function isSafeCommandName(name) {
+    return typeof name === "string" && SAFE_COMMAND_NAME.test(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.
+ * Mirrors `agent-catalog.ts`'s `defaultReaddirMd`.
+ */
+function defaultReaddirMd(dir) {
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.toLowerCase().endsWith(".md"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Default `readdirDirs`: list the IMMEDIATE sub-directory names of `dir`, returning `[]` when the
+ * directory is missing or unreadable (the empty-state — never throws). Sorted for a stable first-wins
+ * ordering within the skills tier. Mirrors the graceful try/catch style of {@link defaultReaddirMd}.
+ */
+function defaultReaddirDirs(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name)
+            .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 command file — the command's name. */
+function baseName(filename) {
+    return filename.replace(/\.md$/i, "");
+}
+/**
+ * Minimal `---`-fenced frontmatter line-parser (NOT a full YAML dep). Reads the leading `---\n … \n---`
+ * block and pulls the `description` and `argument-hint` `key: value` lines; a single pair of surrounding
+ * quotes on a value is stripped. The frontmatter key `argument-hint` (a HYPHEN) is returned as the
+ * camelCase {@link CommandFrontmatter.argumentHint}. A file whose first line is not `---` yields `{}`.
+ * Tiny + pure on purpose, mirroring `agent-catalog.ts`'s `parseFrontmatter` — the command frontmatter we
+ * consume is flat `key: value`.
+ */
+export function parseCommandFrontmatter(content) {
+    // The opening fence must be the very first line. 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 !== "description" && key !== "argument-hint")
+            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)
+            continue;
+        if (key === "description")
+            out.description = value;
+        else
+            out.argumentHint = value; // `argument-hint` → camelCase `argumentHint`
+    }
+    return out;
+}
+/**
+ * Resolve a single command `*.md` file into an {@link AvailableCommand}, or `null` when it cannot
+ * contribute a SAFE entry. The name is the filename stem, run through the R3 allowlist — the file is
+ * DROPPED (→ `null`) on any failure, including an unreadable file (NEVER throws). `description` defaults
+ * to `""` (the SDK REQUIRES it) when absent; an `argument-hint` maps to `input: { hint }`, which is
+ * OMITTED entirely when there is none.
+ */
+function resolveEntry(dir, filename, readFile) {
+    const name = baseName(filename);
+    // SECURITY (R3): drop any entry whose name escapes the allowlist — optional debug log, never a throw.
+    if (!isSafeCommandName(name)) {
+        if (process.env.FORK_COMMAND_DEBUG === "1") {
+            process.stderr.write(`[command-catalog] dropped unsafe command name: ${JSON.stringify(name)}\n`);
+        }
+        return null;
+    }
+    let fm;
+    try {
+        fm = parseCommandFrontmatter(readFile(join(dir, filename)));
+    }
+    catch {
+        return null; // unreadable file — skip it, never throw (R3 / R5 graceful)
+    }
+    const description = fm.description ?? ""; // AvailableCommand.description is REQUIRED
+    return {
+        name,
+        description,
+        ...(fm.argumentHint ? { input: { hint: fm.argumentHint } } : {}), // OMIT `input` when no hint
+    };
+}
+/**
+ * Resolve a single skill sub-directory into an {@link AvailableCommand}, or `null` when it cannot
+ * contribute a SAFE entry (R7 / R7.1). The name is the DIRECTORY name `subdirName`, run through the R3
+ * allowlist — DROPPED (→ `null`, same optional `FORK_COMMAND_DEBUG` log as {@link resolveEntry}) on any
+ * failure. The skill's `SKILL.md` is REQUIRED: `join(skillsDir, subdirName, "SKILL.md")` is read inside
+ * a try/catch and a subdir WITHOUT one (`readFile` throws) is NOT a skill (→ `null`, never throws).
+ * `description` is the `SKILL.md` frontmatter `description` (default `""` when absent). Skills carry NO
+ * `argument-hint`, so the entry is `{ name, description }` — no `input`.
+ */
+function resolveSkillEntry(skillsDir, subdirName, readFile) {
+    const name = subdirName;
+    // SECURITY (R3): drop any skill whose dir name escapes the allowlist — optional debug log, never a throw.
+    if (!isSafeCommandName(name)) {
+        if (process.env.FORK_COMMAND_DEBUG === "1") {
+            process.stderr.write(`[command-catalog] dropped unsafe skill name: ${JSON.stringify(name)}\n`);
+        }
+        return null;
+    }
+    let fm;
+    try {
+        fm = parseCommandFrontmatter(readFile(join(skillsDir, subdirName, "SKILL.md")));
+    }
+    catch {
+        return null; // no readable SKILL.md — NOT a skill, skip it, never throw (R7 guard / R5 graceful)
+    }
+    const description = fm.description ?? ""; // AvailableCommand.description is REQUIRED
+    return { name, description }; // skills have no argument-hint → no `input`
+}
+/** Sort entries by `name` for a stable, scope-independent ordering (parity with `sortByValue`). */
+function sortByName(entries) {
+    return entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/**
+ * Read the set of ENABLED plugin MARKETPLACES from `~/.claude/plugins/installed_plugins.json` (R8). The
+ * gate is intentionally PRESENCE-in-the-manifest: per R8's explicitly-named source, an INSTALLED plugin
+ * == an ENABLED plugin for this story (a finer `settings.json` → `enabledPlugins` gate is out of scope).
+ *
+ * The real manifest shape is `{ version, plugins: { "<name>@<marketplace>": [ { installPath, … }, … ] } }`
+ * — a marketplace is enabled iff at least one `<name>@<marketplace>` key maps to a NON-EMPTY install
+ * array. Everything here is DEFENSIVE against manifest-shape drift (R8 risk): a MISSING or MALFORMED
+ * manifest, a non-object `plugins`, or any key/value that doesn't fit is treated as "disabled" and simply
+ * contributes nothing — this NEVER throws (an unreadable/parse failure degrades to the empty set → all
+ * plugins skipped).
+ *
+ * @param home     the resolved home dir (the manifest lives under `home/.claude/plugins`).
+ * @param readFile the injectable UTF-8 file reader (throws on a missing manifest — caught here).
+ * @returns the set of enabled marketplace names (EMPTY when the manifest is absent/malformed).
+ */
+function readEnabledMarketplaces(home, readFile) {
+    const path = join(home, ".claude", "plugins", "installed_plugins.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFile(path));
+    }
+    catch {
+        return new Set(); // missing or malformed manifest → no enabled marketplaces (plugins skipped)
+    }
+    const enabled = new Set();
+    // `plugins` must be a plain, non-null object; anything else (array, primitive, null, absent) → empty.
+    const plugins = parsed?.plugins;
+    if (typeof plugins !== "object" || plugins === null || Array.isArray(plugins))
+        return enabled;
+    for (const [key, value] of Object.entries(plugins)) {
+        // An installed plugin: a `<name>@<marketplace>` key mapping to a NON-EMPTY install array.
+        if (!Array.isArray(value) || value.length === 0)
+            continue; // treat "not installed" as disabled
+        const at = key.lastIndexOf("@"); // marketplace = substring AFTER the last `@`
+        if (at < 0)
+            continue;
+        const marketplace = key.slice(at + 1);
+        if (marketplace.length > 0)
+            enabled.add(marketplace);
+    }
+    return enabled;
+}
+/**
+ * Discover the custom slash-commands to advertise via ACP `available_commands` — FULLY OFFLINE (no
+ * subprocess, no network).
+ *
+ * TIERS, highest precedence first:
+ *   1. `<cwd>/.claude/commands/*.md`      (cwd commands — R1.1 precedence)
+ *   2. `<cwd>/.claude/skills/<name>/SKILL.md` (cwd skills — R7)
+ *   3. `~/.claude/commands/*.md`           (user commands)
+ *   4. `~/.claude/skills/<name>/SKILL.md`   (user skills — R7)
+ *   5. `~/.claude/plugins/marketplaces/<m>/{commands,skills}` (ENABLED-plugin tier — R8; a plugin
+ *      surface loses a name collision to any higher tier — R8.1)
+ *   6. {@link DiscoverCommandsDeps.builtins} (the R9 built-in tier — LOWEST; a built-in loses a name
+ *      collision to any disk entry)
+ *
+ * Each command `*.md` file yields `{ name, description, input? }` (R2): `name` = basename sans `.md`,
+ * `description` = frontmatter `description` (else `""`), `input: { hint }` from `argument-hint` (omitted
+ * when absent). Each skill `<name>/SKILL.md` yields `{ name, description }` (no `input`): `name` = the
+ * DIRECTORY name, `description` = the `SKILL.md` frontmatter (R7 / R7.1). Every name is dropped if it
+ * fails the R3 {@link SAFE_COMMAND_NAME} allowlist. Names are deduped FIRST-WINS across the ordered
+ * surfaces — so a cwd command out-ranks a cwd skill (cmd > skill, same scope), any cwd surface
+ * out-ranks any user surface, an enabled-plugin surface out-ranks the built-ins but LOSES to any
+ * cwd/user surface (R8.1) — then the merged set is returned FLAT ALPHABETICAL by `name`.
+ *
+ * Never throws (R3 / R5): a missing/unreadable dir or file yields `[]` for that surface; a skills subdir
+ * without a readable `SKILL.md` is skipped.
+ *
+ * @param cwd  the SESSION cwd (project dir) whose `.claude/{commands,skills}` take precedence.
+ * @param deps injectable fs/home/builtins seams (default: `node:` stdlib + {@link BUILTIN_COMMANDS}).
+ */
+export function discoverCommands(cwd, deps = {}) {
+    const homedir = deps.homedir ?? osHomedir;
+    const readdirMd = deps.readdirMd ?? defaultReaddirMd;
+    const readdirDirs = deps.readdirDirs ?? defaultReaddirDirs;
+    const readFile = deps.readFile ?? defaultReadFile;
+    const builtins = deps.builtins ?? BUILTIN_COMMANDS;
+    const home = homedir();
+    // Ordered disk surfaces (highest precedence first) — commands scanned via `readdirMd`+`resolveEntry`,
+    // skills via `readdirDirs`+`resolveSkillEntry`. A cwd command outranks a cwd skill; any cwd surface
+    // outranks any user surface (R1.1 / R7). The plugin tier (R8) slots in AFTER these, before builtins.
+    const userSources = [
+        { kind: "commands", dir: join(cwd, ".claude", "commands") }, // cwd commands — highest
+        { kind: "skills", dir: join(cwd, ".claude", "skills") }, // cwd skills
+        { kind: "commands", dir: join(home, ".claude", "commands") }, // user commands
+        { kind: "skills", dir: join(home, ".claude", "skills") }, // user skills
+    ];
+    const byName = new Map();
+    const add = (entry) => {
+        if (entry && !byName.has(entry.name))
+            byName.set(entry.name, entry);
+    };
+    // Fold one ordered disk surface into `byName` (first-wins): a commands dir via `readdirMd`, a skills
+    // dir via `readdirDirs`. Shared by the user tier and the per-marketplace plugin tier.
+    const foldSource = (source) => {
+        if (source.kind === "commands") {
+            for (const filename of readdirMd(source.dir))
+                add(resolveEntry(source.dir, filename, readFile));
+        }
+        else {
+            for (const subdir of readdirDirs(source.dir))
+                add(resolveSkillEntry(source.dir, subdir, readFile));
+        }
+    };
+    for (const source of userSources)
+        foldSource(source);
+    // Plugin tier (R8), AFTER the user surfaces and BEFORE builtins — gated to ENABLED marketplaces per
+    // `installed_plugins.json`. For each enabled marketplace (dirs already sorted), fold its `commands`
+    // then its `skills`; first-wins means any plugin name already claimed by a cwd/user surface is DROPPED
+    // (R8.1). A missing marketplaces dir / manifest degrades to skipping plugins (never throws).
+    const marketplacesDir = join(home, ".claude", "plugins", "marketplaces");
+    const enabled = readEnabledMarketplaces(home, readFile);
+    for (const m of readdirDirs(marketplacesDir)) {
+        if (!enabled.has(m))
+            continue; // treat a not-installed marketplace as disabled
+        foldSource({ kind: "commands", dir: join(marketplacesDir, m, "commands") });
+        foldSource({ kind: "skills", dir: join(marketplacesDir, m, "skills") });
+    }
+    // Built-in tier LAST (lowest precedence): a built-in whose name already appeared on disk is dropped.
+    for (const cmd of builtins) {
+        if (isSafeCommandName(cmd.name) && !byName.has(cmd.name))
+            byName.set(cmd.name, cmd);
+    }
+    return sortByName([...byName.values()]);
+}

package/dist/diff-enriched-reader.d.ts

@@ -38,4 +38,3 @@ export interface DiffEnrichedReaderOptions {
  * @returns a {@link GetMessages} that yields the base messages with `toolUseResult` hydrated by uuid.
  */
 export declare function createDiffEnrichedReader(base: GetMessages, opts?: DiffEnrichedReaderOptions): GetMessages;
-//# sourceMappingURL=diff-enriched-reader.d.ts.map

package/dist/diff-source.d.ts

@@ -101,4 +101,3 @@ export interface DiffToolCallUpdate {
  *   diff content (an unsupported/not-a-diff-source source, or a translation with no `content`).
  */
 export declare function diffToolCallUpdate(source: DiffSource, toolCallId: string): DiffToolCallUpdate | null;
-//# sourceMappingURL=diff-source.d.ts.map

package/dist/drift-checks.d.ts

@@ -54,4 +54,3 @@ export declare function checkJsonlShape(lines: ReadonlyArray<Record<string, unkn
  * allow-inject.ts:29 `KEYSTROKE_YES`. Pure: depends only on `keystroke`.
  */
 export declare function checkAllowKeystroke(keystroke: string): CheckResult;
-//# sourceMappingURL=drift-checks.d.ts.map

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 {
@@ -169,4 +175,3 @@ export interface TurnResolver {
  * late boundary cannot produce a second settlement).
  */
 export declare function createTurnResolver(opts?: TurnResolverOptions): TurnResolver;
-//# sourceMappingURL=end-of-turn.d.ts.map

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
@@ -238,4 +303,3 @@ export interface CreateSessionEngineOptions {
  * ──────────────────────────────────────────────────────────────────────────────────────────────
  */
 export declare function createSessionEngine(opts: CreateSessionEngineOptions): SessionEngine;
-//# sourceMappingURL=engine-lifecycle.d.ts.map

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);