external-subagent 0.1.0

package/plugins/codex/external-subagent/hooks/guard-bash.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+let raw = '';
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) raw += chunk;
+try {
+  const input = JSON.parse(raw);
+  const managed = process.env.ZCODE_AGENT_POLICY === '1';
+  const mode = process.env.ZCODE_AGENT_PERMISSION_MODE || process.env.ZCODE_PERMISSION_MODE;
+  if (!managed || mode !== 'plan' || (input?.tool_name ?? input?.toolName) !== 'Bash') process.exit(0);
+  process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: 'external-subagent policy: Bash is disabled in plan probes' } })}\n`);
+} catch {
+  if (process.env.ZCODE_AGENT_POLICY === '1') {
+    process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: 'external-subagent policy: malformed hook input' } })}\n`);
+  }
+}

package/plugins/codex/external-subagent/lib/agent-file-policy.mjs

@@ -0,0 +1,206 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const AGENT_FILE_POLICY_VERSION = 'zcode-agent-file-policy/v1.0.0';
+const MAX_MANIFEST_BYTES = 64 * 1024;
+const MAX_MANIFEST_ENTRIES = 256;
+const MAX_BOOTSTRAP_ROOTS = 8;
+const MAX_PATH_BYTES = 4096;
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'Delete', 'Move']);
+const READ_TOOLS = new Set(['Read', 'Grep', 'Glob']);
+const PATH_KEYS = new Set([
+  'path', 'file_path', 'filePath', 'directory', 'directory_path', 'directoryPath',
+  'source', 'source_path', 'sourcePath', 'destination', 'destination_path', 'destinationPath',
+  'old_path', 'oldPath', 'new_path', 'newPath', 'from', 'to',
+]);
+const PROTECTED_PART = /^(?:\.git|\.gitmodules|\.zcode|\.codex|\.agent-work)$/u;
+
+function deny(code) {
+  return { decision: 'deny', code, reason: `${AGENT_FILE_POLICY_VERSION}: ${code}` };
+}
+
+function allow() {
+  return { decision: 'allow', code: 'ok', reason: `${AGENT_FILE_POLICY_VERSION}: allowed` };
+}
+
+function ask() {
+  return { decision: 'ask', code: 'edit_requires_approval', reason: `${AGENT_FILE_POLICY_VERSION}: edit requires external approval` };
+}
+
+function envRequired(env) {
+  if (env?.ZCODE_AGENT_POLICY !== '1') return { decision: 'skip', code: 'policy_not_managed', reason: `${AGENT_FILE_POLICY_VERSION}: unmanaged session` };
+  const rawRoot = env?.ZCODE_AGENT_WORKSPACE_ROOT;
+  if (typeof rawRoot !== 'string' || rawRoot.length === 0 || !path.isAbsolute(rawRoot)) {
+    return deny('workspace_root_missing');
+  }
+  let root;
+  try {
+    root = fs.realpathSync.native(rawRoot);
+    if (!fs.statSync(root).isDirectory()) return deny('workspace_root_invalid');
+  } catch {
+    return deny('workspace_root_invalid');
+  }
+  let manifest = [];
+  const rawManifest = env?.ZCODE_AGENT_WRITE_MANIFEST;
+  if (typeof rawManifest !== 'string' || Buffer.byteLength(rawManifest, 'utf8') > MAX_MANIFEST_BYTES) {
+    return deny('write_manifest_invalid');
+  }
+  try {
+    const parsed = rawManifest.length === 0 ? [] : JSON.parse(rawManifest);
+    if (!Array.isArray(parsed) || parsed.length > MAX_MANIFEST_ENTRIES) return deny('write_manifest_invalid');
+    manifest = parsed.map((item) => {
+      if (typeof item !== 'string' || item.length === 0 || Buffer.byteLength(item, 'utf8') > MAX_PATH_BYTES) {
+        throw new Error('manifest path');
+      }
+      const candidate = path.posix.normalize(item.replaceAll('\\', '/'));
+      if (path.posix.isAbsolute(candidate) || candidate === '..' || candidate.startsWith('../') || candidate.includes('\0')) {
+        throw new Error('manifest traversal');
+      }
+      if (candidate.split('/').some((part) => PROTECTED_PART.test(part))) {
+        throw new Error('manifest protected');
+      }
+      return candidate === '.' ? '' : candidate;
+    });
+  } catch {
+    return deny('write_manifest_invalid');
+  }
+  let bootstrapRoots = [];
+  const rawBootstrapRoots = env?.ZCODE_AGENT_BOOTSTRAP_ROOTS;
+  if (rawBootstrapRoots !== undefined) {
+    if (typeof rawBootstrapRoots !== 'string' || Buffer.byteLength(rawBootstrapRoots, 'utf8') > MAX_MANIFEST_BYTES) {
+      return deny('bootstrap_roots_invalid');
+    }
+    try {
+      const parsed = rawBootstrapRoots.trimStart().startsWith('[')
+        ? JSON.parse(rawBootstrapRoots)
+        : [rawBootstrapRoots];
+      if (!Array.isArray(parsed) || parsed.length > MAX_BOOTSTRAP_ROOTS) throw new Error('bootstrap roots');
+      bootstrapRoots = parsed.map((item) => {
+        if (typeof item !== 'string' || !path.isAbsolute(item) || item.length > MAX_PATH_BYTES || item.includes('\0') || hasParentTraversal(item)) {
+          throw new Error('bootstrap root path');
+        }
+        if (item.split(/[\\/]/u).some((part) => PROTECTED_PART.test(part))) {
+          throw new Error('bootstrap protected');
+        }
+        try {
+          if (!fs.statSync(item).isDirectory()) throw new Error('bootstrap not directory');
+          return fs.realpathSync.native(item);
+        } catch {
+          // A missing optional bootstrap root is inert; reads under it remain denied.
+          return item;
+        }
+      });
+    } catch {
+      return deny('bootstrap_roots_invalid');
+    }
+  }
+  return { root, manifest, bootstrapRoots };
+}
+
+function collectPaths(value, key = '') {
+  if (typeof value === 'string') return PATH_KEYS.has(key) ? [value] : [];
+  if (!value || typeof value !== 'object') return [];
+  if (Array.isArray(value)) return value.flatMap((item) => collectPaths(item, key));
+  return Object.entries(value).flatMap(([childKey, child]) => collectPaths(child, childKey));
+}
+
+function hasParentTraversal(value) {
+  return value.split(/[\\/]/u).some((part) => part === '..');
+}
+
+function confinedPath(root, value) {
+  if (typeof value !== 'string' || value.length === 0 || Buffer.byteLength(value, 'utf8') > MAX_PATH_BYTES) {
+    return false;
+  }
+  if (value.includes('\0') || hasParentTraversal(value)) return false;
+  const canonicalCandidate = resolveCanonicalPath(root, value);
+  if (!canonicalCandidate) return false;
+  return canonicalCandidate === root || canonicalCandidate.startsWith(`${root}${path.sep}`);
+}
+
+function resolveCanonicalPath(root, value) {
+  if (typeof value !== 'string' || value.length === 0 || Buffer.byteLength(value, 'utf8') > MAX_PATH_BYTES) {
+    return null;
+  }
+  if (value.includes('\0') || hasParentTraversal(value)) return null;
+  const candidate = path.isAbsolute(value) ? value : path.join(root, value);
+  const lexical = path.normalize(candidate);
+  let existing = lexical;
+  const missing = [];
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return null;
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+  try {
+    const canonical = fs.realpathSync.native(existing);
+    return missing.length > 0 ? path.join(canonical, ...missing) : canonical;
+  } catch {
+    return null;
+  }
+}
+
+function protectedPath(root, value) {
+  const relative = path.isAbsolute(value) ? path.relative(root, value) : value;
+  const lexicalProtected = relative.split(/[\\/]/u).some((part) => PROTECTED_PART.test(part));
+  if (lexicalProtected) return true;
+  const canonical = resolveCanonicalPath(root, value);
+  if (!canonical) return false;
+  return path.relative(root, canonical)
+    .split(/[\\/]/u)
+    .some((part) => PROTECTED_PART.test(part));
+}
+
+function pathAllowedForRead(state, value) {
+  // Relative paths are daemon-worktree paths.  Never reinterpret a relative
+  // payload against a bootstrap root (that would turn a worktree symlink into
+  // an apparently safe bootstrap path).  Bootstrap roots are absolute-only.
+  if (!path.isAbsolute(value)) {
+    return confinedPath(state.root, value) && !protectedPath(state.root, value);
+  }
+  return [state.root, ...state.bootstrapRoots].some(
+    (root) => confinedPath(root, value) && !protectedPath(root, value),
+  );
+}
+
+function withinManifest(root, value, manifest) {
+  const candidate = resolveCanonicalPath(root, value);
+  if (!candidate) return false;
+  return manifest.some((entry) => {
+    const target = resolveCanonicalPath(root, entry);
+    if (!target) return false;
+    return candidate === target || candidate.startsWith(`${target}${path.sep}`);
+  });
+}
+
+export function evaluateAgentFileInput(input, env = process.env) {
+  const state = envRequired(env);
+  if (state.decision) return state;
+  const tool = input?.tool_name ?? input?.toolName ?? input?.name;
+  if (typeof tool !== 'string' || (!READ_TOOLS.has(tool) && !WRITE_TOOLS.has(tool))) {
+    return deny('unsupported_tool');
+  }
+  const toolInput = input?.tool_input ?? input?.toolInput ?? input?.input ?? {};
+  const paths = collectPaths(toolInput);
+  // An omitted path is valid for a search rooted at cwd, but a file mutation must name a target.
+  if (WRITE_TOOLS.has(tool) && paths.length === 0) return deny('path_missing');
+  const cwd = input?.cwd ?? input?.working_directory ?? input?.workingDirectory ?? state.root;
+  if (!confinedPath(state.root, cwd) || protectedPath(state.root, cwd)) return deny('cwd_outside_root');
+  for (const value of paths.length ? paths : [cwd]) {
+    if (!pathAllowedForRead(state, value)) return deny('path_outside_root');
+    if (WRITE_TOOLS.has(tool) && !withinManifest(state.root, value, state.manifest)) return deny('write_not_allowlisted');
+  }
+  if (WRITE_TOOLS.has(tool) && env.ZCODE_AGENT_PERMISSION_MODE === 'edit') return ask();
+  return allow();
+}
+
+export function createAgentFileHookOutput(result) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: result.decision,
+      permissionDecisionReason: result.reason,
+    },
+  };
+}

package/plugins/codex/external-subagent/scripts/install-agent-hooks.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const pluginRoot = path.resolve(new URL('..', import.meta.url).pathname);
+const hookRoot = pluginRoot;
+const configPath = process.argv[process.argv.indexOf('--config') + 1];
+if (!configPath || configPath.startsWith('--')) {
+  console.error('usage: node install-agent-hooks.mjs --config /absolute/config.json [--provenance /absolute/provenance.json]');
+  process.exit(2);
+}
+const provenanceIndex = process.argv.indexOf('--provenance');
+const provenancePath = provenanceIndex >= 0
+  ? process.argv[provenanceIndex + 1]
+  : path.join(path.dirname(configPath), 'zcode-agent-hook-provenance.json');
+
+function readJson(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) {
+    if (error?.code === 'ENOENT') return fallback;
+    throw error;
+  }
+}
+
+function atomicWriteBytes(file, bytes) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.tmp-${process.pid}`;
+  try {
+    fs.writeFileSync(temporary, bytes, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+  } finally {
+    try { fs.unlinkSync(temporary); } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+const encodeJson = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const atomicWrite = (file, value) => atomicWriteBytes(file, encodeJson(value));
+
+const config = readJson(configPath, {});
+if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('config must be a JSON object');
+if (fs.existsSync(provenancePath)) {
+  const prior = readJson(provenancePath, null);
+  if (!prior || prior.effective_config_path !== path.resolve(configPath)) {
+    throw new Error(`HOOK_PROVENANCE_INVALID: effective_config_path does not match ${path.resolve(configPath)}`);
+  }
+}
+const next = structuredClone(config);
+next.hooks ??= {};
+next.hooks.enabled = true;
+next.hooks.events ??= {};
+const hashFile = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+// Resolve every shipped decision owner before mutating the caller's config.
+// A copied or incomplete plugin must fail without leaving a partial install.
+const effectiveConfigPath = path.resolve(configPath);
+const effectiveFilePolicyPath = path.join(hookRoot, 'lib', 'agent-file-policy.mjs');
+const auditWrapperPath = path.join(hookRoot, 'hooks', 'audit-bash-result.mjs');
+const fileWrapperPath = path.join(hookRoot, 'hooks', 'check-agent-files.mjs');
+const guardWrapperPath = path.join(hookRoot, 'hooks', 'guard-bash.mjs');
+const verifierSourcePath = path.join(pluginRoot, 'scripts', 'policy-verifier.mjs');
+const filePolicySha256 = hashFile(effectiveFilePolicyPath);
+if (effectiveConfigPath === path.resolve(provenancePath)) throw new Error('config and provenance paths must differ');
+const events = {
+  PreToolUse: [
+    { matcher: 'Bash', script: 'hooks/guard-bash.mjs' },
+    { matcher: '^(Read|Grep|Glob|Write|Edit|Delete|Move)$', script: 'hooks/check-agent-files.mjs' },
+  ],
+  PostToolUse: [{ matcher: 'Bash', script: 'hooks/audit-bash-result.mjs' }],
+  PostToolUseFailure: [{ matcher: 'Bash', script: 'hooks/audit-bash-result.mjs' }],
+};
+
+function processHookArgs(candidate) {
+  if (!candidate || !Array.isArray(candidate.hooks)) return [];
+  return candidate.hooks
+    .filter((hook) => hook?.type === 'process' && Array.isArray(hook.args))
+    .flatMap((hook) => hook.args)
+    .filter((arg) => typeof arg === 'string');
+}
+
+function isRecognizedAgentHook(candidate, matcher, expectedScript) {
+  if (candidate?.matcher !== matcher) return false;
+  const args = processHookArgs(candidate);
+  return args.some((arg) => path.resolve(arg) === expectedScript);
+}
+
+for (const [event, expectedEntries] of Object.entries(events)) {
+  const existing = Array.isArray(next.hooks.events[event]) ? next.hooks.events[event] : [];
+  for (const { matcher, script } of expectedEntries) {
+    const expectedScript = path.join(hookRoot, script);
+    const managedEntries = existing.filter((candidate) => candidate?.matcher === matcher);
+    const unknownEntries = managedEntries.filter((candidate) => !isRecognizedAgentHook(candidate, matcher, expectedScript));
+    if (unknownEntries.length > 0) {
+      throw new Error(`${event} contains an unknown managed hook; refusing to modify configuration`);
+    }
+  }
+  const unrelated = existing.filter((candidate) => !expectedEntries.some(({ matcher }) => candidate?.matcher === matcher));
+  next.hooks.events[event] = [
+    ...unrelated,
+    ...expectedEntries.map(({ matcher, script }) => ({
+      matcher,
+      hooks: [{ type: 'process', command: process.execPath, args: [path.join(hookRoot, script)], timeoutMs: 5000 }],
+    })),
+  ];
+}
+const nextConfigBytes = encodeJson(next);
+const nextProvenance = {
+  effective_file_policy_version: 'zcode-agent-file-policy/v1.0.0',
+  effective_file_policy_sha256: filePolicySha256,
+  effective_file_policy_path: effectiveFilePolicyPath,
+  effective_guard_wrapper_path: guardWrapperPath,
+  effective_guard_wrapper_sha256: hashFile(guardWrapperPath),
+  effective_config_path: effectiveConfigPath,
+  effective_config_sha256: crypto.createHash('sha256').update(nextConfigBytes).digest('hex'),
+  effective_audit_wrapper_path: auditWrapperPath,
+  effective_audit_wrapper_sha256: hashFile(auditWrapperPath),
+  effective_file_wrapper_path: fileWrapperPath,
+  effective_file_wrapper_sha256: hashFile(fileWrapperPath),
+  hook_activation_verified: true,
+  activation_method: 'outer-plugin-install',
+  activation_generation: `${Date.now()}-${filePolicySha256.slice(0, 12)}`,
+};
+const previousProvenance = fs.existsSync(provenancePath) ? fs.readFileSync(provenancePath) : null;
+const verifierPath = path.join(path.dirname(provenancePath), 'external-subagent-policy-verifier');
+const previousVerifier = fs.existsSync(verifierPath)
+  ? { bytes: fs.readFileSync(verifierPath), mode: fs.statSync(verifierPath).mode & 0o777 }
+  : null;
+try {
+  atomicWrite(provenancePath, nextProvenance);
+  atomicWriteBytes(verifierPath, fs.readFileSync(verifierSourcePath));
+  fs.chmodSync(verifierPath, 0o700);
+  atomicWriteBytes(configPath, nextConfigBytes);
+} catch (error) {
+  if (previousProvenance === null) {
+    try { fs.unlinkSync(provenancePath); } catch (unlinkError) {
+      if (unlinkError?.code !== 'ENOENT') throw unlinkError;
+    }
+  } else {
+    atomicWriteBytes(provenancePath, previousProvenance);
+  }
+  if (previousVerifier === null) {
+    try { fs.unlinkSync(verifierPath); } catch (unlinkError) { if (unlinkError?.code !== 'ENOENT') throw unlinkError; }
+  } else {
+    atomicWriteBytes(verifierPath, previousVerifier.bytes);
+    fs.chmodSync(verifierPath, previousVerifier.mode);
+  }
+  throw error;
+}
+console.log(JSON.stringify({ config: effectiveConfigPath, provenance: path.resolve(provenancePath), file_policy_sha256: filePolicySha256 }));

package/plugins/codex/external-subagent/scripts/mcp-stdio-bridge.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Stateless stdio bridge for the shared daemon MCP listener, in node.
+//
+// Mirrors crates/external-mcp (the native facade) byte for byte in
+// behavior: resolve the daemon MCP stream endpoint from
+// ZCODE_AGENTD_SOCKET, connect, and pipe client stdio <-> socket until
+// either side reaches EOF.  Hosts that spawn MCP servers inside
+// restricted execution contexts (ZCode kills ad-hoc-signed native
+// binaries there, while node processes and unix sockets are allowed)
+// bind this script through the installing node instead of the native
+// binary; see docs/compatibility/zcode.md.
+import net from 'node:net';
+import path from 'node:path';
+
+const socket = process.env.ZCODE_AGENTD_SOCKET;
+if (!socket || !path.isAbsolute(socket)) {
+  console.error('mcp-stdio-bridge: ZCODE_AGENTD_SOCKET must be an absolute path');
+  process.exit(1);
+}
+// The stable daemon RPC socket keeps its name; MCP is exposed by the
+// sibling `.mcp` stream endpoint, except in isolated tests and
+// non-standard deployments that point at the MCP endpoint directly.
+const endpoint = path.basename(socket) === 'external-subagent.sock'
+  ? socket.replace(/\.sock$/u, '.mcp')
+  : socket;
+
+const stream = net.createConnection(endpoint);
+stream.on('error', (error) => {
+  console.error(`mcp-stdio-bridge: failed to connect to daemon MCP socket ${endpoint}: ${error.message}`);
+  process.exit(1);
+});
+stream.on('close', () => process.exit(0));
+process.stdin.on('end', () => process.exit(0));
+process.stdin.on('error', () => process.exit(0));
+process.stdin.pipe(stream);
+stream.pipe(process.stdout);

package/plugins/codex/external-subagent/scripts/policy-verifier.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+function value(name) {
+  const index = process.argv.indexOf(name);
+  const result = index >= 0 ? process.argv[index + 1] : undefined;
+  if (!result || result.startsWith('--')) process.exit(2);
+  return result;
+}
+
+const workspace = path.resolve(value('--workspace'));
+const home = path.resolve(value('--home'));
+const mode = value('--permission-mode');
+const manifest = value('--write-manifest');
+if (mode !== 'plan' || manifest !== '[]' || !fs.statSync(workspace).isDirectory()) process.exit(2);
+const configPath = path.join(home, '.zcode', 'cli', 'config.json');
+const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+const events = config?.hooks?.events;
+if (config?.hooks?.enabled !== true || !events || !Array.isArray(events.PreToolUse)) process.exit(2);
+const pre = events.PreToolUse.find((entry) => entry?.matcher === '^(Read|Grep|Glob|Write|Edit|Delete|Move)$');
+const hook = pre?.hooks?.find((entry) => entry?.type === 'process' && Array.isArray(entry.args));
+const script = hook?.args?.find((candidate) => typeof candidate === 'string' && candidate.endsWith('/hooks/check-agent-files.mjs'));
+const guard = events.PreToolUse.find((entry) => entry?.matcher === 'Bash')?.hooks?.find((entry) => entry?.type === 'process')?.args?.[0];
+const audit = events.PostToolUse?.find((entry) => entry?.matcher === 'Bash')?.hooks?.find((entry) => entry?.type === 'process')?.args?.[0];
+if (!script || !fs.statSync(script).isFile() || hook.command !== process.execPath || !guard || !fs.statSync(guard).isFile() || !audit || !fs.statSync(audit).isFile()) process.exit(2);
+const provenancePath = path.join(home, 'Library', 'Application Support', 'external-subagent', 'zcode-agent-hook-provenance.json');
+if (!fs.existsSync(provenancePath)) process.exit(2);
+const provenance = JSON.parse(fs.readFileSync(provenancePath, 'utf8'));
+const hash = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+const policy = path.resolve(path.dirname(script), '../lib/agent-file-policy.mjs');
+if (provenance.effective_config_path !== path.resolve(configPath)
+  || provenance.hook_activation_verified !== true
+  || provenance.effective_file_policy_version !== 'zcode-agent-file-policy/v1.0.0'
+  || provenance.effective_file_policy_path !== policy
+  || provenance.effective_file_policy_sha256 !== hash(policy)
+  || provenance.effective_guard_wrapper_path !== path.resolve(guard)
+  || provenance.effective_guard_wrapper_sha256 !== hash(guard)
+  || provenance.effective_file_wrapper_path !== path.resolve(script)
+  || provenance.effective_file_wrapper_sha256 !== hash(script)
+  || provenance.effective_audit_wrapper_path !== path.resolve(audit)
+  || provenance.effective_audit_wrapper_sha256 !== hash(audit)) process.exit(2);
+process.exit(0);

package/plugins/codex/external-subagent/skills/external-subagent/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: external-subagent
+description: Manage bounded repository-scoped tasks through external-subagent.
+---
+
+# external-subagent
+
+Use the `external_subagent_*` tools to inspect status, spawn a task with an explicit
+`subagent`, wait for progress, retrieve the complete result, and close the task.
+Execution targets are `zcode`, `dsh`, and `codex`; each name currently has one
+runtime instance and no instance selector is supported. Omitting `subagent` uses
+`default_subagent` or returns `subagent_required`; unknown targets return
+`subagent_unknown`, and unknown spawn fields are rejected before dispatch.
+
+Spawn is intentionally non-idempotent: every successful call creates a fresh task
+and returns `{agent_id, status}` (a duplicate workspace or id is a `conflict`
+error, never reuse of an existing task). `status` carries only routing,
+capability, and readiness facts (`subagents[]` with `configured`, `enabled`,
+`spawn_supported`, permission modes, model selection, and per-scope states);
+deployment identity, config revisions, adapter transport detail, and probe
+evidence are operator diagnostics — read them with the CLI `diagnose` command
+instead of the MCP status tool.
+
+Spawn accepts an optional `effort` token that steers the task's reasoning
+effort. Omit it to keep each agent's current default (codex keeps its existing
+wire default; zcode and dsh send no effort field or call at all). `codex`
+admits only the closed set
+`low | medium | high | xhigh` — `minimal` and `max` are rejected;
+`zcode` and `dsh` accept any bounded token (1..24 bytes of `[a-z0-9_]`) and
+pass it through to the runtime, because the supported set is only known at
+runtime. A malformed or unsupported token is rejected before dispatch, so no
+task is created. Example: spawn with
+`{"subagent": "zcode", "repository": "/absolute/path", "prompt": "...", "effort": "high"}`.
+
+The caller is a `host`. Any unregistered local MCP client can act as `custom` and
+call status or spawn without a host record or Codex home. Built-in `host.codex`
+exists for installation and automatic-upgrade coordination, supports multiple
+Codex home instances, and offers plugin or direct MCP bindings; built-in
+`host.zcode` binds this same plugin through the ZCode config's inline plugin
+dirs with a single per-user instance. This is separate
+from `subagent.codex`. Protocol implementations are adapters.
+
+Actual per-subagent limitations (from the accepted code):
+
+- `zcode` — enabled and spawn-supported by default; all four permission modes
+  (build/edit/plan/yolo); an explicit spawn `model` is rejected
+  (`model_selection_unsupported`).
+- `dsh` — disabled until explicitly enabled and configured
+  (`runtime_path`/`home`/`profile`/`version`); admits only `build` and strict
+  `plan`.
+- `codex` — disabled by default; `plan` (sandbox=read-only) and `yolo`
+  (sandbox=danger-full-access), both pinning approvalPolicy=never;
+  `build`/`edit` are refused before the prompt.
+- `observe` — verified public reasoning exists only for zcode tasks; observe
+  on a non-zcode task truthfully errors `unavailable`.