external-subagent 0.1.0

package/cli/maintenance.mjs

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from './errors.mjs';
+import { jsonBytes, sha256 } from './fs-atomic.mjs';
+import { legacyPaths, productPaths } from './paths.mjs';
+import { bootoutService } from './install/service-macos.mjs';
+
+function copyTree(source, destination, records, root = source) {
+  if (!fs.existsSync(source)) return;
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name);
+    const relative = path.relative(root, from);
+    const to = path.join(destination, relative);
+    if (entry.isSymbolicLink()) throw new CliError('UNSAFE_BACKUP_ENTRY', `refusing symlink: ${from}`);
+    if (entry.isDirectory()) copyTree(from, destination, records, root);
+    else if (entry.isFile()) {
+      fs.mkdirSync(path.dirname(to), { recursive: true, mode: 0o700 });
+      const bytes = fs.readFileSync(from);
+      fs.writeFileSync(to, bytes, { mode: 0o600 });
+      records.push({ path: relative, bytes: bytes.length, sha256: sha256(bytes) });
+    }
+  }
+}
+
+export function backupData(destination, paths = productPaths()) {
+  const resolved = path.resolve(destination);
+  const source = path.resolve(paths.data);
+  const relativeToSource = path.relative(source, resolved);
+  if (relativeToSource === '' || (!relativeToSource.startsWith('..') && !path.isAbsolute(relativeToSource))) {
+    throw new CliError('BACKUP_DESTINATION_IN_DATA', 'backup destination must not be inside product data');
+  }
+  if (fs.existsSync(resolved)) throw new CliError('BACKUP_EXISTS', 'backup destination already exists');
+  fs.mkdirSync(resolved, { recursive: false, mode: 0o700 });
+  const records = [];
+  copyTree(paths.data, path.join(resolved, 'data'), records);
+  const manifest = { schema_version: 1, product: 'external-subagent', files: records.sort((a, b) => a.path.localeCompare(b.path)) };
+  fs.writeFileSync(path.join(resolved, 'manifest.json'), jsonBytes(manifest), { mode: 0o600 });
+  return { destination: resolved, files: records.length };
+}
+
+export function restoreData(source, paths = productPaths()) {
+  const resolved = path.resolve(source);
+  const manifest = JSON.parse(fs.readFileSync(path.join(resolved, 'manifest.json'), 'utf8'));
+  if (manifest.product !== 'external-subagent' || !Array.isArray(manifest.files)) throw new CliError('BACKUP_INVALID', 'backup manifest is invalid');
+  for (const record of manifest.files) {
+    if (path.isAbsolute(record.path) || record.path.split(path.sep).includes('..')) throw new CliError('BACKUP_INVALID', 'backup contains an unsafe path');
+    const bytes = fs.readFileSync(path.join(resolved, 'data', record.path));
+    if (bytes.length !== record.bytes || sha256(bytes) !== record.sha256) throw new CliError('BACKUP_CORRUPT', `backup verification failed: ${record.path}`);
+  }
+  const temporary = `${paths.data}.restore-${process.pid}`;
+  if (fs.existsSync(temporary)) fs.rmSync(temporary, { recursive: true });
+  fs.mkdirSync(temporary, { recursive: true, mode: 0o700 });
+  copyTree(path.join(resolved, 'data'), temporary, []);
+  const displaced = `${paths.data}.previous-${process.pid}`;
+  try {
+    if (fs.existsSync(paths.data)) fs.renameSync(paths.data, displaced);
+    fs.renameSync(temporary, paths.data);
+    if (fs.existsSync(displaced)) fs.rmSync(displaced, { recursive: true });
+  } catch (error) {
+    if (!fs.existsSync(paths.data) && fs.existsSync(displaced)) fs.renameSync(displaced, paths.data);
+    throw error;
+  }
+  return { restored: true, files: manifest.files.length };
+}
+
+function removeOne(target) {
+  try {
+    const stat = fs.lstatSync(target);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) fs.rmSync(target, { recursive: true });
+    else fs.unlinkSync(target);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+// Deleting the plist alone leaves a job launchd already loaded running until
+// the next logout (observed live: uninstall reported success while the daemon
+// process, the launchd registration, and the RPC socket all stayed alive).
+// The ES-owned service is therefore booted out — with the bounded
+// removal-confirmation bootoutService owns — before its definition file is
+// removed.  A service that is not registered is not an error (idempotent
+// uninstall); a bootout that cannot complete fails the command rather than
+// deleting the definition out from under a still-running service.
+export function uninstall(paths = productPaths(), options = {}) {
+  const service = bootoutService(paths, process.getuid(), options);
+  return {
+    service_stopped: true,
+    service_already_stopped: Boolean(service.already_stopped),
+    removed_launch_agent: removeOne(paths.launchAgent),
+    data_retained: true,
+    data: paths.data,
+  };
+}
+
+export function purge(paths = productPaths()) {
+  return { purged: removeOne(paths.data), logs_purged: removeOne(paths.logs) };
+}
+
+export function cleanupLegacy(home) {
+  const removed = legacyPaths(home).filter(removeOne);
+  return { migration: false, aliases_created: [], removed };
+}

package/cli/paths.mjs

@@ -0,0 +1,40 @@
+import os from 'node:os';
+import path from 'node:path';
+import { LAUNCH_AGENT_LABEL, PRODUCT_NAME } from './constants.mjs';
+import { PLUGIN_NAME } from './install/layout.mjs';
+
+export function platform() {
+  return process.env.ZCODE_AS_SUBAGENT_TEST_PLATFORM || process.platform;
+}
+
+// State paths derive from PRODUCT_NAME, so the debug variant gets a fully
+// parallel tree (its own data directory, database, socket, and logs) and
+// never touches the released product's state.
+export function productPaths(home = os.homedir()) {
+  const data = path.join(home, 'Library', 'Application Support', PRODUCT_NAME);
+  return {
+    home,
+    data,
+    config: path.join(data, 'config.json'),
+    state: path.join(data, 'install-state.json'),
+    hookProvenance: path.join(data, 'zcode-agent-hook-provenance.json'),
+    database: path.join(data, `${PRODUCT_NAME}.sqlite3`),
+    socket: path.join(data, `${PRODUCT_NAME}.sock`),
+    logs: path.join(home, 'Library', 'Logs', PRODUCT_NAME),
+    launchAgent: path.join(home, 'Library', 'LaunchAgents', `${LAUNCH_AGENT_LABEL}.plist`),
+    zcodeConfig: path.join(home, '.zcode', 'cli', 'config.json'),
+    zcodePlugin: path.join(data, 'zcode-plugin', PLUGIN_NAME),
+  };
+}
+
+export function legacyPaths(home = os.homedir()) {
+  return [
+    path.join(home, 'Library', 'LaunchAgents', 'com.zcode-reviewd.plist'),
+    path.join(home, 'Library', 'LaunchAgents', 'com.zcode-review-mcp.plist'),
+    path.join(home, 'Library', 'Logs', 'zcode-reviewd'),
+    path.join(home, 'Library', 'Application Support', 'zcode-review-mcp'),
+    path.join(home, 'Library', 'Application Support', 'zcode-reviewd'),
+    path.join(home, '.local', 'bin', 'zcode-reviewd'),
+    path.join(home, '.local', 'bin', 'zcode-review-mcp'),
+  ];
+}

package/cli/rpc.mjs

@@ -0,0 +1,261 @@
+import net from 'node:net';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { CliError } from './errors.mjs';
+
+export const MAX_FRAME_BYTES = 512 * 1024;
+export const MAX_RESPONSE_FRAME_BYTES = 2 * 1024 * 1024;
+export const MAX_RESULT_CHUNK_BYTES = 256 * 1024;
+export const AGENT_PROBE_TRANSPORT_TIMEOUT_MS = 200_000;
+export const MIN_TASK_ID = 10_000_000;
+export const MAX_TASK_ID = 99_999_999;
+
+// Daemon RpcErrorCode values serialize snake_case on the wire
+// ("unknown_method", "validation"), while CLI error codes are
+// SCREAMING_SNAKE. callDaemon preserves the raw daemon code verbatim —
+// diagnose compares 'not_found' directly — so upgrade-surface consumers
+// canonicalize through this mapping before matching or recording codes.
+export function canonicalDaemonCode(code) {
+  return typeof code === 'string' && code.length > 0 ? code.toUpperCase() : 'DAEMON_ERROR';
+}
+
+function taskId(value) {
+  if (!Number.isInteger(value) || value < MIN_TASK_ID || value > MAX_TASK_ID) {
+    throw new CliError('INVALID_ARGUMENT', 'agent_id must be an integer between 10000000 and 99999999', 2);
+  }
+  return value;
+}
+
+function daemonTaskId(value) { return String(taskId(value)); }
+
+export function waitTransportTimeoutMs(waitTime = 290) {
+  if (!Number.isInteger(waitTime) || waitTime < 0 || waitTime > 299) {
+    throw new CliError('INVALID_ARGUMENT', 'wait_time must be an integer between 0 and 299', 2);
+  }
+  return waitTime * 1000 + 5000;
+}
+
+export function daemonTransportTimeoutMs(command, params = {}) {
+  if (command === 'wait') return waitTransportTimeoutMs(params.wait_time);
+  if (command === 'agent-probe' || command === 'agent-models') return AGENT_PROBE_TRANSPORT_TIMEOUT_MS;
+  return 6000;
+}
+
+function publicTaskId(value) {
+  const id = Number(value);
+  if (!Number.isSafeInteger(id) || String(id) !== String(value) || id < MIN_TASK_ID || id > MAX_TASK_ID) {
+    throw new CliError('PROTOCOL_ERROR', 'daemon returned an invalid agent_id');
+  }
+  return id;
+}
+
+function readJsonInput(args) {
+  const inline = args.find((arg) => arg.startsWith('--json='));
+  if (inline) return JSON.parse(inline.slice('--json='.length));
+  const index = args.indexOf('--json');
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith('--')) return JSON.parse(args[index + 1]);
+  if (index >= 0 || !process.stdin.isTTY) {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  }
+  return {};
+}
+
+function requestId() { return `cli-${process.pid}-${crypto.randomUUID()}`; }
+
+function manifest(input) {
+  const allowed = new Set(['subagent', 'repository', 'permission_mode', 'prompt', 'model', 'effort', 'write_manifest']);
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) throw new CliError('INVALID_ARGUMENT', `spawn contains unsupported field: ${key}`, 2);
+  }
+  if (input.subagent !== undefined && (typeof input.subagent !== 'string' || input.subagent.length === 0)) throw new CliError('INVALID_ARGUMENT', 'subagent must be a non-empty string', 2);
+  if (input.model !== undefined && (typeof input.model !== 'string' || input.model.length === 0)) throw new CliError('INVALID_ARGUMENT', 'model must be a non-empty string', 2);
+  if (input.effort !== undefined && (typeof input.effort !== 'string' || input.effort.length === 0)) throw new CliError('INVALID_ARGUMENT', 'effort must be a non-empty string', 2);
+  if (typeof input.repository !== 'string' || input.repository.length === 0 || typeof input.prompt !== 'string' || input.prompt.length === 0) throw new CliError('INVALID_ARGUMENT', 'create requires non-empty repository and prompt strings', 2);
+  if (input.permission_mode !== undefined && (typeof input.permission_mode !== 'string' || input.permission_mode.length === 0)) throw new CliError('INVALID_ARGUMENT', 'permission_mode must be a non-empty string', 2);
+  if (input.write_manifest !== undefined && (!Array.isArray(input.write_manifest) || input.write_manifest.some((value) => typeof value !== 'string' || value.length === 0))) throw new CliError('INVALID_ARGUMENT', 'write_manifest must contain non-empty strings', 2);
+  return {
+    schema: 'zcode-general-task/v1', agent_id: requestId(), repository: input.repository,
+    permission_mode: input.permission_mode || 'build', prompt: input.prompt,
+    write_manifest: input.write_manifest || [],
+  };
+}
+
+function rejectUnknownFields(command, input, allowed) {
+  for (const key of Object.keys(input)) {
+    if (!allowed.has(key)) throw new CliError('INVALID_ARGUMENT', `${command} contains unsupported field: ${key}`, 2);
+  }
+}
+
+function methodFor(command, input) {
+  switch (command) {
+    case 'status': return { method: 'system_status' };
+    case 'drain': return { method: 'daemon_begin_drain', ...(input.cancel_active === true ? { params: { cancel_active: true } } : {}) };
+    case 'drain-status': return { method: 'daemon_drain_status' };
+    case 'drain-abort': return { method: 'daemon_abort_drain' };
+    case 'activate-ready': return { method: 'daemon_activate_ready' };
+    case 'agent-probe': return { method: 'agent_probe', params: input };
+    case 'agent-models': return { method: 'agent_models', params: input };
+    case 'create': case 'spawn': return {
+      method: 'submit_general',
+      params: {
+        ...(input.subagent !== undefined ? { subagent: input.subagent } : {}),
+        ...(input.model !== undefined ? { model: input.model } : {}),
+        ...(input.effort !== undefined ? { effort: input.effort } : {}),
+        manifest: manifest(input),
+      },
+    };
+    case 'wait': {
+      rejectUnknownFields('wait', input, new Set(['agent_id', 'wait_time', 'message_id']));
+      return {
+        method: 'task_wait',
+        params: {
+          agent_id: daemonTaskId(input.agent_id),
+          wait_time: input.wait_time ?? 290,
+          ...(input.message_id ? { message_id: input.message_id } : {}),
+        },
+      };
+    }
+    case 'list': {
+      const allowed = new Set(['subagent', 'repository', 'workspace', 'phase', 'outcome', 'cursor', 'limit']);
+      for (const key of Object.keys(input)) {
+        if (!allowed.has(key)) throw new CliError('INVALID_ARGUMENT', `list contains unsupported field: ${key}`, 2);
+      }
+      if (input.subagent === null || (input.subagent !== undefined && (typeof input.subagent !== 'string' || input.subagent.length === 0))) {
+        throw new CliError('INVALID_ARGUMENT', 'list subagent must be omitted or a non-empty string', 2);
+      }
+      const repository = input.repository ?? input.workspace;
+      if (!repository) throw new CliError('INVALID_ARGUMENT', 'list requires repository or workspace scope', 2);
+      return { method: 'task_list', params: {
+        ...(input.subagent !== undefined ? { subagent: input.subagent } : {}),
+        repository,
+        phase: input.phase ?? null,
+        outcome: input.outcome ?? null,
+        cursor: input.cursor ?? null,
+        limit: input.limit ?? 100,
+      } };
+    }
+    case 'send': {
+      rejectUnknownFields('send', input, new Set(['agent_id', 'message_id', 'content']));
+      return { method: 'task_message', params: {
+        agent_id: daemonTaskId(input.agent_id),
+        ...(input.message_id ? { message_id: input.message_id } : {}),
+        content: input.content,
+      } };
+    }
+    case 'respond': {
+      rejectUnknownFields('respond', input, new Set(['agent_id', 'request_id', 'decision', 'content']));
+      return { method: 'task_respond', params: { agent_id: daemonTaskId(input.agent_id), request_id: input.request_id, decision: input.decision, content: input.content ?? null } };
+    }
+    case 'cancel': return { method: 'task_cancel', params: { agent_id: daemonTaskId(input.agent_id) } };
+    case 'result': {
+      rejectUnknownFields('result', input, new Set(['agent_id', 'offset', 'limit']));
+      return { method: 'task_result', params: {
+        agent_id: daemonTaskId(input.agent_id),
+        offset: input.offset ?? 0,
+        limit: input.limit ?? MAX_RESULT_CHUNK_BYTES,
+      } };
+    }
+    case 'close': return { method: 'task_close', params: { agent_id: daemonTaskId(input.agent_id) } };
+    case 'observe': return { method: 'task_observe', params: { agent_id: daemonTaskId(input.agent_id) } };
+    default: throw new CliError('UNKNOWN_COMMAND', `unsupported daemon command: ${command}`, 2);
+  }
+}
+
+// The CLI projection is field-for-field identical to the MCP tool outputs:
+// both pass the daemon's public wire views through unchanged, except the
+// numeric agent_id coercion.
+function publicTask(task) {
+  return {
+    agent_id: publicTaskId(task.agent_id),
+    status: task.status,
+    session_id: task.session_id ?? null,
+    input_identity: task.input_identity ?? null,
+  };
+}
+
+function publicResult(result) {
+  if (result == null) return null;
+  return {
+    outcome: result.outcome,
+    final_text: result.final_text,
+    partial: result.partial,
+    offset: result.offset,
+    total_bytes: result.total_bytes,
+    next_offset: result.next_offset ?? null,
+    complete: result.complete,
+  };
+}
+
+export function projectDaemonResult(command, result) {
+  switch (command) {
+    case 'status': return result.status;
+    case 'drain': case 'drain-status': case 'drain-abort': case 'activate-ready': return result;
+    case 'agent-probe': return { evidence: result.evidence, status: result.status };
+    case 'agent-models': return result.catalog ?? result;
+    case 'create': case 'spawn':
+      return { agent_id: publicTaskId(result.task.agent_id), status: result.task.status };
+    case 'wait': {
+      const { result: taskResult, task, activity, kind: _kind, ...rest } = result;
+      return { ...rest, task: publicTask(task), activity, result: publicResult(taskResult) };
+    }
+    case 'list': return { tasks: result.tasks.map(publicTask), next_cursor: result.next_cursor ?? null };
+    case 'send': return { message_id: result.message_id, disposition: result.disposition };
+    case 'respond': return { ...result.outcome, policy_reason_code: result.outcome.policy_reason_code ?? null };
+    case 'cancel': case 'close': return { task: publicTask(result.task) };
+    case 'result': return { task: publicTask(result.task), result: publicResult(result.result) };
+    case 'observe': return { ...result.observation, agent_id: publicTaskId(result.observation.agent_id) };
+    default: throw new CliError('PROTOCOL_ERROR', `daemon returned an unsupported result for ${command}`);
+  }
+}
+
+export function callDaemon(socketPath, command, input, timeoutMs) {
+  const { method, params } = methodFor(command, input);
+  const effectiveTimeoutMs = timeoutMs ?? daemonTransportTimeoutMs(command, params);
+  const request_id = requestId();
+  const request = JSON.stringify({ request_id, method, params }) + '\n';
+  if (Buffer.byteLength(request, 'utf8') > MAX_FRAME_BYTES) {
+    throw new CliError('OVERSIZED', 'encoded RPC request exceeds frame cap', 2);
+  }
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath); let data = ''; let dataBytes = 0; let settled = false;
+    const finish = (fn, value) => { if (!settled) { settled = true; socket.destroy(); fn(value); } };
+    const timer = setTimeout(() => finish(reject, new CliError('SOCKET_UNAVAILABLE', `daemon socket unavailable: ${socketPath}`)), effectiveTimeoutMs);
+    socket.setEncoding('utf8');
+    // Keep the client write side open while the daemon processes the request.
+    // A half-close is interpreted by the daemon as peer disconnect, which
+    // would incorrectly interrupt long-polling wait requests.
+    socket.on('connect', () => socket.write(request));
+    socket.on('data', (chunk) => {
+      dataBytes += Buffer.byteLength(chunk, 'utf8');
+      if (dataBytes > MAX_RESPONSE_FRAME_BYTES) {
+        finish(reject, new CliError('OVERSIZED', 'encoded RPC response exceeds frame cap', 2));
+        return;
+      }
+      data += chunk;
+      const newline = data.indexOf('\n');
+      if (newline < 0) return;
+      const line = data.slice(0, newline);
+      if (!line) return;
+      clearTimeout(timer);
+      try {
+        const response = JSON.parse(line);
+        if (response.request_id !== request_id) finish(reject, new CliError('PROTOCOL_ERROR', 'daemon returned an RPC response for a different request'));
+        else if (response.outcome === 'error') { const daemon = response.error || {}; const error = new CliError(daemon.code || 'DAEMON_ERROR', daemon.message || 'daemon request failed'); error.agentId = daemon.active_agent_id == null ? undefined : publicTaskId(daemon.active_agent_id); error.daemonResponded = true; finish(reject, error); }
+        else if (response.outcome === 'success') {
+          try {
+            const projected = projectDaemonResult(command, response.result);
+            Object.defineProperty(projected, '__request_id', { value: request_id, enumerable: false });
+            finish(resolve, projected);
+          }
+          catch (error) { finish(reject, error instanceof CliError ? error : new CliError('PROTOCOL_ERROR', 'daemon returned an invalid public result')); }
+        }
+        else finish(reject, new CliError('PROTOCOL_ERROR', 'daemon returned an invalid RPC response'));
+      } catch { finish(reject, new CliError('PROTOCOL_ERROR', 'daemon returned invalid JSON')); }
+    });
+    socket.on('error', () => { clearTimeout(timer); finish(reject, new CliError('SOCKET_UNAVAILABLE', `daemon socket unavailable: ${socketPath}`)); });
+    socket.on('close', () => { clearTimeout(timer); if (!settled) finish(reject, new CliError('SOCKET_UNAVAILABLE', 'daemon closed the RPC connection')); });
+  });
+}
+
+export function parseDaemonInput(args) { try { return readJsonInput(args); } catch (error) { throw new CliError('INVALID_JSON', error.message, 2); } }

package/launchd/com.external-subagent.daemon.plist.template

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- Reference template for the managed daemon LaunchAgent. The installed
+     plist is generated by cli/install/service-macos.mjs with absolute payload
+     paths and the fixed GUI PATH; this file documents the managed shape and
+     is not read at runtime. -->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.external-subagent.daemon</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/&lt;npm-prefix&gt;/lib/node_modules/external-subagent/npm/native/darwin-arm64/external-subagentd</string>
+        <string>--database</string>
+        <string>&lt;home&gt;/Library/Application Support/external-subagent/external-subagent.sqlite3</string>
+        <string>--socket</string>
+        <string>&lt;home&gt;/Library/Application Support/external-subagent/external-subagent.sock</string>
+        <string>--runtime</string>
+        <string>/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs</string>
+        <string>--diagnostic-log</string>
+        <string>&lt;home&gt;/Library/Logs/external-subagent/daemon-error.log</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>&lt;home&gt;/Library/Logs/external-subagent/daemon.log</string>
+    <key>StandardErrorPath</key>
+    <string>&lt;home&gt;/Library/Logs/external-subagent/daemon-error.log</string>
+</dict>
+</plist>

package/npm/native/README.md

@@ -0,0 +1,19 @@
+# Native payload
+
+`npm/native/darwin-arm64/` carries the prebuilt native payload for the npm
+package: the `external-subagentd` daemon and the `external-subagent-mcp`
+stdio facade, plus the generated `payload.json` manifest (product version,
+platform, and per-file bytes/sha256/mode).
+
+The directory is build output, not source:
+
+```
+node scripts/release/build-native-payload.mjs           # build + manifest
+node scripts/release/build-native-payload.mjs --if-stale
+```
+
+Supported platforms install without compiling Rust; the installer verifies
+the payload manifest, digest, permissions (755), and Mach-O arm64 image
+before any `init` step runs.  There is no payload for other platforms in
+S05; unsupported platforms keep `help`/`version` working and reject business
+commands without writing HOME.

package/npm/native/darwin-arm64/payload.json

@@ -0,0 +1,20 @@
+{
+  "schema_version": 1,
+  "product": "external-subagent",
+  "version": "0.1.0",
+  "platform": "darwin-arm64",
+  "files": [
+    {
+      "name": "external-subagentd",
+      "bytes": 9185936,
+      "mode": "755",
+      "sha256": "31b8d52d84d3ffa04eb17d3ce7e6b57fd3f8d5d4e40572edc1996ef328893bd6"
+    },
+    {
+      "name": "external-subagent-mcp",
+      "bytes": 930896,
+      "mode": "755",
+      "sha256": "7da0c995d192fd166b9bd69c0b75bd02e3b3835bab2abbf48f32a47e01c38848"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "external-subagent",
+  "version": "0.1.0",
+  "description": "Manage bounded ZCode, DeepSeek Harness (DSH), and Codex subagent tasks through a local MCP service for any local host (Codex, ZCode, or a custom MCP client)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iBobbyTS/external-subagent.git"
+  },
+  "homepage": "https://github.com/iBobbyTS/external-subagent#readme",
+  "bugs": {
+    "url": "https://github.com/iBobbyTS/external-subagent/issues"
+  },
+  "keywords": [
+    "mcp",
+    "subagent",
+    "codex",
+    "zcode",
+    "dsh",
+    "agent-tasks"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "bin": {
+    "external-subagent": "bin/external-subagent.mjs",
+    "external-subagent-mcp": "bin/external-subagent-mcp.mjs",
+    "external-subagent-debug": "bin/external-subagent-debug.mjs",
+    "external-subagent-debug-mcp": "bin/external-subagent-debug-mcp.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "npm/native/",
+    "plugins/codex/external-subagent/",
+    "schema/",
+    "launchd/",
+    "scripts/release/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node cli/install/npm-hook.mjs",
+    "prepack": "node scripts/release/build-native-payload.mjs",
+    "postpack": "node scripts/release/check-native-tarball.mjs",
+    "prepublishOnly": "node scripts/release/check-native-tarball.mjs --staged",
+    "test:install": "node --test tests/install/*.test.mjs",
+    "check": "node --check bin/external-subagent.mjs && node --check bin/external-subagent-mcp.mjs && node --check bin/external-subagent-debug.mjs && node --check bin/external-subagent-debug-mcp.mjs && node --check cli/main.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/plugins/codex/external-subagent/.codex-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "external-subagent",
+  "version": "0.1.3",
+  "description": "Manage bounded external agent tasks through the external-subagent MCP service.",
+  "author": { "name": "external-subagent maintainers" },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "External Subagent",
+    "shortDescription": "Run bounded local external agent tasks.",
+    "longDescription": "Connects this host (Codex or ZCode) to the external-subagent lifecycle service for repository-scoped tasks.",
+    "developerName": "external-subagent maintainers",
+    "category": "Productivity",
+    "capabilities": ["Local MCP", "Durable tasks", "Agent tasks"],
+    "defaultPrompt": ["Check external-subagent status.", "Spawn a repository-scoped task.", "Review a complete task result."]
+  },
+  "mcpServers": "./.mcp.json"
+}

package/plugins/codex/external-subagent/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "external_subagent": {
+      "command": "__EXTERNAL_SUBAGENT_MCP_EXECUTABLE__",
+      "args": [],
+      "env": { "ZCODE_AGENTD_SOCKET": "__EXTERNAL_SUBAGENT_SOCKET__" }
+    }
+  }
+}

package/plugins/codex/external-subagent/hooks/audit-bash-result.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) raw += chunk;
+
+function boundedText(value, maxBytes = 1_048_576) {
+  if (typeof value !== 'string') return '';
+  const bytes = Buffer.from(value, 'utf8');
+  return bytes.length <= maxBytes ? value : bytes.subarray(0, maxBytes).toString('utf8');
+}
+
+try {
+  const input = JSON.parse(raw);
+  const tool = input?.tool_name ?? input?.toolName ?? '';
+  if (tool !== 'Bash') process.exit(0);
+
+  const toolInput = input?.tool_input ?? input?.input ?? {};
+  const command = String(toolInput?.command ?? '');
+  const cwd = String(input?.cwd ?? '');
+  const response = input?.tool_response ?? input?.toolResponse ?? {};
+  const stdout = boundedText(response?.stdout ?? response?.output ?? '');
+  const stderr = boundedText(response?.stderr ?? input?.error ?? '');
+  const record = {
+    schema: 'zcode-agent-bash-fact/v2',
+    at: new Date().toISOString(),
+    session_id: input?.session_id ?? input?.sessionId ?? null,
+    tool_use_id: input?.tool_use_id ?? input?.toolUseId ?? null,
+    hook_event_name: input?.hook_event_name ?? input?.hookEventName ?? null,
+    cwd_sha256: crypto.createHash('sha256').update(cwd).digest('hex'),
+    command_sha256: crypto.createHash('sha256').update(command).digest('hex'),
+    status_code: Number.isInteger(response?.status_code) ? response.status_code : (Number.isInteger(response?.exitCode) ? response.exitCode : null),
+    duration_ms: Number.isFinite(input?.duration_ms) ? Math.max(0, Math.floor(input.duration_ms))
+      : (Number.isFinite(response?.duration_ms) ? Math.max(0, Math.floor(response.duration_ms)) : null),
+    stdout_sha256: crypto.createHash('sha256').update(stdout).digest('hex'),
+    stderr_sha256: crypto.createHash('sha256').update(stderr).digest('hex'),
+    stdout_bytes_observed: Buffer.byteLength(stdout),
+    stderr_bytes_observed: Buffer.byteLength(stderr),
+    failed: Boolean(input?.error) || input?.hook_event_name === 'PostToolUseFailure' || input?.hookEventName === 'PostToolUseFailure',
+    permission_mode: ['build', 'edit', 'plan', 'yolo'].includes(process.env.ZCODE_PERMISSION_MODE || process.env.ZCODE_AGENT_PERMISSION_MODE)
+      ? (process.env.ZCODE_PERMISSION_MODE || process.env.ZCODE_AGENT_PERMISSION_MODE)
+      : null,
+  };
+
+  const dataRoot = process.env.ZCODE_PLUGIN_DATA;
+  if (!dataRoot) process.exit(0);
+  fs.mkdirSync(dataRoot, { recursive: true, mode: 0o700 });
+  const logPath = path.join(dataRoot, 'readonly-bash-audit.jsonl');
+  fs.appendFileSync(logPath, `${JSON.stringify(record)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'a' });
+} catch (error) {
+  process.stderr.write(`[zcode-agent-bash-audit] ${error instanceof Error ? error.message : String(error)}\n`);
+}

package/plugins/codex/external-subagent/hooks/check-agent-files.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { createAgentFileHookOutput, evaluateAgentFileInput } from '../lib/agent-file-policy.mjs';
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) raw += chunk;
+try {
+  const input = JSON.parse(raw);
+  // Hooks are optional and must not claim ordinary, unmanaged ZCode sessions.
+  if (process.env.ZCODE_AGENT_POLICY !== '1') process.exit(0);
+  process.stdout.write(`${JSON.stringify(createAgentFileHookOutput(evaluateAgentFileInput(input)))}\n`);
+} catch {
+  if (process.env.ZCODE_AGENT_POLICY !== '1') process.exit(0);
+  // Never echo input, paths, or parser details: hook failures are denied and redacted.
+  process.stdout.write(`${JSON.stringify(createAgentFileHookOutput({
+    decision: 'deny',
+    reason: 'zcode-agent-file-policy/v1.0.0: hook_internal_error',
+  }))}\n`);
+}