external-subagent 0.5.2 → 0.5.3

package/README.md

@@ -6,8 +6,9 @@ tools) and subagents (the execution targets that run the tasks) are two
 independent axes:
 
 - **Hosts** — Codex (`install-plugin codex` or `install-mcp`), ZCode
-  (`install-plugin zcode`), and any custom local MCP client that connects
-  directly to the facade without registration.
+  (`install-plugin zcode`), DSH (`install-plugin dsh --profile <name>`), and
+  any custom local MCP client that connects directly to the facade without
+  registration.
 - **Subagents** — ZCode, DeepSeek Harness (DSH), Codex, and Google
   Antigravity (`agy`), each routed through an internal adapter and subject to
   the per-subagent limitations listed in [docs/product.md](docs/product.md)
@@ -38,7 +39,8 @@ All four subagents are **disabled by default** and are enabled per name with
 `external-subagent agents enable <zcode|dsh|codex|agy>`: a successful local probe
 writes the configuration (no write on failure), and `dsh`/`codex`/`agy` need a
 daemon restart to take effect. ZCode admits all four permission modes
-(build/edit/plan/yolo) and rejects an explicit spawn `model`; DSH admits
+(build/edit/plan/yolo) and requires an explicit `provider/model` spawn
+selection; DSH admits
 `build` and strict `plan`, with model selection as explicit spawn model,
 configured default, then the native default, and its `build` mode admits a
 non-empty caller `write_manifest` through the guarded manifest-build
@@ -90,7 +92,8 @@ intentionally diverge; see
 ```
 npm install -g external-subagent     # stages package + payload only (macOS arm64, Linux x64)
 external-subagent init               # explicit: standalone daemon service only
-external-subagent install-plugin zcode   # optional host binding (or: install-plugin codex / install-mcp)
+external-subagent install-plugin zcode   # optional host binding (or: install-plugin codex /
+                                        # install-plugin dsh --profile web / install-mcp)
 ```
 
 Packing and publishing are gated by npm lifecycle scripts: `prepack` always
@@ -151,7 +154,7 @@ from the available set.
 |---|---|
 | `name` | Required, unique across files; trimmed, non-empty, at most 128 bytes |
 | `subagent` | `zcode`, `dsh`, `codex`, or `agy` |
-| `model` | Model token, named per target: `dsh` wants `provider:model`, `zcode` accepts `provider/model` or a bare token, `codex` and `agy` take a bare slug |
+| `model` | Model token, named per target: `dsh` wants `provider:model`, `zcode` requires `provider/model` (from the spawn request or a named profile; a bare token and omission are rejected), `codex` and `agy` take a bare slug |
 | `effort` | Effort token; some runtime models require one (for example `agy` rejects `gemini-3.8-flash` without `--effort`) and the spawn error surfaces the runtime's message verbatim |
 | `permission_mode` | `build`, `edit`, `plan`, or `yolo`; defaults to `build` when unset |
 | `developer_instructions` | Free-form instructions, delivered as described below |

package/bin/external-subagent-mcp.mjs

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { nativePlatform } from '../cli/install/layout.mjs';
+import { nativeExecutableName, nativePlatform } from '../cli/install/layout.mjs';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -18,8 +18,9 @@ export function mcpFacadePath(
   platform = nativePlatform() ?? `${process.platform}-${process.arch}`,
   debug = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug',
 ) {
+  const name = debug ? 'external-subagent-debug-mcp' : 'external-subagent-mcp';
   return path.join(packageRoot, 'npm', debug ? 'native-debug' : 'native', platform,
-    debug ? 'external-subagent-debug-mcp' : 'external-subagent-mcp');
+    nativeExecutableName(name, platform));
 }
 
 export function runMcpFacade() {

package/cli/commands/agents.mjs

@@ -90,13 +90,8 @@ export async function subagentsCommand(paths, input = {}, options = {}) {
     const result = await options.callDaemon(options.socket, 'agent-probe', { subagent: agent, through: 'local', scope });
     const local = result.evidence?.local;
     if (local?.state !== 'READY') throw new CliError('agent_probe_failed', `Cannot enable ${agent}: ${local?.reason ?? 'local runtime probe did not succeed'}`, 2);
-    const requiredVersion = result.status?.required_version;
-    if (agent === 'dsh' && (typeof requiredVersion !== 'string' || !requiredVersion.trim())) {
-      throw new CliError('agent_probe_failed', 'Cannot enable dsh: daemon did not report required_version; update and restart the daemon, then retry', 2);
-    }
-    if (requiredVersion != null && local.version !== requiredVersion) {
-      throw new CliError('agent_probe_failed', `Cannot enable ${agent}: expected version ${requiredVersion}, observed ${local.version ?? 'unknown'}; install the required runtime version and retry`, 2);
-    }
+    // Version differences are advisory (surfaced by status and failure
+    // instructions); enable records the observed version without rejecting it.
     const patch = { enabled: true, spawn_supported: true };
     if (agent !== 'zcode') {
       if (typeof local.runtime_path !== 'string' || !path.isAbsolute(local.runtime_path) || typeof local.version !== 'string' || !local.version.trim()) {
@@ -158,11 +153,11 @@ export async function subagentsCommand(paths, input = {}, options = {}) {
 }
 
 // Source compatibility for internal callers while the public CLI name is
-// `subagents`; wire-level agent fields remain S02's responsibility.
+// `subagents`; wire-level agent fields remain the daemon wire contract's responsibility.
 export const agentsCommand = subagentsCommand;
 export const parseAgentsArgs = parseSubagentsArgs;
 
-// The daemon wire contract is migrated by S02; the CLI already exposes the
+// The daemon wire contract is owned by the daemon; the CLI already exposes the
 // canonical execution-target name at its own boundary.
 function subagentView(value) {
   if (!value) return value;

package/cli/commands/config.mjs

@@ -96,7 +96,7 @@ export function parseConfigArgs(args) {
 // regenerates the service definition from the new config.  Only the file is
 // rewritten — launchd picks the environment up at its next load, so a running
 // daemon is never restarted or disturbed here.  The launchd plist is macOS
-// only; the Linux systemd unit is re-rendered by the S03 service backend, so a
+// only; the Linux systemd unit is re-rendered by the service backend, so a
 // Linux config write refreshes nothing yet instead of writing a plist to the
 // unit path.
 function refreshServiceDefinition(paths) {

package/cli/commands/daemon.mjs

@@ -28,11 +28,16 @@ export function localInstallStatus(paths, { verbose = false } = {}) {
     ? payload
     : { status: payload.status, platform: payload.platform, version: payload.version };
   // The service-definition path is the macOS LaunchAgent plist or the Linux
-  // systemd user unit (paths.mjs).  The reported field stays platform-truthful
+  // systemd user unit (paths.mjs).  Windows has no file-based definition (the
+  // SCM registration is the definition), so `launchAgent` is null there and
+  // must not reach fs.existsSync. The reported field stays platform-truthful
   // so a Linux install never reads as a launchd agent.
-  const serviceDefinition = platform() === 'darwin'
+  const currentPlatform = platform();
+  const serviceDefinition = currentPlatform === 'darwin'
     ? { launch_agent: fs.existsSync(paths.launchAgent) }
-    : { service_definition: fs.existsSync(paths.launchAgent) };
+    : currentPlatform === 'win32'
+      ? { service_definition: false }
+      : { service_definition: fs.existsSync(paths.launchAgent) };
   return {
     installed: fs.existsSync(paths.state),
     ...serviceDefinition,

package/cli/commands/maintenance.mjs

@@ -1,6 +1,10 @@
 import { backupData, purge, restoreData, uninstall as removeService } from '../maintenance.mjs';
 import { unregisterAllCodexHomes } from '../install/reconcile.mjs';
 import { uninstallZcodePlugin } from '../install/zcode.mjs';
+import { uninstallAllDshBindings } from '../install/dsh.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWrite, jsonBytes, readOptional } from '../fs-atomic.mjs';
 
 // Maintenance command coordination.  The ES-owned service is booted out and
 // its definition removed before any D08 claim is released: a bootout that
@@ -12,6 +16,149 @@ import { uninstallZcodePlugin } from '../install/zcode.mjs';
 // released the same way: the product-owned staging tree and its single
 // plugins.dirs entry go away together.
 
+// Event-bound legacy shapes. The retired installer wrote each script under
+// exactly these events and always placed the script as the single process
+// argument.
+const MANAGED_HOOK_EVENTS = {
+  PreToolUse: new Map([
+    ['guard-bash.mjs', 'Bash'],
+    ['check-agent-files.mjs', '^(Read|Grep|Glob|Write|Edit|Delete|Move)$'],
+  ]),
+  PostToolUse: new Map([['audit-bash-result.mjs', 'Bash']]),
+  PostToolUseFailure: new Map([['audit-bash-result.mjs', 'Bash']]),
+};
+const PROVENANCE_WRAPPER_KEYS = [
+  'effective_guard_wrapper_path',
+  'effective_audit_wrapper_path',
+  'effective_file_wrapper_path',
+];
+const POLICY_VERIFIER_NAME = 'external-subagent-policy-verifier';
+
+function exactWrapperPaths(provenance) {
+  const paths = new Set();
+  if (!provenance || typeof provenance !== 'object' || Array.isArray(provenance)) return paths;
+  for (const key of PROVENANCE_WRAPPER_KEYS) {
+    const value = provenance[key];
+    if (typeof value === 'string' && value.length > 0) paths.add(path.resolve(value));
+  }
+  return paths;
+}
+
+// A managed entry is exactly the installer's written shape: a process hook
+// whose script position (`args[0]`) is either a provenance-recorded exact
+// wrapper path or an event-bound legacy `<plugin root>/hooks/<managed
+// script>` with the matching matcher. Arguments after the script position
+// are data, never executable positions.
+function managedHookEntry(entry, exactPaths, managedScripts) {
+  if (!entry || typeof entry !== 'object' || !Array.isArray(entry.hooks)) return false;
+  const hooks = entry.hooks.filter((hook) => hook?.type === 'process' && Array.isArray(hook.args));
+  for (const hook of hooks) {
+    const script = hook.args[0];
+    if (typeof script === 'string' && exactPaths.has(path.resolve(script))) return true;
+  }
+  if (typeof entry.matcher !== 'string') return false;
+  for (const hook of hooks) {
+    const script = hook.args[0];
+    if (typeof script !== 'string') continue;
+    const expectedMatcher = managedScripts.get(path.basename(script));
+    if (expectedMatcher !== undefined
+      && path.basename(path.dirname(script)) === 'hooks'
+      && entry.matcher === expectedMatcher) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Only a genuinely absent record routes to the empty path. A real I/O read
+// failure propagates so the caller treats the config phase as failed and
+// retains the exact-path evidence a retry needs. An unparseable record cannot
+// contribute exact paths, so it is treated as absent.
+function readProvenance(file) {
+  if (typeof file !== 'string') return {};
+  const bytes = readOptional(file);
+  if (bytes === null) return {};
+  try {
+    const doc = JSON.parse(bytes.toString('utf8'));
+    return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {};
+  } catch {
+    return {};
+  }
+}
+
+function removeFile(file) {
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+// Inverse of the retired hook installer, bounded to the references it
+// actually wrote: recognized managed entries are removed from the three
+// event lists, while every foreign entry, unknown hooks key, and unrelated
+// top-level key stays untouched.  The write is atomic.  Afterwards the
+// provenance record and the verifier staged beside it are deleted — but only
+// when the config phase completed, so a failed read/parse/write retains the
+// exact-path evidence a retry needs.
+function removeManagedHooks(paths) {
+  const configPath = paths.zcodeConfig;
+  const provenancePath = paths.hookProvenance;
+  const result = {
+    config: configPath ?? null,
+    entries_removed: 0,
+    config_updated: false,
+    provenance_removed: false,
+    verifier_removed: false,
+  };
+  let configPhaseFailed = false;
+  try {
+    const exactPaths = exactWrapperPaths(readProvenance(provenancePath));
+    const bytes = typeof configPath === 'string' ? readOptional(configPath) : null;
+    if (bytes !== null) {
+      const config = JSON.parse(bytes.toString('utf8'));
+      const events = config?.hooks && typeof config.hooks === 'object' && !Array.isArray(config.hooks)
+        ? config.hooks.events
+        : undefined;
+      if (events && typeof events === 'object' && !Array.isArray(events)) {
+        let removed = 0;
+        for (const [event, managedScripts] of Object.entries(MANAGED_HOOK_EVENTS)) {
+          const entries = events[event];
+          if (!Array.isArray(entries)) continue;
+          const kept = entries.filter((entry) => !managedHookEntry(entry, exactPaths, managedScripts));
+          removed += entries.length - kept.length;
+          if (kept.length !== entries.length) events[event] = kept;
+        }
+        if (removed > 0) {
+          atomicWrite(configPath, jsonBytes(config));
+          result.entries_removed = removed;
+          result.config_updated = true;
+        }
+      }
+    }
+  } catch (error) {
+    configPhaseFailed = true;
+    result.error = { code: error?.code || 'ZCODE_HOOKS_CLEANUP_FAILED', message: error.message };
+  }
+  if (!configPhaseFailed) {
+    try {
+      if (typeof provenancePath === 'string') result.provenance_removed = removeFile(provenancePath);
+    } catch (error) {
+      result.error ??= { code: error?.code || 'ZCODE_HOOKS_CLEANUP_FAILED', message: error.message };
+    }
+    try {
+      if (typeof provenancePath === 'string') {
+        result.verifier_removed = removeFile(path.join(path.dirname(provenancePath), POLICY_VERIFIER_NAME));
+      }
+    } catch (error) {
+      result.error ??= { code: error?.code || 'ZCODE_HOOKS_CLEANUP_FAILED', message: error.message };
+    }
+  }
+  return result;
+}
+
 export function uninstall(paths, options = {}) {
   const removed = removeService(paths, options);
   const released = unregisterAllCodexHomes(paths);
@@ -21,7 +168,17 @@ export function uninstall(paths, options = {}) {
   try { zcode = uninstallZcodePlugin(paths); } catch (error) {
     zcode = { uninstalled: false, error: { code: error.code || 'ZCODE_BINDING_FAILED', message: error.message } };
   }
-  return { ...removed, codex_homes_unregistered: released.unregistered, zcode_binding: zcode };
+  // DSH bindings are released by scanning every profile's patch sentinel;
+  // the same per-item reporting posture as the codex homes release.
+  let dsh;
+  try { dsh = uninstallAllDshBindings(paths); } catch (error) {
+    dsh = { released: 0, error: { code: error.code || 'DSH_BINDING_RELEASE_FAILED', message: error.message } };
+  }
+  // Retained installations may still carry managed hooks pointing at the
+  // removed scripts.  Cleanup is bounded to recognized entries and reports
+  // its own failure without failing the rest of the uninstall.
+  const zcode_hooks = removeManagedHooks(paths);
+  return { ...removed, codex_homes_unregistered: released.unregistered, zcode_binding: zcode, dsh_bindings: dsh, zcode_hooks };
 }
 
 export { backupData, purge, restoreData };

package/cli/commands/plugin.mjs

@@ -1,6 +1,7 @@
 import { CliError } from '../errors.mjs';
 import { installMcp, installPlugin, uninstallPlugin } from '../install/codex.mjs';
 import { installZcodePlugin, uninstallZcodePlugin } from '../install/zcode.mjs';
+import { installDshPlugin, uninstallDshPlugin } from '../install/dsh.mjs';
 import { registerCodexHome, unregisterCodexHome } from '../install/reconcile.mjs';
 import { verifyPayload } from '../install/payload.mjs';
 
@@ -9,10 +10,12 @@ import { verifyPayload } from '../install/payload.mjs';
 // stages the plugin and goes through the official codex CLI, claiming the
 // Codex home in the D08 registry; zcode stages the same plugin into a
 // product-owned tree and registers it through the ZCode config's inline
-// plugin dirs.  The MCP TOML binding stays an explicit codex-only
-// alternative for hosts without plugin support.
+// plugin dirs; dsh appends one managed mcp-client entry to the profile's
+// cordis.patch.yml and stages the skill into the DSH user skill root.  The
+// MCP TOML binding stays an explicit codex-only alternative for hosts
+// without plugin support.
 
-const PLUGIN_HOSTS = ['codex', 'zcode'];
+const PLUGIN_HOSTS = ['codex', 'zcode', 'dsh'];
 
 function parseCommon(args, flags) {
   const options = {};
@@ -29,6 +32,16 @@ function parseCommon(args, flags) {
       if (!value || value.startsWith('--')) throw new CliError('INVALID_ARGUMENT', '--codex-home requires a value', 2);
       options.codexHome = value;
       index += 1;
+    } else if (arg === '--dsh-home') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new CliError('INVALID_ARGUMENT', '--dsh-home requires a value', 2);
+      options.dshHome = value;
+      index += 1;
+    } else if (arg === '--profile') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new CliError('INVALID_ARGUMENT', '--profile requires a value', 2);
+      options.profile = value;
+      index += 1;
     } else {
       throw new CliError('INVALID_ARGUMENT', `unsupported plugin option: ${arg}`, 2);
     }
@@ -45,8 +58,20 @@ export function pluginCommand(paths, args) {
   const installerOptions = withInstallerFlags(options);
   if (options.host === 'zcode') {
     if (options.codexHome) throw new CliError('INVALID_ARGUMENT', '--codex-home applies to the codex host only', 2);
+    if (options.dshHome) throw new CliError('INVALID_ARGUMENT', '--dsh-home applies to the dsh host only', 2);
+    if (options.profile) throw new CliError('INVALID_ARGUMENT', '--profile applies to the dsh host only', 2);
     return options.uninstall ? uninstallZcodePlugin(paths, installerOptions) : installZcodePlugin(paths, installerOptions);
   }
+  if (options.host === 'dsh') {
+    if (options.codexHome) throw new CliError('INVALID_ARGUMENT', '--codex-home applies to the codex host only', 2);
+    // installDshPlugin re-requires --profile, but failing here keeps the
+    // error at the CLI parsing boundary with the other flag-combination
+    // errors instead of deep inside the installer.
+    if (!options.profile) throw new CliError('INVALID_ARGUMENT', 'the dsh host requires --profile <name>', 2);
+    return options.uninstall ? uninstallDshPlugin(paths, installerOptions) : installDshPlugin(paths, installerOptions);
+  }
+  if (options.profile) throw new CliError('INVALID_ARGUMENT', '--profile applies to the dsh host only', 2);
+  if (options.dshHome) throw new CliError('INVALID_ARGUMENT', '--dsh-home applies to the dsh host only', 2);
   if (options.uninstall) {
     const result = uninstallPlugin(paths, installerOptions);
     if (!options.dry_run && result.uninstalled) {

package/cli/commands/tasks.mjs

@@ -114,7 +114,7 @@ function trimRust(value) {
 //      outside a string is therefore rejected iff `Number(token)` is not finite.
 //      This uses correctly-rounded IEEE rounding; serde_json's default
 //      accumulator can round to infinity within one ulp of `f64::MAX` (a
-//      recorded residual, see S02-HANDOFF).
+//      recorded residual).
 //   3. `JSON.parse` has no container-depth limit (it is iterative), while
 //      serde_json starts with `remaining_depth = 128` (de.rs:63) and
 //      `check_recursion` decrements before descending and errors when it reaches
@@ -344,6 +344,12 @@ function rustExtension(fileName) {
 // by `profilesDir` (an empty directory yields the bare name).
 function joinChild(dir, name) {
   if (dir === '') return name;
+  if (process.platform === 'win32') {
+    // Rust Path::join uses '\' on Windows and treats both separators as
+    // already-separated components.
+    if (dir.endsWith('/') || dir.endsWith('\\')) return dir + name;
+    return `${dir}\\${name}`;
+  }
   if (dir.endsWith('/')) return dir + name;
   return `${dir}/${name}`;
 }

package/cli/commands/update.mjs

@@ -1,5 +1,6 @@
 import { npmUpdateCoordination, reconcileCodexHomes } from '../install/reconcile.mjs';
 import { reconcileZcodeBinding } from '../install/zcode.mjs';
+import { reconcileDshBindings } from '../install/dsh.mjs';
 import { preflightUpdate, reconcileInstallation, updateInstallation } from '../install/update.mjs';
 import { callDaemon, canonicalDaemonCode } from '../rpc.mjs';
 import { CliError } from '../errors.mjs';
@@ -28,7 +29,16 @@ function partialHostSync(result) {
     const { error } = result.zcode;
     failures.push(`zcode: ${error ? `${error.code}: ${error.message}` : 'binding refresh failed'}`);
   }
-  return failures.length > 0 ? { zcodeFailed, failures } : null;
+  // DSH reconciles per profile; a bound-but-failed profile is a partial
+  // sync (retryable through reconcile), an absent binding is not.
+  const dshFailed = Array.isArray(result?.dsh?.profiles) && result.dsh.profiles.some((entry) => entry.status === 'failed');
+  if (dshFailed) {
+    for (const entry of result.dsh.profiles.filter((item) => item.status === 'failed')) {
+      const { error } = entry;
+      failures.push(`dsh ${entry.profile}: ${error ? `${error.code}: ${error.message}` : 'binding refresh failed'}`);
+    }
+  }
+  return failures.length > 0 ? { zcodeFailed, dshFailed, failures } : null;
 }
 
 export async function updateCommand(paths, args = [], daemon = {}) {
@@ -115,13 +125,14 @@ export async function updateCommand(paths, args = [], daemon = {}) {
     const serviceInstalled = typeof daemon.hasInstalledService === 'function' ? daemon.hasInstalledService(paths) : hasInstalledService(paths);
     const serviceDue = serviceInstalled && !daemon.skipServiceActivation;
     result = (reconciling && !coordinate)
-      ? { ...reconcileInstallation(paths, { cancelActive, yes }), homes: reconcileCodexHomes(paths), zcode: reconcileZcodeBinding(paths) }
+      ? { ...reconcileInstallation(paths, { cancelActive, yes }), homes: reconcileCodexHomes(paths), zcode: reconcileZcodeBinding(paths), dsh: reconcileDshBindings(paths) }
       : await (daemon.updateInstallation || updateInstallation)(paths, { version: requestedVersion, deferCodexSync: serviceDue });
-    // The zcode binding has neither a registry nor a service dependency, so
-    // it refreshes on every activation attempt — including service-less
-    // installs, where the codex homes sync runs inside updateInstallation
-    // instead of the service activation block below.
+    // The zcode and dsh bindings have neither a registry nor a service
+    // dependency, so they refresh on every activation attempt — including
+    // service-less installs, where the codex homes sync runs inside
+    // updateInstallation instead of the service activation block below.
     if (!result.zcode) result.zcode = reconcileZcodeBinding(paths);
+    if (!result.dsh) result.dsh = reconcileDshBindings(paths);
     if (!result || typeof result !== 'object' || result.phase !== 'active') {
       throw new Error(`installation update did not activate payload (phase=${result?.phase ?? 'none'})`);
     }
@@ -214,6 +225,6 @@ export async function updateCommand(paths, args = [], daemon = {}) {
   // error, the receipt, and the per-host registries the reconcile owners
   // already persisted — and the public reconcile command finishes the
   // remaining hosts idempotently.  The activation itself stays published.
-  throw new CliError(partialHosts.zcodeFailed ? 'ZCODE_SYNC_PARTIAL' : 'CODEX_SYNC_PARTIAL',
+  throw new CliError(partialHosts.zcodeFailed ? 'ZCODE_SYNC_PARTIAL' : (partialHosts.dshFailed ? 'DSH_SYNC_PARTIAL' : 'CODEX_SYNC_PARTIAL'),
     `activation completed at ${result?.active?.version || requestedVersion}, but host binding reconciliation is partial — ${partialHosts.failures.join('; ')}; run 'external-subagent reconcile' after fixing the listed hosts`);
 }