@lyupro/codex-bridge 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.4] - 2026-08-28
+
+### Added
+
+- A gate that holds every registered hook to one rule: a hook may not add anything to what the host
+  runs. A neighbouring package spent a whole plan undoing the opposite habit — its `PreToolUse` hook
+  wrapped the agent's command in a pipe, and because a host permission rule is matched against the
+  beginning of the final string and is not applied at all once that string carries a substitution or
+  a compound operator, every command it touched became unresolvable by the operator's own rules.
+  This package reported those windows on 2026-08-15 while carrying none of the cause. The gate reads
+  both behaviour and sources: a hook may return only the keys that refuse or speak
+  (`permissionDecision` of `deny` or `ask`, `permissionDecisionReason`, `additionalContext`), and no
+  hook source may mention a key that replaces what the host is about to run. `permissionDecision:
+  "allow"` is refused as well — the host stopped honouring it between 2.1.119 and 2.1.231, and while
+  it worked it was a blanket auto-approve over the operator's own deny rules.
+
+- `doctor` and `install` now say whether this host still honours a hook refusal. Every guard in this
+  package refuses work with `permissionDecision: "deny"`, and the sibling key of that same object
+  died quietly — a neighbouring package established that `"allow"` stopped being honoured somewhere
+  between host 2.1.119 and 2.1.231, with no error printed on the way. Nothing here would have
+  noticed `deny` going the same way, because the suite checks that a hook RETURNED a refusal, never
+  that the host APPLIED it. The record is bound to a host version, since that is what changes
+  underneath an installation, and reports five states: never probed, probed on another version,
+  refusals ignored (which names the guards it makes inert and exits non-zero), verified, and a host
+  whose version cannot be read.
+
+- `codex-bridge doctor --probe-contract` performs that measurement on a live host, and every message
+  that a probe could change now names it. The probe builds a throwaway rig outside the repository,
+  registers one temporary hook there that refuses one marker command, runs the real host inside it
+  and judges by whether the marker file appeared. Three conditions were bought by a measurement that
+  first reported a working host as dead: only the tool under test is allowed (`--allowedTools Bash`),
+  because the nested session otherwise sidesteps the refusal with `Write` and writes its own report
+  of being blocked into the marker file; the verdict comes from what executed, never from what the
+  model said about it; and settings are read from the project alone, or the operator's own hooks get
+  measured instead. A crash, a timeout or a hook that never fired records nothing and exits 2 — an
+  absent marker is only evidence when the host survived to the end, and a probe that announced a
+  contract as verified without measuring it would be the very silence this record exists to break.
+
+### Fixed
+
+- A run now reads the operator's configuration instead of the copy shipped inside the package. The
+  installer seeds `config.json` into `~/.lyupro/.codex-bridge/`, the CLI read it from there, and the
+  runner built its own path from the module it happened to live in — so `codex-bridge run` opened the
+  package's seed, in which no profile is ever configured. A model and a reasoning depth pinned by the
+  operator on 5 August reached no run at all: every run silently used defaults, `env.json` recorded
+  `"models": {}`, `meta.json` recorded no model because no `-m` was ever passed, and `doctor` kept
+  confirming the setting because it resolved the path correctly. Three releases shipped that way, and
+  it surfaced only when a service refused a reasoning level and the command line in the run folder
+  turned out to name no model. Installed from npm, the file the runner read also sat inside
+  `node_modules` and was replaced by every update, contradicting the documented promise that
+  configured profiles survive one. There is now one resolver of the host home for both halves of the
+  repository, the printed state names the file together with where that path came from, and an
+  end-to-end test fails if a configured profile stops reaching the assembled Codex command line — the
+  existing unit tests injected the profile as an argument and could not see the file at all.
+
+- Every reply now names the worker that ran it: `Model: <model> at <depth> effort (<where the depth
+  came from>)`, beside the log link. `worker.json` and `meta.json` carry the same profile, including
+  whether the model came from the configuration or was left to Codex, and whether the depth came
+  from the request, the configuration or the fallback. A dispatcher reads these rows and nothing
+  else, and for three releases none of them named a model at all — which is why a run on a model
+  nobody ordered could go unnoticed. A depth silently served by the fallback is the same silence one
+  level down, so it is reported the same way. Runs recorded before the field simply keep their old
+  replies.
+
+- `minimal` is no longer accepted as a reasoning effort. It passed validation and was then rejected
+  by the model itself (`Unsupported value: 'minimal' is not supported with the … model`), so an order
+  died four seconds after launch on quota already spent. The allowed set is now exactly what the
+  service enumerates: `none`, `low`, `medium`, `high`, `xhigh`, `max`. A validator that admits a
+  known-dead value is worse than no validator: it moves the refusal past the point where refusing is
+  free.
+
 ## [0.5.3] - 2026-08-23
 
 ### Fixed

package/README.md

@@ -1,152 +1,152 @@
-# codex-bridge
-
-**Delegate implementation, reconnaissance and review from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
-
-[![npm version](https://img.shields.io/npm/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-[![npm downloads](https://img.shields.io/npm/dm/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![npm unpacked size](https://img.shields.io/npm/unpacked-size/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
-[![dependencies: zero](https://img.shields.io/badge/dependencies-zero-brightgreen)](package.json)
-
-Agentic coding spends one model subscription on everything, and implementation is the expensive part. codex-bridge moves that work to a separate [Codex CLI](https://developers.openai.com/codex/cli) subscription: Claude Code plans, dispatches and accepts, Codex executes — and every delegated run is guarded, verified and audited on disk.
-
-## Install
-
-```bash
-npm i -g @lyupro/codex-bridge   # puts both command names on PATH
-codex-bridge install            # into ~/.claude and ~/.lyupro/.codex-bridge/
-codexb install                  # the short name, same command
-```
-
-Two other entry points reach the same command: `npx @lyupro/codex-bridge install` for a one-off run without a global install, and `node bin/codex-bridge.mjs install` from a clone. Every command below works through all three.
-
-Shipped agents invoke delegated runs through `codex-bridge run`. This is a permission contract,
-not a style choice: the stable package command lets host permission rules match the invocation
-without exposing an installation-specific absolute path and prompting on every delegation.
-
-Use `--scope project` to install the Claude Code-facing files under `<repo>/.claude`; the default user scope uses `~/.claude`.
-
-Installation has two roots:
-
-- `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, and the installation record.
-- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the three agents, two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
-
-The repository's `src/home/` directory is the literal image copied into the branded root: its
-`hooks/`, `lib/`, `config.json`, and `conventions.md` paths are the host paths without remapping.
-Only npm's `package.json` is copied into that root from outside the image.
-
-Before every `settings.json` write, the existing file is backed up. Existing settings and foreign hooks are preserved. `--dry-run` prints the plan without writing.
-
-If a global install and a clone coexist, you have two package copies. `codex-bridge update`, `codexb update`, and the clone entry point copy files from whichever copy launched the command; using the wrong one can replace a newer host installation with older files.
-
-`codex-runs/` contains operator data. Uninstall never removes it.
-
-## Requirements
-
-- Node.js >= 24
-- An authenticated [Codex CLI](https://developers.openai.com/codex/cli): `codex --version` and `codex login`
-- Claude Code, which hosts the agents, commands, and guards
-
-## What it gives you
-
-- **Runs survive the caller.** A detached worker keeps the run and its artifacts alive after the dispatcher exits.
-- **Invalid work is rejected before quota is spent.** Scope, order, retry, branch, and continuation checks run before a run folder is created.
-- **Verdicts come from artifacts.** CLI events, git state, and the declared report decide the result, not model claims about itself.
-- **Identical retries attach safely.** Repeating the same command joins the active run instead of starting another one.
-- **6 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping; `worktree-witness` stands behind the lock and names a write that reached the tree anyway.
-- **Installation is identifiable and reversible.** Writes to `settings.json` are merged and backed up; uninstall removes recorded package files only.
-- **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
-- **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
-
-The current suite contains **757 automated tests: 756 passing and 1 skipped**.
-
-## Verify
-
-```bash
-codex-bridge doctor
-```
-
-Output on a healthy host (trimmed):
-
-```text
-[ok] host: ~/.claude (user, exists)
-[ok] installation: @lyupro/codex-bridge@0.5.1 (matches package)
-[ok] files: 53 installed file(s) present
-[ok] rules: ~/.codex/rules/codex-bridge.rules (matches record)
-[ok] permissions: installed (24/24 own strings in allow/deny)
-[ok] hook:SubagentStop: matcher * -> ~/.lyupro/.codex-bridge/hooks/reply-guard.mjs
-[ok] hook:PreToolUse: matcher Agent|Task -> ~/.lyupro/.codex-bridge/hooks/order-gate.mjs
-[ok] hook:PreToolUse: matcher Write|Edit|MultiEdit|NotebookEdit -> ~/.lyupro/.codex-bridge/hooks/worktree-lock.mjs
-[ok] hook:PreToolUse: matcher Bash|PowerShell -> ~/.lyupro/.codex-bridge/hooks/prune-guard.mjs
-[ok] hook:PreToolUse: matcher TaskStop -> ~/.lyupro/.codex-bridge/hooks/stop-guard.mjs
-[warn] retention: Automatic cleanup is ON — run transport older than 30 days is removed to reclaim disk space.
-[ok] conventions: ~/.lyupro/.codex-bridge/conventions.md (found)
-[ok] codex: codex-cli 0.146.1
-[ok] node: 24.18.0 (requires >=24)
-[ok] runsRoot: ~/.claude/codex-runs
-[ok] liveRuns: 0 runs working right now
-```
-
-`doctor` reports the selected host, package source, installed files and guards, Codex availability, retention policy, permissions, live runs, and the current repository's run folder. The `agents` line is a read, not a file count: each installed definition is parsed and its `name` checked against the dispatcher it claims to be, because a definition the host cannot read is a dispatcher that does not exist while every other line still says `[ok]`. Content that drifts from the packaged definition is a failure, not a warning: `doctor` exits 1 and names `codex-bridge update --force`, because a host running someone else's agent files may be calling the runner in a form no permission rule matches.
-
-If a session answers `Agent type 'codex-build' not found`, a run can still be started without the dispatcher — the agent is a wrapper that types one command:
-
-```bash
-codex-bridge run --agent codex-build --repo <repository> --order-id <id> --scope <globs> --task-file <absolute path>
-```
-
-The trade-off is explicit: `order-gate` and `reply-guard` sit on the dispatcher call, so a direct run is unguarded and its result is judged by the worktree and the suite.
-
-## Update
-
-Update the global package, then refresh the selected host installation:
-
-```bash
-npm i -g @lyupro/codex-bridge
-codex-bridge update
-```
-
-`update` refreshes unchanged package files, refuses to overwrite operator edits unless `--force` is supplied, and removes obsolete files only when their installed fingerprint is unchanged.
-
-## Limitations
-
-- **Runs are not isolated from one another.** They share one worktree; guards prevent concurrent writers instead of creating sandboxes.
-- **A build run has a 25-minute deadline.** Work and artifacts survive a timeout, but the run may need an explicit continuation.
-- **A dispatcher verdict is not the work outcome.** Judge completion from the worktree and tests as well as the recorded verdict.
-
-Transport files from runs at least **30 days** old are pruned automatically when a new run starts. Configuration can change or disable that retention policy; reports, accounting, and worktree snapshots are retained.
-
-## Command reference
-
-| Command | Purpose |
-| --- | --- |
-| `install [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Install into a Claude Code host. |
-| `update [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Refresh a recorded installation. |
-| `permissions [add\|remove] [--scope user\|project] [--host <path>]` | Inspect or manage optional shell rules. |
-| `uninstall [--scope user\|project] [--host <path>] [--dry-run]` | Remove recorded package files while preserving run artifacts. |
-| `doctor [--scope user\|project] [--host <path>]` | Diagnose the selected host and Codex connection. |
-| `run <runner options> --task-file <abs path>` | Start or attach to a delegated run through the permission-stable package command. The task file carries the statement, the scout questions and the verification command; its path must be absolute. Piping the statement on stdin is the alternative channel, and the two cannot be combined. |
-| `projects [<name>] [--json]` | List projects or runs in the run store. |
-| `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup. |
-| `unlock [<project>\|--all]` | Close records whose runner is gone. |
-| `read <run>` | Render a run's structured event stream. |
-| `stop <run>` | Stop a run and record a `FAIL` verdict. |
-
-Both `codex-bridge` and `codexb` invoke the same command. Run `codex-bridge --help` for exact forms.
-
-### Development
-
-```bash
-git clone https://github.com/lyupro/codex-bridge.git
-cd codex-bridge
-git config core.hooksPath .githooks
-npm test
-```
-
-The Git hook enforces the 400-line source-file limit.
-
-## License
-
-[MIT](LICENSE)
+# codex-bridge
+
+**Delegate implementation, reconnaissance and review from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
+
+[![npm version](https://img.shields.io/npm/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[![npm downloads](https://img.shields.io/npm/dm/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![npm unpacked size](https://img.shields.io/npm/unpacked-size/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
+[![dependencies: zero](https://img.shields.io/badge/dependencies-zero-brightgreen)](package.json)
+
+Agentic coding spends one model subscription on everything, and implementation is the expensive part. codex-bridge moves that work to a separate [Codex CLI](https://developers.openai.com/codex/cli) subscription: Claude Code plans, dispatches and accepts, Codex executes — and every delegated run is guarded, verified and audited on disk.
+
+## Install
+
+```bash
+npm i -g @lyupro/codex-bridge   # puts both command names on PATH
+codex-bridge install            # into ~/.claude and ~/.lyupro/.codex-bridge/
+codexb install                  # the short name, same command
+```
+
+Two other entry points reach the same command: `npx @lyupro/codex-bridge install` for a one-off run without a global install, and `node bin/codex-bridge.mjs install` from a clone. Every command below works through all three.
+
+Shipped agents invoke delegated runs through `codex-bridge run`. This is a permission contract,
+not a style choice: the stable package command lets host permission rules match the invocation
+without exposing an installation-specific absolute path and prompting on every delegation.
+
+Use `--scope project` to install the Claude Code-facing files under `<repo>/.claude`; the default user scope uses `~/.claude`.
+
+Installation has two roots:
+
+- `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, and the installation record.
+- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the three agents, two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
+
+The repository's `src/home/` directory is the literal image copied into the branded root: its
+`hooks/`, `lib/`, `config.json`, and `conventions.md` paths are the host paths without remapping.
+Only npm's `package.json` is copied into that root from outside the image.
+
+Before every `settings.json` write, the existing file is backed up. Existing settings and foreign hooks are preserved. `--dry-run` prints the plan without writing.
+
+If a global install and a clone coexist, you have two package copies. `codex-bridge update`, `codexb update`, and the clone entry point copy files from whichever copy launched the command; using the wrong one can replace a newer host installation with older files.
+
+`codex-runs/` contains operator data. Uninstall never removes it.
+
+## Requirements
+
+- Node.js >= 24
+- An authenticated [Codex CLI](https://developers.openai.com/codex/cli): `codex --version` and `codex login`
+- Claude Code, which hosts the agents, commands, and guards
+
+## What it gives you
+
+- **Runs survive the caller.** A detached worker keeps the run and its artifacts alive after the dispatcher exits.
+- **Invalid work is rejected before quota is spent.** Scope, order, retry, branch, and continuation checks run before a run folder is created.
+- **Verdicts come from artifacts.** CLI events, git state, and the declared report decide the result, not model claims about itself.
+- **Identical retries attach safely.** Repeating the same command joins the active run instead of starting another one.
+- **6 host guards enforce the boundary.** `reply-guard`, `order-gate`, `worktree-lock`, `prune-guard`, and `stop-guard` cover replies, orders, edits, deletion, and stopping; `worktree-witness` stands behind the lock and names a write that reached the tree anyway.
+- **Installation is identifiable and reversible.** Writes to `settings.json` are merged and backed up; uninstall removes recorded package files only.
+- **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
+- **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
+
+The current suite contains **809 automated tests: 808 passing and 1 skipped**.
+
+## Verify
+
+```bash
+codex-bridge doctor
+```
+
+Output on a healthy host (trimmed):
+
+```text
+[ok] host: ~/.claude (user, exists)
+[ok] installation: @lyupro/codex-bridge@0.5.1 (matches package)
+[ok] files: 53 installed file(s) present
+[ok] rules: ~/.codex/rules/codex-bridge.rules (matches record)
+[ok] permissions: installed (24/24 own strings in allow/deny)
+[ok] hook:SubagentStop: matcher * -> ~/.lyupro/.codex-bridge/hooks/reply-guard.mjs
+[ok] hook:PreToolUse: matcher Agent|Task -> ~/.lyupro/.codex-bridge/hooks/order-gate.mjs
+[ok] hook:PreToolUse: matcher Write|Edit|MultiEdit|NotebookEdit -> ~/.lyupro/.codex-bridge/hooks/worktree-lock.mjs
+[ok] hook:PreToolUse: matcher Bash|PowerShell -> ~/.lyupro/.codex-bridge/hooks/prune-guard.mjs
+[ok] hook:PreToolUse: matcher TaskStop -> ~/.lyupro/.codex-bridge/hooks/stop-guard.mjs
+[warn] retention: Automatic cleanup is ON — run transport older than 30 days is removed to reclaim disk space.
+[ok] conventions: ~/.lyupro/.codex-bridge/conventions.md (found)
+[ok] codex: codex-cli 0.146.1
+[ok] node: 24.18.0 (requires >=24)
+[ok] runsRoot: ~/.claude/codex-runs
+[ok] liveRuns: 0 runs working right now
+```
+
+`doctor` reports the selected host, package source, installed files and guards, Codex availability, retention policy, permissions, live runs, and the current repository's run folder. The `agents` line is a read, not a file count: each installed definition is parsed and its `name` checked against the dispatcher it claims to be, because a definition the host cannot read is a dispatcher that does not exist while every other line still says `[ok]`. Content that drifts from the packaged definition is a failure, not a warning: `doctor` exits 1 and names `codex-bridge update --force`, because a host running someone else's agent files may be calling the runner in a form no permission rule matches.
+
+If a session answers `Agent type 'codex-build' not found`, a run can still be started without the dispatcher — the agent is a wrapper that types one command:
+
+```bash
+codex-bridge run --agent codex-build --repo <repository> --order-id <id> --scope <globs> --task-file <absolute path>
+```
+
+The trade-off is explicit: `order-gate` and `reply-guard` sit on the dispatcher call, so a direct run is unguarded and its result is judged by the worktree and the suite.
+
+## Update
+
+Update the global package, then refresh the selected host installation:
+
+```bash
+npm i -g @lyupro/codex-bridge
+codex-bridge update
+```
+
+`update` refreshes unchanged package files, refuses to overwrite operator edits unless `--force` is supplied, and removes obsolete files only when their installed fingerprint is unchanged.
+
+## Limitations
+
+- **Runs are not isolated from one another.** They share one worktree; guards prevent concurrent writers instead of creating sandboxes.
+- **A build run has a 25-minute deadline.** Work and artifacts survive a timeout, but the run may need an explicit continuation.
+- **A dispatcher verdict is not the work outcome.** Judge completion from the worktree and tests as well as the recorded verdict.
+
+Transport files from runs at least **30 days** old are pruned automatically when a new run starts. Configuration can change or disable that retention policy; reports, accounting, and worktree snapshots are retained.
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `install [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Install into a Claude Code host. |
+| `update [--scope user\|project] [--host <path>] [--dry-run] [--force]` | Refresh a recorded installation. |
+| `permissions [add\|remove] [--scope user\|project] [--host <path>]` | Inspect or manage optional shell rules. |
+| `uninstall [--scope user\|project] [--host <path>] [--dry-run]` | Remove recorded package files while preserving run artifacts. |
+| `doctor [--scope user\|project] [--host <path>] [--probe-contract]` | Diagnose the selected host and Codex connection. `--probe-contract` measures on a live host whether it still honours a hook refusal, and records the answer. |
+| `run <runner options> --task-file <abs path>` | Start or attach to a delegated run through the permission-stable package command. The task file carries the statement, the scout questions and the verification command; its path must be absolute. Piping the statement on stdin is the alternative channel, and the two cannot be combined. |
+| `projects [<name>] [--json]` | List projects or runs in the run store. |
+| `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]`<br>`prune --all-projects [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup, for one project or across the whole run store. |
+| `unlock [<project>\|--all]` | Close records whose runner is gone. |
+| `read <run>` | Render a run's structured event stream. |
+| `stop <run>` | Stop a run and record a `FAIL` verdict. |
+
+Both `codex-bridge` and `codexb` invoke the same command. Run `codex-bridge --help` for exact forms.
+
+### Development
+
+```bash
+git clone https://github.com/lyupro/codex-bridge.git
+cd codex-bridge
+git config core.hooksPath .githooks
+npm test
+```
+
+The Git hook enforces the 400-line source-file limit.
+
+## License
+
+[MIT](LICENSE)