@fusengine/harness 0.1.56 → 0.1.58

package/README.md

@@ -1,16 +1,14 @@
 # @fusengine/harness
 
-A **harness-agnostic enforcement engine** for AI coding agents. It ports the
-guard/gate logic of a Claude Code plugin into one reusable, **Bun-native** npm
-package that runs on **any** harness — Claude Code, OpenAI Codex, Cursor, Cline,
-Gemini CLI — plus a cli-mode fallback for Aider / Windsurf / OpenHands.
-
-It splits cleanly into a **pure policy core** (no harness coupling, fully tested)
-and **thin per-harness adapters** that map a hook payload to the policy and back
-to that harness's native response.
+A **governance layer for AI coding agents**: gates backed by cited evidence
+(not vibes), a decision-time lesson memory, verification receipts, and a
+one-shot gate metric — ported from a Claude Code plugin into one **Bun-native**
+npm package. The policy core is harness-agnostic; how much of it actually
+*enforces* depends on the harness's own hook system — see the
+[compatibility matrix](#compatibility) below before assuming parity across harnesses.
 
 ```
-detect → init (pre+post hooks) → `harness hook` → guards + APEX gates → native deny/ask
+detect → init (writes that harness's hook wiring) → `harness hook` → guards + APEX gates → native deny/ask/context
 ```
 
 ## Install
@@ -25,18 +23,37 @@ bun add @fusengine/harness      # Bun reads the TS source directly — no build
 
 ```sh
 cd your-project
-harness init                              # detects the harness, writes its pre+post hooks
-# The SOLID-read gate auto-activates from discovered skills (default marketplace: fusengine-plugins).
+harness init                              # detects the harness, writes its pre+post hook wiring
 export FUSE_HARNESS_MARKETPLACES=fusengine-plugins   # (optional) which marketplaces to auto-scan
 export FUSE_HARNESS_REFS=.claude/skills              # (optional) explicit refs dir, overrides auto-discovery
 ```
 
-That's it. `init` writes the wiring file for the detected harness
-(`.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`,
-`.gemini/settings.json`, or `.clinerules/hooks/PreToolUse`+`PostToolUse`), each
-pointing at `harness hook <id>`. From then on every tool-use is gated, and the
-session activity (agents run, docs consulted, refs read) is recorded
-automatically under `<project>/.harness/` (track, cache, memory).
+`init` writes the wiring file for the detected harness (`.claude/settings.json`,
+`.codex/hooks.json`, `.cursor/hooks.json`, `.gemini/settings.json`, or
+`.clinerules/hooks/PreToolUse`+`PostToolUse`) — for Claude Code, Codex, Cursor,
+Gemini CLI and Cline this covers **PreToolUse + PostToolUse only**
+(`src/init/templates.ts`); Hermes has no `init` runner because its config lives
+outside the project at `~/.hermes/config.yaml` (`src/adapters/hermes/index.ts:3-4`).
+The richer lifecycle (SessionStart, SubagentStart/Stop, Stop, PreCompact/PostCompact,
+TaskCompleted, TeammateIdle, PostToolUseFailure, InstructionsLoaded — 14 distinct
+Claude Code hook events in total, `src/runtime/lifecycle/dispatch.ts` +
+`src/runtime/handle.ts:56-80`) is **implemented** in the runtime but only fires
+when something wires those extra hook events into `.claude/settings.json` — either
+by hand, or via the fusengine-plugins marketplace this repo is itself developed
+under (its ~11 sibling plugins each add their own event, `src/runtime/burst-window.ts:5-11`).
+
+**Where state lives** (two separate roots — this changed across 0.1.34→0.1.51,
+don't assume either the old or the "everything in one place" story):
+
+- Session track, deny-loop/one-shot sidecars: **out-of-tree**, under
+  `~/.fuse-harness/state/<8-char-md5-of-project-path>/` (`src/runtime/paths.ts:5-6,41-43`) —
+  deliberately outside the repo so the protected-path guard never has to bless
+  writes to its own enforcement state.
+- MCP/WebFetch response cache and the curated `MEMORY/LESSON.md`-equivalent lessons
+  file: still **in-tree**, under `<project>/.harness/{cache,memory}`
+  (`src/config/layout.ts:15-26`) — `.harness/` is gitignored except
+  `memory/LESSON.md`, which is meant to be committed (`STATE_GITIGNORE`,
+  `src/config/layout.ts:10`).
 
 ### CLI
 
@@ -66,7 +83,7 @@ Any consumer `hooks.json` / `settings.json` that runs the harness via `bunx`
 
 ```jsonc
 // .claude/settings.json — correct: exact pin
-"command": "bunx @fusengine/harness@0.1.41 hook claude"
+"command": "bunx @fusengine/harness@0.1.56 hook claude"
 // WRONG — may silently keep running a stale global install:
 "command": "bunx @fusengine/harness hook claude"
 ```
@@ -75,9 +92,8 @@ Any consumer `hooks.json` / `settings.json` that runs the harness via `bunx`
 prefer an already-installed **global** copy over npm-latest, and publishing a new
 version updates neither that global nor the bunx cache (`bun pm cache rm` does
 **not** remove the global). A hook wired without an exact pin can therefore keep
-executing an old harness indefinitely after you publish a fix — the failure is
-silent because the smoke test (importing the local dist) never exercises the
-`bunx`-resolved binary. Pinning `@X.Y.Z` forces the exact version to resolve.
+executing an old harness indefinitely after you publish a fix. Pinning `@X.Y.Z`
+forces the exact version to resolve.
 
 Run `harness doctor` to see which version is actually executing and whether npm
 has a newer one:
@@ -85,11 +101,11 @@ has a newer one:
 ```sh
 harness doctor
 # @fusengine/harness doctor
-#   running:    0.1.41
+#   running:    0.1.56
 #   package:    /Users/you/.bun/install/global/node_modules/@fusengine/harness
 #   runtime:    /Users/you/.bun/bin/bun
-#   npm latest: 0.1.42
-#   ! stale — npm serves 0.1.42. Pin "@fusengine/harness@0.1.42" in hooks.json.
+#   npm latest: 0.1.57
+#   ! stale — npm serves 0.1.57. Pin "@fusengine/harness@0.1.57" in hooks.json.
 ```
 
 If `doctor` reports a stale global, clear it and re-pin:
@@ -100,29 +116,88 @@ bun remove -g @fusengine/harness && bun pm cache rm
 
 [oven-sh/bun#5791]: https://github.com/oven-sh/bun/issues/5791
 
+## Compatibility
+
+**There is no "runs the same on any harness."** Each row is a real ceiling, not
+a formatting nuance — read it before assuming a gate that works on Claude Code
+also works elsewhere.
+
+| Harness | PreToolUse coverage | Lifecycle (Session/Subagent/Stop/Compact/…) | Known limit |
+|---|---|---|---|
+| **claude-code** | Full: `evaluate` + APEX gates via `handleHook` (`src/adapters/claude/index.ts`) | 14 event types implemented (`dispatch.ts`) — fires once wired into `.claude/settings.json` beyond the `init` default | None found; richer lifecycle needs manual/marketplace wiring (see Quickstart) |
+| **codex** | Bash gated reliably; **`apply_patch` edits are now gated too** — the patch text is parsed per file (`adapters/codex/apply-patch.ts`), each hunk runs the file gates and ONE violating hunk denies the whole patch (`runtime/apply-patch-gate.ts`, sim scenario 22 incl. the multi-file smuggling case). `ask` prompts are **downgraded to explicit deny** (`respond.ts`, sim scenario 23) because Codex fails open on unsupported shapes. | Not wired by `harness init codex` (PreToolUse `Bash\|apply_patch` + PostToolUse only, `src/init/templates.ts:29-38`) | Upstream caveat: Codex itself does not always enforce a correct `apply_patch` deny (openai/codex#27833) — we emit the right verdict; enforcement is theirs. No interactive `ask`. |
+| **cursor** | `beforeShellExecution` can deny/ask (shell only, `cursor/index.ts:16-21`) | none | File edits are **advisory only**: `afterFileEdit` always returns `allow` + a `user_message` correction on violation — a `deny` there has no proven effect (hook was "informational only" at launch, and Cursor's deny-enforcement for file ops is confirmed broken upstream, forum.cursor.com/t/154377). Human sees the message; the model is never re-informed. Platform ceiling, documented in `cursor/index.ts`. |
+| **gemini-cli** | `BeforeTool` denies via `{decision:"deny",reason}` (`gemini/index.ts:22-36`) | none | Thin stateless adapter — no session track, no APEX gates wired through it. |
+| **cline** | `PreToolUse` only; block → `{cancel:true}`, non-block → `contextModification` (`cline/index.ts:24-36`) | none | Same as gemini-cli: stateless guard only. |
+| **hermes** | `pre_tool_call` proven: reuses the Claude stdin reader, blocks via `{decision:"block",reason}` (`hermes/index.ts:12-36`) | untested — no lifecycle dispatch wired for Hermes in this repo | `ask`/`inform` degrade to non-blocking `{context}` — Hermes "has no interactive ask state" (`hermes/index.ts:27-28`). |
+
 ## What it enforces
 
-Ten portable guards + the APEX gate chain, all evaluated before a tool runs:
+Guard/gate chain evaluated before a tool runs (`src/policy/guards/index.ts`,
+`src/policy/apex-gates.ts`, `src/policy/evaluate.ts`):
 
 | Guard / gate | Fires on |
 |---|---|
-| file-size (SOLID) | a code file over `FUSE_SOLID_MAX_LINES` (default 100) |
-| git | destructive git (`push --force`, `reset --hard`, …) |
-| bash-write | `python3 -c` / `sed -i` / redirects to code files |
-| install | `npm/pip/brew/...` installs (asks) |
 | security | `rm -rf /`, fork bombs, `curl \| sh`; `sudo` (asks) |
+| protected-path | edits to `.claude/plugins\|logs\|cache`, `.git/`, the harness's own state dirs |
+| bash-write | `python3 -c` / `sed -i` / redirects to code files |
 | interface-separation | top-level interface/type/protocol in a component/controller |
-| protected-path | edits to `.claude/plugins\|logs\|cache`, `.git/` |
+| install | `npm/pip/brew/...` installs (asks) |
+| git | destructive git (`push --force`, `reset --hard`, …) — block; routine git — ask |
+| file-size (SOLID) | a code file over `FUSE_SOLID_MAX_LINES` (default 100) |
+| APEX brainstorm | creating a new file without brainstorming (when flagged) |
 | APEX freshness | `explore-codebase` + `research-expert` not run within the window |
-| APEX doc-consulted | no doc source (Context7 / Exa / fuse-browser / WebSearch / WebFetch) consulted this session |
-| APEX solid-read | required SOLID refs (auto-discovered, or `FUSE_HARNESS_REFS`) not read |
-| framework sub-skill | framework / shadcn / Tailwind code whose required skill (`skills/<name>/`) wasn't read this session |
+| APEX doc-consulted | Context7 **and** Exa not consulted this session (a web-only fallback also passes) |
+| APEX solid-read | required SOLID refs (auto-discovered, or `FUSE_HARNESS_REFS`) not read within the TTL |
+| framework sub-skill | framework / shadcn / Tailwind code whose required skill wasn't read this session |
 | Gemini MCP (opt-in) | hand-written Tailwind UI without a `mcp__gemini-design__*` call — only when `FUSE_ENFORCE_GEMINI_MCP` is set |
-| brainstorm | creating a new file without brainstorming (when flagged) |
 | MCP verbosity / cache | caps exa `numResults`; serves a fresh cached MCP/WebFetch result |
 
-A trivial-edit fast path lets a few tiny (< 5-line, non-`replace_all`) edits
-through per window without the full APEX gates.
+A trivial-edit fast path lets a few tiny (< 5-line, non-`replace_all`) `Edit`s
+through per window without the full APEX gates (`Write` is never trivial).
+
+## Beyond gating: memory, receipts, one-shot metric
+
+Features shipped since 0.1.44, each with its own test:
+
+- **Deny-loop breaker** — an identical retried call that was already denied gets
+  a rewritten `[REPEAT] … STOP` message forcing a different approach, instead of
+  looping silently (`src/policy/deny-loop.ts`, `test/deny-loop.test.ts`).
+- **Burst-window dedup** — every deployed plugin registers its own hook, so one
+  real tool call can fan out to ~11 sibling processes; a same-op record within
+  2s is folded into the first instead of re-counted (`src/runtime/burst-window.ts`,
+  `test/burst-dedup.test.ts`).
+- **One-shot gate metric** — every gate outcome (deny or its later fix) lands in
+  a 7-day sidecar keyed by a content-free op hash, so a deny→allow transition is
+  visible (`src/tracking/one-shot.ts`, `test/one-shot.test.ts`).
+- **Verification receipts** — a `tsc`/test run is captured from PostToolUse Bash
+  output; `TaskCompleted` **refuses** a "done" over modified code files without a
+  fresh passing receipt (`src/tracking/receipts.ts`, `test/receipts.test.ts`).
+- **Decision-time lessons** — a `MEMORY/LESSON.md` bullet tagged with
+  `[TRIGGERS tool:… path:… error:… keyword:…]` is injected as `additionalContext`
+  the moment a matching call is about to repeat a known mistake, cooldown-guarded
+  (`src/policy/lessons/lesson-gate.ts`).
+- **Failure lessons** *(Claude-Code-only — no `PostToolUseFailure` hook on Codex/Hermes,
+  `src/runtime/lifecycle/failure-lesson.ts:8-9`)* — a tool failure's error message is
+  matched against `error:`-triggered lessons and injected on the spot
+  (`test/failure-lesson.test.ts`, `test/sim/scenarios/17-failure-lesson.json`).
+- **TeammateIdle anti-false-done** *(Claude-Code-only, `teammate-idle-check.ts:9-10`)* —
+  files a teammate announced as changed are checked against disk; a missing file
+  warns the lead before it's treated as done (`test/teammate-idle-check.test.ts`).
+- **PostCompact re-injection** — after context compaction, the reconciliation
+  snapshot is re-sent with a "reread files before editing" reminder, deduped per
+  session (`src/runtime/lifecycle/post-compact.ts`, `test/post-compact.test.ts`).
+- **Reconciliation snapshot at SessionStart** — git state, running harness
+  version + drift vs. npm, `.claude/BOARD.md`, and the one-shot summary, each
+  collector isolated so one failure can't blank the rest
+  (`src/runtime/lifecycle/snapshot/index.ts`, `test/snapshot.test.ts`).
+- **Injection budget cap** — harness-produced context fragments (lessons,
+  snapshot, APEX task context) are capped at ~8000 chars each; owner-authored
+  content (CLAUDE.md/rules) is never capped
+  (`src/runtime/inject-budget.ts`, `test/inject-budget.test.ts`).
+- **Hook simulator** — 18 end-to-end scenarios (payload in, expected verdict out)
+  replayed against the real CLI in both `src` and built `dist` modes in CI
+  (`test/sim/README.md`, `test/sim/scenarios/`).
 
 ### Environment
 
@@ -130,11 +205,15 @@ through per window without the full APEX gates.
 |---|---|
 | `FUSE_SOLID_MAX_LINES` | SOLID file-size limit (default `100`). |
 | `FUSE_HARNESS_REFS` | Explicit `path.delimiter`-list of `.md` SOLID-reference dirs → activates `solidReadGate`. Overrides auto-discovery. |
-| `FUSE_HARNESS_MARKETPLACES` | Comma-list of marketplace names whose `solid-*` skill refs are auto-discovered when `FUSE_HARNESS_REFS` is unset (default `fusengine-plugins`; an absent marketplace contributes nothing). Standalone `.claude`/`.codex`/`.cursor`/`.agents` skills are always scanned. |
-| `FUSE_ENFORCE_TTL_SEC` | APEX freshness window in seconds. |
-| `FUSE_LESSONS_THROTTLE_MIN` | Lessons-injection throttle (memory module). |
-| `FUSE_ENFORCE_GEMINI_MCP` | **Opt-in (default off).** `1`/`true` blocks hand-written Tailwind UI (`.tsx/.jsx/.vue/.svelte`, ≥3 utility classes) until a `mcp__gemini-design__*` call is made this session. Read fresh per call. |
-| `RALPH_MODE` | **Opt-in (default off).** `1`/`true` enables autonomous "Ralph" mode: exempts the safe git commands (`add`/`commit`/`checkout -b`/`status`/`diff`/`log`) from the confirmation ASK and auto-approves project installs. Destructive git (force-push, `reset --hard`) and system installs still gate. |
+| `FUSE_HARNESS_MARKETPLACES` | Comma-list of marketplace names whose `solid-*` skill refs are auto-discovered when `FUSE_HARNESS_REFS` is unset (default `fusengine-plugins`). |
+| `FUSE_ENFORCE_TTL_SEC` | APEX freshness window in seconds (default `120`). |
+| `FUSE_LESSONS_THROTTLE_MIN` | Lessons-injection throttle, minutes (default `5`). |
+| `FUSE_ENFORCE_GEMINI_MCP` | **Opt-in (default off).** Blocks hand-written Tailwind UI (`.tsx/.jsx/.vue/.svelte`) until a `mcp__gemini-design__*` call is made this session. Read fresh per call (`src/policy/gemini-mcp-gate.ts`). |
+| `FUSE_DESIGN_GEMINI` | **Opt-in (default off), a *different* gate from the one above.** Enables the design-pipeline's own Gemini gates (`create_frontend` validation + "generate before hand-writing HTML/CSS") — inert unless a design agent is active (`src/policy/design/gates.ts:58-60`, see [docs/design.md](docs/design.md)). |
+| `FUSE_MCP_TTL_SEC` | MCP (Context7/Exa) cache freshness, seconds (default 48h, `src/runtime/mcp-key.ts`). |
+| `FUSE_WEBFETCH_TTL_SEC` | WebFetch cache freshness, seconds (default 24h — pages stale faster than docs). |
+| `RALPH_MODE` | **Opt-in (default off).** Exempts safe git commands (`add`/`commit`/`checkout -b`/`status`/`diff`/`log`) from the confirmation ask and auto-approves project installs. Destructive git (force-push, `reset --hard`) and system installs still gate. |
+| `CLAUDE_PROJECT_DIR` | Overrides the project root used to hash the out-of-tree state dir (`src/runtime/paths.ts:20`). |
 
 ## Library usage
 
@@ -155,7 +234,8 @@ const prompt = await gate({ sessionId, framework: "react", tool: "Write",
 ```
 
 The `Prompt` it returns (`{ kind: "block" | "ask" | "inform", title, reason, actions? }`)
-is portable; each adapter maps it to the harness's native shape.
+is portable; each adapter maps it to the harness's native shape — but, per the
+compatibility matrix above, not every harness can act on every `kind`.
 
 ### Extend it
 
@@ -177,15 +257,15 @@ registerGuard(({ tool, command }) =>
 | Subpath | What |
 |---------|------|
 | `./detect` | `detectHarness()` / `detectMode()` — 13 harnesses, `hook` vs `cli`. |
-| `./policy` | `evaluate(ctx)`, the 10 guards, `evaluateApex`, framework detection. |
+| `./policy` | `evaluate(ctx)`, the guard chain, `evaluateApex`, framework detection. |
 | `./runtime` | `handleHook`, `gate`, `recordActivity`, `activityFor`, per-harness storage + MCP intercept. |
-| `./tracking` | Session track: `recordAgent/Doc/RefRead`, `agentsFresh`, trivial-edit counter. |
+| `./tracking` | Session track: `recordAgent/Doc/RefRead`, `agentsFresh`, receipts, one-shot metric. |
 | `./refs` | Frontmatter parse, `loadRefs(dir)`, SOLID ref scoring/routing. |
 | `./prompt` | The portable `Prompt` type + `formatPrompt`. |
 | `./cache` | MCP/WebFetch cache: key, lookup/store, compaction, response extraction. |
 | `./memory` | Per-project "never reproduce" lessons. |
 | `./config` `./util` `./state` `./statusline` `./freshness` `./init` `./cli` | env config, project-root, locks, statusline, doc-freshness, wiring templates, staged checks. |
-| `./adapters/{claude,codex,cursor,cline,gemini}` | Thin per-harness adapters. |
+| `./adapters/{claude,codex,cursor,cline,gemini,hermes}` | Thin per-harness adapters — see [Compatibility](#compatibility) for what each can actually enforce. |
 
 ## Documentation
 
@@ -193,20 +273,40 @@ registerGuard(({ tool, command }) =>
 |-------|------|
 | [docs/index.md](https://github.com/fusengine/harness/blob/main/docs/index.md) | architecture overview + map |
 | [docs/detect.md](https://github.com/fusengine/harness/blob/main/docs/detect.md) | harness detection (`hook` vs `cli`) |
-| [docs/policy.md](https://github.com/fusengine/harness/blob/main/docs/policy.md) | `evaluate`, file-size, framework, APEX gates |
+| [docs/policy.md](https://github.com/fusengine/harness/blob/main/docs/policy.md) | `evaluate`, the guard chain, framework, APEX gates |
 | [docs/guards.md](https://github.com/fusengine/harness/blob/main/docs/guards.md) | the guard chain, `registerGuard`, fail-closed |
-| [docs/runtime.md](https://github.com/fusengine/harness/blob/main/docs/runtime.md) | `handleHook`, `gate`, tracking, MCP intercept |
-| [docs/config.md](https://github.com/fusengine/harness/blob/main/docs/config.md) | env config (TTL, max-lines, refs dir) |
+| [docs/runtime.md](https://github.com/fusengine/harness/blob/main/docs/runtime.md) | `handleHook`, `gate`, tracking, MCP intercept, state paths |
+| [docs/config.md](https://github.com/fusengine/harness/blob/main/docs/config.md) | env config (TTL, max-lines, refs dir, Gemini opt-ins) |
 | [docs/modules.md](https://github.com/fusengine/harness/blob/main/docs/modules.md) | cache · refs · state · memory · statusline · util |
-| [docs/adapters.md](https://github.com/fusengine/harness/blob/main/docs/adapters.md) | adapters + `harness init`/`hook` wiring |
+| [docs/adapters.md](https://github.com/fusengine/harness/blob/main/docs/adapters.md) | adapters, compatibility, `harness init`/`hook` wiring |
+| [docs/design.md](https://github.com/fusengine/harness/blob/main/docs/design.md) | design-agent pipeline — state machine, gates, opt-in Gemini |
 | [CHANGELOG.md](https://github.com/fusengine/harness/blob/main/CHANGELOG.md) | release history |
 
 Run `bun run docs:api` for the generated typedoc API reference.
 
+## Known limitations
+
+- **Codex file edits are not gated.** The SOLID/file-size gate keys off
+  `tool_input.file_path`, which Codex's `apply_patch` call never supplies — only
+  Bash is reliably gated on Codex today (see [Compatibility](#compatibility)).
+- **Cursor file edits are advisory-only.** `afterFileEdit` fires after the edit
+  already happened — a platform limit, not something this harness can work around.
+- **Hook fan-out is mitigated, not eliminated.** The ~11-sibling-plugin burst is
+  deduped within a 2s window (`BURST_DEDUP_MS`), but that window is a heuristic,
+  not a protocol guarantee — an unusually slow fan-out could in theory land
+  outside it.
+- **Sidechain hook reliability is a platform issue, worked around, not fixed.**
+  Sub-agent `PostToolUse` hooks don't always fire on Claude Code (documented
+  platform issues #43612/#27655/#34692); `SubagentStop` transcript harvesting
+  (`src/freshness/evidence-harvest-io.ts`) compensates, but only at that
+  checkpoint, not continuously.
+- **Hermes coverage beyond `pre_tool_call` is unverified** — no lifecycle events
+  have been proven against a live Hermes install in this repo.
+
 ## Develop
 
 ```sh
-bun test            # 117 tests
+bun test            # 484 tests (94 files)
 bunx tsc --noEmit   # typecheck (isolatedDeclarations)
 bun run build       # dist + .d.mts via tsdown (for Node/bundler consumers)
 bun run docs:api    # generate the typedoc API reference

package/dist/adapters/claude/index.mjs

@@ -1,2 +1,2 @@
-import { a as fileSizeGuard, c as readClaudeInput, i as denyResponse, l as systemMessage, n as blockResponse, o as guard, r as contextResponse, s as informResponse, t as attachSystemMessage, u as toClaudeResponse } from "../../claude-BxC9semG.mjs";
+import { a as fileSizeGuard, c as readClaudeInput, i as denyResponse, l as systemMessage, n as blockResponse, o as guard, r as contextResponse, s as informResponse, t as attachSystemMessage, u as toClaudeResponse } from "../../claude-BLuab-tR.mjs";
 export { attachSystemMessage, blockResponse, contextResponse, denyResponse, fileSizeGuard, guard, informResponse, readClaudeInput, systemMessage, toClaudeResponse };

package/dist/adapters/cline/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-CNAzgxnN.mjs";
+import { t as evaluate } from "../../evaluate-BgFLlqrs.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/cline/index.ts
 /**

package/dist/adapters/codex/index.d.mts

@@ -1,2 +1,14 @@
-import { a as denyResponse, i as contextResponse, l as readClaudeInput, s as guard, t as ClaudeHookInput } from "../../index-DZCLmSoO.mjs";
-export { type ClaudeHookInput as CodexHookInput, contextResponse, denyResponse, guard, readClaudeInput as readCodexInput };
+import { t as Prompt } from "../../types-DVbIl9md.mjs";
+import { a as denyResponse, i as contextResponse, l as readClaudeInput, t as ClaudeHookInput } from "../../index-DZCLmSoO.mjs";
+
+//#region src/adapters/codex/index.d.ts
+/** Render a portable {@link Prompt} as a Codex hook response, `ask` → explicit deny. */
+declare function toCodexResponse(prompt: Prompt): string;
+/**
+* Run the bundled policy over a Codex payload and return the native response
+* string (deny/additionalContext), or null to allow. `apply_patch` is fanned
+* into per-file checks; every other tool routes through the portable policy.
+*/
+declare function guard(input: ClaudeHookInput): string | null;
+//#endregion
+export { type ClaudeHookInput as CodexHookInput, contextResponse, denyResponse, guard, readClaudeInput as readCodexInput, toCodexResponse };

package/dist/adapters/codex/index.mjs

@@ -1,2 +1,66 @@
-import { c as readClaudeInput, i as denyResponse, o as guard, r as contextResponse } from "../../claude-BxC9semG.mjs";
-export { contextResponse, denyResponse, guard, readClaudeInput as readCodexInput };
+import { f as countLines } from "../../home-state-D0RLWP8J.mjs";
+import { t as evaluate } from "../../evaluate-BgFLlqrs.mjs";
+import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
+import { t as parseApplyPatch } from "../../apply-patch-CIS2EZ_q.mjs";
+import { c as readClaudeInput, i as denyResponse, r as contextResponse } from "../../claude-BLuab-tR.mjs";
+//#region src/adapters/codex/index.ts
+/**
+* OpenAI Codex CLI adapter (hook-mode). Codex's `PreToolUse` hook (since 2026)
+* uses the SAME envelope as Claude Code — `tool_name`/`tool_input` in,
+* `hookSpecificOutput.permissionDecision` out — so it shares Claude's readers.
+* Config lives at `.codex/hooks.json`.
+*
+* Two Codex-specific quirks this adapter closes (audit 2026-07-06):
+* 1. `apply_patch` is Codex's PRIMARY edit primitive; its payload is a freeform
+*    patch in `tool_input.command`, with NO `file_path`/`content`. Claude's guard
+*    keyed off those fields, so the SOLID/DRY gates saw NOTHING (enforcement 0%).
+*    Here the patch is parsed and each file is judged (one violating hunk denies).
+* 2. Codex parses but NEVER honors `permissionDecision: "ask"` (deny-only) — an
+*    `ask` silently fails open (verified: `pre_tool_use.rs` test
+*    `unsupported_permission_decision_fails_open`). Every `ask` is downgraded to
+*    an explicit deny.
+*/
+const ASK_PREFIX = "[downgraded from ask — Codex has no interactive approval]";
+/** Render a portable {@link Prompt} as a Codex hook response, `ask` → explicit deny. */
+function toCodexResponse(prompt) {
+	const message = formatPrompt(prompt);
+	if (prompt.kind === "inform") return contextResponse("PreToolUse", message);
+	if (prompt.kind === "ask") return denyResponse("PreToolUse", `${ASK_PREFIX}\n${message}`);
+	return denyResponse("PreToolUse", message);
+}
+/** OR the per-file SOLID verdict of an `apply_patch` payload — first block wins. */
+function applyPatchPrompt(command) {
+	for (const f of parseApplyPatch(command)) {
+		if (f.op === "delete") continue;
+		const r = evaluate({
+			tool: f.op === "add" ? "Write" : "Edit",
+			filePath: f.path,
+			content: f.content,
+			existingLines: countLines(f.content)
+		});
+		if (r.decision !== "allow" && r.prompt) return r.prompt;
+	}
+	return null;
+}
+/** Portable single-tool verdict for non-`apply_patch` Codex tools. */
+function resolvePrompt(input) {
+	const i = input.tool_input;
+	const r = evaluate({
+		tool: input.tool_name ?? "Write",
+		filePath: i?.file_path,
+		content: i?.content ?? i?.new_string,
+		command: i?.command
+	});
+	return r.decision === "allow" || !r.prompt ? null : r.prompt;
+}
+/**
+* Run the bundled policy over a Codex payload and return the native response
+* string (deny/additionalContext), or null to allow. `apply_patch` is fanned
+* into per-file checks; every other tool routes through the portable policy.
+*/
+function guard(input) {
+	const prompt = input.tool_name === "apply_patch" ? applyPatchPrompt(input.tool_input?.command ?? "") : resolvePrompt(input);
+	return prompt ? toCodexResponse(prompt) : null;
+}
+//#endregion
+export { contextResponse, denyResponse, guard, readClaudeInput as readCodexInput, toCodexResponse };

package/dist/adapters/cursor/index.d.mts

@@ -15,6 +15,19 @@ interface CursorEditPayload {
   }[];
 }
 /**
+* `afterFileEdit` stdout response. Its schema (cursor.com/docs/hooks#afterFileEdit)
+* is DELIBERATELY narrower than the "before" hooks: `permission` + `user_message`
+* only — there is NO `agent_message` and NO `updated_input`. Since the edit is
+* already on disk when this "after" hook fires, `deny` cannot revert it and the
+* correction reaches only the HUMAN (`user_message`), never the model — so this
+* path is strictly ADVISORY, not an enforceable gate.
+*/
+interface CursorEditResponse {
+  permission: "allow" | "deny";
+  /** User-visible correction — snake_case (#141516); the only channel afterFileEdit exposes. */
+  user_message?: string;
+}
+/**
 * `beforeShellExecution` stdout response. Message keys are snake_case:
 * Cursor silently ignores camelCase `userMessage`/`agentMessage` (#141516,
 * regression persists through v2.0.77+ — forum #142589), matching the
@@ -32,9 +45,24 @@ interface CursorResponse {
 //#region src/adapters/cursor/index.d.ts
 /** Guard a shell command (git/install policies). */
 declare function beforeShellExecution(payload: CursorShellPayload): CursorResponse;
-/** Observe a file edit (Cursor cannot block here). Returns the verdict for logging. */
-declare function afterFileEdit(payload: CursorEditPayload): {
-  violation: string | null;
-};
+/**
+* Advise on a file edit AFTER Cursor has written it — a HUMAN-VISIBLE audit note,
+* never a gate. This is an "after" hook: the edit is already on disk. On a
+* SOLID/DRY violation we surface the correction through `user_message` (the only
+* channel afterFileEdit exposes — no `agent_message`, so the model is never
+* re-informed) while ALWAYS returning `permission: "allow"`.
+*
+* We deliberately never emit `permission: "deny"` here, for two distinct reasons:
+* (1) structural — afterFileEdit was "informational only" at launch (Chacon,
+* Cursor hooks beta 1.7, 2025-09: no channel to stop the agent), and a post-write
+* deny has no documented rollback; (2) empirical — Cursor staff confirm the
+* deny-enforcement path is broken for file operations (forum.cursor.com/t/154377,
+* v2.6.18, 2026-03, open) — proven for file READS, plausibly the same for writes.
+* So a `deny` would be a false blocking signal; `allow` + `user_message` is the
+* only proven-safe shape.
+* @param payload - The `afterFileEdit` stdin payload.
+* @returns Always an allow; carries the user-visible correction on a violation.
+*/
+declare function afterFileEdit(payload: CursorEditPayload): CursorEditResponse;
 //#endregion
-export { type CursorEditPayload, type CursorResponse, type CursorShellPayload, afterFileEdit, beforeShellExecution };
+export { type CursorEditPayload, type CursorEditResponse, type CursorResponse, type CursorShellPayload, afterFileEdit, beforeShellExecution };

package/dist/adapters/cursor/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-CNAzgxnN.mjs";
+import { t as evaluate } from "../../evaluate-BgFLlqrs.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/cursor/index.ts
 /**
@@ -23,7 +23,24 @@ function beforeShellExecution(payload) {
 		agent_message: msg
 	};
 }
-/** Observe a file edit (Cursor cannot block here). Returns the verdict for logging. */
+/**
+* Advise on a file edit AFTER Cursor has written it — a HUMAN-VISIBLE audit note,
+* never a gate. This is an "after" hook: the edit is already on disk. On a
+* SOLID/DRY violation we surface the correction through `user_message` (the only
+* channel afterFileEdit exposes — no `agent_message`, so the model is never
+* re-informed) while ALWAYS returning `permission: "allow"`.
+*
+* We deliberately never emit `permission: "deny"` here, for two distinct reasons:
+* (1) structural — afterFileEdit was "informational only" at launch (Chacon,
+* Cursor hooks beta 1.7, 2025-09: no channel to stop the agent), and a post-write
+* deny has no documented rollback; (2) empirical — Cursor staff confirm the
+* deny-enforcement path is broken for file operations (forum.cursor.com/t/154377,
+* v2.6.18, 2026-03, open) — proven for file READS, plausibly the same for writes.
+* So a `deny` would be a false blocking signal; `allow` + `user_message` is the
+* only proven-safe shape.
+* @param payload - The `afterFileEdit` stdin payload.
+* @returns Always an allow; carries the user-visible correction on a violation.
+*/
 function afterFileEdit(payload) {
 	const content = payload.edits?.map((e) => e.new_string).join("\n") ?? "";
 	const r = evaluate({
@@ -31,7 +48,11 @@ function afterFileEdit(payload) {
 		filePath: payload.file_path,
 		content
 	});
-	return { violation: r.decision === "deny" ? r.message : null };
+	if (r.decision !== "deny" || !r.prompt) return { permission: "allow" };
+	return {
+		permission: "allow",
+		user_message: formatPrompt(r.prompt)
+	};
 }
 //#endregion
 export { afterFileEdit, beforeShellExecution };

package/dist/adapters/gemini/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-CNAzgxnN.mjs";
+import { t as evaluate } from "../../evaluate-BgFLlqrs.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/gemini/index.ts
 /**

package/dist/adapters/hermes/index.mjs

@@ -1,2 +1,2 @@
-import { n as readHermesInput, r as toHermesResponse, t as guard } from "../../hermes-DWXCRFZU.mjs";
+import { n as readHermesInput, r as toHermesResponse, t as guard } from "../../hermes-CyhCYqD7.mjs";
 export { guard, readHermesInput, toHermesResponse };

package/dist/apply-patch-CIS2EZ_q.mjs

@@ -0,0 +1,81 @@
+//#region src/adapters/codex/apply-patch.ts
+const BEGIN = "*** Begin Patch";
+const END = "*** End Patch";
+const ADD = "*** Add File: ";
+const DEL = "*** Delete File: ";
+const UPD = "*** Update File: ";
+const MOVE = "*** Move to: ";
+const EOF = "*** End of File";
+const ENV = "*** Environment ID: ";
+/**
+* Parse a Codex freeform patch into its per-file changes. Lenient on whitespace
+* around structural markers (as Codex's own parser is); returns `[]` when no
+* recognizable hunk is present (malformed input fails open, not closed).
+* @param text - Raw patch body from `tool_input.command`.
+* @returns One {@link PatchedFile} per Add/Update/Delete hunk, in order.
+*/
+function parseApplyPatch(text) {
+	const files = [];
+	let cur = null;
+	let buf = [];
+	const flush = () => {
+		if (cur) {
+			cur.content = buf.join("\n");
+			files.push(cur);
+		}
+		cur = null;
+		buf = [];
+	};
+	for (const line of text.split("\n")) {
+		const marker = line.trimStart();
+		if (marker === BEGIN || marker.startsWith(ENV)) continue;
+		if (marker === END) {
+			flush();
+			continue;
+		}
+		if (marker.startsWith(ADD)) {
+			flush();
+			cur = {
+				path: marker.slice(14).trim(),
+				content: "",
+				op: "add"
+			};
+			continue;
+		}
+		if (marker.startsWith(DEL)) {
+			flush();
+			files.push({
+				path: marker.slice(17).trim(),
+				content: "",
+				op: "delete"
+			});
+			continue;
+		}
+		if (marker.startsWith(UPD)) {
+			flush();
+			cur = {
+				path: marker.slice(17).trim(),
+				content: "",
+				op: "update"
+			};
+			continue;
+		}
+		if (marker.startsWith(MOVE)) {
+			if (cur) cur.path = marker.slice(13).trim();
+			continue;
+		}
+		if (marker === EOF || !cur) continue;
+		if (cur.op === "add") {
+			if (line.startsWith("+")) buf.push(line.slice(1));
+			continue;
+		}
+		if (line.startsWith("@@")) continue;
+		if (line.startsWith("+")) buf.push(line.slice(1));
+		else if (line.startsWith("-")) continue;
+		else buf.push(line.startsWith(" ") ? line.slice(1) : line);
+	}
+	flush();
+	return files;
+}
+//#endregion
+export { parseApplyPatch as t };

package/dist/{claude-BxC9semG.mjs → claude-BLuab-tR.mjs}

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-CNAzgxnN.mjs";
+import { t as evaluate } from "./evaluate-BgFLlqrs.mjs";
 import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";

package/dist/cli/bin.mjs

@@ -2,9 +2,9 @@
 import { r as loadDotenv, s as resolveTtlSec } from "../dotenv-Jj8aL1FL.mjs";
 import { t as detectHarness } from "../harness-Cb9xR8dC.mjs";
 import { t as claudeHome } from "../home-state-D0RLWP8J.mjs";
-import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-DZvP_9xB.mjs";
+import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-B4b2_7Qm.mjs";
 import { n as writeInitFile, t as initFor } from "../run-Do2JltgU.mjs";
-import { F as runDoctor, I as runningVersion, L as versionBanner, Lt as todayUtc, t as handleHook } from "../handle-CoyvRORV.mjs";
+import { J as runningVersion, Lt as todayUtc, Y as versionBanner, q as runDoctor, t as handleHook } from "../handle-BdOh1jPG.mjs";
 import { delimiter, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

package/dist/cli/index.mjs

@@ -1,2 +1,2 @@
-import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-DZvP_9xB.mjs";
+import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-B4b2_7Qm.mjs";
 export { checkStaged, stagedContent, stagedFiles };

package/dist/{evaluate-CNAzgxnN.mjs → evaluate-BgFLlqrs.mjs}

@@ -436,7 +436,7 @@ const CODE_MUTATORS = [
 		desc: "awk in-place edit"
 	},
 	{
-		re: /\bpatch\b/,
+		re: /(?:^|[\n;&|(])\s*patch(?=\s|<|[;&|)>]|$)/,
 		desc: "patch file modification"
 	},
 	{