@sriinnu/omit 0.4.1 → 0.6.0

package/.cursor/rules/omit.mdc

@@ -1,5 +1,5 @@
 ---
-description: omit: Omit needless code. Draft less, cite everything, cut last.
+description: "omit: Omit needless code. Draft less, cite everything, cut last."
 alwaysApply: true
 ---
 

package/.github/workflows/omit.yml

@@ -0,0 +1,21 @@
+name: omit
+
+on: pull_request
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  omit:
+    runs-on: ubuntu-latest
+    # A fork's PR gets a read-only token, so the comment could only fail there.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # `./`, not a tag: this runs the PR's own action.yml end to end, which
+      # nothing else does — test.yml only proves the file parses.
+      - uses: ./

package/.github/workflows/publish.yml

@@ -5,6 +5,11 @@ on:
     tags:
       - "v*.*.*"
 
+# No npm token anywhere. npm's trusted publishing has this workflow prove who
+# it is with a short-lived OIDC token GitHub mints for the run (that is what
+# id-token: write allows), and npm checks it against the publisher configured
+# for the package: sriinnu/omit, publish.yml. A stored token expired twice and
+# stopped two releases after their tags were already pushed.
 permissions:
   contents: read
   id-token: write
@@ -17,9 +22,21 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "24"
           registry-url: "https://registry.npmjs.org"
 
+      # Trusted publishing needs npm 11.5.1 or later. An older npm does not
+      # fail by saying so: it sends no credentials and the registry answers
+      # 404, which reads as a missing package. Say it here instead.
+      - name: npm is new enough for trusted publishing
+        run: |
+          node -e '
+            const [major, minor, patch] = process.argv[1].split(".").map(Number)
+            const older = major < 11 || (major === 11 && (minor < 5 || (minor === 5 && patch < 1)))
+            if (older) { console.error(`npm ${process.argv[1]} cannot do trusted publishing: it needs 11.5.1 or later`); process.exit(1) }
+            console.log(`npm ${process.argv[1]}`)
+          ' "$(npm --version)"
+
       - name: Verify tag matches package.json version
         run: |
           TAG_VERSION="${GITHUB_REF_NAME#v}"
@@ -44,10 +61,9 @@ jobs:
 
       - name: Publish
         if: steps.check.outputs.already_published == 'false'
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          if npm publish --access public --provenance; then
+          # The provenance attestation comes with trusted publishing; no flag.
+          if npm publish --access public; then
             echo "Publish succeeded."
             exit 0
           fi

package/.github/workflows/test.yml

@@ -38,3 +38,39 @@ jobs:
           assert doc["runs"].get("using") == "composite", "runs.using must be composite"
           print("action.yml parses and carries its required keys")
           PY
+
+      # Same failure mode as action.yml: Claude Code tolerates an unquoted ": "
+      # in a description, but strict YAML loaders (the skills CLI, skill
+      # indexers) reject the whole file, and the skill silently disappears.
+      - name: skill and rule frontmatter parses
+        run: |
+          python3 - <<'PY'
+          import sys
+          try:
+              import yaml
+          except ImportError:
+              print("PyYAML unavailable on this runner — frontmatter was NOT validated")
+              sys.exit(0)
+          for path in ("skills/omit/SKILL.md", "skills/omit-codemode/SKILL.md", ".cursor/rules/omit.mdc"):
+              meta = yaml.safe_load(open(path).read().split("---")[1])
+              assert meta.get("description"), f"{path}: frontmatter has no description"
+              print(f"{path}: frontmatter parses")
+          PY
+
+  # The sandbox is an optional peer, so `npm test` above never installs it and
+  # the end-to-end case there is announced as skipped. This job is where a real
+  # script runs in the real sandbox, at the version the lockfile pins.
+  codemode:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - run: npm ci
+
+      - run: node --test test/codemode.test.mjs
+        env:
+          OMIT_CODEMODE_REQUIRED: "1"

package/README.md

@@ -48,7 +48,9 @@ Every other skill in this genre is words the agent can ignore under context pres
 | **Final Draft gate** (hook) | The session cannot end with an edited tree and no current `.omit/final-draft.md` net report — and the report is read, not just stat'd. Its files/lines/deps counts are cross-checked against the actual diff, so a stub or a stale draft does not pass. The deletion pass is a gate, not a suggestion. |
 | **Receipts ledger** | Every Fact-Check citation is appended to `.omit/receipts.jsonl` as a claim *plus the evidence that settles it*, and `omit verify` re-checks the lot. Run it on a PR: "17/17 claims survived" is a number a reviewer can act on, and "3 refuted" names exactly which shortcuts were invented. |
 
-Hooks install automatically with the Claude Code plugin. Codex CLI has its own hooks system in the same shape (`PreToolUse` fires with `tool_input.command` for Bash, exit 2 blocks) — run `npx @sriinnu/omit hook install codex` to write `.codex/hooks.json`. The command and leak sentinels are verified against Codex's documented schema and payload shape (not yet a live Codex session firing them end-to-end); the file-based sentinels (dep/hazard/lint) and the Final Draft gate are wired too but best-effort, since Codex's `apply_patch` input shape for those isn't verified. Escape hatch for humans: `OMIT_OFF=1`.
+Hooks install automatically with the Claude Code plugin. For Codex, run `npx @sriinnu/omit hook install codex` to merge hooks into `.codex/hooks.json`; rerunning preserves existing hooks without duplicating omit's entries. Command and leak sentinels check `Bash` before execution. Dependency and hazard sentinels also check shell edits afterward. File sentinels read `apply_patch` from `tool_input.command`, checking all added/updated paths and move destinations while skipping deleted files. Malformed patch envelopes produce an objection. Payload regression tests cover these contracts; live Codex delivery and Stop-gate behavior still require end-to-end verification. These hooks do not impose a token budget or compact transcripts. Escape hatch for humans: `OMIT_OFF=1`.
+
+[Ribhu](https://github.com/sriinnu/ribhu) has shell hooks too, with its own file shape and payload: `npx @sriinnu/omit hook install ribhu` writes `.ribhu/hooks.json`, and a small adapter translates Ribhu's payload so the same sentinels run unchanged. Ribhu sends every tool call a code-mode script makes through those hooks, so a script's writes are checked like direct ones. The hooks are tested by firing each installed command the way Ribhu does, with payloads in its shape; they have not yet been watched firing inside a live Ribhu session.
 
 ## What this does not catch
 
@@ -112,6 +114,7 @@ npx @sriinnu/omit guard "<cmd>"  # is this shell command a disaster? (wire into
 npx @sriinnu/omit leak "<cmd>"   # would this command print a real secret to stdout?
 npx @sriinnu/omit gate           # the pre-commit check, callable from anywhere
 npx @sriinnu/omit hook install codex  # write .codex/hooks.json — live sentinels inside Codex CLI
+npx @sriinnu/omit hook install ribhu  # write .ribhu/hooks.json — live sentinels inside Ribhu
 ```
 
 And server-side, the GitHub Action comments the verdict on every PR regardless of what wrote the code:
@@ -119,14 +122,16 @@ And server-side, the GitHub Action comments the verdict on every PR regardless o
 ```yaml
 # .github/workflows/omit.yml
 on: pull_request
-permissions: { pull-requests: write }
+permissions: { contents: read, pull-requests: write }
 jobs:
   omit:
     runs-on: ubuntu-latest
+    # A fork's PR gets a read-only token, so the comment could only fail there.
+    if: github.event.pull_request.head.repo.full_name == github.repository
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
-      - uses: sriinnu/omit@main
+      - uses: sriinnu/omit@v0.6.0
         # with: { exec: true }   # execute receipts' `run` snippets to verify them
                                  # fully. Off by default: a PR's receipts are
                                  # untrusted code, and this runs on pull requests.
@@ -148,6 +153,50 @@ jobs:
 // the receipts; a single number would just be another uncited claim.
 ```
 
+## Codemode (experimental)
+
+An agent exploring a repo pays for every intermediate result: each read and each grep is a round-trip whose raw output lands in the transcript and is sent again on every later turn. With `omit codemode` the model writes a script, the reads happen inside it, and only what the script returns comes back.
+
+```sh
+omit codemode run <<'EOF'
+const libs = (await tools.files({ under: 'lib' })).filter((f) => f.endsWith('.mjs'))
+const sources = await Promise.all(libs.map((path) => tools.read({ path })))
+return Object.fromEntries(libs.map((f, i) => [f, (sources[i].match(/^export /gm) ?? []).length]))
+EOF
+```
+
+- **Read-only.** Three tools: `files`, `read`, `grep`. They read the tree through git, so ignored files stay out, and every path is confined to the directory the server started in: no `..`, no absolute path, no symlink out.
+- **Sandboxed.** The script runs in a QuickJS VM compiled to wasm ([`@earendil-works/pi-codemode`](https://www.npmjs.com/package/@earendil-works/pi-codemode), the sandbox behind pi's codemode): no file system, no network, no `process`. `node:vm` is not isolation, and the receipt for this dependency runs the escape to show it.
+- **Secrets stay in.** A script may read a credentials file; it may not return it. Output that matches a secret rule is withheld whole.
+- **Bounded.** A script has 60 seconds, and output past 20,000 characters loses its middle.
+
+The sandbox is an optional peer that only this command loads, so `omit` itself still installs zero dependencies. It needs Node 22.19 or newer.
+
+```
+npm install -g @sriinnu/omit @earendil-works/pi-codemode
+```
+
+Any agent with a shell can use it as it stands: `omit codemode run` takes a script on stdin or from a file and prints the answer, and the `omit-codemode` skill (`skills/omit-codemode/SKILL.md`) teaches the agent when to reach for it and what a script can call. Nothing has to be registered.
+
+For a host without a shell, or one where you would rather approve a single read-only tool, the same thing is an MCP server on stdio:
+
+```
+claude mcp add omit -- omit codemode        # Claude Code
+```
+
+```toml
+# Codex: ~/.codex/config.toml
+[mcp_servers.omit]
+command = "omit"
+args = ["codemode"]
+```
+
+```
+// omitted: write and edit tools: a nested write is not seen by the host's
+// hooks, so it has to carry the hazard, dependency and lint gates itself. Add
+// them once bench/ shows the read side pays for the surface.
+```
+
 ## The referee (experimental)
 
 `bench/` is METHODOLOGY.md made runnable: paired agentic runs of the same tasks under baseline, omit, or **any competing skill**, metrics computed from the actual git diffs, all transcripts kept. The category argues about self-reported numbers; omit ships the measuring instrument. See `bench/README.md`.
@@ -165,6 +214,66 @@ Say `omit redline` (or any mode) in chat, or use `/omit <mode>` where slash comm
 
 ## Install
 
+### Hook health and context controls
+
+These features run locally with Node and do not call a model or provider API.
+Use the same CLI with any provider/model; hook installation targets the host,
+not the model. Codex and Claude adapters are included. Other hosts need the
+documented stdin/output contract below; automatic interception is not universal.
+
+```sh
+omit doctor                # read-only hook inspection; never runs discovered commands
+omit doctor --json         # same findings for scripts; exit 1 on errors
+omit init skill            # discoverable .agents/skills/omit/SKILL.md; never overwrite
+omit hook install codex --context
+omit hook install claude --context
+```
+
+The doctor inspects global Codex hooks plus the current directory's
+`.codex/hooks.json` and `.claude/settings.json`. It reports missing scripts,
+duplicate registrations, malformed matchers, some legacy shell-tool name
+mismatches, and Git `core.hooksPath` overrides. It checks simple Node/Python
+script commands statically; other command shapes are explicitly unchecked.
+It does not resolve all parent layers, host trust, executable availability, or
+prove that hooks fired. `liveDelivery` remains `unverified`.
+
+`--context` adds advisory broad-read warnings and a text output guard. Default
+installations keep the existing safety hooks without adding context controls.
+At more than 6,000 characters, a plain-string shell result is archived privately
+under the OS temporary directory and replaced with head/tail excerpts, selected
+error lines, and its full-output path. Set `OMIT_OUTPUT_CHARS` to 1000–100000 to
+change the excerpt character budget. The wrapper/path adds a small overhead.
+Structured results (objects, arrays, MCP content) are left intact. Storage
+failure preserves the original result and emits a diagnostic. Archives can
+contain sensitive output: files use mode 0600 inside a mode-0700 directory on
+POSIX systems. They persist until temporary storage is cleaned; no existing
+transcript is rewritten. Inspect the archive when a missing middle section
+matters; diagnostic extraction is heuristic and not exhaustive.
+
+Three consecutive identical command/result pairs in the same cwd/session
+produce one advisory warning. A changed pair resets the counter. Only hashes
+and a bounded counter are stored for this check; it does not prove filesystem
+state is unchanged. Parallel invocations may undercount, so this is not a gate.
+
+For another host, invoke `omit context` with JSON on stdin:
+
+```json
+{"hook_event_name":"PostToolUse","tool_name":"Bash","session_id":"example","cwd":"/your/project","tool_input":{"command":"your command"},"tool_response":"plain text output"}
+```
+
+Use `PreToolUse` for read-scope advice. Shell names `Bash`, `exec_command`, and
+`shell` are accepted (`tool_input.cmd` is also accepted). `systemMessage` is
+advisory; `decision: "block"` with `reason` requests post-tool feedback replacing
+the result in Codex. Other hosts must translate that response into their own
+replacement API: some only append feedback. Verify delivery and replacement
+before claiming context savings. No model quota or token-saving guarantee is
+inferred from character counts. Set `OMIT_OFF=1` to bypass the hooks; remove only
+the `context-sentinel.mjs` entries to uninstall these optional controls.
+
+The packaged skill remains at `skills/omit/SKILL.md`; `omit init skill` copies it
+to the shared project discovery path. Hosts with different discovery paths can
+install the same skill there. No provider credentials are required.
+
 New here? **[GETTING-STARTED.md](GETTING-STARTED.md)** has a copy-paste setup for every agent.
 
 **Claude Code (plugin marketplace)**: one command pair, gets you the skill plus `/omit` and `/omit-edit`:
@@ -174,6 +283,12 @@ New here? **[GETTING-STARTED.md](GETTING-STARTED.md)** has a copy-paste setup fo
 /plugin install omit@omit
 ```
 
+**Any SKILL.md-aware agent** (Claude Code, Codex, Cursor, and others, via [skills.sh](https://skills.sh)):
+
+```
+npx skills add sriinnu/omit
+```
+
 **Global command**: install once from GitHub, use everywhere:
 
 ```
@@ -213,9 +328,9 @@ skills/omit/SKILL.md  →  .claude/skills/omit/SKILL.md      (project)
 **Anything else**: paste the contents of `AGENTS.md` into the agent's custom-instructions/rules mechanism. It's plain markdown; there is nothing to build.
 
 ```
-// omitted: an MCP server: MCP exposes tools and data; omit is a behavioral
-// discipline, and rule files + skills already deliver it. Add one only if
-// omit ever grows verifiable tooling (e.g., a standalone diff auditor).
+// omitted: the discipline itself over MCP: MCP exposes tools and data; omit is
+// a behavioral discipline, and rule files + skills already deliver it. The one
+// MCP server omit ships is codemode, which is tooling.
 ```
 
 ## Commands (Claude Code)
@@ -229,21 +344,25 @@ One command, three destinations (npm, GitHub, Homebrew):
 
     npm run release -- patch    # or minor / major
 
-`scripts/release.mjs` runs the tests (via `preversion`), bumps and tags with
-`npm version` (signed, per repo policy), and pushes — the tag triggers
-`publish.yml`, which publishes to npm **with a provenance attestation**. It
-then cuts the GitHub release with generated notes, waits for the registry to
-serve the version, and updates the `omit` formula in
-[`sriinnu/homebrew-tap`](https://github.com/sriinnu/homebrew-tap). A failed
-step aborts the release, in order.
+`scripts/release.mjs` runs the tests (via `preversion`), bumps the version,
+and lands the bump on main **through a PR** (main takes no direct pushes).
+Once checks pass and it merges, the script tags the merge (signed, per repo
+policy) and pushes the tag — which triggers `publish.yml`, publishing to npm
+**with a provenance attestation**. It then cuts the GitHub release with
+generated notes, waits for the registry to serve the version, and updates the
+`omit` formula in [`sriinnu/homebrew-tap`](https://github.com/sriinnu/homebrew-tap),
+again through a PR. A failed step aborts the release, in order.
 
 Never `npm publish` by hand: a local publish cannot attach provenance, and
 npm will not let the same version be republished to add one later. If the CI
 publish fails, fix CI — don't work around it locally.
 
-If the `NPM_TOKEN` secret ever goes stale, put the new token in `~/.npmrc`
-and run `npm run token:sync` — it verifies the token against the registry
-before pushing, so a dead token never reaches CI.
+There is no npm token to keep alive. `publish.yml` uses npm's
+[trusted publishing](https://docs.npmjs.com/trusted-publishers): the workflow
+proves its identity to npm with a short-lived token GitHub mints for that run,
+and npm checks it against the publisher configured in the package's settings
+(GitHub Actions, `sriinnu/omit`, `publish.yml`). If a publish is refused, that
+form is the thing to check.
 
 ## Prior art
 

package/action.yml

@@ -34,10 +34,13 @@ runs:
         BASE="${{ inputs.base }}"
         if [ -z "$BASE" ]; then BASE="origin/${{ github.event.pull_request.base.ref }}"; fi
         git fetch --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
-        node "${{ github.action_path }}/bin/omit.mjs" audit --base "$BASE" --markdown > omit-verdict.md
-        cat omit-verdict.md
+        # Outside the workspace: the redirect creates the file before the audit
+        # runs, and the audit counts untracked files — a verdict written into
+        # the checkout reports itself as one more changed file.
+        node "${{ github.action_path }}/bin/omit.mjs" audit --base "$BASE" --markdown > "$RUNNER_TEMP/omit-verdict.md"
+        cat "$RUNNER_TEMP/omit-verdict.md"
     - name: Comment on PR
       shell: bash
       env:
         GH_TOKEN: ${{ github.token }}
-      run: gh pr comment ${{ github.event.pull_request.number }} --body-file omit-verdict.md --repo ${{ github.repository }}
+      run: gh pr comment ${{ github.event.pull_request.number }} --body-file "$RUNNER_TEMP/omit-verdict.md" --repo ${{ github.repository }}

package/bin/omit.mjs

@@ -10,7 +10,10 @@
 //   omit leak "<cmd>"                                     would this command print a real secret to stdout?
 //   omit hook install                                     add the gate to .git/hooks/pre-commit
 //   omit hook install codex                                write .codex/hooks.json (live sentinels inside Codex CLI)
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'
+//   omit hook install ribhu                               write .ribhu/hooks.json (live sentinels inside Ribhu)
+//   omit codemode run [file]                              run one sandboxed script over read-only repo tools (stdin without a file)
+//   omit codemode                                         the same, as an MCP server on stdio
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, chmodSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { isManifest, addedDeps, unparsedDependencyFile } from '../lib/deps.mjs'
@@ -20,6 +23,8 @@ import { findHazards } from '../lib/hazards.mjs'
 import { lintFiles } from '../lib/lint.mjs'
 import { assessCommand } from '../lib/danger.mjs'
 import { assessLeak } from '../lib/leaks.mjs'
+import { execute, serve } from '../lib/codemode.mjs'
+import { doctor } from '../lib/doctor.mjs'
 
 const cwd = process.cwd()
 const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
@@ -27,6 +32,7 @@ const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
 // ---------- init ----------
 const targets = {
   agents: [['AGENTS.md', 'AGENTS.md']],
+  skill: [['skills/omit/SKILL.md', '.agents/skills/omit/SKILL.md']],
   claude: [[join('skills', 'omit', 'SKILL.md'), join('.claude', 'skills', 'omit', 'SKILL.md')]],
   cursor: [[join('.cursor', 'rules', 'omit.mdc'), join('.cursor', 'rules', 'omit.mdc')]],
   cline: [[join('.clinerules', 'omit.md'), join('.clinerules', 'omit.md')]],
@@ -510,18 +516,9 @@ function leak(args) {
   process.exit(1)
 }
 
-// Codex CLI's hook schema is the same shape as Claude Code's (confirmed against
-// developers.openai.com/codex/hooks: PreToolUse fires with tool_input.command for
-// Bash, exit 2 blocks). Command-sentinel and leak-sentinel run on that shape as-is.
-// The PostToolUse file hooks (dep/hazard/lint-sentinel) and the Stop gate are wired
-// too since Codex documents the same events, but Codex's apply_patch tool_input
-// shape for PostToolUse isn't confirmed here — those three no-op safely if the
-// file_path field isn't present, so this is best-effort, not verified parity.
-function hookInstallCodex() {
-  const dir = '.codex'
-  const hooksPath = join(dir, 'hooks.json')
-  mkdirSync(dir, { recursive: true })
-
+// An existing hooks file is merged into, never replaced: someone else's hooks
+// live there too. One that cannot be read is refused rather than overwritten.
+function loadHooksDoc(hooksPath) {
   let doc = { hooks: {} }
   if (existsSync(hooksPath)) {
     try {
@@ -534,10 +531,24 @@ function hookInstallCodex() {
   doc.hooks ??= {}
   for (const [event, entry] of Object.entries(doc.hooks)) {
     if (entry !== undefined && !Array.isArray(entry)) {
-      console.error(`omit: ${hooksPath} has a malformed "${event}" entry (expected an array of matcher groups) — fix or remove it first`)
+      console.error(`omit: ${hooksPath} has a malformed "${event}" entry (expected an array) — fix or remove it first`)
       process.exit(1)
     }
   }
+  return doc
+}
+
+// Codex CLI's hook schema is the same shape as Claude Code's (confirmed against
+// developers.openai.com/codex/hooks: PreToolUse fires with tool_input.command for
+// Bash, exit 2 blocks). Command-sentinel and leak-sentinel run on that shape as-is.
+// File sentinels extract surviving paths from Codex's apply_patch command.
+// Contract tests cover these payloads; live harness delivery is a separate check.
+function hookInstallCodex(options = [], host = 'codex') {
+  if (options.some(option => option !== '--context')) die('usage: omit hook install codex [--context]')
+  const dir = host === 'claude' ? '.claude' : '.codex'
+  const hooksPath = join(dir, host === 'claude' ? 'settings.json' : 'hooks.json')
+  mkdirSync(dir, { recursive: true })
+  const doc = loadHooksDoc(hooksPath)
 
   const scriptCmd = (script) => `node "${join(pkgRoot, 'hooks', script)}"`
   const mergeHook = (event, matcher, script) => {
@@ -553,16 +564,22 @@ function hookInstallCodex() {
 
   mergeHook('PreToolUse', 'Bash', 'command-sentinel.mjs')
   mergeHook('PreToolUse', 'Bash', 'leak-sentinel.mjs')
+  mergeHook('PostToolUse', 'Bash', 'dep-sentinel.mjs')
+  mergeHook('PostToolUse', 'Bash', 'hazard-sentinel.mjs')
   mergeHook('PostToolUse', 'apply_patch|Edit|Write', 'dep-sentinel.mjs')
   mergeHook('PostToolUse', 'apply_patch|Edit|Write', 'hazard-sentinel.mjs')
   mergeHook('PostToolUse', 'apply_patch|Edit|Write', 'lint-sentinel.mjs')
   mergeHook('Stop', '', 'final-draft-gate.mjs')
+  if (options.includes('--context')) {
+    mergeHook('PreToolUse', 'Bash', 'context-sentinel.mjs')
+    mergeHook('PostToolUse', 'Bash', 'context-sentinel.mjs')
+  }
 
   writeFileSync(hooksPath, JSON.stringify(doc, null, 2) + '\n')
   console.log(`wrote ${hooksPath}`)
   console.log('  verified against Codex\'s documented schema: command sentinel + leak sentinel run on Bash commands (same tool_input.command shape as Claude Code)')
-  console.log('  best-effort, unverified: dep/hazard/lint sentinels + Final Draft gate on apply_patch/Edit/Write — they no-op safely if the field shape differs, report back if you see them miss real edits')
-  console.log('\nCodex requires trusting new hook definitions once per session: run `/hooks` in Codex to review, or start with --dangerously-bypass-hook-trust for unattended runs.')
+  console.log('  file sentinels cover apply_patch/Edit/Write; dependency and hazard checks also cover Bash edits. Payload tests do not establish live Codex hook delivery.')
+  console.log(`\nReview the installed hooks in ${host}; installation does not prove live delivery.`)
 }
 
 // The gate goes in the repository's own hooks directory — always, never into
@@ -658,6 +675,68 @@ function verify() {
 // on purpose: a verdict rendered from a diff that could not be read is the
 // failure this whole contract exists to prevent, and a gate that cannot read the
 // change has to block it rather than pass it.
+// Ribhu's hooks.json is not Codex's. Each event holds a flat list of
+// { matcher, command }, the matcher is a regex over Ribhu's own lowercase tool
+// names, and the payload a command receives is shaped differently, so every
+// entry runs a sentinel through hooks/ribhu-adapter.mjs. Ribhu's code mode
+// sends each nested tool call through these same hooks, so a script's writes
+// are checked like direct ones.
+function hookInstallRibhu() {
+  const dir = '.ribhu'
+  const hooksPath = join(dir, 'hooks.json')
+  mkdirSync(dir, { recursive: true })
+  const doc = loadHooksDoc(hooksPath)
+
+  const add = (event, matcher, sentinel, extra) => {
+    const command = `node "${join(pkgRoot, 'hooks', 'ribhu-adapter.mjs')}" ${sentinel}`
+    doc.hooks[event] ??= []
+    if (!doc.hooks[event].some((h) => h?.command === command)) doc.hooks[event].push({ ...(matcher && { matcher }), command, ...extra })
+  }
+  // Anchored: Ribhu matches with an unanchored regex, and a bare `write`
+  // would also catch todo_write.
+  const files = 'edit|multi_edit|ast_edit|write'
+  add('PreToolUse', '^bash$', 'command-sentinel')
+  add('PreToolUse', '^bash$', 'leak-sentinel')
+  add('PostToolUse', `^(bash|${files})$`, 'dep-sentinel')
+  add('PostToolUse', `^(bash|${files})$`, 'hazard-sentinel')
+  // Ribhu gives a hook ten seconds unless told otherwise, and a linter on a
+  // large repo takes longer; sixty is the most it allows.
+  add('PostToolUse', `^(${files})$`, 'lint-sentinel', { timeoutMs: 60000 })
+  add('Stop', undefined, 'final-draft-gate')
+
+  writeFileSync(hooksPath, JSON.stringify(doc, null, 2) + '\n')
+  console.log(`wrote ${hooksPath}`)
+  console.log('  command + leak sentinels before bash; dependency + hazard sentinels after bash and file edits; lint after file edits; Final Draft gate on Stop')
+  console.log("  checked against Ribhu's hook contract with real payload shapes; not yet verified firing inside a live Ribhu session")
+  console.log('\nRibhu runs a repository\'s hooks only once the project is trusted.')
+}
+
+// ---------- codemode ----------
+// The sandbox is an optional peer, loaded here and nowhere else: every other
+// command has to keep working on a machine that never installed it.
+async function codemode(args) {
+  if (args.length && args[0] !== 'run') die('usage: omit codemode [run [file]]')
+  let sandbox
+  try {
+    sandbox = await import('@earendil-works/pi-codemode')
+  } catch (e) {
+    if (e.code !== 'ERR_MODULE_NOT_FOUND') throw e
+    die('omit codemode needs its sandbox, which is not installed. Run: npm install @earendil-works/pi-codemode (it needs Node 22.19 or newer)')
+  }
+  const root = realpathSync(cwd)
+  // `run` is the whole feature for any agent that has a shell: one script in,
+  // one answer out, no server to register. Exit 1 marks a failed or withheld
+  // result, so a harness can tell it from an answer.
+  if (args[0] === 'run') {
+    const { text, isError } = await execute(readFileSync(args[1] ?? 0, 'utf8'), { CodemodeSandbox: sandbox.CodemodeSandbox, root })
+    console.log(text)
+    process.exitCode = isError ? 1 : 0
+    return
+  }
+  const { version } = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'))
+  serve({ sandbox, root, version })
+}
+
 const [cmd, ...rest] = process.argv.slice(2)
 try {
   if (cmd === 'audit') audit(rest)
@@ -667,16 +746,29 @@ try {
   else if (cmd === 'guard') guard(rest)
   else if (cmd === 'leak') leak(rest)
   else if (cmd === 'verify') verify()
-  else if (cmd === 'hook' && rest[0] === 'install' && rest[1] === 'codex') hookInstallCodex()
+  else if (cmd === 'codemode') await codemode(rest)
+  else if (cmd === 'context') {
+    if (rest.length) die('usage: omit context < hook-payload.json')
+    await import('../hooks/context-sentinel.mjs')
+  }
+  else if (cmd === 'doctor') {
+    if (rest.some(arg => arg !== '--json')) die('usage: omit doctor [--json]')
+    const report = doctor(cwd)
+    console.log(rest.includes('--json') ? JSON.stringify(report, null, 2) : ['omit doctor (read-only; live delivery unverified)', ...report.findings.map(f => `${f.level}: ${f.message}`)].join('\n'))
+    if (report.findings.some(f => f.level === 'error')) process.exitCode = 1
+  }
+  else if (cmd === 'hook' && rest[0] === 'install' && rest[1] === 'codex') hookInstallCodex(rest.slice(2))
+  else if (cmd === 'hook' && rest[0] === 'install' && rest[1] === 'claude') hookInstallCodex(rest.slice(2), 'claude')
+  else if (cmd === 'hook' && rest[0] === 'install' && rest[1] === 'ribhu') hookInstallRibhu()
   else if (cmd === 'hook' && rest[0] === 'install' && rest[1] === undefined) hookInstall()
   else if (cmd === 'hook' && rest[0] === 'install') {
-    console.error(`omit: unrecognized 'hook install' target '${rest[1]}' — usage: omit hook install [codex]`)
+    console.error(`omit: unrecognized 'hook install' target '${rest[1]}' — usage: omit hook install [codex|claude|ribhu]`)
     process.exit(1)
   }
   else if (cmd === 'init') init(rest[0])
   else if (targets[cmd]) init(cmd) // back-compat: `omit cursor`
   else {
-    console.error('usage: omit <init|audit|check|gate|lint|guard|leak|verify|hook install|hook install codex>')
+    console.error('usage: omit <init|audit|check|gate|lint|guard|leak|verify|codemode|context|doctor [--json]|hook install [codex|claude|ribhu] [--context]>')
     process.exit(cmd ? 1 : 0)
   }
 } catch (e) {

package/hooks/context-sentinel.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Opt-in context controls. Structured tool results are never replaced.
+import { readFileSync } from 'node:fs'
+import { digest, readWarnings, preview, existingSessionDir, archiveText, repeatCount } from '../lib/context.mjs'
+
+if (process.env.OMIT_OFF === '1') process.exit(0)
+try {
+  const data = JSON.parse(readFileSync(0, 'utf8'))
+  if (!['Bash', 'exec_command', 'shell'].includes(data.tool_name)) process.exit(0)
+  const command = data.tool_input?.command ?? data.tool_input?.cmd
+  if (data.hook_event_name === 'PreToolUse') {
+    const warnings = readWarnings(command)
+    if (warnings.length) console.log(JSON.stringify({ systemMessage: `omit: ${warnings.join(' ')}` }))
+    process.exit(0)
+  }
+  if (data.hook_event_name !== 'PostToolUse' || typeof data.tool_response !== 'string') process.exit(0)
+  const text = data.tool_response
+  const limit = Number(process.env.OMIT_OUTPUT_CHARS ?? 6000)
+  if (!Number.isInteger(limit) || limit < 1000 || limit > 100000) throw new Error('OMIT_OUTPUT_CHARS must be 1000..100000')
+  if (typeof data.session_id !== 'string' || !data.session_id) throw new Error('missing session_id')
+  const dir = existingSessionDir(data.cwd ?? process.cwd(), data.session_id)
+  const count = typeof command === 'string' ? repeatCount(dir, digest(`${command}\0${text}`)) : 0
+  const warning = count === 3 ? 'omit: three consecutive identical commands returned identical text. Check whether another run adds information.' : ''
+  const shortened = preview(text, limit)
+  if (!shortened) {
+    if (warning) console.log(JSON.stringify({ systemMessage: warning }))
+    process.exit(0)
+  }
+  const path = archiveText(dir, text)
+  console.log(JSON.stringify({
+    decision: 'block',
+    reason: `${shortened.head}\n[omit: ${shortened.omitted} characters outside head/tail; full output: ${path}]\n${shortened.diagnostics ? `[selected diagnostics]\n${shortened.diagnostics}\n` : ''}${shortened.tail}`,
+    ...(warning ? { systemMessage: warning } : {}),
+  }))
+} catch {
+  // Preserve the original result if archiving or decoding fails.
+  console.log(JSON.stringify({ systemMessage: 'omit: context guard could not complete; original output was not replaced.' }))
+}

package/hooks/dep-sentinel.mjs

@@ -11,6 +11,7 @@ import { isManifest, addedDeps, MANIFESTS } from '../lib/deps.mjs'
 import { probe, fileAtRevision, repoRelPath } from '../lib/git.mjs'
 import { execDisabled, flagOn } from '../lib/exec.mjs'
 import { newDepCitations } from '../lib/receipts.mjs'
+import { patchPaths } from '../lib/patch-paths.mjs'
 
 if (process.env.OMIT_OFF === '1') process.exit(0)
 
@@ -117,7 +118,8 @@ try {
   }
 
   const cwd = data.cwd ?? process.cwd()
-  const targets =
+  const patched = patchPaths(data)
+  const targets = patched !== null ? patched.filter(isManifest) :
     typeof ti.file_path === 'string' ? (isManifest(ti.file_path) ? [ti.file_path] : []) : typeof ti.command === 'string' ? manifestsTouched(ti.command) : []
   if (targets.length === 0) process.exit(0) // an edit that cannot be a manifest edit
 

package/hooks/hazard-sentinel.mjs

@@ -11,6 +11,7 @@ import { readFileSync, realpathSync } from 'node:fs'
 import { basename, resolve } from 'node:path'
 import { probe, git, fileAtRevision, repoRelPath } from '../lib/git.mjs'
 import { findHazards } from '../lib/hazards.mjs'
+import { patchPaths } from '../lib/patch-paths.mjs'
 
 if (process.env.OMIT_OFF === '1') process.exit(0)
 
@@ -128,16 +129,19 @@ try {
 
   const file = typeof ti.file_path === 'string' ? ti.file_path : typeof ti.notebook_path === 'string' ? ti.notebook_path : null
   let findings = []
-  if (file !== null && !/\.lock$/.test(basename(file)) && basename(file) !== 'package-lock.json') {
+  const files = patchPaths(data) ?? (file === null ? [] : [file])
+  if (files.length) {
     const root = repoRootOrNull(cwd)
-    const abs = resolve(cwd, file)
-    const rel = root === null ? null : relInRoot(root, abs)
-    if (!inOmitDir(rel ?? file)) {
-      // A notebook's added content is the cell the tool just wrote; there is no
-      // useful diff of a .ipynb and no file_path to diff it with.
-      findings = typeof ti.new_source === 'string' ? findHazards(ti.new_source.split('\n')) : findHazards(addedLines(abs, rel, root))
+    for (const file of files) {
+      if (/\.lock$/.test(basename(file)) || basename(file) === 'package-lock.json') continue
+      const abs = resolve(cwd, file)
+      const rel = root === null ? null : relInRoot(root, abs)
+      if (!inOmitDir(rel ?? file)) {
+        // A notebook's added content is the cell the tool just wrote.
+        findings.push(...(typeof ti.new_source === 'string' ? findHazards(ti.new_source.split('\n')) : findHazards(addedLines(abs, rel, root))))
+      }
     }
-  } else if (typeof ti.command === 'string' && WRITE_SHAPES.test(ti.command)) {
+  } else if (data.tool_name !== 'apply_patch' && typeof ti.command === 'string' && WRITE_SHAPES.test(ti.command)) {
     const root = repoRootOrNull(cwd)
     // The command's own text carries what a heredoc writes. Secret rules only:
     // the injection rules are about code landing in a file, and the file check

package/hooks/lint-sentinel.mjs

@@ -3,6 +3,7 @@
 // objects immediately on errors. omit brings no lint rules of its own.
 import { readFileSync } from 'node:fs'
 import { lintFiles } from '../lib/lint.mjs'
+import { patchPaths } from '../lib/patch-paths.mjs'
 
 if (process.env.OMIT_OFF === '1') process.exit(0)
 
@@ -31,10 +32,11 @@ try {
     )
   }
   const file = ti.file_path
-  if (!file) process.exit(0)
+  const files = patchPaths(data) ?? (file ? [file] : [])
+  if (!files.length) process.exit(0)
 
   const cwd = data.cwd ?? process.cwd()
-  const failing = lintFiles(cwd, [file]).filter((r) => !r.ok)
+  const failing = lintFiles(cwd, files).filter((r) => !r.ok)
   if (failing.length === 0) process.exit(0)
 
   console.error(

package/hooks/ribhu-adapter.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Ribhu's shell hooks hand a command a different payload from the one Claude
+// Code and Codex do:
+//
+//   Ribhu:     { event, tool, input: { path | command, … }, cwd }
+//   sentinels: { tool_input: { file_path | command, … }, cwd }
+//
+// The exit contract is the same on both sides: 2 blocks, and stderr is the
+// reason. So this translates the payload, runs the named sentinel on it, and
+// hands back that sentinel's own status and reason. The sentinels are not
+// touched, which means an objection raised under Ribhu is the same code as
+// one raised under Claude Code, and so is every nested call a Ribhu code-mode
+// script makes: those go through the same hooks as a direct call.
+//
+//   node ribhu-adapter.mjs <sentinel>     payload on stdin
+//
+// omitted: hook_event_name, tool_name and tool_response: no sentinel reads
+// them today; translate them with the first one that does.
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// load-bearing: the sentinel name comes from a hooks.json, and a cloned repo
+// can carry one. Only these six files are ever run, never a path.
+const SENTINELS = new Set(['command-sentinel', 'leak-sentinel', 'dep-sentinel', 'hazard-sentinel', 'lint-sentinel', 'final-draft-gate'])
+const name = process.argv[2]
+if (!SENTINELS.has(name)) {
+  console.error(`omit: the Ribhu adapter has no sentinel called "${name}". It runs: ${[...SENTINELS].join(', ')}`)
+  process.exit(1)
+}
+
+// A payload this cannot read is passed on as it arrived. Each sentinel already
+// decides what an unreadable payload means, and that decision is not this
+// file's to make differently.
+const raw = readFileSync(0, 'utf8')
+let payload = raw
+try {
+  const { input, cwd } = JSON.parse(raw)
+  const { path, ...rest } = input !== null && typeof input === 'object' ? input : {}
+  payload = JSON.stringify({ cwd, tool_input: path === undefined ? rest : { ...rest, file_path: path } })
+} catch {}
+
+const run = spawnSync(process.execPath, [fileURLToPath(new URL(`./${name}.mjs`, import.meta.url))], { input: payload, encoding: 'utf8' })
+if (run.error) {
+  console.error(`omit: could not run ${name}: ${run.error.message}`)
+  process.exit(1)
+}
+// The sentinel's stdout stops here. Ribhu reads a hook's stdout as a rewrite of
+// the tool's input or output, and nothing a sentinel prints is one.
+process.stderr.write(run.stderr)
+process.exit(run.status ?? 1)

package/lib/codemode.mjs

@@ -0,0 +1,198 @@
+// omit codemode: one MCP tool that runs a model-written script in a sandbox
+// whose only capability is the read-only tools below.
+//
+// An agent exploring a repo pays for every intermediate result: each file read
+// and each grep is a round-trip whose raw output lands in the transcript and is
+// re-sent on every later turn. Here the reads happen inside the script and only
+// what it returns reaches the model.
+//
+// The sandbox itself is not written here. Isolation is load-bearing, and
+// node:vm is not isolation (the receipt in .omit/receipts.jsonl executes the
+// escape), so it comes from @earendil-works/pi-codemode: a QuickJS VM compiled
+// to wasm with no file system, network or process. It is an optional peer and
+// only this command loads it, so the rest of the CLI stays zero-dependency.
+//
+// omitted: write and edit tools: a nested write is not seen by the host's
+// hooks, so it has to carry the hazard, dependency and lint gates itself; add
+// them once bench/ shows the read side pays for the surface.
+// omitted: a tree walk for directories that are not git repositories: `files`
+// and `grep` read the tree through git, which is what knows what is ignored;
+// add one if a host turns out to run this outside repositories.
+import { execFile } from 'node:child_process'
+import { readFile, realpath, stat } from 'node:fs/promises'
+import { relative, resolve, sep } from 'node:path'
+import { createInterface } from 'node:readline'
+import { promisify } from 'node:util'
+import { findHazards } from './hazards.mjs'
+
+const run = promisify(execFile)
+
+const TIMEOUT_MS = 60_000
+// What may reach the transcript from one script. Past it the middle is cut: a
+// script that returns this much has not filtered anything.
+const MAX_OUTPUT_CHARS = 20_000
+// A read is one JSON round trip into the VM, so a multi-gigabyte log would be
+// held three times over before the script saw a byte.
+const MAX_READ_BYTES = 8 << 20
+const GIT_BUFFER = 64 << 20
+
+// load-bearing: path confinement. The lexical check refuses `..` and absolute
+// paths before the file system is touched; the realpath check refuses a
+// symlink inside the workspace that points out of it.
+async function confine(root, path) {
+  if (typeof path !== 'string' || !path) throw new Error('path must be a non-empty string')
+  const outside = (full) => full !== root && !full.startsWith(root + sep)
+  if (outside(resolve(root, path))) throw new Error(`${path} is outside the workspace`)
+  let full
+  try {
+    full = await realpath(resolve(root, path))
+  } catch (e) {
+    throw new Error(`${path}: ${e.code === 'ENOENT' ? 'no such file or directory' : e.message}`)
+  }
+  if (outside(full)) throw new Error(`${path} is outside the workspace`)
+  return full
+}
+
+// Async on purpose: the host owns the script's deadline, and a synchronous git
+// call would hold the event loop that enforces it. It also lets a script's
+// Promise.all actually run its calls side by side.
+async function git(root, args) {
+  try {
+    return (await run('git', args, { cwd: root, encoding: 'utf8', maxBuffer: GIT_BUFFER })).stdout
+  } catch (e) {
+    if (e.code === 1 && !e.stderr) return '' // `git grep` found nothing
+    if (e.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') throw new Error('too much output to hold: narrow the pattern or pass `under`')
+    throw new Error(String(e.stderr ?? '').trim() || e.message)
+  }
+}
+
+const pathspec = async (root, under) => (under === undefined ? [] : ['--', relative(root, await confine(root, under)) || '.'])
+
+export const toolsFor = (root) => [
+  {
+    name: 'files',
+    description: 'List files, tracked and untracked, minus what git ignores.',
+    inputSchema: { type: 'object', properties: { under: { type: 'string', description: 'only files below this directory' } } },
+    outputSchema: { type: 'array', items: { type: 'string' } },
+    execute: async ({ under } = {}) => {
+      const out = await git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', ...(await pathspec(root, under))])
+      return [...new Set(out.split('\0').filter(Boolean))]
+    },
+  },
+  {
+    name: 'read',
+    description: 'Read one file as text.',
+    inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    outputSchema: { type: 'string' },
+    execute: async ({ path } = {}) => {
+      const full = await confine(root, path)
+      const { size } = await stat(full)
+      if (size > MAX_READ_BYTES) throw new Error(`${path} is ${size} bytes, past the ${MAX_READ_BYTES} a read holds: use grep`)
+      return readFile(full, 'utf8')
+    },
+  },
+  {
+    name: 'grep',
+    description: 'Search file contents with an extended regular expression.',
+    inputSchema: {
+      type: 'object',
+      properties: { pattern: { type: 'string' }, under: { type: 'string', description: 'only files below this directory' } },
+      required: ['pattern'],
+    },
+    outputSchema: {
+      type: 'array',
+      items: { type: 'object', properties: { path: { type: 'string' }, line: { type: 'number' }, text: { type: 'string' } }, required: ['path', 'line', 'text'] },
+    },
+    execute: async ({ pattern, under } = {}) => {
+      if (typeof pattern !== 'string' || !pattern) throw new Error('pattern must be a non-empty string')
+      // -z: a path is then followed by NUL, never by the `:` a file name may contain.
+      const out = await git(root, ['grep', '-nIz', '-E', '--untracked', '-e', pattern, ...(await pathspec(root, under))])
+      return out.split('\n').filter(Boolean).map((row) => {
+        const [path, line, ...text] = row.split('\0')
+        return { path, line: Number(line), text: text.join('\0') }
+      })
+    },
+  },
+]
+
+// What a finished script hands back to the model.
+export function shape(text, isError) {
+  // load-bearing: secrets stay out of the transcript. A script that read a
+  // credentials file must not be able to return it, and the same rules that
+  // stop a key landing in a file decide what counts as one.
+  const secrets = findHazards(text.split('\n')).filter((h) => h.type === 'secret')
+  if (secrets.length) {
+    const where = secrets.map((h) => `${h.rule} (output line ${h.line})`).join(', ')
+    return { isError: true, text: `omit: output withheld, it carries ${where}. A transcript is not a safe place for a key: filter it out in the script and return only what you need.` }
+  }
+  if (!text) return { isError, text: '(no output: return a value or call text())' }
+  if (text.length <= MAX_OUTPUT_CHARS) return { isError, text }
+  const half = MAX_OUTPUT_CHARS / 2
+  return {
+    isError,
+    text: `${text.slice(0, half)}\n[omit: ${text.length - MAX_OUTPUT_CHARS} characters cut here. Return less: count, aggregate or filter in the script.]\n${text.slice(-half)}`,
+  }
+}
+
+export async function execute(code, { CodemodeSandbox, root }) {
+  const sandbox = new CodemodeSandbox({ tools: toolsFor(root), timeoutMs: TIMEOUT_MS })
+  try {
+    const r = await sandbox.execute(code)
+    const parts = r.output.map((item) => (item.type === 'text' ? item.text : `[${item.type} output is not supported]`))
+    if (r.ok && r.value !== undefined) parts.push(typeof r.value === 'string' ? r.value : JSON.stringify(r.value, null, 1))
+    if (!r.ok) parts.push(`Script error (${r.error.kind}): ${r.error.stack ?? r.error.message}`)
+    return shape(parts.join('\n'), !r.ok)
+  } finally {
+    await sandbox.close()
+  }
+}
+
+const PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05']
+
+// MCP over stdio is one JSON-RPC message per line, and three methods are all a
+// tools-only server answers, so the protocol is spoken here rather than
+// imported. stdout carries nothing but those messages.
+export function serve({ sandbox, root, version, stdin = process.stdin, stdout = process.stdout }) {
+  const tool = {
+    name: 'codemode',
+    description:
+      'Run JavaScript that explores this repository through read-only tools, and get back only what the script returns. ' +
+      'Use it instead of many separate reads and searches: call tools in parallel with Promise.all, filter and count in the script, return the conclusion. ' +
+      `\`code\` is the body of an async function: \`await\` and \`return\` work at the top level, text(value) adds to the output, and there is no fs, network or process. Paths are relative to ${root}.\n\n` +
+      sandbox.renderDeclarations({ tools: toolsFor(root) }),
+    inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'JavaScript source, the body of an async function' } }, required: ['code'] },
+    annotations: { readOnlyHint: true },
+  }
+  const invalid = (message) => Object.assign(new Error(message), { code: -32602 })
+  // A Map, not an object literal: `method` is untrusted, and "constructor"
+  // would otherwise resolve to something callable.
+  const methods = new Map([
+    ['initialize', (p) => ({ protocolVersion: PROTOCOLS.includes(p?.protocolVersion) ? p.protocolVersion : PROTOCOLS[0], capabilities: { tools: {} }, serverInfo: { name: 'omit', version } })],
+    ['ping', () => ({})],
+    ['tools/list', () => ({ tools: [tool] })],
+    ['tools/call', async (p) => {
+      if (p?.name !== tool.name) throw invalid(`unknown tool: ${p?.name}`)
+      if (typeof p.arguments?.code !== 'string') throw invalid('`code` must be a string')
+      const { text, isError } = await execute(p.arguments.code, { CodemodeSandbox: sandbox.CodemodeSandbox, root })
+      return { content: [{ type: 'text', text }], isError }
+    }],
+  ])
+  const send = (message) => stdout.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`)
+  createInterface({ input: stdin }).on('line', async (line) => {
+    if (!line.trim()) return
+    let message
+    try {
+      message = JSON.parse(line)
+    } catch {
+      return send({ id: null, error: { code: -32700, message: 'parse error' } })
+    }
+    if (message?.id === undefined) return // a notification: nothing to answer
+    const method = methods.get(message.method)
+    if (!method) return send({ id: message.id, error: { code: -32601, message: `method not found: ${message.method}` } })
+    try {
+      send({ id: message.id, result: await method(message.params) })
+    } catch (e) {
+      send({ id: message.id, error: { code: Number.isInteger(e.code) ? e.code : -32603, message: e.message } })
+    }
+  })
+}

package/lib/context.mjs

@@ -0,0 +1,59 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdirSync, lstatSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export const digest = text => createHash('sha256').update(text).digest('hex')
+
+// Advisory heuristics only: shell syntax is not parsed or rewritten here.
+export function readWarnings(command) {
+  if (typeof command !== 'string') return []
+  const warnings = []
+  if (/\b(cat|rg|grep|find)\b/.test(command) && /(?:node_modules|\.git|coverage|\*\*|\$HOME|~\/)/.test(command)) {
+    warnings.push('Broad read: scope the search to source paths and exclude generated directories.')
+  }
+  if (/^\s*cat\s+[^|;>]+$/.test(command)) warnings.push('Whole-file read: prefer a targeted range or search when only part of the file is needed.')
+  if (/\b(?:rg|grep|find)\b.*\s\.(?:\s|$)/.test(command) && !/\|\s*(?:head|tail)\b/.test(command)) warnings.push('Repository-wide read: choose a source subdirectory or bound the returned matches.')
+  return warnings
+}
+
+export function preview(text, limit = 6000) {
+  if (text.length <= limit) return null
+  // Preserve some diagnostic lines even when the failure sits in the middle.
+  const diagnostics = (text.match(/^.*\b(?:error|failed|failure|fatal)\b.*$/gim) ?? []).join('\n').slice(0, Math.floor(limit / 5))
+  const remaining = limit - diagnostics.length
+  const head = Math.ceil(remaining / 2)
+  return { head: text.slice(0, head), tail: text.slice(-(remaining - head)), diagnostics, omitted: text.length - remaining }
+}
+
+// load-bearing: private, owner-controlled storage; never follow an existing symlink.
+export function existingSessionDir(cwd, session) {
+  const path = join(tmpdir(), `omit-context-${process.getuid?.() ?? 'user'}-${digest(`${cwd}\0${session}`).slice(0, 32)}`)
+  try { mkdirSync(path, { mode: 0o700 }) } catch (e) {
+    if (e.code !== 'EEXIST') throw e
+    const stat = lstatSync(path)
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()) || (stat.mode & 0o077)) throw new Error('unsafe context storage')
+  }
+  return path
+}
+
+export function archiveText(dir, text) {
+  const path = join(dir, `${randomUUID()}.txt`)
+  writeFileSync(path, text, { flag: 'wx', mode: 0o600 })
+  return path
+}
+
+export function repeatCount(dir, key) {
+  const path = join(dir, 'repeat.json')
+  let previous = {}
+  try {
+    const stat = lstatSync(path)
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024) throw new Error('unsafe repeat state')
+    previous = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (e) { if (e.code !== 'ENOENT') throw e }
+  const count = previous.key === key ? Math.min((previous.count || 0) + 1, 1000000) : 1
+  const temporary = join(dir, `${randomUUID()}.json`)
+  writeFileSync(temporary, JSON.stringify({ key, count }), { flag: 'wx', mode: 0o600 })
+  renameSync(temporary, path)
+  return count
+}

package/lib/doctor.mjs

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, isAbsolute, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import { probe } from './git.mjs'
+
+// Read-only: never execute discovered hook commands to test their health.
+export function doctor(cwd, codexHome = process.env.CODEX_HOME || join(homedir(), '.codex')) {
+  const findings = []
+  const seen = new Set()
+  const files = [...new Set([join(codexHome, 'hooks.json'), join(cwd, '.codex', 'hooks.json'), join(cwd, '.claude', 'settings.json')])]
+  for (const file of files) {
+    if (!existsSync(file)) { findings.push({ level: 'info', file, message: 'No hooks file.' }); continue }
+    try {
+      const doc = JSON.parse(readFileSync(file, 'utf8'))
+      if (!doc.hooks || typeof doc.hooks !== 'object' || Array.isArray(doc.hooks)) throw new Error('invalid hooks object')
+      for (const [event, groups] of Object.entries(doc.hooks)) {
+        if (!Array.isArray(groups)) throw new Error('invalid hook groups')
+        for (const group of groups) {
+          if (!Array.isArray(group.hooks)) throw new Error('invalid hooks list')
+          if (group.matcher) {
+            try { new RegExp(group.matcher) } catch { findings.push({ level: 'error', file, message: `${event}: invalid matcher.` }) }
+            if (/exec_command|^exec$|^shell$/.test(group.matcher) && !group.matcher.includes('Bash')) findings.push({ level: 'warning', file, message: `${event}: shell matcher lacks canonical Bash; verify harness aliases.` })
+          }
+          for (const hook of group.hooks) {
+            if (hook.type !== 'command') { findings.push({ level: 'info', file, message: `${event}: non-command hook not inspected.` }); continue }
+            if (typeof hook.command !== 'string') throw new Error('missing hook command')
+            const key = `${event}\0${group.matcher ?? ''}\0${hook.command}`
+            if (seen.has(key)) findings.push({ level: 'warning', file, message: `${event}: duplicate hook registration.` })
+            seen.add(key)
+            const match = /^(?:\S*\/)?(?:node|python3?)\s+(?:"([^"$]+)"|'([^']+)'|([^\s$;|&]+))\s*$/.exec(hook.command)
+            if (!match) { findings.push({ level: 'info', file, message: `${event}: command shape not statically checked.` }); continue }
+            const script = match[1] ?? match[2] ?? match[3]
+            const path = isAbsolute(script) ? script : resolve(cwd, script)
+            findings.push({ level: existsSync(path) ? 'info' : 'error', file, message: `${event}: script ${existsSync(path) ? 'exists' : 'missing'}: ${path}` })
+            if (existsSync(path) && path.endsWith('.py')) {
+              const source = readFileSync(path, 'utf8')
+              const names = /^TOOL_NAMES\s*=\s*\{([^}\n]*)\}/m.exec(source)?.[1]
+              if (names && /['"](?:exec|exec_command|shell)['"]/.test(names) && !/['"]Bash['"]/.test(names)) {
+                findings.push({ level: 'warning', file, message: `${event}: literal Python TOOL_NAMES omits Bash; synthetic payload testing recommended.` })
+              }
+            }
+          }
+        }
+      }
+    } catch { findings.push({ level: 'error', file, message: 'Unreadable or malformed hooks configuration.' }) }
+  }
+  const git = probe(cwd, ['config', '--get', 'core.hooksPath'])
+  if (git.ok && git.out.trim()) findings.push({ level: 'warning', message: 'core.hooksPath overrides the repository .git/hooks directory.' })
+  return { liveDelivery: 'unverified', scope: 'global Codex and current-directory Codex/Claude hook files; selected script existence and Git routing', findings }
+}

package/lib/patch-paths.mjs

@@ -0,0 +1,28 @@
+// Codex reports apply_patch as tool_input.command, not file_path.
+// Return null for other tools; deletions have no surviving file to inspect.
+export function patchPaths(data) {
+  if (data.tool_name !== 'apply_patch') return null
+  const patch = data.tool_input?.command
+  // load-bearing: malformed patch payloads must not silently pass inspection.
+  if (typeof patch !== 'string') throw new Error('apply_patch requires tool_input.command')
+  const lines = patch.trim().split(/\r?\n/)
+  if (lines.shift() !== '*** Begin Patch' || lines.pop() !== '*** End Patch') {
+    throw new Error('unrecognized apply_patch envelope')
+  }
+  const paths = new Set()
+  let current = null
+  for (const line of lines) {
+    const header = /^\*\*\* (Add|Update|Delete) File: (.+)$/.exec(line)
+    if (header) {
+      current = header[1] === 'Delete' ? null : header[2]
+      if (current) paths.add(current)
+    } else if (line.startsWith('*** Move to: ')) {
+      if (!current) throw new Error('patch move without a source file')
+      paths.delete(current)
+      current = line.slice('*** Move to: '.length)
+      if (!current) throw new Error('patch move without a destination')
+      paths.add(current)
+    }
+  }
+  return [...paths]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sriinnu/omit",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Omit needless code. Editorial discipline for AI coding agents: draft less, cite everything, cut last: enforced by hooks, a pre-commit gate, and a PR bot, whatever agent writes the code.",
   "type": "module",
   "bin": {
@@ -9,8 +9,7 @@
   "scripts": {
     "test": "node --test",
     "preversion": "npm test",
-    "release": "node scripts/release.mjs",
-    "token:sync": "node scripts/sync-token.mjs"
+    "release": "node scripts/release.mjs"
   },
   "files": [
     "bin",
@@ -36,12 +35,35 @@
     "code-quality",
     "agent-skill",
     "secrets-detection",
-    "pre-commit"
+    "pre-commit",
+    "agent-skills",
+    "claude-skills",
+    "skill-md",
+    "agents-md",
+    "codex",
+    "windsurf",
+    "cline",
+    "github-copilot",
+    "llm",
+    "ai-coding",
+    "code-review",
+    "github-action"
   ],
   "repository": {
     "type": "git",
     "url": "https://github.com/sriinnu/omit.git"
   },
+  "devDependencies": {
+    "@earendil-works/pi-codemode": "^1.0.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-codemode": "^1.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-codemode": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   },

package/skills/omit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: omit
-description: Editorial discipline for AI-written code: omit needless code, cite every claim, cut after it works. Use when writing or changing code, when the user says "omit", "tighten this", "simplest solution", "do less", or complains about over-engineering, bloat, or hallucinated APIs.
+description: "Editorial discipline for AI-written code and local agent guardrails. Use for omit, simplifying code, verifying hook health, or reducing excessive tool output and repeated reads."
 ---
 
 # omit
@@ -11,7 +11,27 @@ Great software is edited, not written. You are the editor, not just the author:
 
 > Draft less. Cite everything. Cut last.
 
-## Modes
+## Hook health and context controls
+
+Use the locally installed `omit` CLI, or `node bin/omit.mjs` from its source
+checkout. These deterministic checks require no model, provider, API key, or
+network call. `omit doctor --json` inspects configuration without executing hook
+commands. Script existence and synthetic tests do not prove live hook delivery.
+
+`omit hook install codex --context` or `omit hook install claude --context`
+merges opt-in context hooks into the current project's hook file. This changes
+host configuration; use it when installation is requested. `omit init skill`
+copies this skill to `.agents/skills/omit/SKILL.md` without overwriting a file.
+
+The context guard warns about broad reads and three consecutive identical
+command/results. It archives long plain-text shell output privately and returns
+head/tail excerpts; inspect the archive when omitted details matter. Structured
+results are untouched. `OMIT_OUTPUT_CHARS` controls excerpt characters (default
+6000, range 1000–100000), not tokens. It is not a quota cap. `OMIT_OFF=1` disables
+the hooks. Other hosts can invoke `omit context` with compatible JSON on stdin;
+verify their output-replacement contract before enabling truncation.
+
+## Editorial modes
 
 - **margin**: build as asked; leave notes in the margin where something could have been omitted.
 - **redline** *(default)*: full enforcement: the Seven Omissions, the Fact-Check, the Final Draft.

package/skills/omit-codemode/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: omit-codemode
+description: "Explore a repository with one sandboxed script instead of many separate reads and searches, so only the answer reaches the conversation. Use when a task needs three or more reads or greps, a loop over files, or a count or summary across the codebase. Read-only."
+---
+
+# omit codemode
+
+*Omit needless context.*
+
+Every separate read or grep puts its raw output into the conversation, where it is paid for again on every later turn. Write one script instead: the reads happen inside it, and only what it returns comes back.
+
+## Run it
+
+```sh
+omit codemode run <<'EOF'
+const libs = (await tools.files({ under: 'lib' })).filter((f) => f.endsWith('.mjs'))
+const sources = await Promise.all(libs.map((path) => tools.read({ path })))
+return Object.fromEntries(libs.map((f, i) => [f, (sources[i].match(/^export /gm) ?? []).length]))
+EOF
+```
+
+Quote the delimiter (`'EOF'`) so the shell leaves the script alone. Exit status 1 means the script failed or its result was withheld.
+
+## The script
+
+The body of an async function: `await` and `return` work at the top level.
+
+| Call | Resolves to |
+|---|---|
+| `tools.files({ under? })` | `string[]`: tracked and untracked files, minus what git ignores |
+| `tools.read({ path })` | `string`: one file as text |
+| `tools.grep({ pattern, under? })` | `{ path, line, text }[]`: extended regular expression; no match is `[]` |
+
+`text(value)` adds to the output and `return` adds the returned value. A call that fails rejects with an `Error`; use `Promise.allSettled` to keep the calls that worked. Run independent calls together with `Promise.all`.
+
+There is nothing else in there: no file system, network, `process` or timers. Paths are relative to the current directory and cannot leave it.
+
+## Return the conclusion
+
+- Return counts, names and the few lines that matter, not file contents. Past 20,000 characters the middle of the result is cut.
+- A result that contains a secret is withheld whole. Filter it out in the script.
+- A script has 60 seconds.
+
+## When not to
+
+- One file or one search: use the ordinary tool.
+- Anything that writes. Codemode is read-only: make edits with the ordinary tools, where the sentinels see them.
+- If the command says its sandbox is not installed, give the user the install line it prints and carry on with ordinary tools. Do not work around it.