agent-tempo 1.2.0 → 1.4.0

package/dist/tools/recruit.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerRecruitTool = registerRecruitTool;
+exports.buildRecruitTool = buildRecruitTool;
 exports.checkHostPreflight = checkHostPreflight;
 exports.nearestHostname = nearestHostname;
 const zod_1 = require("zod");
@@ -42,13 +42,20 @@ const config_1 = require("../config");
 const types_1 = require("../types");
 const resolve_1 = require("./resolve");
 const signals_1 = require("../workflows/signals");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const agent_types_1 = require("../ensemble/agent-types");
 const validation_1 = require("../utils/validation");
 const sdk_probe_1 = require("../utils/sdk-probe");
 const pre_flight_1 = require("../adapters/claude-code-headless/pre-flight");
 const types_2 = require("../adapters/claude-code-headless/types");
+const probe_1 = require("../pi/probe");
 const toolLog = (...args) => console.error('[agent-tempo:recruit]', ...args);
+/**
+ * True dynamic ESM import (survives tsc's commonjs downlevel) — used to load
+ * pi-ai's sessionless `getModel` for the Copilot model-index pre-flight gate.
+ */
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const esmImport = new Function('s', 'return import(s)');
 /**
  * #449 Phase C — check whether the `opencode` binary is on PATH. Used by
  * the recruit pre-flight to fail fast with an actionable error before the
@@ -71,7 +78,7 @@ function hasOpencodeOnPath() {
         return false;
     }
 }
-function registerRecruitTool(server, client, config, getPlayerId, handle, ownAgentType = 'claude', deps = {}) {
+function buildRecruitTool(client, config, getPlayerId, handle, ownAgentType = 'claude', deps = {}) {
     // Lazy default — only imports utils/hosts when actually called, so the
     // MCP server's module load graph doesn't drag the whole join layer
     // into every consumer at import time.
@@ -83,282 +90,344 @@ function registerRecruitTool(server, client, config, getPlayerId, handle, ownAge
             taskQueue: config.taskQueue,
         });
     });
-    (0, helpers_1.defineTool)(server, 'recruit', `Start a new named session in a directory. Rejects if the name is already active. Supports Claude Code or Copilot CLI agents. Defaults to "${ownAgentType}" (same as this session).`, {
-        workDir: zod_1.z.string().max(validation_1.PATH_MAX).describe('The working directory for the new session'),
-        name: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('Name for the new session'),
-        conductor: zod_1.z.boolean().optional()
-            .describe('Whether this session is a conductor (default: false)'),
-        initialMessage: zod_1.z.string().max(validation_1.MESSAGE_MAX).optional()
-            .describe('Optional task or message for the new session (sent after it sets its name)'),
-        agent: zod_1.z.enum(types_1.AGENT_TYPES).optional()
-            .describe(`Which agent to use (default: "${ownAgentType}", same as this session). "mock" requires dev mode (--dev). "claude-api" runs headless via the Anthropic Messages API — requires ANTHROPIC_API_KEY env var and the @anthropic-ai/sdk optional dependency installed; has access to agent-tempo MCP tools (cue, report, recall, ensemble, …) but NOT file-edit or shell tools (use "claude" for those). "opencode" runs headless via a local opencode serve subprocess; multi-provider (Anthropic, OpenAI, Bedrock, Ollama, …) — requires the @opencode-ai/sdk optional dep and an opencode binary on PATH. opencode players ARE file-op-capable (file edits / shell / web search via OpenCode's built-in tools). "claude-code-headless" runs the official Claude Code CLI as a headless per-turn \`claude -p\` subprocess — requires the \`claude\` binary on PATH AND a logged-in Claude Code session (\`claude auth login\`); turns bill against the host's existing subscription extra-usage credits, NOT a Console API key. claude-code-headless players have full Claude Code tool access (Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch).`),
-        model: zod_1.z.string().regex(/^[a-z0-9][a-z0-9-/.:_]*$/).optional()
-            .describe('Model id. For "claude-api": bare Anthropic id (e.g. "claude-opus-4-7"). For "opencode": combined "provider/model" (e.g. "anthropic/claude-opus-4-7", "openai/gpt-4o", "ollama/llama3"). Falls back to AGENT_TEMPO_API_MODEL (claude-api) or AGENT_TEMPO_OPENCODE_MODEL (opencode), then a constants-pinned default. Ignored for claude / copilot / mock adapters.'),
-        type: zod_1.z.string().optional()
-            .describe('Agent type name — references a Claude Code agent definition (e.g., "tempo-soloist")'),
-        systemPrompt: zod_1.z.string().optional()
-            .describe('Path to a .md file to use as custom agent system prompt (--system-prompt)'),
-        host: zod_1.z.string().optional()
-            .describe('Target hostname for cross-machine recruiting. Omit for local spawn.'),
-        force: zod_1.z.boolean().optional()
-            .describe('Force-terminate any existing session with this name before recruiting. Use when a previous session is orphaned or stuck.'),
-        mockMode: zod_1.z.enum(types_1.MOCK_MODES).optional()
-            .describe('Dev-mode only (agent: "mock"). Mock adapter mode. Default: "echo". "silent" never replies (heartbeat-stale validation); "chaos" probabilistic fail/crash injection (env-tuned).'),
-        mockScenario: zod_1.z.string().optional()
-            .describe('Dev-mode only (agent: "mock", mockMode: "scripted"). Bare scenario name (resolved against shipped scenarios/) or absolute path to a scenario YAML.'),
-        // #520 — claude-code-headless adapter knobs. Both ignored for other adapters.
-        permissionMode: zod_1.z.enum(types_2.CLAUDE_CODE_PERMISSION_MODES).optional()
-            .describe('claude-code-headless only. Permission mode forwarded to `claude -p --permission-mode`. Default "acceptEdits" auto-approves writes + common fs commands. "bypassPermissions" / "dangerouslySkipPermissions" trades safety for speed in trusted contexts. "plan" plans without executing — not useful for headless players. Mutually exclusive with `dangerouslySkipPermissions`.'),
-        dangerouslySkipPermissions: zod_1.z.boolean().optional()
-            .describe('claude-code-headless only. When true, passes `--dangerously-skip-permissions` to `claude -p` instead of `--permission-mode`. Use only in sandboxed/trusted contexts. Mutually exclusive with `permissionMode`.'),
-    }, async (args) => {
-        const { workDir, name, initialMessage } = args;
-        const isConductor = args.conductor === true;
-        const agent = args.agent || ownAgentType;
-        const model = args.model;
-        const agentTypeName = args.type;
-        const systemPrompt = args.systemPrompt;
-        const host = args.host;
-        const force = args.force === true;
-        const mockMode = args.mockMode;
-        const mockScenario = args.mockScenario;
-        const permissionMode = args.permissionMode;
-        const dangerouslySkipPermissions = args.dangerouslySkipPermissions === true;
-        // ADR 0014 §7 gate 3 — recruit-time rejection of `agent: 'mock'`
-        // outside dev mode. Defense-in-depth: even if a hand-edited install
-        // had `dist/adapters/mock/` present (gate 1 bypassed) AND somehow
-        // got the registry to register the descriptor (gate 2 bypassed),
-        // this rejects the request with a clear, actionable error.
-        if (agent === 'mock' && !(0, config_1.isDevMode)()) {
-            return (0, helpers_1.fail)(`agent: "mock" is only available in dev mode. Restart agent-tempo with --dev (or set AGENT_TEMPO_DEV_MODE=1) to enable.`);
-        }
-        // mockMode / mockScenario are only meaningful with the mock adapter —
-        // reject silently-ignored params so users learn the right flag shape.
-        if (mockMode != null && agent !== 'mock') {
-            return (0, helpers_1.fail)(`mockMode is only valid when agent: "mock" (got agent: "${agent}").`);
-        }
-        if (mockScenario != null && agent !== 'mock') {
-            return (0, helpers_1.fail)(`mockScenario is only valid when agent: "mock" (got agent: "${agent}").`);
-        }
-        if (agent === 'mock' && mockMode === 'scripted' && !mockScenario) {
-            return (0, helpers_1.fail)(`mockMode: "scripted" requires mockScenario (a bare scenario name or path to a YAML file).`);
-        }
-        // PR-3: silent + chaos modes don't consult the scenario file. Reject
-        // explicitly rather than silently ignore so users learn the right
-        // shape and don't sit wondering why their scenario wasn't applied.
-        if (mockScenario && (mockMode === 'silent' || mockMode === 'chaos')) {
-            return (0, helpers_1.fail)(`mockMode: "${mockMode}" does not use a scenario. Drop mockScenario or switch to mockMode: "scripted".`);
-        }
-        // #131 / #449 Phase C — model knob is meaningful for claude-api AND
-        // opencode (different shapes — bare vs `provider/model` — both flow
-        // through the same recruit field). Reject silently-ignored params for
-        // the other adapters so users learn the right shape.
-        // Local-spawn pre-flight checks (env vars + SDK install + binaries)
-        // run only when `host` is unset; cross-host recruits delegate to the
-        // target daemon's `availableAgentTypes` advertisement (the existing
-        // `checkHostPreflight` path), which already gates on whether the
-        // remote daemon resolved the SDK at boot.
-        if (model != null && agent !== 'claude-api' && agent !== 'opencode') {
-            return (0, helpers_1.fail)(`model is only valid when agent: "claude-api" or agent: "opencode" (got agent: "${agent}").`);
-        }
-        // #520 — claude-code-headless permission knobs are mutually exclusive
-        // and only meaningful for that adapter. Reject silently-ignored
-        // params so users learn the right shape.
-        if (permissionMode != null && agent !== 'claude-code-headless') {
-            return (0, helpers_1.fail)(`permissionMode is only valid when agent: "claude-code-headless" (got agent: "${agent}").`);
-        }
-        if (dangerouslySkipPermissions && agent !== 'claude-code-headless') {
-            return (0, helpers_1.fail)(`dangerouslySkipPermissions is only valid when agent: "claude-code-headless" (got agent: "${agent}").`);
-        }
-        if (permissionMode != null && dangerouslySkipPermissions) {
-            return (0, helpers_1.fail)(`permissionMode and dangerouslySkipPermissions are mutually exclusive — pass at most one.`);
-        }
-        if (agent === 'claude-api' && !host && !force) {
-            if (!process.env.ANTHROPIC_API_KEY) {
-                return (0, helpers_1.fail)(`agent: "claude-api" requires the ANTHROPIC_API_KEY environment variable on the spawn host. Set it before recruiting (export ANTHROPIC_API_KEY=sk-...) or use \`force: true\` to bypass this check.`);
+    return {
+        name: 'recruit',
+        description: `Start a new named session in a directory. Rejects if the name is already active. Supports Claude Code or Copilot CLI agents. Defaults to "${ownAgentType}" (same as this session).`,
+        params: {
+            workDir: zod_1.z.string().max(validation_1.PATH_MAX).describe('The working directory for the new session'),
+            name: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('Name for the new session'),
+            conductor: zod_1.z.boolean().optional()
+                .describe('Whether this session is a conductor (default: false)'),
+            initialMessage: zod_1.z.string().max(validation_1.MESSAGE_MAX).optional()
+                .describe('Optional task or message for the new session (sent after it sets its name)'),
+            agent: zod_1.z.enum(types_1.AGENT_TYPES).optional()
+                .describe(`Which agent to use (default: "${ownAgentType}", same as this session). "mock" requires dev mode (--dev). "claude-api" runs headless via the Anthropic Messages API — requires ANTHROPIC_API_KEY env var and the @anthropic-ai/sdk optional dependency installed; has access to agent-tempo MCP tools (cue, report, recall, ensemble, …) but NOT file-edit or shell tools (use "claude" for those). "opencode" runs headless via a local opencode serve subprocess; multi-provider (Anthropic, OpenAI, Bedrock, Ollama, …) — requires the @opencode-ai/sdk optional dep and an opencode binary on PATH. opencode players ARE file-op-capable (file edits / shell / web search via OpenCode's built-in tools). "claude-code-headless" runs the official Claude Code CLI as a headless per-turn \`claude -p\` subprocess — requires the \`claude\` binary on PATH AND a logged-in Claude Code session (\`claude auth login\`); turns bill against the host's existing subscription extra-usage credits, NOT a Console API key. claude-code-headless players have full Claude Code tool access (Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch).`),
+            model: zod_1.z.string().regex(/^[a-z0-9][a-z0-9-/.:_]*$/).optional()
+                .describe('Model id. For "claude-api": bare Anthropic id (e.g. "claude-opus-4-7"). For "opencode": combined "provider/model" (e.g. "anthropic/claude-opus-4-7", "openai/gpt-4o", "ollama/llama3"). Falls back to AGENT_TEMPO_API_MODEL (claude-api) or AGENT_TEMPO_OPENCODE_MODEL (opencode), then a constants-pinned default. Ignored for claude / copilot / mock adapters.'),
+            type: zod_1.z.string().optional()
+                .describe('Agent type name — references a Claude Code agent definition (e.g., "tempo-soloist")'),
+            systemPrompt: zod_1.z.string().optional()
+                .describe('Path to a .md file to use as custom agent system prompt (--system-prompt)'),
+            host: zod_1.z.string().optional()
+                .describe('Target hostname for cross-machine recruiting. Omit for local spawn.'),
+            force: zod_1.z.boolean().optional()
+                .describe('Force-terminate any existing session with this name before recruiting. Use when a previous session is orphaned or stuck.'),
+            mockMode: zod_1.z.enum(types_1.MOCK_MODES).optional()
+                .describe('Dev-mode only (agent: "mock"). Mock adapter mode. Default: "echo". "silent" never replies (heartbeat-stale validation); "chaos" probabilistic fail/crash injection (env-tuned).'),
+            mockScenario: zod_1.z.string().optional()
+                .describe('Dev-mode only (agent: "mock", mockMode: "scripted"). Bare scenario name (resolved against shipped scenarios/) or absolute path to a scenario YAML.'),
+            // #520 — claude-code-headless adapter knobs. Both ignored for other adapters.
+            permissionMode: zod_1.z.enum(types_2.CLAUDE_CODE_PERMISSION_MODES).optional()
+                .describe('claude-code-headless only. Permission mode forwarded to `claude -p --permission-mode`. Default "acceptEdits" auto-approves writes + common fs commands. "bypassPermissions" / "dangerouslySkipPermissions" trades safety for speed in trusted contexts. "plan" plans without executing — not useful for headless players. Mutually exclusive with `dangerouslySkipPermissions`.'),
+            dangerouslySkipPermissions: zod_1.z.boolean().optional()
+                .describe('claude-code-headless only. When true, passes `--dangerously-skip-permissions` to `claude -p` instead of `--permission-mode`. Use only in sandboxed/trusted contexts. Mutually exclusive with `permissionMode`.'),
+            // Phase 3a / MD-C — headless Pi tool-access policy. Ignored for other agents.
+            // NOTE: stays `.optional()` (NOT `.default('restricted')`): this tool's
+            // params are rendered to the Pi front-end via renderToPi → the zod→TypeBox
+            // converter, which is fail-loud on `.default()` (D1). A schema default would
+            // throw at Pi tool registration ("Pi missing tool: recruit"). The concrete
+            // 'restricted' default is applied once at the read site below instead.
+            toolAccess: zod_1.z.enum(['restricted', 'standard', 'full']).optional()
+                .describe('pi only. Headless Pi tool-class policy. "restricted" (default): agent-tempo tools + Read/Edit/Write; Bash/shell/exec HARD-BLOCKED. "standard": Bash enabled; no tool-level scope restriction (operator/container responsible for scoping). "full": unsandboxed — requires force: true (admin confirmation). Ignored for other agents.'),
+        },
+        handler: async (args) => {
+            const { workDir, name, initialMessage } = args;
+            const isConductor = args.conductor === true;
+            const agent = args.agent || ownAgentType;
+            const model = args.model;
+            const agentTypeName = args.type;
+            const systemPrompt = args.systemPrompt;
+            const host = args.host;
+            const force = args.force === true;
+            const mockMode = args.mockMode;
+            const mockScenario = args.mockScenario;
+            const permissionMode = args.permissionMode;
+            const dangerouslySkipPermissions = args.dangerouslySkipPermissions === true;
+            // N1 (adapted): normalize to a concrete value ONCE here so the guard below
+            // and the outbox entry both see a real value with no scattered `?? 'restricted'`.
+            // (A schema `.default()` would be cleaner but the Pi converter rejects it —
+            // see the toolAccess param note above.) Omitted → 'restricted'.
+            const toolAccess = (args.toolAccess ?? 'restricted');
+            // ADR 0014 §7 gate 3 — recruit-time rejection of `agent: 'mock'`
+            // outside dev mode. Defense-in-depth: even if a hand-edited install
+            // had `dist/adapters/mock/` present (gate 1 bypassed) AND somehow
+            // got the registry to register the descriptor (gate 2 bypassed),
+            // this rejects the request with a clear, actionable error.
+            if (agent === 'mock' && !(0, config_1.isDevMode)()) {
+                return (0, descriptor_1.fail)(`agent: "mock" is only available in dev mode. Restart agent-tempo with --dev (or set AGENT_TEMPO_DEV_MODE=1) to enable.`);
             }
-            try {
-                require.resolve('@anthropic-ai/sdk');
+            // mockMode / mockScenario are only meaningful with the mock adapter —
+            // reject silently-ignored params so users learn the right flag shape.
+            if (mockMode != null && agent !== 'mock') {
+                return (0, descriptor_1.fail)(`mockMode is only valid when agent: "mock" (got agent: "${agent}").`);
             }
-            catch {
-                return (0, helpers_1.fail)(`agent: "claude-api" requires the @anthropic-ai/sdk optional dependency. Install with \`npm install @anthropic-ai/sdk\` and retry, or use \`force: true\` to bypass this check.`);
+            if (mockScenario != null && agent !== 'mock') {
+                return (0, descriptor_1.fail)(`mockScenario is only valid when agent: "mock" (got agent: "${agent}").`);
             }
-        }
-        // #449 Phase C — opencode pre-flight. Two checks: the optional SDK
-        // (signal that opencode integration is intended on this host) AND
-        // the `opencode` binary on PATH (the adapter spawns `opencode serve`
-        // as a subprocess). Cross-host recruits skip both — the target
-        // daemon's `availableAgentTypes` is the gate there.
-        if (agent === 'opencode' && !host && !force) {
-            if (!(0, sdk_probe_1.probeSdkInstall)('@opencode-ai/sdk')) {
-                return (0, helpers_1.fail)(`agent: "opencode" requires the @opencode-ai/sdk optional dependency. Install with \`npm install @opencode-ai/sdk\` and retry, or use \`force: true\` to bypass this check.`);
+            if (agent === 'mock' && mockMode === 'scripted' && !mockScenario) {
+                return (0, descriptor_1.fail)(`mockMode: "scripted" requires mockScenario (a bare scenario name or path to a YAML file).`);
             }
-            if (!hasOpencodeOnPath()) {
-                return (0, helpers_1.fail)(`agent: "opencode" requires the \`opencode\` binary on PATH. Install with \`npm install -g opencode-ai\` and retry, or use \`force: true\` to bypass this check.`);
+            // PR-3: silent + chaos modes don't consult the scenario file. Reject
+            // explicitly rather than silently ignore so users learn the right
+            // shape and don't sit wondering why their scenario wasn't applied.
+            if (mockScenario && (mockMode === 'silent' || mockMode === 'chaos')) {
+                return (0, descriptor_1.fail)(`mockMode: "${mockMode}" does not use a scenario. Drop mockScenario or switch to mockMode: "scripted".`);
             }
-        }
-        // #520 — claude-code-headless pre-flight. Two checks, both bounded by
-        // short timeouts (3s + 5s). The auth probe uses the official `claude
-        // auth status` subcommand — no billed API call. Cross-host recruits
-        // skip both — the target daemon's `availableAgentTypes` is the gate
-        // there (PR-2 wires the daemon-side probe).
-        if (agent === 'claude-code-headless' && !host && !force) {
-            const claudeBin = config.claudeBin ?? 'claude';
-            const binProbe = (0, pre_flight_1.probeClaudeBinary)(claudeBin);
-            if (!binProbe.ok) {
-                return (0, helpers_1.fail)(`agent: "claude-code-headless" pre-flight failed: ${binProbe.error} Use \`force: true\` to bypass.`);
+            // #131 / #449 Phase C — model knob is meaningful for claude-api AND
+            // opencode (different shapes — bare vs `provider/model` — both flow
+            // through the same recruit field). Reject silently-ignored params for
+            // the other adapters so users learn the right shape.
+            // Local-spawn pre-flight checks (env vars + SDK install + binaries)
+            // run only when `host` is unset; cross-host recruits delegate to the
+            // target daemon's `availableAgentTypes` advertisement (the existing
+            // `checkHostPreflight` path), which already gates on whether the
+            // remote daemon resolved the SDK at boot.
+            if (model != null && agent !== 'claude-api' && agent !== 'opencode') {
+                return (0, descriptor_1.fail)(`model is only valid when agent: "claude-api" or agent: "opencode" (got agent: "${agent}").`);
             }
-            const authProbe = (0, pre_flight_1.probeClaudeAuth)(claudeBin);
-            if (!authProbe.loggedIn) {
-                return (0, helpers_1.fail)(`agent: "claude-code-headless" pre-flight failed: ${authProbe.error} Use \`force: true\` to bypass.`);
+            // #520 — claude-code-headless permission knobs are mutually exclusive
+            // and only meaningful for that adapter. Reject silently-ignored
+            // params so users learn the right shape.
+            if (permissionMode != null && agent !== 'claude-code-headless') {
+                return (0, descriptor_1.fail)(`permissionMode is only valid when agent: "claude-code-headless" (got agent: "${agent}").`);
             }
-        }
-        // #532 — copilot pre-flight. SDK-only probe (mirrors claude-api's
-        // pattern; copilot has no subprocess CLI on PATH). The bridge
-        // subprocess hard-requires `@github/copilot-sdk` at module load
-        // (`src/adapters/copilot/adapter.ts:71`), so without this gate the
-        // user only learns of the missing dep AFTER bridge spawn —
-        // adapter crashes with `process.exit(1)` and the player sits in
-        // `booting` until lease timeout. We use `probeSdkInstall` (FS walk)
-        // rather than `require.resolve` because pnpm layouts without a
-        // top-level hoisted link otherwise false-negative; see issue #532
-        // investigation footnote. GITHUB_TOKEN / Copilot CLI login are
-        // intentionally NOT checked: the SDK falls through to the
-        // logged-in user (`adapter.ts:31, :263`), so token presence is not
-        // a hard requirement. Cross-host recruits skip — the target
-        // daemon's `availableAgentTypes` is the gate there.
-        if (agent === 'copilot' && !host && !force) {
-            if (!(0, sdk_probe_1.probeSdkInstall)('@github/copilot-sdk')) {
-                return (0, helpers_1.fail)(`agent: "copilot" requires the @github/copilot-sdk optional dependency. Install with \`npm install @github/copilot-sdk\` and retry, or use \`force: true\` to bypass this check.`);
+            if (dangerouslySkipPermissions && agent !== 'claude-code-headless') {
+                return (0, descriptor_1.fail)(`dangerouslySkipPermissions is only valid when agent: "claude-code-headless" (got agent: "${agent}").`);
             }
-        }
-        // Resolve agent type if provided
-        let agentDefinition;
-        let agentDefinitionPath;
-        let agentDefinitionDescription;
-        let nativeResolvable;
-        let allowedTools;
-        if (agentTypeName) {
-            const info = (0, agent_types_1.resolveAgentType)(agentTypeName);
-            if (!info) {
-                const available = (0, agent_types_1.listAgentTypes)().map(t => t.name);
-                return (0, helpers_1.fail)(`Unknown agent type "${agentTypeName}". Available types: ${available.length ? available.join(', ') : '(none)'}`);
+            // Reject an EXPLICIT non-default toolAccess on a non-pi agent. With Zod
+            // `.default('restricted')` the omitted case is indistinguishable from an
+            // explicit `'restricted'`, so we only flag a non-default value — that is
+            // unambiguously a user mistake (toolAccess is ignored for non-pi agents).
+            if (toolAccess !== 'restricted' && agent !== 'pi') {
+                return (0, descriptor_1.fail)(`toolAccess is only valid when agent: "pi" (got agent: "${agent}").`);
             }
-            agentDefinition = info.name;
-            agentDefinitionPath = info.path;
-            agentDefinitionDescription = info.description;
-            nativeResolvable = info.nativeResolvable;
-            allowedTools = info.allowedTools;
-        }
-        // Validate name
-        const nameError = (0, validation_1.validatePlayerName)(name);
-        if (nameError) {
-            return (0, helpers_1.fail)(nameError);
-        }
-        if (name === 'conductor' && !isConductor) {
-            return (0, helpers_1.fail)(`The name "conductor" is reserved for conductor sessions. Use a different name, or set conductor: true.`);
-        }
-        // ── #274 AC12 — cross-host recruit pre-flight ──
-        //
-        // When `host` is specified, verify that the target is live + has
-        // the requested agent runtime available BEFORE submitting to the
-        // outbox. Otherwise `recruit --host foo` could queue forever on a
-        // per-host task queue nobody's listening on (the exact failure
-        // mode #274 set out to close).
-        //
-        // `force: true` bypasses pre-flight entirely (AC12d) — covers the
-        // scripted-recruit-on-about-to-boot-daemon case plus any other
-        // "I know what I'm doing" override. RPC failure during pre-flight
-        // falls through with a warning (AC12e) so today's recruit
-        // availability characteristics are preserved.
-        if (host && !force) {
-            try {
-                const hosts = await listHostsFn(client);
-                const preflightError = checkHostPreflight(hosts, host, agent);
-                if (preflightError)
-                    return (0, helpers_1.fail)(preflightError);
+            if (toolAccess === 'full' && !force) {
+                return (0, descriptor_1.fail)(`toolAccess: "full" (unsandboxed Pi) requires force: true (admin confirmation). "restricted" (default) and "standard" do not.`);
             }
-            catch (err) {
-                toolLog(`Host pre-flight RPC failed for "${host}"; proceeding without validation (use --force to silence this warning): ${err instanceof Error ? err.message : err}`);
+            if (permissionMode != null && dangerouslySkipPermissions) {
+                return (0, descriptor_1.fail)(`permissionMode and dangerouslySkipPermissions are mutually exclusive — pass at most one.`);
             }
-        }
-        try {
-            // Check if a conductor already exists when recruiting a conductor
-            if (isConductor) {
+            if (agent === 'claude-api' && !host && !force) {
+                if (!process.env.ANTHROPIC_API_KEY) {
+                    return (0, descriptor_1.fail)(`agent: "claude-api" requires the ANTHROPIC_API_KEY environment variable on the spawn host. Set it before recruiting (export ANTHROPIC_API_KEY=sk-...) or use \`force: true\` to bypass this check.`);
+                }
                 try {
-                    const conductorWfId = (0, config_1.conductorWorkflowId)(config.ensemble);
-                    const conductorHandle = client.workflow.getHandle(conductorWfId);
-                    const desc = await conductorHandle.describe();
-                    if (desc.status.name === 'RUNNING') {
-                        if (force) {
-                            await conductorHandle.terminate(`Force-terminated for re-recruit by ${getPlayerId()}`);
-                        }
-                        else {
-                            return (0, helpers_1.fail)(`A conductor is already running in ensemble "${config.ensemble}". Use \`agent-tempo conduct --replace\` from the CLI to replace it, \`stop\` it first, or use \`force: true\` to replace it.`);
-                        }
-                    }
+                    require.resolve('@anthropic-ai/sdk');
                 }
                 catch {
-                    // No existing conductor — proceed
+                    return (0, descriptor_1.fail)(`agent: "claude-api" requires the @anthropic-ai/sdk optional dependency. Install with \`npm install @anthropic-ai/sdk\` and retry, or use \`force: true\` to bypass this check.`);
+                }
+            }
+            // #449 Phase C — opencode pre-flight. Two checks: the optional SDK
+            // (signal that opencode integration is intended on this host) AND
+            // the `opencode` binary on PATH (the adapter spawns `opencode serve`
+            // as a subprocess). Cross-host recruits skip both — the target
+            // daemon's `availableAgentTypes` is the gate there.
+            if (agent === 'opencode' && !host && !force) {
+                if (!(0, sdk_probe_1.probeSdkInstall)('@opencode-ai/sdk')) {
+                    return (0, descriptor_1.fail)(`agent: "opencode" requires the @opencode-ai/sdk optional dependency. Install with \`npm install @opencode-ai/sdk\` and retry, or use \`force: true\` to bypass this check.`);
+                }
+                if (!hasOpencodeOnPath()) {
+                    return (0, descriptor_1.fail)(`agent: "opencode" requires the \`opencode\` binary on PATH. Install with \`npm install -g opencode-ai\` and retry, or use \`force: true\` to bypass this check.`);
+                }
+            }
+            // #520 — claude-code-headless pre-flight. Two checks, both bounded by
+            // short timeouts (3s + 5s). The auth probe uses the official `claude
+            // auth status` subcommand — no billed API call. Cross-host recruits
+            // skip both — the target daemon's `availableAgentTypes` is the gate
+            // there (PR-2 wires the daemon-side probe).
+            if (agent === 'claude-code-headless' && !host && !force) {
+                const claudeBin = config.claudeBin ?? 'claude';
+                const binProbe = (0, pre_flight_1.probeClaudeBinary)(claudeBin);
+                if (!binProbe.ok) {
+                    return (0, descriptor_1.fail)(`agent: "claude-code-headless" pre-flight failed: ${binProbe.error} Use \`force: true\` to bypass.`);
+                }
+                const authProbe = (0, pre_flight_1.probeClaudeAuth)(claudeBin);
+                if (!authProbe.loggedIn) {
+                    return (0, descriptor_1.fail)(`agent: "claude-code-headless" pre-flight failed: ${authProbe.error} Use \`force: true\` to bypass.`);
+                }
+            }
+            // #532 — copilot pre-flight. SDK-only probe (mirrors claude-api's
+            // pattern; copilot has no subprocess CLI on PATH). The bridge
+            // subprocess hard-requires `@github/copilot-sdk` at module load
+            // (`src/adapters/copilot/adapter.ts:71`), so without this gate the
+            // user only learns of the missing dep AFTER bridge spawn —
+            // adapter crashes with `process.exit(1)` and the player sits in
+            // `booting` until lease timeout. We use `probeSdkInstall` (FS walk)
+            // rather than `require.resolve` because pnpm layouts without a
+            // top-level hoisted link otherwise false-negative; see issue #532
+            // investigation footnote. GITHUB_TOKEN / Copilot CLI login are
+            // intentionally NOT checked: the SDK falls through to the
+            // logged-in user (`adapter.ts:31, :263`), so token presence is not
+            // a hard requirement. Cross-host recruits skip — the target
+            // daemon's `availableAgentTypes` is the gate there.
+            if (agent === 'copilot' && !host && !force) {
+                if (!(0, sdk_probe_1.probeSdkInstall)('@github/copilot-sdk')) {
+                    return (0, descriptor_1.fail)(`agent: "copilot" requires the @github/copilot-sdk optional dependency. Install with \`npm install @github/copilot-sdk\` and retry, or use \`force: true\` to bypass this check.`);
+                }
+            }
+            // Phase 3a — headless Pi pre-flight. The Pi SDK is an optional Node-22.19+
+            // dep required at the headless entry; gate at recruit (cross-host skips —
+            // the target daemon's availableAgentTypes is the gate there).
+            if (agent === 'pi' && !host && !force) {
+                // Validate the model selector format up front (provider/model).
+                let parsedModel;
+                if (model) {
+                    const r = (0, config_1.parsePiProviderModel)(model);
+                    if ('error' in r)
+                        return (0, descriptor_1.fail)(`agent: "pi" — ${r.error} Or use \`force: true\` to bypass.`);
+                    parsedModel = r;
+                }
+                if (parsedModel?.provider === 'github-copilot') {
+                    // Copilot-via-Pi: full pre-flight (deps + version floor + Copilot auth +
+                    // model-index Gate 4 via pi-ai's sessionless getModel, injected here).
+                    let resolveModel;
+                    try {
+                        const piAi = await esmImport(probe_1.PI_AI_PACKAGE);
+                        resolveModel = piAi.getModel;
+                    }
+                    catch { /* dep-present gate inside the preflight fails first if pi-ai is unimportable */ }
+                    const pf = (0, probe_1.probeCopilotPiPreflight)({ requestedModel: parsedModel, resolveModel });
+                    if (!pf.available)
+                        return (0, descriptor_1.fail)(`agent: "pi" (Copilot) pre-flight failed: ${pf.reason}`);
+                }
+                else if (!(0, sdk_probe_1.probeSdkInstall)(probe_1.PI_PACKAGE)) {
+                    // Anthropic / Pi-default path: just require the Pi SDK installed.
+                    return (0, descriptor_1.fail)(`agent: "pi" requires the ${probe_1.PI_PACKAGE} optional dependency (Node >= 22.19). Install with \`npm install -g ${probe_1.PI_PACKAGE}\` and retry, or use \`force: true\` to bypass.`);
+                }
+            }
+            // Resolve agent type if provided
+            let agentDefinition;
+            let agentDefinitionPath;
+            let agentDefinitionDescription;
+            let nativeResolvable;
+            let allowedTools;
+            if (agentTypeName) {
+                const info = (0, agent_types_1.resolveAgentType)(agentTypeName);
+                if (!info) {
+                    const available = (0, agent_types_1.listAgentTypes)().map(t => t.name);
+                    return (0, descriptor_1.fail)(`Unknown agent type "${agentTypeName}". Available types: ${available.length ? available.join(', ') : '(none)'}`);
+                }
+                agentDefinition = info.name;
+                agentDefinitionPath = info.path;
+                agentDefinitionDescription = info.description;
+                nativeResolvable = info.nativeResolvable;
+                allowedTools = info.allowedTools;
+            }
+            // Validate name
+            const nameError = (0, validation_1.validatePlayerName)(name);
+            if (nameError) {
+                return (0, descriptor_1.fail)(nameError);
+            }
+            if (name === 'conductor' && !isConductor) {
+                return (0, descriptor_1.fail)(`The name "conductor" is reserved for conductor sessions. Use a different name, or set conductor: true.`);
+            }
+            // ── #274 AC12 — cross-host recruit pre-flight ──
+            //
+            // When `host` is specified, verify that the target is live + has
+            // the requested agent runtime available BEFORE submitting to the
+            // outbox. Otherwise `recruit --host foo` could queue forever on a
+            // per-host task queue nobody's listening on (the exact failure
+            // mode #274 set out to close).
+            //
+            // `force: true` bypasses pre-flight entirely (AC12d) — covers the
+            // scripted-recruit-on-about-to-boot-daemon case plus any other
+            // "I know what I'm doing" override. RPC failure during pre-flight
+            // falls through with a warning (AC12e) so today's recruit
+            // availability characteristics are preserved.
+            if (host && !force) {
+                try {
+                    const hosts = await listHostsFn(client);
+                    const preflightError = checkHostPreflight(hosts, host, agent);
+                    if (preflightError)
+                        return (0, descriptor_1.fail)(preflightError);
+                }
+                catch (err) {
+                    toolLog(`Host pre-flight RPC failed for "${host}"; proceeding without validation (use --force to silence this warning): ${err instanceof Error ? err.message : err}`);
                 }
             }
-            // Check if a session with this name is already active
-            const existing = await (0, resolve_1.resolveSession)(client, config.ensemble, name);
-            if (existing) {
-                if (force) {
-                    // Force-terminate the existing session before recruiting
-                    await existing.terminate(`Force-terminated for re-recruit by ${getPlayerId()}`);
-                    // Best-effort notify conductor
+            try {
+                // Check if a conductor already exists when recruiting a conductor
+                if (isConductor) {
                     try {
-                        const condId = (0, config_1.conductorWorkflowId)(config.ensemble);
-                        const condHandle = client.workflow.getHandle(condId);
-                        await condHandle.signal('receiveMessage', {
-                            from: 'system',
-                            text: `Session "${name}" was force-terminated for re-recruit by ${getPlayerId()}.`,
-                            responseRequested: false,
-                        });
+                        const conductorWfId = (0, config_1.conductorWorkflowId)(config.ensemble);
+                        const conductorHandle = client.workflow.getHandle(conductorWfId);
+                        const desc = await conductorHandle.describe();
+                        if (desc.status.name === 'RUNNING') {
+                            if (force) {
+                                await conductorHandle.terminate(`Force-terminated for re-recruit by ${getPlayerId()}`);
+                            }
+                            else {
+                                return (0, descriptor_1.fail)(`A conductor is already running in ensemble "${config.ensemble}". Use \`agent-tempo conduct --replace\` from the CLI to replace it, \`stop\` it first, or use \`force: true\` to replace it.`);
+                            }
+                        }
                     }
                     catch {
-                        // Conductor may not exist — that's fine
+                        // No existing conductor — proceed
                     }
                 }
-                else {
-                    return (0, helpers_1.fail)(`Session **${name}** is already active. Use \`cue\` to send it a message, \`stop\` it first, or use \`force: true\` to replace it.`);
+                // Check if a session with this name is already active
+                const existing = await (0, resolve_1.resolveSession)(client, config.ensemble, name);
+                if (existing) {
+                    if (force) {
+                        // Force-terminate the existing session before recruiting
+                        await existing.terminate(`Force-terminated for re-recruit by ${getPlayerId()}`);
+                        // Best-effort notify conductor
+                        try {
+                            const condId = (0, config_1.conductorWorkflowId)(config.ensemble);
+                            const condHandle = client.workflow.getHandle(condId);
+                            await condHandle.signal('receiveMessage', {
+                                from: 'system',
+                                text: `Session "${name}" was force-terminated for re-recruit by ${getPlayerId()}.`,
+                                responseRequested: false,
+                            });
+                        }
+                        catch {
+                            // Conductor may not exist — that's fine
+                        }
+                    }
+                    else {
+                        return (0, descriptor_1.fail)(`Session **${name}** is already active. Use \`cue\` to send it a message, \`stop\` it first, or use \`force: true\` to replace it.`);
+                    }
                 }
+                const entry = {
+                    type: 'recruit',
+                    targetName: name,
+                    workDir,
+                    isConductor,
+                    initialMessage,
+                    agent,
+                    systemPrompt: agentDefinition ? undefined : systemPrompt,
+                    targetHostname: host,
+                    agentDefinition,
+                    agentDefinitionPath,
+                    agentDefinitionDescription,
+                    nativeResolvable,
+                    allowedTools,
+                    claudeBin: config.claudeBin,
+                    ...(agent === 'mock' ? { mockMode: mockMode ?? 'echo' } : {}),
+                    ...(agent === 'mock' && mockScenario ? { mockScenario } : {}),
+                    ...(agent === 'claude-api' && model ? { model } : {}),
+                    // #520 — claude-code-headless permission knobs flow through the
+                    // outbox so PR-2's spawn helper picks them up via env. Fields
+                    // are only present on the entry when actually set; the
+                    // OutboxEntryInput shape will gain typed `permissionMode` /
+                    // `dangerouslySkipPermissions` fields in PR-2.
+                    ...(agent === 'claude-code-headless' && permissionMode ? { permissionMode } : {}),
+                    ...(agent === 'claude-code-headless' && dangerouslySkipPermissions ? { dangerouslySkipPermissions: true } : {}),
+                    // Phase 3a / MD-C — explicit toolAccess on the entry. Normalized at the
+                    // read site (above) to a concrete value, so the spawned gate + audit
+                    // always see one without a fallback here.
+                    ...(agent === 'pi' ? { toolAccess } : {}),
+                };
+                const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+                return (0, descriptor_1.ok)(`Recruit request submitted for **${name}** in ${workDir}. The session will be spawned shortly. (outbox: ${entryId})`);
             }
-            const entry = {
-                type: 'recruit',
-                targetName: name,
-                workDir,
-                isConductor,
-                initialMessage,
-                agent,
-                systemPrompt: agentDefinition ? undefined : systemPrompt,
-                targetHostname: host,
-                agentDefinition,
-                agentDefinitionPath,
-                agentDefinitionDescription,
-                nativeResolvable,
-                allowedTools,
-                claudeBin: config.claudeBin,
-                ...(agent === 'mock' ? { mockMode: mockMode ?? 'echo' } : {}),
-                ...(agent === 'mock' && mockScenario ? { mockScenario } : {}),
-                ...(agent === 'claude-api' && model ? { model } : {}),
-                // #520 — claude-code-headless permission knobs flow through the
-                // outbox so PR-2's spawn helper picks them up via env. Fields
-                // are only present on the entry when actually set; the
-                // OutboxEntryInput shape will gain typed `permissionMode` /
-                // `dangerouslySkipPermissions` fields in PR-2.
-                ...(agent === 'claude-code-headless' && permissionMode ? { permissionMode } : {}),
-                ...(agent === 'claude-code-headless' && dangerouslySkipPermissions ? { dangerouslySkipPermissions: true } : {}),
-            };
-            const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
-            return (0, helpers_1.ok)(`Recruit request submitted for **${name}** in ${workDir}. The session will be spawned shortly. (outbox: ${entryId})`);
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to recruit: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to recruit: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }
 // ────────────────────────────────────────────────────────────────────────
 // #274 AC12 — host pre-flight validation (exported for unit tests)