external-subagent 0.5.2 → 0.5.4

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

@@ -1,19 +0,0 @@
-#!/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`);
-}

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

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

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

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

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

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

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

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-
-function value(name) {
-  const index = process.argv.indexOf(name);
-  const result = index >= 0 ? process.argv[index + 1] : undefined;
-  if (!result || result.startsWith('--')) process.exit(2);
-  return result;
-}
-
-const workspace = path.resolve(value('--workspace'));
-const home = path.resolve(value('--home'));
-const mode = value('--permission-mode');
-const manifest = value('--write-manifest');
-if (mode !== 'plan' || manifest !== '[]' || !fs.statSync(workspace).isDirectory()) process.exit(2);
-const configPath = path.join(home, '.zcode', 'cli', 'config.json');
-const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-const events = config?.hooks?.events;
-if (config?.hooks?.enabled !== true || !events || !Array.isArray(events.PreToolUse)) process.exit(2);
-const pre = events.PreToolUse.find((entry) => entry?.matcher === '^(Read|Grep|Glob|Write|Edit|Delete|Move)$');
-const hook = pre?.hooks?.find((entry) => entry?.type === 'process' && Array.isArray(entry.args));
-const script = hook?.args?.find((candidate) => typeof candidate === 'string' && candidate.endsWith('/hooks/check-agent-files.mjs'));
-const guard = events.PreToolUse.find((entry) => entry?.matcher === 'Bash')?.hooks?.find((entry) => entry?.type === 'process')?.args?.[0];
-const audit = events.PostToolUse?.find((entry) => entry?.matcher === 'Bash')?.hooks?.find((entry) => entry?.type === 'process')?.args?.[0];
-if (!script || !fs.statSync(script).isFile() || hook.command !== process.execPath || !guard || !fs.statSync(guard).isFile() || !audit || !fs.statSync(audit).isFile()) process.exit(2);
-// The provenance is staged by install-agent-hooks.mjs beside this verifier,
-// inside the product data directory of the probe home. The candidates mirror
-// the daemon's policy_verifier_candidates exactly: the frozen macOS
-// `~/Library/Application Support` bytes on darwin; elsewhere an exported
-// absolute $XDG_DATA_HOME is probed first, then the `~/.local/share` XDG
-// fallback for the scope home.
-const provenanceCandidates = process.platform === 'darwin'
-  ? [path.join(home, 'Library', 'Application Support', 'external-subagent', 'zcode-agent-hook-provenance.json')]
-  : [
-      ...(typeof process.env.XDG_DATA_HOME === 'string' && path.isAbsolute(process.env.XDG_DATA_HOME)
-        ? [path.join(process.env.XDG_DATA_HOME, 'external-subagent', 'zcode-agent-hook-provenance.json')]
-        : []),
-      path.join(home, '.local', 'share', 'external-subagent', 'zcode-agent-hook-provenance.json'),
-    ];
-const provenancePath = provenanceCandidates.find((candidate) => fs.existsSync(candidate));
-if (!provenancePath) process.exit(2);
-const provenance = JSON.parse(fs.readFileSync(provenancePath, 'utf8'));
-const hash = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
-const policy = path.resolve(path.dirname(script), '../lib/agent-file-policy.mjs');
-if (provenance.effective_config_path !== path.resolve(configPath)
-  || provenance.hook_activation_verified !== true
-  || provenance.effective_file_policy_version !== 'zcode-agent-file-policy/v1.0.0'
-  || provenance.effective_file_policy_path !== policy
-  || provenance.effective_file_policy_sha256 !== hash(policy)
-  || provenance.effective_guard_wrapper_path !== path.resolve(guard)
-  || provenance.effective_guard_wrapper_sha256 !== hash(guard)
-  || provenance.effective_file_wrapper_path !== path.resolve(script)
-  || provenance.effective_file_wrapper_sha256 !== hash(script)
-  || provenance.effective_audit_wrapper_path !== path.resolve(audit)
-  || provenance.effective_audit_wrapper_sha256 !== hash(audit)) process.exit(2);
-process.exit(0);