@crouton-kit/crouter 0.3.3 → 0.3.11

package/dist/core/spawn.js

@@ -1,25 +1,247 @@
 // Tmux pane spawning machinery for crtr job subtree.
 //
 // Kept: spawnAgent (fire-and-forget new pane), spawnAndDetach (detach + kill originating pane),
-//       shellQuote, isInTmux, countPanesInCurrentWindow.
+//       shellQuote, isInTmux, countPanesInCurrentWindow, findWindowWithSpace.
 //
 // Removed: createSession, submitToSession, awaitSession, waitForResult,
 //          sessionDirForId, writeSessionMeta, readSessionMeta — all superseded
 //          by the jobs.ts sidecar model (result.json + log.jsonl).
 //
+// Agent-CLI selection: crtr can be hosted by different coding agents (Claude
+// Code, pi). `detectAgentKind()` inspects the environment crtr inherited from
+// its host and `buildAgentCommand()` emits the matching invocation, so a spawn
+// launches a sibling of whatever agent is driving it.
+//
 // Crash detection: the wrapper shell command is:
-//   `claude --dangerously-skip-permissions <prompt>; crtr job _fail <job_id>`
-// If the worker calls `crtr job submit` before claude exits, result.json is
+//   `<agent invocation>; crtr job _fail <job_id>`
+// If the worker calls `crtr job submit` before the agent exits, result.json is
 // written and `_fail` is a no-op (writeResult is idempotent for done status).
-// If claude dies without a submit, `_fail` writes status 'failed'. Either way
+// If the agent dies without a submit, `_fail` writes status 'failed'. Either way
 // `job read result` sees a terminal result.json.
-import { spawnSync } from 'node:child_process';
+import { spawnSync, spawn } from 'node:child_process';
 export function isInTmux() {
     return Boolean(process.env.TMUX);
 }
 export function shellQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
+/**
+ * Foreground `comm` names that mark a tmux pane as hosting an interactive
+ * agent. claude reports `claude`; pi sets process.title to `pi`. Used by
+ * findWindowWithSpace so panes of EITHER agent count as agent panes and a
+ * mixed window still qualifies for placement.
+ */
+const AGENT_COMMS = new Set(['claude', 'pi']);
+/**
+ * Detect which coding-agent CLI is hosting the current crtr process so spawns
+ * launch a matching sibling. pi exports `PI_CODING_AGENT=true` into its tool
+ * subprocess environment; Claude Code exports `CLAUDECODE` /
+ * `CLAUDE_CODE_SESSION_ID`. Defaults to claude when no signal is present
+ * (preserves prior behavior).
+ */
+export function detectAgentKind() {
+    if (process.env.PI_CODING_AGENT === 'true')
+        return 'pi';
+    return 'claude';
+}
+/** Bare Claude-Code model aliases that subagent frontmatter uses. */
+const CLAUDE_MODEL_ALIASES = new Set(['sonnet', 'opus', 'haiku']);
+/**
+ * Normalize a `--model` value for the target agent CLI.
+ *
+ * Subagent frontmatter uses Claude Code's bare aliases (`sonnet`, `opus`,
+ * `haiku`, optionally with a `:thinking` suffix). The `claude` CLI resolves
+ * those natively, but `pi` maps a bare alias to its default provider —
+ * `amazon-bedrock` — which most users have not authenticated, so the spawn
+ * dies with "No API key found for amazon-bedrock". These aliases name Anthropic
+ * models, so under pi we pin them to the `anthropic/` provider (preserving any
+ * `:thinking` suffix). Values that already carry a `provider/` prefix or are
+ * concrete model ids are passed through untouched.
+ */
+export function normalizeModelForKind(model, kind) {
+    if (kind !== 'pi')
+        return model;
+    if (model.includes('/'))
+        return model;
+    const [base, ...rest] = model.split(':');
+    if (!CLAUDE_MODEL_ALIASES.has(base.toLowerCase()))
+        return model;
+    const suffix = rest.length > 0 ? `:${rest.join(':')}` : '';
+    return `anthropic/${base.toLowerCase()}${suffix}`;
+}
+/**
+ * Build the agent-CLI invocation (no job wrapper) for the given kind.
+ *
+ *   claude: `claude [-n <name>] [--resume <id> --fork-session] \
+ *            --dangerously-skip-permissions <prompt>`
+ *   pi:     `pi [-n <name>] [--fork <id>] <prompt>`
+ *
+ * pi has no permission popups, so it needs no skip-permissions flag.
+ */
+export function buildAgentCommand(opts, kind = detectAgentKind()) {
+    if (kind === 'pi') {
+        const parts = ['pi'];
+        if (opts.name !== undefined && opts.name !== '') {
+            parts.push('-n', shellQuote(opts.name));
+        }
+        if (opts.fork !== undefined) {
+            parts.push('--fork', shellQuote(opts.fork.sessionId));
+        }
+        if (opts.model !== undefined && opts.model !== '') {
+            parts.push('--model', shellQuote(normalizeModelForKind(opts.model, 'pi')));
+        }
+        if (opts.tools !== undefined && opts.tools.length > 0) {
+            parts.push('--tools', shellQuote(opts.tools.join(',')));
+        }
+        if (opts.systemPrompt !== undefined && opts.systemPrompt.trim() !== '') {
+            parts.push('--append-system-prompt', shellQuote(opts.systemPrompt));
+        }
+        parts.push(shellQuote(opts.prompt));
+        return parts.join(' ');
+    }
+    const parts = ['claude'];
+    if (opts.name !== undefined && opts.name !== '') {
+        parts.push('-n', shellQuote(opts.name));
+    }
+    if (opts.fork !== undefined) {
+        parts.push('--resume', shellQuote(opts.fork.sessionId), '--fork-session');
+    }
+    if (opts.model !== undefined && opts.model !== '') {
+        parts.push('--model', shellQuote(opts.model));
+    }
+    if (opts.systemPrompt !== undefined && opts.systemPrompt.trim() !== '') {
+        parts.push('--append-system-prompt', shellQuote(opts.systemPrompt));
+    }
+    parts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
+    return parts.join(' ');
+}
+/**
+ * Argv for a non-interactive print-mode run.
+ *
+ *   claude: `claude [-n <name>] [--resume <id> --fork-session] -p \
+ *            --dangerously-skip-permissions <prompt>`
+ *   pi:     `pi [-n <name>] [--fork <id>] -p <prompt>`
+ *
+ * Returned as a cmd + args array so callers can spawn without a shell.
+ */
+export function buildAgentPrintArgv(opts, kind = detectAgentKind()) {
+    if (kind === 'pi') {
+        const args = [];
+        if (opts.name !== undefined && opts.name !== '')
+            args.push('-n', opts.name);
+        if (opts.fork !== undefined)
+            args.push('--fork', opts.fork.sessionId);
+        if (opts.model !== undefined && opts.model !== '')
+            args.push('--model', normalizeModelForKind(opts.model, 'pi'));
+        if (opts.tools !== undefined && opts.tools.length > 0)
+            args.push('--tools', opts.tools.join(','));
+        if (opts.systemPrompt !== undefined && opts.systemPrompt.trim() !== '') {
+            args.push('--append-system-prompt', opts.systemPrompt);
+        }
+        args.push('-p', opts.prompt);
+        return { cmd: 'pi', args };
+    }
+    const args = [];
+    if (opts.name !== undefined && opts.name !== '')
+        args.push('-n', opts.name);
+    if (opts.fork !== undefined)
+        args.push('--resume', opts.fork.sessionId, '--fork-session');
+    if (opts.model !== undefined && opts.model !== '')
+        args.push('--model', opts.model);
+    if (opts.systemPrompt !== undefined && opts.systemPrompt.trim() !== '') {
+        args.push('--append-system-prompt', opts.systemPrompt);
+    }
+    args.push('-p', '--dangerously-skip-permissions', opts.prompt);
+    return { cmd: 'claude', args };
+}
+/** Same as buildAgentPrintArgv but rendered as a single shell-quoted string. */
+export function buildAgentPrintCommand(opts, kind = detectAgentKind()) {
+    const { cmd, args } = buildAgentPrintArgv(opts, kind);
+    return [cmd, ...args.map(shellQuote)].join(' ');
+}
+/**
+ * Run the agent headlessly and resolve once it exits. A blocking caller awaits
+ * this. stdout is captured as the result; a non-zero exit yields status
+ * 'failed' with the combined output.
+ */
+export function runAgentHeadless(opts) {
+    const { cmd, args } = buildAgentPrintArgv({
+        prompt: opts.prompt,
+        name: opts.name,
+        systemPrompt: opts.systemPrompt,
+        model: opts.model,
+        tools: opts.tools,
+    });
+    return new Promise((resolve) => {
+        let out = '';
+        let err = '';
+        let child;
+        try {
+            // stdin 'ignore' so the agent never blocks waiting for stdin EOF (the
+            // prompt is passed as an argv arg, not piped).
+            child = spawn(cmd, args, { cwd: opts.cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch (e) {
+            resolve({ status: 'failed', output: `failed to launch ${cmd}: ${String(e)}`, exitCode: null });
+            return;
+        }
+        child.stdout?.on('data', (d) => { out += d.toString(); });
+        child.stderr?.on('data', (d) => { err += d.toString(); });
+        child.on('error', (e) => {
+            resolve({ status: 'failed', output: `failed to launch ${cmd}: ${String(e)}`, exitCode: null });
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve({ status: 'done', output: out.trim() !== '' ? out : '(agent produced no output)', exitCode: 0 });
+            }
+            else {
+                const combined = `${out}${err}`.trim();
+                resolve({
+                    status: 'failed',
+                    output: combined !== '' ? combined : `agent exited with code ${code ?? 'null'}`,
+                    exitCode: code,
+                });
+            }
+        });
+    });
+}
+/**
+ * Launch a headless agent detached (background). Its print output is captured
+ * and delivered to the job via `crtr job submit`; a non-zero exit marks the job
+ * failed. Returns immediately with the wrapper pid (recorded for crash
+ * detection). No tmux required.
+ */
+export function spawnHeadlessDetached(opts) {
+    const agentCmd = buildAgentPrintCommand({
+        prompt: opts.prompt,
+        name: opts.name,
+        systemPrompt: opts.systemPrompt,
+        model: opts.model,
+        tools: opts.tools,
+    });
+    const jid = shellQuote(opts.jobId);
+    // On failure, forward the captured stdout+stderr as the result body so the
+    // real cause (e.g. an auth error) is visible via `crtr job read result`/`logs`
+    // instead of being discarded behind a generic exit-code reason.
+    const wrapper = `out="$(${agentCmd} 2>&1)"; ec=$?; ` +
+        `if [ "$ec" -eq 0 ]; then ` +
+        `if [ -z "$out" ]; then out='(agent produced no output)'; fi; ` +
+        `printf '%s' "$out" | crtr job submit ${jid}; ` +
+        `else printf '%s' "$out" | crtr job submit ${jid} --status failed --reason "agent exited with code $ec"; fi`;
+    try {
+        const child = spawn('sh', ['-c', wrapper], {
+            cwd: opts.cwd,
+            env: process.env,
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+        return { status: 'spawned', pid: child.pid, message: `headless agent started (pid ${child.pid ?? 'unknown'})` };
+    }
+    catch (e) {
+        return { status: 'spawn-failed', message: `failed to launch headless agent: ${String(e)}` };
+    }
+}
 export function countPanesInCurrentWindow() {
     const result = spawnSync('tmux', ['list-panes', '-F', '#{pane_id}'], {
         encoding: 'utf8',
@@ -28,6 +250,127 @@ export function countPanesInCurrentWindow() {
         return 0;
     return result.stdout.split('\n').filter((line) => line.trim() !== '').length;
 }
+function listWindowsInCurrentSession() {
+    const result = spawnSync('tmux', ['list-windows', '-F', '#{window_id} #{window_panes} #{window_active}'], { encoding: 'utf8' });
+    if (result.status !== 0)
+        return [];
+    return result.stdout
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+        .map((line) => {
+        const [id, count, active] = line.split(' ');
+        return {
+            windowId: id,
+            paneCount: Number.parseInt(count, 10),
+            isActive: active === '1',
+        };
+    });
+}
+/**
+ * Map of window_id → list of pane TTYs (basename, e.g. `ttys008`) for every
+ * pane in the current tmux session. Used as the bridge between tmux's pane
+ * model and the system process table for foreground-command lookup.
+ *
+ * tmux's `#{pane_current_command}` is unreliable on macOS because the Claude
+ * Code CLI sets `process.title` to its version (e.g. `2.1.143`), which is what
+ * tmux then reports. Going through the TTY + `ps` gives us the real foreground
+ * `comm` (`claude`, or `pi` from its process.title) from the kernel.
+ */
+function paneTtysByWindow() {
+    const result = spawnSync('tmux', ['list-panes', '-s', '-F', '#{window_id} #{pane_tty}'], { encoding: 'utf8' });
+    const out = new Map();
+    if (result.status !== 0)
+        return out;
+    for (const line of result.stdout.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const idx = line.indexOf(' ');
+        if (idx === -1)
+            continue;
+        const windowId = line.slice(0, idx);
+        const tty = line.slice(idx + 1);
+        const ttyBase = tty.startsWith('/dev/') ? tty.slice(5) : tty;
+        const existing = out.get(windowId);
+        if (existing === undefined) {
+            out.set(windowId, [ttyBase]);
+        }
+        else {
+            existing.push(ttyBase);
+        }
+    }
+    return out;
+}
+/**
+ * Map of tty basename → set of foreground process `comm` names on that tty.
+ * A process is "foreground" if its STAT field includes `+` (member of the
+ * terminal's foreground process group). Built from one `ps -axo ...` call.
+ */
+function foregroundCommsByTty() {
+    const result = spawnSync('ps', ['-axo', 'stat=,comm=,tty='], { encoding: 'utf8' });
+    const out = new Map();
+    if (result.status !== 0)
+        return out;
+    for (const line of result.stdout.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const m = line.match(/^(\S+)\s+(.+?)\s+(\S+)\s*$/);
+        if (m === null)
+            continue;
+        const [, stat, comm, tty] = m;
+        if (!stat.includes('+'))
+            continue;
+        if (tty === '??' || tty === '?')
+            continue;
+        const existing = out.get(tty);
+        if (existing === undefined) {
+            out.set(tty, new Set([comm.trim()]));
+        }
+        else {
+            existing.add(comm.trim());
+        }
+    }
+    return out;
+}
+/**
+ * Find a window in the current tmux session with fewer than `maxPanesPerWindow`
+ * panes AND where every existing pane hosts an agent (claude or pi) as its
+ * foreground process. Prefers the active window so the spawned pane is visible
+ * to the user; otherwise falls back to the first other eligible window. Returns
+ * the tmux window id (e.g. `@5`) to pass via `-t`, or null if no window qualifies.
+ *
+ * Windows holding non-agent panes (dashboards, log tails, idle shells, editors,
+ * REPLs, etc.) are skipped so spawning never disrupts those workflows. A pane
+ * qualifies as long as an agent comm is among its foreground commands —
+ * co-resident helpers like `caffeinate` don't disqualify it.
+ */
+export function findWindowWithSpace(maxPanesPerWindow) {
+    const windows = listWindowsInCurrentSession();
+    const ttysByWindow = paneTtysByWindow();
+    const fgByTty = foregroundCommsByTty();
+    const isAgentOnly = (windowId) => {
+        const ttys = ttysByWindow.get(windowId);
+        if (ttys === undefined || ttys.length === 0)
+            return false;
+        return ttys.every((tty) => {
+            const comms = fgByTty.get(tty);
+            if (comms === undefined)
+                return false;
+            for (const c of comms) {
+                if (AGENT_COMMS.has(c))
+                    return true;
+            }
+            return false;
+        });
+    };
+    const eligible = windows.filter((w) => w.paneCount < maxPanesPerWindow && isAgentOnly(w.windowId));
+    const active = eligible.find((w) => w.isActive);
+    if (active !== undefined)
+        return active.windowId;
+    const first = eligible[0];
+    if (first === undefined)
+        return null;
+    return first.windowId;
+}
 /**
  * Schedule a kill-pane on the *current* tmux pane after `delaySeconds`, detached
  * so the caller can return normally before the pane dies. No-op outside tmux
@@ -51,22 +394,22 @@ export function scheduleKillCurrentPane(delaySeconds) {
 /**
  * Build the wrapper shell command passed to the tmux pane.
  *
- * Pattern: `claude <args>; crtr job _fail <job_id>`
+ * Pattern: `<agent invocation>; crtr job _fail <job_id>`
  *
- * If the worker submits via `crtr job submit` before claude exits,
+ * If the worker submits via `crtr job submit` before the agent exits,
  * result.json is already written (`done`); `_fail` sees it and is a no-op.
- * If claude crashes/exits without submitting, `_fail` writes status `failed`
+ * If the agent crashes/exits without submitting, `_fail` writes status `failed`
  * so `job read result` can distinguish completion from crash.
  */
-function wrapperCmd(claudeCmd, jobId) {
-    return `${claudeCmd}; crtr job _fail ${shellQuote(jobId)}`;
+function wrapperCmd(agentCmd, jobId) {
+    return `${agentCmd}; crtr job _fail ${shellQuote(jobId)}`;
 }
 /**
- * Fire-and-forget: launch an interactive `claude` in a new pane (or window),
+ * Fire-and-forget: launch an interactive agent in a new pane (or window),
  * then schedule the originating pane to be killed after `killAfterSeconds`.
  *
  * No custom system prompt — the task is delivered as the first user message.
- * Returns as soon as the new pane is up; does NOT wait for claude to finish.
+ * Returns as soon as the new pane is up; does NOT wait for the agent to finish.
  */
 export function spawnAndDetach(opts) {
     if (!isInTmux()) {
@@ -77,7 +420,7 @@ export function spawnAndDetach(opts) {
     }
     const inner = opts.command !== undefined
         ? opts.command
-        : ['claude', '--dangerously-skip-permissions', shellQuote(opts.prompt)].join(' ');
+        : buildAgentCommand({ prompt: opts.prompt, name: opts.name });
     const useFailGuard = opts.failGuard !== false;
     const fullCmd = useFailGuard ? wrapperCmd(inner, opts.jobId) : inner;
     const splitArgs = [];
@@ -116,12 +459,126 @@ export function spawnAndDetach(opts) {
         message: `handed off to pane ${paneId}; this pane will close in ${opts.killAfterSeconds}s`,
     };
 }
+// ---------------------------------------------------------------------------
+// Dedicated subagent session
+//
+// Every subagent crtr spawns lands in a tmux session dedicated to the pi/claude
+// session that launched it, instead of splitting the user's working window. The
+// session is keyed on the originating pane ($TMUX_PANE) so it is reused across
+// spawns for the life of that pane. Spawns are interactive (headed) panes but
+// never steal focus — the user jumps to the session with Alt-o.
+//
+// Navigation state is written as tmux user-options so a keybinding can toggle
+// between the two without crtr involvement:
+//   - origin session:   @crtr_subagent_session = <subagent session name>
+//   - subagent session: @crtr_origin_session   = <origin session id>
+//                       @crtr_origin_pane      = <origin pane id>
+// ---------------------------------------------------------------------------
+function tmuxQuery(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.trim();
+}
+/** Originating pane id + session id of the host (pi/claude) crtr runs under. */
+export function originContext() {
+    const pane = process.env.TMUX_PANE;
+    if (pane === undefined || pane === '')
+        return null;
+    const sessionId = tmuxQuery(['display-message', '-p', '-t', pane, '#{session_id}']);
+    if (sessionId === null || sessionId === '')
+        return null;
+    return { pane, sessionId };
+}
+/** Deterministic subagent session name for an originating pane id (e.g. `%5`). */
+export function subagentSessionName(pane) {
+    return `crtr-agents-${pane.replace(/[^a-zA-Z0-9]/g, '')}`;
+}
+/** A window in `session` with fewer than `maxPanes` panes (active preferred). */
+function findWindowWithSpaceInSession(session, maxPanes) {
+    const r = spawnSync('tmux', ['list-windows', '-t', session, '-F', '#{window_id} #{window_panes} #{window_active}'], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    const wins = r.stdout
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => {
+        const [id, count, active] = l.split(' ');
+        return { id, count: Number.parseInt(count, 10), active: active === '1' };
+    });
+    const eligible = wins.filter((w) => w.count < maxPanes);
+    const active = eligible.find((w) => w.active);
+    if (active !== undefined)
+        return active.id;
+    return eligible[0]?.id ?? null;
+}
+/**
+ * Ensure the dedicated subagent session exists and launch `fullCmd` in it,
+ * filling windows up to `maxPanes` before opening a new window. Records the
+ * cross-session navigation options on both sides. Never switches focus — the
+ * user navigates to the subagent session themselves (Alt-o).
+ */
+function placeInSubagentSession(opts) {
+    if (!isInTmux()) {
+        return { status: 'not-in-tmux', message: 'requires tmux (TMUX env var not set)' };
+    }
+    const origin = originContext();
+    if (origin === null) {
+        return { status: 'not-in-tmux', message: 'requires tmux (TMUX_PANE not set)' };
+    }
+    const session = subagentSessionName(origin.pane);
+    const envArgs = opts.jobId !== undefined ? ['-e', `CRTR_JOB_ID=${opts.jobId}`] : [];
+    const exists = spawnSync('tmux', ['has-session', '-t', session], { encoding: 'utf8' }).status === 0;
+    let paneId;
+    let placement;
+    if (!exists) {
+        const r = spawnSync('tmux', ['new-session', '-d', '-s', session, '-c', opts.cwd, '-P', '-F', '#{pane_id}', ...envArgs, opts.fullCmd], { encoding: 'utf8' });
+        if (r.status !== 0) {
+            return { status: 'spawn-failed', message: r.stderr.trim() || 'tmux new-session failed' };
+        }
+        paneId = r.stdout.trim();
+        placement = 'new-session';
+    }
+    else {
+        const targetWindow = findWindowWithSpaceInSession(session, opts.maxPanes);
+        if (targetWindow === null) {
+            const r = spawnSync('tmux', ['new-window', '-t', session, '-c', opts.cwd, '-P', '-F', '#{pane_id}', ...envArgs, opts.fullCmd], { encoding: 'utf8' });
+            if (r.status !== 0) {
+                return { status: 'spawn-failed', message: r.stderr.trim() || 'tmux new-window failed' };
+            }
+            paneId = r.stdout.trim();
+            placement = 'new-window';
+        }
+        else {
+            const r = spawnSync('tmux', ['split-window', '-h', '-t', targetWindow, '-c', opts.cwd, '-P', '-F', '#{pane_id}', ...envArgs, opts.fullCmd], { encoding: 'utf8' });
+            if (r.status !== 0) {
+                return { status: 'spawn-failed', message: r.stderr.trim() || 'tmux split-window failed' };
+            }
+            paneId = r.stdout.trim();
+            placement = 'split-window';
+            spawnSync('tmux', ['select-layout', '-t', paneId, 'even-horizontal'], { encoding: 'utf8' });
+        }
+    }
+    // Record navigation state for the M-o toggle keybinding.
+    spawnSync('tmux', ['set-option', '-t', origin.sessionId, '@crtr_subagent_session', session], { encoding: 'utf8' });
+    spawnSync('tmux', ['set-option', '-t', session, '@crtr_origin_session', origin.sessionId], { encoding: 'utf8' });
+    spawnSync('tmux', ['set-option', '-t', session, '@crtr_origin_pane', origin.pane], { encoding: 'utf8' });
+    return {
+        status: 'spawned',
+        paneId,
+        session,
+        placement,
+        message: `agent spawned in pane ${paneId} of session ${session} (${placement})`,
+    };
+}
 /**
- * Async sibling spawn. Launches a claude session in a new tmux pane or window
- * (depending on current pane count vs maxPanesPerWindow). Returns immediately
- * with the pane id; the parent stays alive.
+ * Async sibling spawn. Launches an interactive agent (claude or pi, per
+ * detectAgentKind) in the dedicated subagent session, progressively filling
+ * windows up to `maxPanesPerWindow` before creating a new window. Returns
+ * immediately with the pane id; the parent stays alive. Focus is never
+ * switched — the user jumps to the subagent session with Alt-o.
  *
- * If `fork` is set, uses `claude --resume <id> --fork-session`.
+ * If `fork` is set, forks the host session into a fresh one.
  */
 export function spawnAgent(opts) {
     if (!isInTmux()) {
@@ -130,30 +587,25 @@ export function spawnAgent(opts) {
             message: 'crtr job requires tmux (TMUX env var not set)',
         };
     }
-    const claudeParts = ['claude'];
-    if (opts.fork !== undefined) {
-        claudeParts.push('--resume', opts.fork.sessionId, '--fork-session');
-    }
-    claudeParts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
-    const claudeCmd = claudeParts.join(' ');
-    const fullCmd = wrapperCmd(claudeCmd, opts.jobId);
-    const useNewWindow = countPanesInCurrentWindow() >= opts.maxPanesPerWindow;
-    const placement = useNewWindow ? 'new-window' : 'split-window';
-    const tmuxArgs = [placement];
-    if (!useNewWindow)
-        tmuxArgs.push('-h');
-    tmuxArgs.push('-P', '-F', '#{pane_id}', '-c', opts.cwd, '-e', `CRTR_JOB_ID=${opts.jobId}`, fullCmd);
-    const split = spawnSync('tmux', tmuxArgs, { encoding: 'utf8' });
-    if (split.status !== 0) {
-        const stderrText = split.stderr.trim();
-        const msg = stderrText === '' ? `tmux ${placement} failed` : stderrText;
-        return { status: 'spawn-failed', message: msg };
-    }
-    const paneId = split.stdout.trim();
+    const agentCmd = buildAgentCommand({
+        prompt: opts.prompt,
+        name: opts.name,
+        fork: opts.fork,
+        systemPrompt: opts.systemPrompt,
+        model: opts.model,
+        tools: opts.tools,
+    });
+    const fullCmd = wrapperCmd(agentCmd, opts.jobId);
+    const placed = placeInSubagentSession({
+        fullCmd,
+        jobId: opts.jobId,
+        cwd: opts.cwd,
+        maxPanes: opts.maxPanesPerWindow,
+    });
     return {
-        status: 'spawned',
-        paneId,
-        placement,
-        message: `agent spawned in pane ${paneId} (${placement})`,
+        status: placed.status,
+        paneId: placed.paneId,
+        placement: placed.placement === 'split-window' ? 'split-window' : 'new-window',
+        message: placed.message,
     };
 }

package/dist/core/subagents.d.ts

@@ -0,0 +1,18 @@
+import type { Scope, Subagent } from '../types.js';
+/** `<scope-root>/agents` for a given scope, or null when the scope has no root. */
+export declare function scopeAgentsDir(scope: Scope): string | null;
+/** Scope-root agents under `<scope-root>/agents/*.md`. */
+export declare function listScopeRootSubagents(scope: Scope): Subagent[];
+/** All subagents: scope-root agents (project, user) plus enabled plugins. */
+export declare function listSubagents(scopeFilter?: Scope): Subagent[];
+/** Canonical, unambiguous identifier: `<plugin>/<name>`, or bare `<name>` for
+ *  scope-root agents. */
+export declare function subagentId(a: Subagent): string;
+export interface SubagentResolutionOpts {
+    scope?: Scope;
+    plugin?: string;
+}
+/** Resolve a subagent by name. Accepts a bare `<name>` or a `<plugin>/<name>`
+ *  qualifier. Project precedes user precedes builtin; scope-root precedes
+ *  plugin. Throws notFound / ambiguous as the skill resolver does. */
+export declare function resolveSubagent(rawName: string, opts?: SubagentResolutionOpts): Subagent;