brainclaw 0.29.2 → 1.5.4

package/dist/core/agent-capability.js

@@ -4,95 +4,645 @@
  * integration depth, and pressure level accordingly.
  *
  * Three profile tiers drive instruction file templates:
- *   A (full)    — MCP + hooks + auto-approve → lightweight instructions
- *   B (standard) — MCP, no hooks → directive instructions with top traps
+ *   A (full)    — MCP + hooks → lightweight instructions (context via hooks/MCP)
+ *   B (standard) — MCP, no hooks → working rules + architecture + top traps
  *   C (limited) — no MCP → rich static content (plans, traps, decisions)
+ *
+ * Tier A agents (as of 2026-04): Claude Code, Copilot, Codex, Cursor,
+ * Windsurf (12 hooks!), Cline (macOS/Linux only).
+ * Note: Cline hooks don't work on Windows — but templateTier stays A
+ * because brainclaw generates hooks that gracefully degrade.
  */
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+/** Agent name aliases — maps common short names to canonical profile names. */
+const AGENT_ALIASES = {
+    'copilot': 'github-copilot',
+    'gh-copilot': 'github-copilot',
+    'gemini': 'antigravity',
+    'mistral': 'mistral-vibe',
+    'vibe': 'mistral-vibe',
+};
+/** Resolve an alias to its canonical agent name, or return the input unchanged. */
+export function resolveAgentAlias(name) {
+    return AGENT_ALIASES[name] ?? name;
+}
 const PROFILES = {
     // --- Code agents (interactive, IDE-driven) ---
     'claude-code': {
         name: 'claude-code', category: 'code-agent', workflowModel: 'interactive',
         hasMcp: true, hasHooks: true, hasAutoApprove: true, hasSkills: true, hasRules: true,
         instructionFile: 'CLAUDE.md', sharedInstructionFile: true, mcpConfigScope: 'both', templateTier: 'A',
+        role_capabilities: ['execute', 'coordinate', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: true, inbox: true },
+        max_concurrent_tasks: 3,
+        // Claude CLI: -p is a flag (print mode), prompt is positional or via stdin.
+        // Use stdin_pipe to avoid shell quoting issues with long prompts.
+        prompt_delivery: { methods: ['stdin_pipe', 'inline_arg', 'inbox_structured'], preferred: 'stdin_pipe', max_inline_length: 4000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'claude -p --allowedTools "Edit,Write,Bash,Read,Glob,Grep" {prompt}',
+        invoke_binary: 'claude',
+        invoke_review_template: 'claude -p --allowedTools "Read,Glob,Grep" {prompt}',
+        invoke_consult_template: 'claude -p --allowedTools "Read,Glob,Grep" {prompt}',
+    },
+    'claude-sonnet': {
+        name: 'claude-sonnet', category: 'code-agent', workflowModel: 'interactive',
+        hasMcp: true, hasHooks: true, hasAutoApprove: true, hasSkills: true, hasRules: true,
+        instructionFile: 'CLAUDE.md', sharedInstructionFile: true, mcpConfigScope: 'both', templateTier: 'A',
+        role_capabilities: ['execute', 'coordinate', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: true, inbox: true },
+        max_concurrent_tasks: 6,
+        prompt_delivery: { methods: ['stdin_pipe', 'inline_arg', 'inbox_structured'], preferred: 'stdin_pipe', max_inline_length: 4000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'claude --model sonnet -p --allowedTools "Edit,Write,Bash,Read,Glob,Grep" {prompt}',
+        invoke_binary: 'claude',
+        invoke_review_template: 'claude --model sonnet -p --allowedTools "Read,Glob,Grep" {prompt}',
+        invoke_consult_template: 'claude --model sonnet -p --allowedTools "Read,Glob,Grep" {prompt}',
     },
     cursor: {
         name: 'cursor', category: 'code-agent', workflowModel: 'interactive',
-        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: false, hasRules: true,
-        instructionFile: '.cursor/rules/brainclaw.md', sharedInstructionFile: false, mcpConfigScope: 'machine', templateTier: 'B',
+        hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        instructionFile: '.cursor/rules/brainclaw.md', sharedInstructionFile: false, mcpConfigScope: 'machine', templateTier: 'A',
+        role_capabilities: ['execute', 'review'],
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: false, canSpawnOtherCli: false, inbox: false },
+        prompt_delivery: { methods: ['inbox_structured'], preferred: 'inbox_structured' },
+        max_concurrent_tasks: 1,
+        execution_env: { surface: 'ide' },
     },
     windsurf: {
         name: 'windsurf', category: 'code-agent', workflowModel: 'interactive',
-        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: false, hasRules: true,
-        instructionFile: '.windsurfrules', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'B',
+        hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        instructionFile: '.windsurfrules', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'A',
+        role_capabilities: ['execute', 'review'],
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: false, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inbox_structured'], preferred: 'inbox_structured' },
+        execution_env: { surface: 'ide' },
     },
     cline: {
         name: 'cline', category: 'code-agent', workflowModel: 'interactive',
-        hasMcp: true, hasHooks: false, hasAutoApprove: true, hasSkills: false, hasRules: true,
-        instructionFile: '.clinerules/brainclaw.md', sharedInstructionFile: false, mcpConfigScope: 'project', templateTier: 'B',
+        hasMcp: true, hasHooks: true, hasAutoApprove: true, hasSkills: true, hasRules: true,
+        instructionFile: '.clinerules/brainclaw.md', sharedInstructionFile: false, mcpConfigScope: 'project', templateTier: 'A',
+        role_capabilities: ['execute', 'review'],
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
+        max_concurrent_tasks: 3,
+        prompt_delivery: { methods: ['inline_arg', 'inbox_structured'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'extension' },
+        invoke_template: 'cline -y "{prompt}"',
+        invoke_binary: 'cline',
+        invoke_review_template: 'cline -y "{prompt}"',
     },
     roo: {
         name: 'roo', category: 'code-agent', workflowModel: 'interactive',
         hasMcp: true, hasHooks: false, hasAutoApprove: true, hasSkills: false, hasRules: true,
         instructionFile: '.roo/rules/brainclaw.md', sharedInstructionFile: false, mcpConfigScope: 'project', templateTier: 'B',
+        role_capabilities: ['execute', 'review'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
+        max_concurrent_tasks: 2,
+        prompt_delivery: { methods: ['inline_arg', 'inbox_structured'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'extension' },
+        invoke_template: 'roo -y "{prompt}"',
+        invoke_binary: 'roo',
+        invoke_review_template: 'roo -y "{prompt}"',
     },
     continue: {
         name: 'continue', category: 'code-agent', workflowModel: 'interactive',
         hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: false, hasRules: true,
         instructionFile: '.continue/rules/brainclaw.md', sharedInstructionFile: false, mcpConfigScope: 'both', templateTier: 'B',
+        role_capabilities: ['execute', 'consult'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 2,
+        prompt_delivery: { methods: ['inline_arg', 'inbox_structured'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'extension' },
+        invoke_template: 'cn --auto "{prompt}"',
+        invoke_binary: 'cn',
+        invoke_review_template: 'cn --auto --readonly "{prompt}"',
     },
     opencode: {
         name: 'opencode', category: 'code-agent', workflowModel: 'interactive',
         hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: false, hasRules: true,
         instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'project', templateTier: 'B',
+        role_capabilities: ['execute', 'review'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 2,
+        prompt_delivery: { methods: ['inline_arg', 'temp_file'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'opencode "{prompt}"',
+        invoke_binary: 'opencode',
+        invoke_review_template: 'opencode "{prompt}"',
     },
+    // Sandbox note: when running under --sandbox workspace-write, Codex cannot reach
+    // the main project store via MCP. Use filesystem-direct writes instead:
+    // write candidates to .brainclaw/coordination/inbox/cnd_<id>.json in the active
+    // worktree. The coordinator then syncs them via bclaw_harvest_candidates.
     codex: {
         name: 'codex', category: 'code-agent', workflowModel: 'task-based',
-        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: false, hasRules: true,
-        instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'B',
+        hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'A',
+        role_capabilities: ['execute', 'review'],
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
+        max_concurrent_tasks: 5,
+        // pln#475: prefer stdin_pipe to avoid Windows cmd.exe arg-parsing breaking
+        // long prompts. codex.cmd resolves through cmd shell, where embedded
+        // backticks/`#` chars made codex CLI raise "unexpected argument" (trp#59).
+        // Codex CLI reads stdin when the [PROMPT] arg is omitted (`codex exec`
+        // with no positional). The execution adapter pipes promptText to stdin.
+        // inline_arg stays as a fallback for short prompts on POSIX.
+        prompt_delivery: { methods: ['stdin_pipe', 'inline_arg'], preferred: 'stdin_pipe' },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'codex exec -c approval_policy="never" --sandbox workspace-write "{prompt}"',
+        invoke_binary: 'codex',
+        // Review runs need shell access for git/grep/rg and filesystem reads of
+        // the whole repo. Older templates forced --sandbox read-only on reviews,
+        // but that blocks PowerShell exec on Windows and forced reviewers to
+        // fall back to GitHub connectors — which fail for local-only commits.
+        // Aligning with the regular spawn template (workspace-write) is the
+        // accepted pattern per agent_spawn_inventory memory.
+        invoke_review_template: 'codex exec -c approval_policy="never" --sandbox workspace-write "{prompt}"',
     },
     antigravity: {
         name: 'antigravity', category: 'code-agent', workflowModel: 'interactive',
         hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: false, hasRules: true,
         instructionFile: 'GEMINI.md', sharedInstructionFile: true, mcpConfigScope: 'machine', templateTier: 'B',
+        role_capabilities: ['execute', 'consult'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 2,
+        prompt_delivery: { methods: ['inline_arg'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'gemini -p "{prompt}"',
+        invoke_binary: 'gemini',
+        invoke_review_template: 'gemini -p "{prompt}"',
     },
     'github-copilot': {
         name: 'github-copilot', category: 'code-agent', workflowModel: 'interactive',
-        hasMcp: false, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: true,
-        instructionFile: '.github/copilot-instructions.md', sharedInstructionFile: true, mcpConfigScope: 'none', templateTier: 'C',
+        hasMcp: true, hasHooks: true, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        instructionFile: '.github/copilot-instructions.md', sharedInstructionFile: true, mcpConfigScope: 'project', templateTier: 'A',
+        // Copilot CLI 1.0.35+ supports headless spawn via --allow-all + --no-ask-user and
+        // per-session MCP via --additional-mcp-config (validated spike pln#440, 2026-04-24
+        // on Windows: non-interactive prompt, file write, and MCP bclaw_create write path).
+        role_capabilities: ['execute', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: true, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: true },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg', 'inbox_structured'], preferred: 'inline_arg', max_inline_length: 4000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'copilot -p "{prompt}" --allow-all --no-ask-user',
+        invoke_binary: 'copilot',
+        invoke_review_template: 'copilot -p "{prompt}" --allow-all --no-ask-user',
+    },
+    kilocode: {
+        name: 'kilocode', category: 'code-agent', workflowModel: 'interactive',
+        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: true,
+        instructionFile: '.kilo/rules/brainclaw.md', sharedInstructionFile: false, mcpConfigScope: 'project', templateTier: 'B',
+        role_capabilities: ['execute', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 2,
+        prompt_delivery: { methods: ['inline_arg', 'temp_file'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'kilo run --auto "{prompt}"',
+        invoke_binary: 'kilo',
+        invoke_review_template: 'kilo run --auto "{prompt}"',
+        invoke_consult_template: 'kilo run --auto "{prompt}"',
+    },
+    // Mistral Vibe (pln#489) — Tier B: MCP via TOML config + skills + CLI spawn,
+    // but no hooks (BeforePrompt feature request #531 still open) and no native
+    // rules file equivalent to CLAUDE.md. Reuses AGENTS.md as the static
+    // instruction surface and the universal .agents/skills/brainclaw/SKILL.md
+    // for skill discovery (auto-discovered by Mistral Vibe alongside .vibe/skills/).
+    // Strategic value: EU/FR data sovereignty (Mistral Paris-based, not subject
+    // to US CLOUD Act; Apache 2.0 open-source CLI; open-weight models). Caveats:
+    // CLI freezes documented on current version, Windows Git Bash unsupported
+    // (issue #135), max_concurrent_tasks set conservatively to 2.
+    'mistral-vibe': {
+        name: 'mistral-vibe', category: 'code-agent', workflowModel: 'task-based',
+        hasMcp: true, hasHooks: false, hasAutoApprove: true, hasSkills: true, hasRules: false,
+        instructionFile: 'AGENTS.md', sharedInstructionFile: true, mcpConfigScope: 'both', templateTier: 'B',
+        role_capabilities: ['execute', 'review', 'consult'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 2,
+        prompt_delivery: { methods: ['inline_arg', 'stdin_pipe'], preferred: 'inline_arg', max_inline_length: 8000 },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 5',
+        invoke_binary: 'vibe',
+        invoke_review_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 5',
+        invoke_consult_template: 'vibe --prompt "{prompt}" --auto-approve --max-turns 3',
     },
     // --- Autonomous agents (headless, task-based or scheduled) ---
     openclaw: {
         name: 'openclaw', category: 'autonomous-agent', workflowModel: 'task-based',
-        hasMcp: false, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
-        instructionFile: 'skills/openclaw/SKILL.md', sharedInstructionFile: false, mcpConfigScope: 'none', templateTier: 'C',
+        hasMcp: true, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
+        instructionFile: 'skills/openclaw/SKILL.md', sharedInstructionFile: false, mcpConfigScope: 'machine', templateTier: 'B',
+        role_capabilities: ['execute', 'coordinate'],
+        runtime: { mcp_direct: true, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: true, inbox: true },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['temp_file', 'inbox_structured'], preferred: 'temp_file' },
+        execution_env: { surface: 'cli' },
+        invoke_template: 'openclaw run --auto "{prompt}"',
+        invoke_binary: 'openclaw',
     },
     nanoclaw: {
         name: 'nanoclaw', category: 'autonomous-agent', workflowModel: 'task-based',
         hasMcp: false, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
         instructionFile: 'skills/nanoclaw/SKILL.md', sharedInstructionFile: false, mcpConfigScope: 'none', templateTier: 'C',
+        role_capabilities: ['execute'],
+        runtime: { mcp_direct: false, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg', 'stdin_pipe'], preferred: 'inline_arg', max_inline_length: 2000 },
+        execution_env: { surface: 'cli' },
     },
     nemoclaw: {
         name: 'nemoclaw', category: 'autonomous-agent', workflowModel: 'task-based',
         hasMcp: false, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
         instructionFile: 'skills/nemoclaw/SKILL.md', sharedInstructionFile: false, mcpConfigScope: 'none', templateTier: 'C',
+        role_capabilities: ['execute'],
+        runtime: { mcp_direct: false, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg', 'stdin_pipe'], preferred: 'inline_arg', max_inline_length: 2000 },
+        execution_env: { surface: 'cli' },
     },
     picoclaw: {
         name: 'picoclaw', category: 'autonomous-agent', workflowModel: 'scheduled',
         hasMcp: false, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
         instructionFile: 'skills/picoclaw/SKILL.md', sharedInstructionFile: false, mcpConfigScope: 'none', templateTier: 'C',
+        role_capabilities: ['execute'],
+        runtime: { mcp_direct: false, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg'], preferred: 'inline_arg', max_inline_length: 1000 },
+        execution_env: { surface: 'cli' },
     },
     zeroclaw: {
         name: 'zeroclaw', category: 'autonomous-agent', workflowModel: 'task-based',
         hasMcp: false, hasHooks: false, hasAutoApprove: false, hasSkills: true, hasRules: false,
         instructionFile: 'skills/zeroclaw/SKILL.md', sharedInstructionFile: false, mcpConfigScope: 'none', templateTier: 'C',
+        role_capabilities: ['execute'],
+        runtime: { mcp_direct: false, hooks: false, canBeSpawnedCli: true, canSpawnOtherCli: false, inbox: false },
+        max_concurrent_tasks: 1,
+        prompt_delivery: { methods: ['inline_arg', 'stdin_pipe'], preferred: 'stdin_pipe', max_inline_length: 1000 },
+        execution_env: { surface: 'cli' },
     },
 };
+/**
+ * Default capability profiles for all known brainclaw-supported agents.
+ * Use `registerCapabilityProfile` to add custom agent profiles at runtime.
+ */
+export const DEFAULT_CAPABILITY_PROFILES = PROFILES;
+// ── Custom profile registry (for user-defined / custom agents) ─────────────
+const _customProfiles = new Map();
+/**
+ * Register a custom agent capability profile at runtime.
+ * Custom profiles take precedence over DEFAULT_CAPABILITY_PROFILES on lookup.
+ */
+export function registerCapabilityProfile(profile) {
+    _customProfiles.set(profile.name, profile);
+}
+/**
+ * Get the capability profile for an agent by name.
+ * Checks custom registry first, then DEFAULT_CAPABILITY_PROFILES.
+ * Returns undefined for completely unknown agents.
+ */
+export function getCapabilityProfile(name) {
+    const resolved = resolveAgentAlias(name);
+    return _customProfiles.get(resolved) ?? PROFILES[resolved];
+}
+/**
+ * Escape a string for safe use as a double-quoted shell argument.
+ * Escapes characters that have special meaning inside double-quotes
+ * on the target platform.
+ */
+function escapeForDoubleQuote(s, isWin32) {
+    if (isWin32) {
+        // On Windows cmd/PowerShell, escape internal double-quotes by doubling them.
+        return s.replace(/"/g, '""');
+    }
+    // On POSIX shells, escape backslash, dollar, backtick, and double-quote.
+    return s.replace(/\\/g, '\\\\').replace(/\$/g, '\\$').replace(/`/g, '\\`').replace(/"/g, '\\"');
+}
+/**
+ * Build a complete shell argument string for embedding inside double-quotes.
+ * Returns the string wrapped in double-quotes.
+ */
+function quoteArg(s, isWin32) {
+    return `"${escapeForDoubleQuote(s, isWin32)}"`;
+}
+/**
+ * Generate a short, stable filename suffix from an arbitrary string.
+ * Uses a simple djb2-style hash — no crypto dependency needed.
+ */
+function shortHash(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++) {
+        h = ((h << 5) + h) ^ s.charCodeAt(i);
+        h = h >>> 0; // keep unsigned 32-bit
+    }
+    return h.toString(16).padStart(8, '0');
+}
+/**
+ * Parse a raw template string (e.g. `claude -p "{prompt}" --allowedTools "..."`)
+ * into [executable, ...rawArgs], keeping the `{prompt}` token as-is.
+ *
+ * This is a simple shell-word splitter that handles:
+ *   - unquoted tokens
+ *   - double-quoted tokens (with \" escapes)
+ *   - single-quoted tokens (no escape processing)
+ * It does NOT handle variable expansion, redirections, or compound commands.
+ */
+function parseTemplateString(template) {
+    const tokens = [];
+    let i = 0;
+    const len = template.length;
+    while (i < len) {
+        // Skip whitespace between tokens
+        while (i < len && /\s/.test(template[i]))
+            i++;
+        if (i >= len)
+            break;
+        let token = '';
+        while (i < len && !/\s/.test(template[i])) {
+            const ch = template[i];
+            if (ch === '"') {
+                // Consume double-quoted segment
+                i++;
+                while (i < len && template[i] !== '"') {
+                    if (template[i] === '\\' && i + 1 < len) {
+                        i++; // skip backslash, keep next char literal
+                    }
+                    token += template[i];
+                    i++;
+                }
+                if (i < len)
+                    i++; // consume closing "
+            }
+            else if (ch === "'") {
+                // Consume single-quoted segment (no escaping)
+                i++;
+                while (i < len && template[i] !== "'") {
+                    token += template[i];
+                    i++;
+                }
+                if (i < len)
+                    i++; // consume closing '
+            }
+            else {
+                token += ch;
+                i++;
+            }
+        }
+        if (token.length > 0)
+            tokens.push(token);
+    }
+    return tokens;
+}
+/**
+ * Build a structured, ready-to-run invoke command for an agent.
+ *
+ * Resolution order:
+ *   1. Look up profile via `getCapabilityProfile`.
+ *   2. Return undefined if the agent has no CLI invoke template.
+ *   3. Apply mode fallback chain (same as `getDefaultInvokeTemplate`).
+ *   4. Determine prompt delivery method:
+ *      - If `prompt_delivery.preferred` is 'temp_file' OR prompt exceeds
+ *        `max_inline_length`, use 'temp_file'.
+ *      - If `prompt_delivery.preferred` is 'stdin_pipe', use 'stdin_pipe'.
+ *      - Otherwise use 'inline_arg'.
+ *   5. Parse the resolved template into [executable, ...args].
+ *   6. Interpolate `{prompt}` token in the args list.
+ *   7. Build a platform-aware `bashCommand` string.
+ *
+ * @param name    Agent name (matches AgentName or custom profile name).
+ * @param prompt  The actual prompt text to deliver to the agent.
+ * @param options Optional overrides for mode, platform, and temp file path.
+ * @returns Structured InvokeCommand, or undefined if the agent is not CLI-spawnable.
+ */
+export function buildInvokeCommand(name, prompt, options = {}) {
+    const profile = getCapabilityProfile(name);
+    if (!profile?.invoke_template || !profile?.invoke_binary)
+        return undefined;
+    if (!profile.runtime.canBeSpawnedCli)
+        return undefined;
+    const mode = options.mode ?? 'worker';
+    const isWin32 = (options.platform ?? process.platform) === 'win32';
+    // ── 1. Resolve the template string using the mode fallback chain ──────────
+    let templateStr;
+    switch (mode) {
+        case 'consult':
+            templateStr =
+                profile.invoke_consult_template ??
+                    profile.invoke_review_template ??
+                    profile.invoke_template;
+            break;
+        case 'reviewer':
+            templateStr = profile.invoke_review_template ?? profile.invoke_template;
+            break;
+        default:
+            templateStr = profile.invoke_template;
+    }
+    // ── 2. Determine prompt delivery method ──────────────────────────────────
+    const preferredDelivery = profile.prompt_delivery.preferred;
+    const maxInline = profile.prompt_delivery.max_inline_length;
+    let promptDelivery;
+    if (preferredDelivery === 'stdin_pipe') {
+        promptDelivery = 'stdin_pipe';
+    }
+    else if (preferredDelivery === 'temp_file' ||
+        (maxInline !== undefined && prompt.length > maxInline)) {
+        promptDelivery = 'temp_file';
+    }
+    else {
+        promptDelivery = 'inline_arg';
+    }
+    // ── 3. Resolve the prompt value to embed in the command ──────────────────
+    let embeddedPrompt;
+    let tempFilePath;
+    if (promptDelivery === 'temp_file') {
+        tempFilePath =
+            options.tempFilePath ??
+                path.join(os.tmpdir(), `bclaw_prompt_${shortHash(prompt)}.md`);
+        embeddedPrompt = tempFilePath;
+    }
+    else if (promptDelivery === 'stdin_pipe') {
+        // stdin_pipe: the {prompt} placeholder in the template (if present) is
+        // replaced with an empty string; the actual prompt is piped via stdin.
+        embeddedPrompt = '';
+    }
+    else {
+        embeddedPrompt = prompt;
+    }
+    // ── 4. Parse the template and interpolate {prompt} ───────────────────────
+    const rawTokens = parseTemplateString(templateStr);
+    if (rawTokens.length === 0)
+        return undefined;
+    const executable = rawTokens[0];
+    const interpolatedTokens = rawTokens.slice(1).map((tok) => tok === '{prompt}' ? embeddedPrompt : tok);
+    // ── 5. Build the args array ───────────────────────────────────────────────
+    // The args are the interpolated values; they are passed to execFile/spawn
+    // without further shell quoting. The bashCommand is built separately.
+    // Filter out empty strings from stdin_pipe delivery where {prompt} resolves to ''.
+    const args = interpolatedTokens.filter((tok) => tok !== '');
+    // ── 6. Build the platform-aware bashCommand string ───────────────────────
+    //
+    // Strategy:
+    //   - For 'inline_arg': embed the prompt inline, double-quoted.
+    //   - For 'temp_file' on POSIX: write prompt to temp file with `cat >`,
+    //     then run the command; the {prompt} slot holds the file path.
+    //   - For 'temp_file' on Windows: assume the caller has written the file;
+    //     just run the command with the path. No `cat` pipes.
+    //   - For 'stdin_pipe' on POSIX: use a heredoc to pipe prompt into the
+    //     command via stdin.
+    //   - For 'stdin_pipe' on Windows: omit stdin piping (use inbox fallback).
+    let bashCommand;
+    if (promptDelivery === 'temp_file') {
+        if (isWin32) {
+            // Caller writes the file; bashCommand is just the command invocation.
+            const cmdParts = [executable, ...interpolatedTokens.map((t) => quoteArg(t, isWin32))];
+            bashCommand = cmdParts.join(' ');
+        }
+        else {
+            // POSIX: write prompt to temp file, then run command.
+            const escapedPromptForHeredoc = prompt.replace(/\\/g, '\\\\').replace(/'/g, "'\\''");
+            const writeStep = `printf '%s' '${escapedPromptForHeredoc}' > ${tempFilePath}`;
+            const cmdParts = [executable, ...interpolatedTokens.map((t) => quoteArg(t, isWin32))];
+            bashCommand = `${writeStep} && ${cmdParts.join(' ')}`;
+        }
+    }
+    else if (promptDelivery === 'stdin_pipe') {
+        if (isWin32) {
+            // Windows: no heredoc; just run the command without piping.
+            const cmdParts = [executable, ...interpolatedTokens.filter(Boolean).map((t) => quoteArg(t, isWin32))];
+            bashCommand = cmdParts.join(' ');
+        }
+        else {
+            // POSIX: use heredoc to pipe prompt into stdin.
+            const escapedPromptForHeredoc = prompt.replace(/\\/g, '\\\\').replace(/'/g, "'\\''");
+            const nonEmptyArgs = interpolatedTokens.filter(Boolean);
+            const cmdParts = [executable, ...nonEmptyArgs.map((t) => quoteArg(t, isWin32))];
+            bashCommand = `printf '%s' '${escapedPromptForHeredoc}' | ${cmdParts.join(' ')}`;
+        }
+    }
+    else {
+        // inline_arg: embed prompt directly, double-quoted.
+        const cmdParts = rawTokens.map((tok, idx) => {
+            if (idx === 0)
+                return tok; // executable — no quoting
+            return tok === '{prompt}' ? quoteArg(embeddedPrompt, isWin32) : tok;
+        });
+        bashCommand = cmdParts.join(' ');
+    }
+    return {
+        executable,
+        args,
+        promptDelivery,
+        shell: false,
+        bashCommand,
+        ...(tempFilePath !== undefined ? { env: { BCLAW_PROMPT_FILE: tempFilePath } } : {}),
+        promptText: prompt,
+        ...(tempFilePath !== undefined ? { tempFilePath } : {}),
+    };
+}
+/**
+ * Resolve the appropriate brief mode for an agent based on its capability profile.
+ *
+ * Resolution rules:
+ *   1. Agent is NOT canBeSpawnedCli (IDE-only) → 'task_card'
+ *   2. Agent is task-based AND has NO MCP access → 'compact'
+ *      (brief skips the Protocol section because the agent cannot call
+ *      bclaw_assignment_update / bclaw_release_claim anyway)
+ *   3. Otherwise → 'full'
+ *
+ * Rule 2 was previously `workflowModel === 'task-based'` regardless of MCP
+ * capability (pln#496 Phase 1.b). That forced codex (task-based + hasMcp:
+ * true) onto 'compact' mode, which strips the Protocol section that
+ * contains `bclaw_assignment_update(status: …)` lifecycle instructions.
+ * Empirically validated 2026-05-04: every codex review in May 2026
+ * silently stayed `run_running` forever because codex never received the
+ * 'when done, call bclaw_assignment_update(status: completed)' line —
+ * last 'successful' review (lop_950a51aef0bb8263) had assignment
+ * status='offered', completed_at=null. The hasMcp check fixes this for
+ * codex and mistral-vibe (both task-based + MCP) without changing
+ * behaviour for genuinely MCP-less agents (nanoclaw / nemoclaw /
+ * zeroclaw).
+ *
+ * Note: stdin_pipe as prompt delivery is an optimization used by several
+ * interactive agents (claude-code, cline prefer it for long prompts) and
+ * does NOT indicate a sandboxed runtime — use workflowModel as the
+ * discriminator instead.
+ *
+ * Falls back to 'full' for unknown agents.
+ */
+export function resolveBriefMode(agentName) {
+    const profile = getCapabilityProfile(agentName);
+    if (!profile)
+        return 'full';
+    if (!profile.runtime.canBeSpawnedCli)
+        return 'task_card';
+    if (profile.workflowModel === 'task-based' && !profile.hasMcp)
+        return 'compact';
+    return 'full';
+}
+// ── getDefaultInvokeTemplate ───────────────────────────────────────────────
+/**
+ * Get the default invoke template for an agent.
+ * Reads invoke_template / invoke_binary from the capability profile.
+ * Mode selects the appropriate template variant with fallback chain:
+ *   - 'worker' (default): invoke_template
+ *   - 'reviewer': invoke_review_template → invoke_template
+ *   - 'consult': invoke_consult_template → invoke_review_template → invoke_template
+ * Returns undefined for IDE-only agents or unknown agents without a CLI template.
+ */
+export function getDefaultInvokeTemplate(name, mode = 'worker') {
+    const profile = getCapabilityProfile(name);
+    if (!profile?.invoke_template || !profile?.invoke_binary)
+        return undefined;
+    let command;
+    switch (mode) {
+        case 'consult':
+            command = profile.invoke_consult_template ?? profile.invoke_review_template ?? profile.invoke_template;
+            break;
+        case 'reviewer':
+            command = profile.invoke_review_template ?? profile.invoke_template;
+            break;
+        default:
+            command = profile.invoke_template;
+    }
+    return {
+        command,
+        channel: 'spawn',
+        timeout: 600,
+        binary: profile.invoke_binary,
+        mode,
+    };
+}
+/**
+ * Get all agents (known + custom) that have an invoke template (CLI-spawnable).
+ */
+export function getSpawnableAgents() {
+    const result = [];
+    const allProfiles = [
+        ...Object.values(PROFILES),
+        ..._customProfiles.values(),
+    ];
+    for (const profile of allProfiles) {
+        if (profile.runtime.canBeSpawnedCli && profile.invoke_template && profile.invoke_binary) {
+            result.push({
+                name: profile.name,
+                template: {
+                    command: profile.invoke_template,
+                    channel: 'spawn',
+                    timeout: 600,
+                    binary: profile.invoke_binary,
+                    mode: 'worker',
+                },
+            });
+        }
+    }
+    return result;
+}
 /**
  * Get the capability profile for a known agent.
  * Returns undefined for unknown agent names.
+ * @deprecated Prefer getCapabilityProfile — supports custom agents too.
  */
 export function getAgentCapabilityProfile(name) {
-    return PROFILES[name];
+    return getCapabilityProfile(name);
 }
 /**
  * Get all known agent capability profiles.
@@ -110,14 +660,57 @@ export function getAgentsByTier(tier) {
  * Check if an agent name is a known brainclaw-supported agent.
  */
 export function isKnownAgent(name) {
-    return name in PROFILES;
+    const resolved = resolveAgentAlias(name);
+    return resolved in PROFILES;
+}
+export function validateAgentForDispatch(name, options = {}) {
+    const profile = getCapabilityProfile(name);
+    if (!profile) {
+        return {
+            valid: false,
+            code: 'unknown_profile',
+            reason: `Unknown agent profile: '${name}'. Registered agents: ${Object.keys(PROFILES).join(', ')}.`,
+        };
+    }
+    if (options.requireSpawnable) {
+        if (!profile.runtime.canBeSpawnedCli) {
+            return {
+                valid: false,
+                code: 'not_spawnable',
+                reason: `Agent '${name}' has no CLI spawn support (runtime.canBeSpawnedCli=false). Use a worker-capable agent for dispatch.`,
+                profile,
+            };
+        }
+        const bin = profile.invoke_binary;
+        // In test mode we skip the PATH probe: CI runners don't have external
+        // agent CLIs (codex, copilot, …) installed, and tests set BRAINCLAW_NO_SPAWN
+        // so no real spawn ever happens. Probing PATH here used to make the
+        // bclaw-coordinate suite fail on CI while passing locally whenever the
+        // developer had the binaries installed. Profile-based checks
+        // (unknown_profile, not_spawnable) still apply — they're deterministic.
+        const skipBinaryProbe = process.env.BRAINCLAW_TEST_MODE === '1'
+            || process.env.BRAINCLAW_NO_SPAWN === '1';
+        if (bin && !skipBinaryProbe) {
+            const probe = process.platform === 'win32' ? 'where' : 'which';
+            const result = spawnSync(probe, [bin], { encoding: 'utf-8' });
+            if (result.status !== 0) {
+                return {
+                    valid: false,
+                    code: 'binary_missing',
+                    reason: `Agent '${name}' declares invoke_binary='${bin}' but it is not on PATH. Install the agent CLI or update its profile.`,
+                    profile,
+                };
+            }
+        }
+    }
+    return { valid: true, profile };
 }
 /**
  * Summarize which integration surfaces are available for a given agent.
  * Useful for setup UI to explain what brainclaw will configure.
  */
 export function describeAgentSurfaces(name) {
-    const profile = getAgentCapabilityProfile(name);
+    const profile = getCapabilityProfile(name);
     if (!profile)
         return [];
     const surfaces = [];