external-subagent 0.3.2 → 0.4.1

package/README.md

@@ -91,6 +91,52 @@ stale or missing binaries) and `postpack` runs the static tarball checks. A
 development checkout packs the same way (`npm pack` after `cargo` is
 available); see [docs/operations.md](docs/operations.md) for release checks.
 
+## Spawn profiles
+
+A spawn profile is a named JSON preset for the spawn inputs, stored as one
+JSON file per profile in the `profiles/` directory next to `config.json`
+(`~/Library/Application Support/external-subagent/profiles/` by default;
+`profile list` reports the exact path in use). Every `*.json` file in the
+directory is discovered by its `name` field; the same name defined in two
+files is rejected, and invalid files are reported as warnings and excluded
+from the available set.
+
+```json
+{
+  "name": "codex-yolo",
+  "subagent": "codex",
+  "model": "gpt-5",
+  "permission_mode": "yolo",
+  "developer_instructions": "Always reply in English."
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `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 |
+| `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 |
+
+`--profile` cannot be combined with `--subagent`, `--model`, `--effort`, or
+`--permission_mode`; put those in the profile JSON or omit `profile`. Fields
+left out of the profile fall back to the same defaults as an unprofiled
+spawn. `developer_instructions` rides the codex runtime's native
+`developerInstructions` channel when the effective subagent is `codex`; every
+other subagent receives it silently concatenated in front of the prompt:
+
+```
+Developer Instructions: {developer_instructions}
+----------
+{prompt}
+```
+
+Inspect what is loaded with `external-subagent profile list` and
+`external-subagent profile show <name>`; an empty `profile list` result
+carries a `hint` field with this format summary.
+
 ## Publishing
 
 Releases publish from CI via npm Trusted Publishing (OIDC): pushing a `vX.Y.Z`

package/cli/commands/config.mjs

@@ -9,6 +9,7 @@ import { launchAgentPlist } from '../install/service-macos.mjs';
 const CONFIG_INPUT_FIELDS = new Set(['operation', 'patch', 'key']);
 const GET_KEYS = new Set([
   'default_subagent',
+  'runtime_process_model',
   ...SUBAGENT_IDS.flatMap((agent) => [`subagents.${agent}.enabled`, `subagents.${agent}.spawn_supported`, `subagents.${agent}.default_model`, `subagents.${agent}.runtime_path`, `subagents.${agent}.home`, `subagents.${agent}.profile`, `subagents.${agent}.version`]),
 ]);
 const SET_KEYS = GET_KEYS;
@@ -37,6 +38,7 @@ function patchFor(key, value) {
 function unsetPatch(key) {
   if (!SET_KEYS.has(key)) throw new CliError('INVALID_ARGUMENT', `unsupported config key: ${key}`, 2);
   if (key === 'default_subagent') return { default_subagent: null };
+  if (key === 'runtime_process_model') return { runtime_process_model: 'auto' };
   const [, agent, field] = key.split('.');
   const defaults = {
     enabled: false,

package/cli/commands/tasks.mjs

@@ -1,7 +1,10 @@
+import fs from 'node:fs';
 import { CliError } from '../errors.mjs';
+import { profilesDir } from '../paths.mjs';
 
-const SPAWN_FIELDS = new Set(['subagent', 'repository', 'permission_mode', 'prompt', 'model', 'effort', 'write_manifest']);
+const SPAWN_FIELDS = new Set(['profile', 'subagent', 'repository', 'permission_mode', 'prompt', 'model', 'effort', 'write_manifest']);
 const FLAG_FIELDS = new Map([
+  ['--profile', 'profile'],
   ['--subagent', 'subagent'],
   ['--repository', 'repository'],
   ['--prompt', 'prompt'],
@@ -10,6 +13,8 @@ const FLAG_FIELDS = new Map([
   ['--effort', 'effort'],
 ]);
 
+const PROFILE_MUTEX_ERROR = 'profile cannot be combined with subagent, permission_mode, model, or effort; specify these in the profile JSON or omit profile';
+
 function flagValue(args, option) {
   const value = args.shift();
   if (value === undefined || value === '' || value.startsWith('--')) {
@@ -32,6 +37,11 @@ export function parseSpawnArgs(args) {
     if (Object.hasOwn(input, field)) throw new CliError('INVALID_ARGUMENT', `${option} may be provided only once`, 2);
     input[field] = flagValue(remaining, option);
   }
+  if (Object.hasOwn(input, 'profile')) {
+    if (Object.hasOwn(input, 'subagent') || Object.hasOwn(input, 'permission_mode') || Object.hasOwn(input, 'model') || Object.hasOwn(input, 'effort')) {
+      throw new CliError('INVALID_ARGUMENT', PROFILE_MUTEX_ERROR, 2);
+    }
+  }
   if (!Object.hasOwn(input, 'repository')) throw new CliError('INVALID_ARGUMENT', '--repository is required', 2);
   if (!Object.hasOwn(input, 'prompt')) throw new CliError('INVALID_ARGUMENT', '--prompt is required', 2);
   return prepareSpawnInput(input);
@@ -42,6 +52,17 @@ export function prepareSpawnInput(input) {
   for (const key of Object.keys(input)) {
     if (!SPAWN_FIELDS.has(key)) throw new CliError('INVALID_ARGUMENT', `spawn contains unsupported field: ${key}`, 2);
   }
+  if (Object.prototype.hasOwnProperty.call(input, 'profile') && input.profile === null) {
+    throw new CliError('INVALID_ARGUMENT', 'profile must be omitted or a non-null profile name; null is invalid', 2);
+  }
+  if (input.profile !== undefined && (typeof input.profile !== 'string' || input.profile.length === 0)) {
+    throw new CliError('INVALID_ARGUMENT', 'profile must be a non-empty string', 2);
+  }
+  if (input.profile !== undefined) {
+    if (input.subagent !== undefined || input.permission_mode !== undefined || input.model !== undefined || input.effort !== undefined) {
+      throw new CliError('INVALID_ARGUMENT', PROFILE_MUTEX_ERROR, 2);
+    }
+  }
   if (Object.prototype.hasOwnProperty.call(input, 'subagent') && input.subagent === null) {
     throw new CliError('INVALID_ARGUMENT', 'subagent must be omitted or a supported subagent id; null is invalid', 2);
   }
@@ -62,3 +83,501 @@ export function prepareSpawnInput(input) {
   }
   return { ...input };
 }
+
+// Rust `str::trim` strips the Unicode White_Space property (which includes
+// U+0085 NEL and U+00A0 NBSP) but NOT U+FEFF, whereas JavaScript `String.trim`
+// strips U+FEFF and leaves U+0085. Name identity must match the daemon's
+// `raw.name.trim()`, so trim against Rust's exact character set.
+const RUST_WHITESPACE = /[\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/u;
+
+function trimRust(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && RUST_WHITESPACE.test(value[start])) start += 1;
+  while (end > start && RUST_WHITESPACE.test(value[end - 1])) end -= 1;
+  return value.slice(start, end);
+}
+
+// A profile file is strict JSON, and the scanner must reproduce the daemon's
+// `serde_json` decisions. `JSON.parse` differs from serde_json on three points
+// that matter here, so the raw document text is validated *before* parsing.
+// Validating the text (rather than the collapsed object) makes duplicate-key
+// shadowing structurally irrelevant: a shadowed bad value is still visible.
+//   1. lone surrogate escapes (`"\uD800"`) are accepted by `JSON.parse` but
+//      rejected by serde_json, so every `\u` escape in a string is paired here
+//      (high D800-DBFF immediately followed by low DC00-DFFF) and an unpaired
+//      escape rejects the whole document;
+//   2. `JSON.parse` accepts lossless integer literals of any magnitude, while
+//      serde_json parses an integer that does not fit `u64`/`i64` as an `f64`
+//      and rejects the document only when that conversion is infinite (de.rs
+//      `parse_exponent_overflow` / `f64_long_from_parts`); every number literal
+//      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).
+//   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
+//      zero (de.rs:1372-1387); the 128th nested `{`/`[` is rejected, so at most
+//      127 containers may nest.
+// A leading UTF-8 BOM is also stripped by `TextDecoder` unless `ignoreBOM` is
+// set, and serde_json rejects a BOM; `scanProfilesDir` therefore preserves the
+// BOM so that `JSON.parse` fails exactly like serde_json.
+const PROFILE_FIELDS = ['name', 'subagent', 'permission_mode', 'model', 'effort', 'developer_instructions'];
+
+// Match a complete JSON number literal (RFC 8259) at the sticky lastIndex.
+const JSON_NUMBER = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
+
+function decodeHex4(text, index) {
+  const hex = text.slice(index, index + 4);
+  if (!/^[0-9a-fA-F]{4}$/u.test(hex)) return null;
+  return parseInt(hex, 16);
+}
+
+// Validate the raw JSON text against serde_json's lexical rules and recursion
+// limit that `JSON.parse` does not enforce. Returns a diagnostic fragment, or
+// null when the text is acceptable. Structural syntax errors are left to
+// `JSON.parse`; this walk only needs to track string/escape state so that
+// braces, digits and `\u` escapes are interpreted in the right context.
+function rawJsonDiagnostic(text) {
+  let inString = false;
+  let depth = 0;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (inString) {
+      if (ch === '"') {
+        inString = false;
+        i += 1;
+        continue;
+      }
+      if (ch === '\\') {
+        const esc = text[i + 1];
+        if (esc === 'u') {
+          const code = decodeHex4(text, i + 2);
+          if (code === null) {
+            // Malformed escape: let JSON.parse report the syntax error.
+            i += 2;
+            continue;
+          }
+          if (code >= 0xd800 && code <= 0xdbff) {
+            let paired = false;
+            if (text[i + 6] === '\\' && text[i + 7] === 'u') {
+              const low = decodeHex4(text, i + 8);
+              paired = low !== null && low >= 0xdc00 && low <= 0xdfff;
+            }
+            if (!paired) return 'lone surrogate code point';
+            i += 12; // consume both escapes of a valid surrogate pair
+            continue;
+          }
+          if (code >= 0xdc00 && code <= 0xdfff) return 'lone surrogate code point';
+          i += 6;
+          continue;
+        }
+        // \" \\ \/ \b \f \n \r \t: an escaped backslash never starts a `\u`.
+        i += 2;
+        continue;
+      }
+      i += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      i += 1;
+      continue;
+    }
+    if (ch === '{' || ch === '[') {
+      depth += 1;
+      if (depth >= 128) return 'recursion limit exceeded';
+      i += 1;
+      continue;
+    }
+    if (ch === '}' || ch === ']') {
+      if (depth > 0) depth -= 1;
+      i += 1;
+      continue;
+    }
+    if (ch === '-' || (ch >= '0' && ch <= '9')) {
+      JSON_NUMBER.lastIndex = i;
+      const match = JSON_NUMBER.exec(text);
+      if (match !== null) {
+        if (!Number.isFinite(Number(match[0]))) return `number out of range: ${match[0]}`;
+        i += match[0].length;
+        continue;
+      }
+    }
+    i += 1;
+  }
+  return null;
+}
+
+// A decoded astral character is a legitimate UTF-16 surrogate pair in a JS
+// string; an unpaired code unit is a lone surrogate.
+function containsLoneSurrogate(text) {
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = text.charCodeAt(i + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return true;
+      i += 1; // consume the matching low surrogate of a valid pair
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Iterative traversal (never recursive) so an arbitrarily deep decoded value
+// can never raise a `RangeError`; the raw depth gate already rejects documents
+// deeper than serde_json's limit before `JSON.parse` runs.
+function hasLoneSurrogate(value) {
+  const stack = [value];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (typeof current === 'string') {
+      if (containsLoneSurrogate(current)) return true;
+      continue;
+    }
+    if (Array.isArray(current)) {
+      for (const entry of current) stack.push(entry);
+      continue;
+    }
+    if (current !== null && typeof current === 'object') {
+      for (const [key, entry] of Object.entries(current)) {
+        if (containsLoneSurrogate(key)) return true;
+        stack.push(entry);
+      }
+    }
+  }
+  return false;
+}
+
+function invalidJson(diagnostic) {
+  return { name: null, rawName: null, valid: false, syntaxValid: false, errors: [`invalid JSON: ${diagnostic}`] };
+}
+
+// Scan one profile document. `name` is the authoritative owner identity used
+// for duplicate detection and mirrors the daemon's `loose_top_level_name`: a
+// document that parses as JSON, has a plain-object top level, and a string
+// `name` owns that name (trimmed, non-empty, at most 128 bytes, no NUL) even
+// when the profile shape is otherwise invalid. `valid` additionally requires the
+// canonical `RawProfile` shape (only the six known fields; a string `name`; each
+// optional field a string or null) and a usable name. Field *value* validation
+// (for example the permission_mode enum) is deliberately left to the daemon.
+export function scanProfileJson(content, filePath = '<unknown>') {
+  const rawDiagnostic = rawJsonDiagnostic(content);
+  if (rawDiagnostic !== null) return invalidJson(`${rawDiagnostic} in ${filePath}`);
+
+  let value;
+  try {
+    value = JSON.parse(content);
+  } catch (err) {
+    return invalidJson(err.message);
+  }
+
+  if (hasLoneSurrogate(value)) {
+    return invalidJson(`lone surrogate code point in ${filePath}`);
+  }
+
+  const isObject = value !== null && typeof value === 'object' && !Array.isArray(value);
+
+  let name = null;
+  if (isObject && typeof value.name === 'string') {
+    const raw = value.name;
+    const trimmed = trimRust(raw);
+    if (trimmed.length > 0 && Buffer.byteLength(raw, 'utf8') <= 128 && !raw.includes('\0')) {
+      name = trimmed;
+    }
+  }
+
+  const errors = [];
+  let shapeValid = true;
+
+  if (!isObject) {
+    errors.push('top-level value must be an object');
+    shapeValid = false;
+  } else {
+    for (const key of Object.keys(value)) {
+      if (!PROFILE_FIELDS.includes(key)) {
+        errors.push(`unknown top-level key '${key}'`);
+        shapeValid = false;
+      }
+    }
+    if (!Object.hasOwn(value, 'name')) {
+      errors.push("missing required field 'name'");
+      shapeValid = false;
+    } else if (typeof value.name !== 'string') {
+      errors.push("field 'name': must be a string");
+      shapeValid = false;
+    }
+    for (const key of PROFILE_FIELDS) {
+      if (key === 'name' || !Object.hasOwn(value, key)) continue;
+      const fieldValue = value[key];
+      if (fieldValue !== null && typeof fieldValue !== 'string') {
+        errors.push(`field '${key}': must be a string`);
+        shapeValid = false;
+      }
+    }
+    if (shapeValid && name === null && typeof value.name === 'string') {
+      const raw = value.name;
+      if (trimRust(raw).length === 0) errors.push("field 'name': cannot be empty");
+      else if (Buffer.byteLength(raw, 'utf8') > 128) errors.push("field 'name': exceeds 128 bytes");
+      else errors.push("field 'name': cannot contain NUL byte");
+    }
+  }
+
+  return { name, rawName: name, valid: shapeValid && name !== null, syntaxValid: true, errors };
+}
+
+// Rust `Path::extension()` semantics for candidate selection: the extension is
+// derived from the file name only and is absent when the name has no dot or
+// begins with a dot and has no further dot, so a file named exactly ".json" is
+// not a JSON candidate. Comparison stays case-sensitive.
+function rustExtension(fileName) {
+  const dot = fileName.lastIndexOf('.');
+  if (dot <= 0) return null;
+  return fileName.slice(dot + 1);
+}
+
+// Build a child path by string concatenation, never `path.join`, which
+// lexically folds `..` away. Mirrors Rust `Path::join` for the shapes produced
+// by `profilesDir` (an empty directory yields the bare name).
+function joinChild(dir, name) {
+  if (dir === '') return name;
+  if (dir.endsWith('/')) return dir + name;
+  return `${dir}/${name}`;
+}
+
+export function scanProfilesDir(dir) {
+  const profiles = new Map();
+  const fileErrors = [];
+  const nameOwners = new Map();
+
+  if (!fs.existsSync(dir)) {
+    return {
+      exists: false,
+      directory: dir,
+      profiles,
+      availableNames: [],
+      warnings: fileErrors,
+      duplicates: new Map(),
+    };
+  }
+
+  let entries = [];
+  try {
+    const dirEntries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of dirEntries) {
+      // Match the daemon's candidate selection exactly: `Path::extension()`
+      // yields "json" (case-sensitive) from the file name, so a file named
+      // exactly ".json" has no extension and is never a candidate.
+      if (rustExtension(entry.name) !== 'json') continue;
+      const full = joinChild(dir, entry.name);
+      // The daemon selects candidates with `Path::is_file()`, which follows
+      // symbolic links; `Dirent.isFile()` does not. Use stat, and silently
+      // skip entries that stat cannot resolve (e.g. dangling links), matching
+      // `is_file() == false`.
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.isFile()) entries.push(full);
+    }
+  } catch (err) {
+    fileErrors.push({
+      file: dir,
+      diagnostic: `profile directory '${dir}' is unreadable: ${err.message}`,
+    });
+    return {
+      exists: true,
+      directory: dir,
+      profiles,
+      availableNames: [],
+      warnings: fileErrors,
+      duplicates: new Map(),
+    };
+  }
+
+  entries.sort();
+
+  const candidates = [];
+
+  for (const filePath of entries) {
+    let content;
+    try {
+      // Read raw bytes and decode strictly: the daemon uses
+      // `fs::read_to_string`, which fails on invalid UTF-8 and skips the file
+      // without registering a name owner. `readFileSync(path, 'utf8')` would
+      // instead substitute U+FFFD and wrongly accept the file. `ignoreBOM: true`
+      // keeps a leading BOM in the decoded string so `JSON.parse` rejects it,
+      // matching serde_json; the default decoder would silently strip it.
+      const bytes = fs.readFileSync(filePath);
+      content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch (err) {
+      fileErrors.push({
+        file: filePath,
+        diagnostic: `profile file '${filePath}' is unreadable: ${err.message}`,
+      });
+      continue;
+    }
+
+    const res = scanProfileJson(content, filePath);
+    if (res.name) {
+      if (!nameOwners.has(res.name)) nameOwners.set(res.name, []);
+      nameOwners.get(res.name).push(filePath);
+    }
+
+    if (res.valid) {
+      candidates.push({ name: res.name, filePath, content });
+    } else {
+      fileErrors.push({
+        file: filePath,
+        profileName: res.name || null,
+        diagnostic: `profile file '${filePath}' is invalid: ${res.errors.join('; ')}`,
+      });
+    }
+  }
+
+  for (const candidate of candidates) {
+    const owners = nameOwners.get(candidate.name) || [];
+    if (owners.length > 1) {
+      const other = owners.find((p) => p !== candidate.filePath);
+      fileErrors.push({
+        file: candidate.filePath,
+        profileName: candidate.name,
+        diagnostic: `profile file '${candidate.filePath}' is invalid: duplicate profile name '${candidate.name}' already defined in '${other}'`,
+      });
+    } else {
+      profiles.set(candidate.name, candidate);
+    }
+  }
+
+  for (const [name, owners] of nameOwners.entries()) {
+    if (owners.length > 1) {
+      for (const owner of owners) {
+        const hasDupDiag = fileErrors.some((w) => w.file === owner && w.diagnostic.includes('duplicate profile name'));
+        if (!hasDupDiag) {
+          const other = owners.find((p) => p !== owner);
+          fileErrors.push({
+            file: owner,
+            profileName: name,
+            diagnostic: `profile file '${owner}' is invalid: duplicate profile name '${name}' already defined in '${other}'`,
+          });
+        }
+      }
+    }
+  }
+
+  const availableNames = Array.from(profiles.keys()).sort();
+  const duplicates = new Map([...nameOwners.entries()].filter(([, v]) => v.length > 1));
+
+  return {
+    exists: true,
+    directory: dir,
+    profiles,
+    availableNames,
+    warnings: fileErrors,
+    duplicates,
+  };
+}
+
+export function parseProfileArgs(args) {
+  if (!args || args.length === 0) throw new CliError('INVALID_ARGUMENT', 'usage: profile list | profile show <name>', 2);
+  const [operation, ...rest] = args;
+  if (operation === 'list') {
+    if (rest.length !== 0) throw new CliError('INVALID_ARGUMENT', 'usage: profile list', 2);
+    return { operation: 'list' };
+  }
+  if (operation === 'show') {
+    if (rest.length !== 1 || !rest[0] || rest[0].startsWith('--')) {
+      throw new CliError('INVALID_ARGUMENT', 'usage: profile show <name>', 2);
+    }
+    return { operation: 'show', name: rest[0] };
+  }
+  throw new CliError('INVALID_ARGUMENT', `unsupported profile operation: ${operation}`, 2);
+}
+
+// Attached to `profile list` only when no usable profile exists, so a fresh
+// installation sees the format reference instead of an unexplained empty list.
+const EMPTY_PROFILES_HINT = 'no profiles found; create one JSON file per profile in this directory, '
+  + 'e.g. {"name":"codex-yolo","subagent":"codex","model":"gpt-5","permission_mode":"yolo"}; '
+  + 'fields: name (required), subagent, model, effort, permission_mode (build|edit|plan|yolo), '
+  + 'developer_instructions; see the "Spawn profiles" section of README.md';
+
+export function profileCommand(paths, inputOrArgs, env = process.env) {
+  const input = Array.isArray(inputOrArgs) ? parseProfileArgs(inputOrArgs) : inputOrArgs;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new CliError('INVALID_ARGUMENT', 'profile input must be an object', 2);
+  }
+  // Resolution is a pure function of the injected paths/env; there is no
+  // test-only production branch keyed on os.homedir().
+  const dir = profilesDir(env, paths?.home);
+
+  if (input.operation === 'list') {
+    if (dir === null) {
+      return {
+        operation: 'list',
+        directory: null,
+        profiles: [],
+        warnings: [],
+        message: 'profiles are disabled: the configuration path environment variable is exported empty',
+      };
+    }
+    const scanned = scanProfilesDir(dir);
+    if (!scanned.exists) {
+      return {
+        operation: 'list',
+        directory: dir,
+        profiles: [],
+        warnings: [],
+        message: `profiles directory does not exist: ${dir}`,
+        hint: EMPTY_PROFILES_HINT,
+      };
+    }
+    return {
+      operation: 'list',
+      directory: dir,
+      profiles: scanned.availableNames,
+      warnings: scanned.warnings.map((w) => ({ file: w.file, diagnostic: w.diagnostic })),
+      ...(scanned.availableNames.length === 0 ? { hint: EMPTY_PROFILES_HINT } : {}),
+    };
+  }
+
+  if (input.operation === 'show') {
+    const name = input.name;
+    if (!name || typeof name !== 'string') throw new CliError('INVALID_ARGUMENT', 'usage: profile show <name>', 2);
+    if (dir === null) throw new CliError('INVALID_ARGUMENT', `profile '${name}' not found; available profiles: none`, 2);
+    const scanned = scanProfilesDir(dir);
+    if (!scanned.exists) {
+      throw new CliError('INVALID_ARGUMENT', `profile '${name}' not found; available profiles: none`, 2);
+    }
+    if (scanned.duplicates.has(name)) {
+      const files = scanned.duplicates.get(name);
+      throw new CliError('INVALID_ARGUMENT', `profile '${name}' is ambiguous; defined in multiple files: ${files.join(', ')}`, 2);
+    }
+    if (scanned.profiles.has(name)) {
+      const profile = scanned.profiles.get(name);
+      return {
+        operation: 'show',
+        name,
+        file: profile.filePath,
+        content: profile.content,
+        warnings: scanned.warnings.map((w) => ({ file: w.file, diagnostic: w.diagnostic })),
+      };
+    }
+    const availableList = scanned.availableNames.length > 0 ? `[${scanned.availableNames.join(', ')}]` : 'none';
+    const matchedInvalid = scanned.warnings.find((w) => w.profileName === name);
+    if (matchedInvalid) {
+      throw new CliError('INVALID_ARGUMENT', `${matchedInvalid.diagnostic}; available profiles: ${availableList}`, 2);
+    }
+    if (scanned.warnings.length > 0) {
+      const details = scanned.warnings.map((w) => w.diagnostic).join('; ');
+      throw new CliError('INVALID_ARGUMENT', `profile '${name}' not found (directory contains invalid files: ${details}); available profiles: ${availableList}`, 2);
+    }
+    throw new CliError('INVALID_ARGUMENT', `profile '${name}' not found; available profiles: ${availableList}`, 2);
+  }
+
+  throw new CliError('INVALID_ARGUMENT', `unsupported profile operation: ${input.operation}`, 2);
+}

package/cli/config/schema.mjs

@@ -2,7 +2,8 @@ import { CliError } from '../errors.mjs';
 
 export const CONFIG_SCHEMA_VERSION = 2;
 export const SUBAGENT_IDS = Object.freeze(['zcode', 'dsh', 'codex', 'agy']);
-const CONFIG_FIELDS = new Set(['schema_version', 'revision', 'default_subagent', 'subagents']);
+export const RUNTIME_PROCESS_MODELS = Object.freeze(['auto', 'detached', 'attached']);
+const CONFIG_FIELDS = new Set(['schema_version', 'revision', 'default_subagent', 'subagents', 'runtime_process_model']);
 const AGENT_FIELDS = new Set(['enabled', 'spawn_supported', 'default_model', 'runtime_path', 'home', 'profile', 'version']);
 
 function plainObject(value) {
@@ -20,6 +21,7 @@ export function defaultConfig() {
     schema_version: CONFIG_SCHEMA_VERSION,
     revision: 0,
     default_subagent: null,
+    runtime_process_model: 'auto',
     subagents: {
       zcode: { enabled: false, spawn_supported: false, default_model: null },
       dsh: { enabled: false, spawn_supported: false, default_model: null, runtime_path: null, home: null, profile: null, version: null },
@@ -52,8 +54,10 @@ export function validateConfig(input) {
   if (input.schema_version !== undefined && input.schema_version !== CONFIG_SCHEMA_VERSION) throw new CliError('CONFIG_INVALID', 'unsupported config schema version', 2);
   if (input.revision !== undefined && (!Number.isInteger(input.revision) || input.revision < 0)) throw new CliError('CONFIG_INVALID', 'revision must be a non-negative integer', 2);
   if (input.default_subagent !== undefined && input.default_subagent !== null && !SUBAGENT_IDS.includes(input.default_subagent)) throw new CliError('CONFIG_INVALID', 'default_subagent is unknown', 2);
+  if (input.runtime_process_model !== undefined && !RUNTIME_PROCESS_MODELS.includes(input.runtime_process_model)) throw new CliError('CONFIG_INVALID', `runtime_process_model must be one of ${RUNTIME_PROCESS_MODELS.join(', ')}`, 2);
   config.revision = input.revision ?? 0;
   config.default_subagent = input.default_subagent ?? null;
+  config.runtime_process_model = input.runtime_process_model ?? 'auto';
   if (input.subagents !== undefined && !plainObject(input.subagents)) throw new CliError('CONFIG_INVALID', 'subagents must be an object', 2);
   for (const agent of Object.keys(input.subagents || {})) {
     if (!SUBAGENT_IDS.includes(agent)) throw new CliError('CONFIG_INVALID', `subagents contains unknown subagent: ${agent}`, 2);

package/cli/constants.mjs

@@ -8,7 +8,7 @@ const IS_DEBUG_VARIANT = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug';
 
 export const PRODUCT_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug' : 'external-subagent';
 export const PRODUCT_ID = IS_DEBUG_VARIANT ? 'external_subagent_debug' : 'external_subagent';
-export const VERSION = '0.3.2';
+export const VERSION = '0.4.1';
 export const LAUNCH_AGENT_LABEL = IS_DEBUG_VARIANT ? 'com.external-subagent-debug.daemon' : 'com.external-subagent.daemon';
 export const DAEMON_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debugd' : 'external-subagentd';
 export const MCP_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug-mcp' : 'external-subagent-mcp';

package/cli/main.mjs

@@ -15,10 +15,10 @@ import { callDaemon, parseDaemonInput } from './rpc.mjs';
 import { configCommand } from './commands/config.mjs';
 import { parseConfigArgs } from './commands/config.mjs';
 import { subagentsCommand, parseSubagentsArgs } from './commands/agents.mjs';
-import { parseSpawnArgs, prepareSpawnInput } from './commands/tasks.mjs';
+import { parseProfileArgs, parseSpawnArgs, prepareSpawnInput, profileCommand } from './commands/tasks.mjs';
 
-const HELP = `external-subagent ${VERSION}\n\nUsage: external-subagent <command> [options]\n\nCommands:\n  help, version               Show basic product information\n  init [--dry-run] [--resume] [--install-hooks] [--skip-service-start]\n                             Install the standalone daemon service only; bind a\n                             host afterwards with install-plugin or install-mcp\n  hooks install [--dry-run]  Install ZCode policy hooks explicitly\n  install-plugin [codex|zcode] [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the managed host plugin (MCP + skill);\n                             the host defaults to codex, --codex-home is codex-only\n  install-mcp [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the direct Codex MCP TOML binding\n  status, diagnose            Inspect local service and runtime state\n  start, stop                 Bootstrap or boot out the daemon LaunchAgent\n  backup --output <dir>       Back up retained product data\n  restore --input <dir>       Verify and restore product data\n  uninstall                   Release Codex/ZCode bindings; remove service registration; retain data\n  purge --yes                 Explicitly delete new product data\n`;
-const DAEMON_HELP = `  config get [key] | config set <key> <value>\n  subagents list | subagents status [subagent] | subagents probe/models [subagent]\n  create/spawn, wait, list, send, respond, cancel, result, close, observe\n                             Daemon calls accept --json '<object>' or JSON stdin\n                             list JSON requires repository (workspace is an alias)\n                             observe JSON requires only agent_id\n`;
+const HELP = `external-subagent ${VERSION}\n\nUsage: external-subagent <command> [options]\n\nCommands:\n  help, version               Show basic product information\n  init [--dry-run] [--resume] [--install-hooks] [--skip-service-start]\n                             Install the standalone daemon service only; bind a\n                             host afterwards with install-plugin or install-mcp\n  hooks install [--dry-run]  Install ZCode policy hooks explicitly\n  install-plugin [codex|zcode] [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the managed host plugin (MCP + skill);\n                             the host defaults to codex, --codex-home is codex-only\n  install-mcp [--dry-run|--uninstall] [--codex-home <path>]\n                             Install or remove the direct Codex MCP TOML binding\n  status, diagnose            Inspect local service and runtime state\n  start, stop                 Bootstrap or boot out the daemon LaunchAgent\n  profile list | profile show <name>\n                             Inspect global spawn profiles (profiles/*.json);\n                             invalid files are reported as path-based warnings,\n                             and warned or duplicate files are excluded from the\n                             available name set\n  backup --output <dir>       Back up retained product data\n  restore --input <dir>       Verify and restore product data\n  uninstall                   Release Codex/ZCode bindings; remove service registration; retain data\n  purge --yes                 Explicitly delete new product data\n`;
+const DAEMON_HELP = `  config get [key] | config set <key> <value>\n  subagents list | subagents status [subagent] | subagents probe/models [subagent]\n  create/spawn [--profile <name>], wait, list, send, respond, cancel, result, close, observe\n                             Daemon calls accept --json '<object>' or JSON stdin\n                             list JSON requires repository (workspace is an alias)\n                             observe JSON requires only agent_id\n`;
 
 function structuredInput(args, parser) {
   return args.length > 0 && !args[0].startsWith('--') ? parser(args) : parseDaemonInput(args);
@@ -331,7 +331,7 @@ export async function main(args) {
   if (command === 'version' || command === '--version' || command === '-v') {
     process.stdout.write(`${VERSION}\n`); return;
   }
-  if (!BUSINESS_COMMANDS.has(command)) throw new CliError('UNKNOWN_COMMAND', `unknown command: ${command}`, 2);
+  if (command !== 'profile' && !BUSINESS_COMMANDS.has(command)) throw new CliError('UNKNOWN_COMMAND', `unknown command: ${command}`, 2);
   if (platform() !== 'darwin') throw new CliError('UNSUPPORTED_PLATFORM', `${command} is supported only on macOS`);
 
   const paths = productPaths();
@@ -387,6 +387,14 @@ export async function main(args) {
     }
     return;
   }
+  if (command === 'profile') {
+    const profileArgs = args.slice(1);
+    const input = profileArgs.some((arg) => arg === '--json' || arg.startsWith('--json='))
+      ? parseDaemonInput(profileArgs)
+      : parseProfileArgs(profileArgs);
+    output(profileCommand(paths, input));
+    return;
+  }
   if (command === 'config' || command === 'subagents' || command === 'agents') {
     const input = structuredInput(args.slice(1), command === 'config' ? parseConfigArgs : parseSubagentsArgs);
     output(command === 'config'

package/cli/paths.mjs

@@ -24,5 +24,67 @@ export function productPaths(home = os.homedir()) {
     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),
+    profiles: path.join(data, 'profiles'),
   };
 }
+
+// Mirror the daemon's `profiles_directory()` exactly (rpc/profiles.rs):
+// `EXTERNAL_SUBAGENT_CONFIG` wins when it is *exported*, even when exported as
+// an empty string, and only then does `ZCODE_AGENT_CONFIG` apply; presence, not
+// truthiness, selects the variable (`var_os(...).or_else(...)`). An empty
+// exported path has no parent in Rust (`Path::new("").parent() == None`), so the
+// daemon loads no profiles directory at all; return null to represent that.
+// Otherwise take the sibling `profiles/` of the config file, or fall back to the
+// product data directory.
+
+// Rust `Path::parent()` semantics on Unix, implemented with plain string
+// slicing (never `path.dirname`/`path.join`, which lexically normalise and would
+// fold `..` components away). Rust's `Path::components` drops trailing
+// separators and any `.` component that is not the first, so a trailing `.` is
+// not a component of its own: `a/.` has parent `Some("")`, `a/b/.` has parent
+// `Some("a")`, and `/.` is the root with no parent (`None`). `..` is retained.
+function rustPathParent(value) {
+  if (value === '') return null;
+  let end = value.length;
+  for (;;) {
+    while (end > 1 && value[end - 1] === '/') end -= 1;
+    const componentStart = value.lastIndexOf('/', end - 1) + 1;
+    if (end - componentStart === 1 && value[componentStart] === '.' && componentStart > 0) {
+      end = componentStart - 1; // drop the non-leading "." and its separator
+      continue;
+    }
+    break;
+  }
+  const trimmed = value.slice(0, end);
+  if (trimmed === '') return null; // "/." and friends normalise to the root
+  if (/^\/+$/u.test(trimmed)) return null; // root has no parent
+  const slash = trimmed.lastIndexOf('/');
+  if (slash < 0) return ''; // bare name: parent is Some("")
+  if (slash === 0) return '/';
+  return trimmed.slice(0, slash);
+}
+
+// Rust `Path::parent().join("profiles")` without normalisation: appending to the
+// empty path yields "profiles", and existing `..`/`.` components are preserved.
+function joinProfiles(parent) {
+  if (parent === '') return 'profiles';
+  if (parent === '/') return '/profiles';
+  return `${parent}/profiles`;
+}
+
+export function profilesDir(env = {}, home = os.homedir()) {
+  const names = ['EXTERNAL_SUBAGENT_CONFIG', 'ZCODE_AGENT_CONFIG'];
+  let envPath;
+  let exported = false;
+  for (const name of names) {
+    if (env[name] !== undefined) {
+      envPath = env[name];
+      exported = true;
+      break;
+    }
+  }
+  if (!exported) return path.join(productPaths(home).data, 'profiles');
+  const parent = rustPathParent(envPath);
+  if (parent === null) return null;
+  return joinProfiles(parent);
+}

package/cli/rpc.mjs

@@ -66,16 +66,25 @@ function readJsonInput(args) {
 function requestId() { return `cli-${process.pid}-${crypto.randomUUID()}`; }
 
 function manifest(input) {
-  const allowed = new Set(['subagent', 'repository', 'permission_mode', 'prompt', 'model', 'effort', 'write_manifest']);
+  const allowed = new Set(['profile', '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.profile !== undefined && (typeof input.profile !== 'string' || input.profile.length === 0)) throw new CliError('INVALID_ARGUMENT', 'profile must be a non-empty string', 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);
+  if (input.profile !== undefined) {
+    return {
+      schema: 'zcode-general-task/v1', agent_id: requestId(), repository: input.repository,
+      ...(input.permission_mode !== undefined ? { permission_mode: input.permission_mode } : {}),
+      prompt: input.prompt,
+      write_manifest: input.write_manifest || [],
+    };
+  }
   return {
     schema: 'zcode-general-task/v1', agent_id: requestId(), repository: input.repository,
     permission_mode: input.permission_mode || 'build', prompt: input.prompt,
@@ -101,6 +110,7 @@ function methodFor(command, input) {
     case 'create': case 'spawn': return {
       method: 'submit_general',
       params: {
+        ...(input.profile !== undefined ? { profile: input.profile } : {}),
         ...(input.subagent !== undefined ? { subagent: input.subagent } : {}),
         ...(input.model !== undefined ? { model: input.model } : {}),
         ...(input.effort !== undefined ? { effort: input.effort } : {}),

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

@@ -1,20 +1,20 @@
 {
   "schema_version": 1,
   "product": "external-subagent",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "platform": "darwin-arm64",
   "files": [
     {
       "name": "external-subagentd",
-      "bytes": 9907776,
+      "bytes": 10116128,
       "mode": "755",
-      "sha256": "b0dc9625006f6bbce38e78e46aa7ada47c9ba00c193e51b54f430302d931bfa6"
+      "sha256": "9c650b9c096f4060e927eced4d05665749123177e3c7d105a13a8a466633ed77"
     },
     {
       "name": "external-subagent-mcp",
-      "bytes": 935760,
+      "bytes": 935888,
       "mode": "755",
-      "sha256": "0b26f44eaa3407016529aec3b948a56e3318cbc29f6d9b169056f426440b8478"
+      "sha256": "e519c71451bc27bf217316c57fe92d82e8e8fc546c13194455ad60dbc0cdc9f7"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "external-subagent",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Manage bounded ZCode, DeepSeek Harness (DSH), Codex, and Google Antigravity (agy) subagent tasks through a local MCP service for any local host (Codex, ZCode, or a custom MCP client)",
   "type": "module",
   "license": "MIT",

package/schema/external-subagent-public-api.json

@@ -63,6 +63,7 @@
       "description": "Start one durable subagent in an absolute repository workspace, returning after establishing the new session.",
       "required": ["repository", "prompt"],
       "properties": {
+        "profile": { "type": "string", "minLength": 1, "description": "Profile name referencing a JSON preset in profiles/*.json. Mutually exclusive with subagent, permission_mode, model, and effort." },
         "subagent": { "type": "string", "minLength": 1, "description": "Subagent route key; omission uses configured default_subagent or returns subagent_required. Null is invalid; dsh production spawn requires its enabled + spawn_supported + pinned-runtime configuration." },
         "repository": { "type": "string", "minLength": 1 },
         "permission_mode": { "$ref": "#/properties/permission_mode", "description": "codex supports build/edit (workspace-write), plan (read-only), and yolo (danger-full-access), always with approvalPolicy=never; agy supports only build (--mode accept-edits) and yolo (--dangerously-skip-permissions)." },
@@ -183,7 +184,7 @@
       "additionalProperties": false,
       "properties": {
         "external_subagent_status": { "input": [], "output": ["mcp_version", "components", "capabilities", "subagents"] },
-        "external_subagent_spawn": { "input": ["subagent", "repository", "permission_mode", "prompt", "model", "effort", "write_manifest"], "output": ["agent_id", "status", "session_id"], "idempotent": false },
+        "external_subagent_spawn": { "input": ["profile", "subagent", "repository", "permission_mode", "prompt", "model", "effort", "write_manifest"], "output": ["agent_id", "status", "session_id"], "idempotent": false },
         "external_subagent_wait": { "input": ["agent_id", "wait_time", "message_id"], "output": ["task", "pending_requests", "result_available", "activity", "result", "instruction", "timed_out", "message_receipt"] },
         "external_subagent_observe": { "input": ["agent_id"], "output": ["tools", "reasoning", "coverage"], "idempotent": true },
         "external_subagent_list": { "input": ["subagent", "repository", "phase", "outcome", "cursor", "limit"], "output": ["tasks", "next_cursor"] },