@mrciphersmith/keryx 0.3.41 → 0.3.42

package/README.md

@@ -487,7 +487,7 @@ What is in it today:
   bounded parallel scheduling, and an offline fleet report over a recorded event
   log (`keryx agents monitor <events-file>`).
 - **Vendor CLIs as child agents — off by default.** keryx can hand a bounded,
-  **read-only** task (or, for `claude-cli` only, a reviewed write — see below)
+  **read-only** task (or, for `claude-cli` and `codex-cli`, a reviewed write — see below)
   to a coding CLI you already have installed (`codex exec`,
   `claude -p`, or Google's Antigravity CLI, `agy -p --output-format
   stream-json`) and host it as a child of the same harness: a disposable git
@@ -509,16 +509,20 @@ What is in it today:
 - **A write from an external agent you review before it lands.**
   `keryx agents external run claude-cli --task "…" --write` runs `claude` in a
   throwaway worktree with only `Read Grep Glob Edit Write` (no shell, no network,
-  no MCP). Its diff is captured, secret-redacted, hashed and stored as a pending
+  no MCP); `codex-cli --write` runs `codex` in the same kind of worktree under an
+  OS sandbox (as measured: writes outside the worktree fail, a DNS lookup fails, `.git` read-only)
+  that still leaves it a shell able to read files your account can read, so review
+  its output too. Its diff is captured, secret-redacted, hashed and stored as a pending
   review — nothing reaches your checkout. `keryx agents external review <run-id>`
   shows it; `apply <run-id>` needs a real terminal, shows the diff and asks you to
   type the first 12 hex digits of the patch hash, then creates a NEW local branch
   `external/<run-id>` with one commit. Your current branch and working tree are
   never touched, nothing is pushed and no pull request is opened;
   `discard <run-id>` drops it. There is no flag that skips the confirmation. Only
-  `claude-cli` can write (`codex-cli` and `antigravity-cli` refuse `--write`), the
-  review is a human reading the diff (a model review is not built), and a full run
-  through the installed CLI is not recorded yet. In the TUI: `/external-diff` and a
+  `claude-cli` and `codex-cli` can write (`antigravity-cli` refuses `--write`), the
+  review is a human reading the diff (a model review is not built), and neither
+  has a long live history (`codex` was verified in a scratch repository on
+  `codex` 0.159.2; versions outside 0.159.2 up to 0.160.0 are refused). In the TUI: `/external-diff` and a
   sidebar row while a diff waits. See the [external agent write
   guide](docs/docs/guides/external-agent-write.md).
 - **Completion you can audit.** The completion gate blocks on missing evidence: a
@@ -948,7 +952,7 @@ untouched.
 | No bundled embedding runtime | No semantic ranking in memory search | Lexical memory search remains fully available |
 | ripgrep is external | `keryx ctx rg` needs `rg` on `PATH` | Install ripgrep, or let the agent read files directly |
 | Model commands need a credential | Four of the five commands above exit non-zero without one; `wiki enrich` exits `0` and marks the affected pages skipped | Everything else runs deterministically offline |
-| External agents are read-only, except `claude-cli` write mode, which has no full live run recorded | A delegated CLI can read and search; only `claude-cli` can write, and only as a stored diff a human reviews (`keryx agents external review\|apply\|discard`) that lands as a new local branch — never on your checkout, never pushed. `codex-cli` and `antigravity-cli` refuse `--write` ("write mode is claude-only in this release"). A model review is not built. The parent gets the child's result and nothing before it — supervision of a running external child is not implemented. `claude` and `agy` read-only runs are live-verified; a write run through the installed CLI is not yet | Use keryx's own child agents for work that must mutate the tree, or the [external agent write guide](docs/docs/guides/external-agent-write.md) for a reviewed `claude-cli` diff |
+| External agents are read-only, except `claude-cli` and `codex-cli` write mode, which have no long live history | A delegated CLI can read and search; only `claude-cli` and `codex-cli` can write, and only as a stored diff a human reviews (`keryx agents external review\|apply\|discard`) that lands as a new local branch — never on your checkout, never pushed. `claude` is confined by a tool allow-list (no shell, no network); `codex` by an OS sandbox that still leaves it a shell that can read files your user can read (it cannot send them, but they can show up in the run output), and is refused when older than 0.159.0 — live-verified in a scratch repository on `codex` 0.159.0. `antigravity-cli` refuses `--write`. A model review is not built. The parent gets the child's result and nothing before it — supervision of a running external child is not implemented. `claude` and `agy` read-only runs are live-verified | Use keryx's own child agents for work that must mutate the tree, or the [external agent write guide](docs/docs/guides/external-agent-write.md) for a reviewed `claude-cli` or `codex-cli` diff |
 | A dispatched `flow-next` task is "done" by checks, not review | `task done` means normal end + a commit on the trigger branch + `keryx health gate` passing in the worktree; nobody has read the diff | Review and merge the `trigger/<flow>-<task>` branch yourself |
 | `trust` dispatch needs Linux + a working bubblewrap | The hardened unattended sandbox (network off, home hidden, allow-listed env) is bwrap-only; without it — or on macOS — a `trust` dispatch refuses before starting | Use `permissionMode: "ask"` (read-only), or run triggers on a Linux host with bwrap |
 | `dispatch.network: true` is the host's full network | The agent's commands then reach the internet and every host loopback service; the model call never needs it (it is made outside the sandbox) | Leave `network` off; review the `trigger/*` branch before installing or building it |

package/dist/cli.js

@@ -14119,7 +14119,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@mrciphersmith/keryx",
-    version: "0.3.41",
+    version: "0.3.42",
     description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
     private: false,
     publishConfig: {
@@ -51368,13 +51368,15 @@ permission bridge.
 A line-stream agent (\`claude-cli\`, \`codex-cli\`) is a DIFFERENT thing:
 \`run\` refuses it outright ("speaks the one-way line stream. Delegate to it
 from \`keryx shell\` with /delegate"). There is no ACP permission bridge and
-no patch capture for it \u2014 this release implements \`worktree-write\` for the
-ACP transport only; a dispatch that asks for \`worktree-write\` on a
-line-stream agent is REFUSED fail-closed with a distinguishable
-\`not-implemented\` reason everywhere keryx dispatches one (the internal
-\`runtime\` block, and \`keryx shell\`'s /delegate) \u2014 never silently accepted
-and its writes discarded. It stays \`read-only\`, contained by the same
-disposable worktree as every external run.
+no patch capture for it in those paths \u2014 \`worktree-write\` is implemented for
+the ACP transport, and for \`claude-cli\` and \`codex-cli\` only through the
+operator's own \`keryx agents external run <id> --write\`, which captures the
+diff for human review. A dispatch that asks for \`worktree-write\` on a
+line-stream agent anywhere else (the internal \`runtime\` block, and
+\`keryx shell\`'s /delegate) is REFUSED fail-closed with a distinguishable
+\`not-implemented\` reason \u2014 never silently accepted and its writes
+discarded. There it stays \`read-only\`, contained by the same disposable
+worktree as every external run.
 
 See \`docs/docs/guides/acp-client.md\` for the full ACP contract, including the
 output size bounds (a stderr-only flood and an output flood both end the run
@@ -85139,14 +85141,14 @@ var init_registry3 = __esm(() => {
       label: "Codex",
       binary: "codex",
       detect: ["--version"],
-      versionPattern: "codex-cli (\\d+\\.\\d+\\.\\d+)",
+      versionPattern: "codex-cli (\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.]+)?)",
       knownGoodRange: { min: "0.147.0" },
       sandboxModes: ["read-only", "worktree-write"],
       streamingInput: false,
       resumable: true,
       reportsCost: false,
       budgetFlag: false,
-      notes: "Resume requires NOT passing `--ephemeral`: an ephemeral thread fails resume with " + "`no rollout found for thread id \u2026 (code -32600)`. `codex exec resume` also takes a " + "narrower flag set than `codex exec` \u2014 no `-s`, no `-C` \u2014 so its sandbox level cannot " + "be re-asserted and it must be spawned with cwd already set to the worktree."
+      notes: "Resume requires NOT passing `--ephemeral`: an ephemeral thread fails resume with " + "`no rollout found for thread id \u2026 (code -32600)`. `codex exec resume` also takes a " + "narrower flag set than `codex exec` \u2014 no `-s`, no `-C` \u2014 so a read-only resume inherits " + "its sandbox, a write run re-asserts its confinement as `-c` overrides, and it must be " + "spawned with cwd already set to the worktree. Write mode needs codex 0.159.2 up to, but not including, 0.160.0."
     },
     {
       id: "claude-cli",
@@ -85196,10 +85198,27 @@ var init_registry3 = __esm(() => {
 });
 
 // src/harness/external/dispatch.ts
+function codecWriteVersionRefusal(entry, version) {
+  const verified = CODEC_WRITE_VERIFIED_VERSIONS[entry.id];
+  if (verified === undefined)
+    return;
+  const range = `\`${entry.binary}\` ${verified.min} up to, but not including, ${verified.before}`;
+  const prefix = `${entry.label} write mode needs ${range}, the versions whose sandbox confinement was measured; `;
+  if (version === undefined)
+    return `${prefix}the installed version could not be read`;
+  if (!/^\d+\.\d+\.\d+$/.test(version))
+    return `${prefix}found ${version}, a pre-release`;
+  if (compareVersions(version, verified.min) < 0)
+    return `${prefix}found ${version}, which is older`;
+  if (compareVersions(version, verified.before) >= 0) {
+    return `${prefix}found ${version}, which is newer and not yet verified: update keryx, or use \`--task\` without \`--write\``;
+  }
+  return;
+}
 function implementedSandboxModesFor(entry, options = {}) {
   if (transportOf(entry) === "acp")
     return IMPLEMENTED_ACP_SANDBOX_MODES;
-  return entry.id === CODEC_WRITE_AGENT_ID && options.ownsWriteCapture === true ? IMPLEMENTED_ACP_SANDBOX_MODES : IMPLEMENTED_SANDBOX_MODES;
+  return CODEC_WRITE_AGENT_IDS.includes(entry.id) && options.ownsWriteCapture === true ? IMPLEMENTED_ACP_SANDBOX_MODES : IMPLEMENTED_SANDBOX_MODES;
 }
 function validateRuntimeBlock(runtime, allowedActions, options = {}) {
   if (runtime === undefined || runtime.kind === "keryx") {
@@ -85241,7 +85260,7 @@ function validateRuntimeBlock(runtime, allowedActions, options = {}) {
     return {
       ok: false,
       code: "not-implemented",
-      reason: `sandbox "${sandbox}" is not implemented in this release; only ${implemented.join(", ")} is available` + (sandbox === "worktree-write" && transportOf(entry) !== "acp" ? `; write mode is claude-only in this release (${CODEC_WRITE_AGENT_ID})` : "")
+      reason: `sandbox "${sandbox}" is not implemented in this release; only ${implemented.join(", ")} is available` + (sandbox === "worktree-write" && transportOf(entry) !== "acp" ? `; write mode is available for ${CODEC_WRITE_AGENT_IDS.join(", ")} only` + (entry.id === "antigravity-cli" ? ": antigravity-cli's edit tool writes outside the worktree" : "") : "")
     };
   }
   if (sandbox === "read-only") {
@@ -85267,12 +85286,16 @@ function readRuntimeBlock(dispatch) {
     return;
   return raw;
 }
-var READ_ONLY_FORBIDDEN_ACTIONS, IMPLEMENTED_SANDBOX_MODES, IMPLEMENTED_ACP_SANDBOX_MODES, CODEC_WRITE_AGENT_ID = "claude-cli";
+var READ_ONLY_FORBIDDEN_ACTIONS, IMPLEMENTED_SANDBOX_MODES, IMPLEMENTED_ACP_SANDBOX_MODES, CODEC_WRITE_AGENT_IDS, CODEC_WRITE_VERIFIED_VERSIONS;
 var init_dispatch = __esm(() => {
   init_registry3();
   READ_ONLY_FORBIDDEN_ACTIONS = ["write", "network", "spawn-subagent"];
   IMPLEMENTED_SANDBOX_MODES = ["read-only"];
   IMPLEMENTED_ACP_SANDBOX_MODES = ["read-only", "worktree-write"];
+  CODEC_WRITE_AGENT_IDS = ["claude-cli", "codex-cli"];
+  CODEC_WRITE_VERIFIED_VERSIONS = {
+    "codex-cli": { min: "0.159.2", before: "0.160.0" }
+  };
 });
 
 // src/harness/external/env-deny.ts
@@ -85806,7 +85829,7 @@ var init_prompt2 = __esm(() => {
   EXTERNAL_WRITE_RUNTIME_DIRECTIVE = [
     "# Runtime directive",
     "",
-    "You are running non-interactively as a bounded child agent. Produce the work itself as " + "your final message, in the requested output schema. Do not ask questions, do not offer a " + "choice of modes, do not route to another skill, orchestrator, or flow, do not delegate to " + "another agent. You may create and modify files, only inside your current working " + "directory, using the Read, Grep, Glob, Edit and Write tools; no shell is available. Do not " + "touch .git, .github, .claude or .metaproject. Your changes are captured as a patch that a " + "human reviews before anything lands, so summarise what you changed in the final message."
+    "You are running non-interactively as a bounded child agent. Produce the work itself as " + "your final message, in the requested output schema. Do not ask questions, do not offer a " + "choice of modes, do not route to another skill, orchestrator, or flow, do not delegate to " + "another agent. You may create and modify files, only inside your current working " + "directory, using your file reading, searching and editing tools. Do not use a shell to reach " + "outside it. Do not touch .git, .github, .claude or .metaproject. Your changes are captured as a patch that a " + "human reviews before anything lands, so summarise what you changed in the final message."
   ].join(`
 `);
   DIFF_INTRO_COMPLETE = "The operator's uncommitted changes are below. Your worktree is checked out at HEAD and " + "does not contain them, so this diff is the only place they exist for you.";
@@ -88338,6 +88361,8 @@ function buildCodexArgv(input) {
     "--ignore-user-config",
     "--skip-git-repo-check"
   ];
+  if (input.sandbox === "worktree-write")
+    argv.push(...CODEX_WRITE_CONFINEMENT_FLAGS);
   if (input.resultSchemaPath !== undefined)
     argv.push("--output-schema", input.resultSchemaPath);
   if (input.model !== undefined)
@@ -88345,8 +88370,9 @@ function buildCodexArgv(input) {
   argv.push(input.prompt);
   return argv;
 }
-function buildCodexResumeArgv(sessionRef, message) {
-  return ["codex", "exec", "resume", sessionRef, "--json", "--ignore-user-config", "--skip-git-repo-check", message];
+function buildCodexResumeArgv(sessionRef, message, input) {
+  const confinement = input?.sandbox === "worktree-write" ? ["-c", `sandbox_mode="${CODEX_SANDBOX_MODES["worktree-write"]}"`, ...CODEX_WRITE_CONFINEMENT_FLAGS] : [];
+  return ["codex", "exec", "resume", sessionRef, "--json", "--ignore-user-config", "--skip-git-repo-check", ...confinement, message];
 }
 function parseCodexEvents(line) {
   const record = readJsonObject2(line);
@@ -88501,12 +88527,21 @@ function brief2(text, max = 200) {
   const flat = text.replace(/\s+/g, " ").trim();
   return flat.length <= max ? flat : `${flat.slice(0, max - 1)}\u2026`;
 }
-var CODEX_SANDBOX_MODES, RECOGNISED_TYPES, NARRATED_FAILURE_LINE, CLI_USAGE_PATTERNS, AUTH_PATTERNS2, LIMIT_PATTERNS2, codexCliCodec;
+var CODEX_SANDBOX_MODES, CODEX_WRITE_CONFINEMENT_FLAGS, RECOGNISED_TYPES, NARRATED_FAILURE_LINE, CLI_USAGE_PATTERNS, AUTH_PATTERNS2, LIMIT_PATTERNS2, codexCliCodec;
 var init_codex_cli = __esm(() => {
   CODEX_SANDBOX_MODES = {
     "read-only": "read-only",
     "worktree-write": "workspace-write"
   };
+  CODEX_WRITE_CONFINEMENT_FLAGS = [
+    "--ignore-rules",
+    "-c",
+    "sandbox_workspace_write.exclude_slash_tmp=true",
+    "-c",
+    "sandbox_workspace_write.exclude_tmpdir_env_var=true",
+    "-c",
+    "sandbox_workspace_write.network_access=false"
+  ];
   RECOGNISED_TYPES = new Set([
     "thread.started",
     "turn.started",
@@ -88536,7 +88571,7 @@ var init_codex_cli = __esm(() => {
     parseLine: parseCodexLine,
     parseEvents: parseCodexEvents,
     classifyFailure: classifyCodexFailure,
-    buildResumeArgv: (sessionRef, message) => buildCodexResumeArgv(sessionRef, message),
+    buildResumeArgv: buildCodexResumeArgv,
     isRecognisedLine: isRecognisedCodexLine
   };
 });
@@ -88650,15 +88685,21 @@ async function runExternalChild(input, deps) {
   if (!isAcp && codec === undefined) {
     return refuse2("Error", `no codec is registered for external agent "${entry.id}"`);
   }
+  let detectedVersion;
   if (deps.detect !== undefined) {
     const availability = resolveAvailability(entry, await deps.detect(entry.binary, entry.detect));
     if (availability.state === "binary-missing") {
       return refuse2("Denied", `${entry.label} is not installed (\`${entry.binary}\` not on PATH)`);
     }
+    if (availability.state === "available")
+      detectedVersion = availability.version;
     if (availability.state === "available" && availability.verdict.state !== "in-range") {
       deps.onWarning?.(`${entry.label} version ${availability.version ?? "unknown"} is outside the range this build's fixtures were recorded against`);
     }
   }
+  const versionRefusal = sandbox === "worktree-write" ? codecWriteVersionRefusal(entry, detectedVersion) : undefined;
+  if (versionRefusal !== undefined)
+    return refuse2("Denied", versionRefusal);
   const schemaPrep = await prepareResultSchema();
   if (!schemaPrep.ok)
     return refuse2("Error", schemaPrep.reason);
@@ -179443,7 +179484,7 @@ async function runCommand4(args, deps, log) {
     maxExternalDepth: DEFAULT_MAX_EXTERNAL_DEPTH,
     onWarning: (warning) => console.error(`warning: ${plain(warning)}`)
   };
-  if (write && id === CODEC_WRITE_AGENT_ID) {
+  if (write && CODEC_WRITE_AGENT_IDS.includes(id)) {
     let handle;
     let interrupted = false;
     const onSigint = () => {
@@ -179717,7 +179758,7 @@ function printExternalHelp() {
     { flag: "--no-probe", desc: "Skip detection entirely; every entry reports `not-probed`." },
     { flag: "--task", desc: "run: what the agent should do. It runs in a disposable worktree; your tree is never touched." },
     { flag: "--unattended", desc: "run: refuse every permission that would need a human (also implied without a TTY)." },
-    { flag: "--write", desc: "run: writes land in the disposable worktree and leave as a never-applied patch. An ACP agent advertises fs.writeTextFile; for a line-stream agent only claude is supported (Edit and Write inside the worktree)." },
+    { flag: "--write", desc: "run: writes land in the disposable worktree and leave as a never-applied patch. An ACP agent advertises fs.writeTextFile; for a line-stream agent only claude-cli and codex-cli are supported. claude gets Edit and Write inside the worktree and no shell; codex runs under its OS sandbox (writes confined to the worktree, network closed as far as measured) and keeps a shell that can read any file you can read. codex needs version 0.159.2 or newer but older than 0.160.0. antigravity-cli is refused: its edit tool writes outside the worktree." },
     { flag: "--timeout", desc: "run: wall-clock ceiling in ms (default: externalAgents.defaultTimeoutMs)." }
   ]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {

package/src/gdskills/contracts/subagent-dispatch.schema.json

@@ -165,7 +165,7 @@
           "minLength": 1
         },
         "sandbox": {
-          "description": "Permission level for the external child. `worktree-write` is schema-valid but refused at runtime in the read-only release, with a reason distinguishable from an unsupported-by-this-agent refusal.",
+          "description": "Permission level for the external child. `worktree-write` is schema-valid but refused at runtime except for an ACP agent and, through the operator's `--write` command only, `claude-cli` and `codex-cli`, with a reason distinguishable from an unsupported-by-this-agent refusal.",
           "type": "string",
           "enum": ["read-only", "worktree-write"]
         },