@crouton-kit/crouter 0.3.8 → 0.3.11

package/dist/core/spawn.js

@@ -7,19 +7,241 @@
 //          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',
@@ -51,8 +273,8 @@ function listWindowsInCurrentSession() {
  *
  * 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 binary
- * name (`claude`) from the kernel.
+ * 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' });
@@ -111,27 +333,36 @@ function foregroundCommsByTty() {
 }
 /**
  * Find a window in the current tmux session with fewer than `maxPanesPerWindow`
- * panes AND where every existing pane has `claude` as a 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.
+ * 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 `claude` is among its foreground commands — co-resident
- * helpers like `caffeinate` don't disqualify it.
+ * 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 isClaudeOnly = (windowId) => {
+    const isAgentOnly = (windowId) => {
         const ttys = ttysByWindow.get(windowId);
         if (ttys === undefined || ttys.length === 0)
             return false;
-        return ttys.every((tty) => fgByTty.get(tty)?.has('claude') === true);
+        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 && isClaudeOnly(w.windowId));
+    const eligible = windows.filter((w) => w.paneCount < maxPanesPerWindow && isAgentOnly(w.windowId));
     const active = eligible.find((w) => w.isActive);
     if (active !== undefined)
         return active.windowId;
@@ -163,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()) {
@@ -187,15 +418,9 @@ export function spawnAndDetach(opts) {
             message: 'handoff requires tmux (TMUX env var not set)',
         };
     }
-    const buildClaudeInner = () => {
-        const parts = ['claude'];
-        if (opts.name !== undefined && opts.name !== '') {
-            parts.push('-n', shellQuote(opts.name));
-        }
-        parts.push('--dangerously-skip-permissions', shellQuote(opts.prompt));
-        return parts.join(' ');
-    };
-    const inner = opts.command !== undefined ? opts.command : buildClaudeInner();
+    const inner = opts.command !== undefined
+        ? opts.command
+        : buildAgentCommand({ prompt: opts.prompt, name: opts.name });
     const useFailGuard = opts.failGuard !== false;
     const fullCmd = useFailGuard ? wrapperCmd(inner, opts.jobId) : inner;
     const splitArgs = [];
@@ -234,17 +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;
+}
 /**
- * Async sibling spawn. Launches a claude session in a tmux pane, progressively
- * filling existing windows up to `maxPanesPerWindow` before creating a new
- * window. Returns immediately with the pane id; the parent stays alive.
- *
- * Placement order:
- *   1. Current window, if it has space.
- *   2. Any other window in the session with space.
- *   3. New window (every existing window at capacity).
+ * 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 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()) {
@@ -253,40 +587,25 @@ export function spawnAgent(opts) {
             message: 'crtr job requires tmux (TMUX env var not set)',
         };
     }
-    const claudeParts = ['claude'];
-    if (opts.name !== undefined && opts.name !== '') {
-        claudeParts.push('-n', shellQuote(opts.name));
-    }
-    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 targetWindow = findWindowWithSpace(opts.maxPanesPerWindow);
-    const placement = targetWindow === null ? 'new-window' : 'split-window';
-    const tmuxArgs = [placement];
-    if (placement === 'split-window') {
-        tmuxArgs.push('-h', '-t', targetWindow);
-    }
-    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();
-    // Re-balance the target window's panes evenly so the new pane doesn't end up
-    // half the size of its siblings. -t <pane_id> resolves to the window it lives
-    // in for both placements (split + new-window).
-    spawnSync('tmux', ['select-layout', '-t', paneId, 'even-horizontal'], {
-        encoding: 'utf8',
+    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;