@ask-llm/plugin 0.13.0

package/skills/codex-pair/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: codex-pair
+description: Show codex-pair status and set up the per-edit Codex review hook for this project. Detects whether codex-pair is active, paused, or not yet configured. On first run (no marker), offers interactive setup with auto-detected project context. On subsequent runs, shows current state, recent review activity, and toggle instructions. The per-edit hook itself runs automatically; this command is the human-facing dashboard for it.
+---
+
+<!-- PORTABLE-CONTRACT:START -->
+## Portable contract
+
+Set up and report status for recall-first per-edit Codex review. The repository marker carries review context but is not, by itself, authorization on Pi. Preserve bounded file context, debounce, pause/resume, acknowledgement, deduplication, failure disclosure, and explicit host lifecycle limitations.
+<!-- PORTABLE-CONTRACT:END -->
+
+## Host adapters
+
+### Pi adapter
+
+Pi requires project trust, this repository marker, and explicit user-owned allowlist consent through `/codex-pair`. Pairing is asynchronous in TUI/RPC/long-lived JSON modes, uses `tool_result`, and surfaces findings non-blockingly. One-shot print mode, blocking Stop-gate parity, and nested Fable execution are unsupported.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:START -->
+### Claude Code adapter
+
+The existing detailed workflow below is the Claude Code adapter. Its Agent, MCP, hook, `CLAUDE_PLUGIN_ROOT`, and `AskUserQuestion` mechanics apply only on Claude Code; they do not override the Pi adapter above.
+
+
+
+# /codex-pair — setup and status dashboard
+
+`/codex-pair` is a user-invocable command that orchestrates setup-and-status for the codex-pair PostToolUse hook. The HOOK runs automatically on every Edit/Write/MultiEdit when a project opts in via `.codex-pair/context.md`; this COMMAND is what you invoke to set up that opt-in (first time) or check the hook's current state (any time).
+
+The hook empirically catches bugs earlier across any codebase and any task type — the improvement is task-agnostic per the [ADR-077](../../../../docs/DECISIONS.md) 4-task benchmark and the [ADR-095](../../../../docs/DECISIONS.md) lived-experience replication. Reference documentation on what the hook does, its cost characteristics, and its configuration knobs is in the second half of this file (below the Instructions section).
+
+> **Note on what the hook is for:** the bug classes and example domains in the reference section below describe what codex-pair *catches in other projects* — they're benchmark fixtures, not properties of `ask-llm` itself. ask-llm is a CLI bridge between MCP clients and LLM CLIs with no money handling, no auth paths, no user-facing security surface. codex-pair runs against this repo for dogfooding (and continues to catch real bugs — see ADR-095).
+
+## Instructions
+
+### Phase 1: Detect current state
+
+1. Locate the marker by walking up from `process.cwd()` looking for `.codex-pair/context.md`. Stop at `$HOME` or filesystem root.
+
+   ```bash
+   dir=$(pwd); while [ "$dir" != "/" ] && [ "$dir" != "$HOME" ]; do
+     if [ -f "$dir/.codex-pair/context.md" ]; then echo "$dir"; break; fi
+     dir=$(dirname "$dir")
+   done
+   ```
+
+   Set `MARKER_DIR` to the result. Empty result means no marker exists.
+
+2. If `MARKER_DIR` is set, check whether the pause sentinel exists:
+   ```bash
+   [ -f "$MARKER_DIR/.codex-pair/state/paused" ] && echo "PAUSED" || echo "ACTIVE"
+   ```
+
+3. If `MARKER_DIR` is set and state is ACTIVE, read the last 5 log entries:
+   ```bash
+   tail -n 5 "$MARKER_DIR/.codex-pair/log.jsonl" 2>/dev/null | jq -c '{ts: .timestamp, verdict: .verdict, file: .file, concerns: .concerns}'
+   ```
+
+4. If `.codex-pair/ignore` exists, read it for the active patterns.
+
+### Phase 2: Branch on detected state
+
+- **No marker found** → execute Phase 3 (setup)
+- **Marker found, state = PAUSED** → execute Phase 4 (paused dashboard)
+- **Marker found, state = ACTIVE** → execute Phase 5 (active dashboard)
+
+### Phase 3: Interactive setup (no marker found)
+
+1. Tell the user: "codex-pair is not yet configured for this project. Setting up now."
+
+2. Auto-detect project context by reading what's already available:
+   - `package.json` (name, description, dependencies — infers language/framework)
+   - `README.md` first 50 lines (project purpose statement)
+   - `pyproject.toml` / `Cargo.toml` / `go.mod` if present (non-Node projects)
+
+   You (Claude) already have this context in your tools — use Read to fetch the files, then synthesize a one-paragraph project-purpose summary.
+
+3. Draft a `.codex-pair/context.md` from the detected context. Structure:
+   ```markdown
+   # .codex-pair/context.md
+
+   <one-paragraph project-purpose summary derived from README/package.json>
+
+   ## Domain invariants Codex can't infer from a single file
+
+   <draft 3-5 bullet-point invariants based on what you found. Examples
+   to seed thinking — pick the ones that match what this actual project
+   does, drop the ones that don't, add others if obvious>
+
+   - <invariant 1 you inferred>
+   - <invariant 2 you inferred>
+   - <invariant 3 you inferred>
+   ```
+
+4. Use `AskUserQuestion` to confirm before writing. Question shape:
+   > "Here's a draft `.codex-pair/context.md` for your project. Should I create it as-is, let you edit it first, or skip setup?"
+   >
+   > Options: **Create as drafted** (recommended) | **Show me the draft to edit** | **Cancel setup**
+   >
+   > Include the full drafted content as the `preview` field on the recommended option so the user sees it before deciding.
+
+5. On user confirmation:
+   - `mkdir -p .codex-pair`
+   - Write `.codex-pair/context.md` with the confirmed content
+   - Check `.gitignore` for an existing `.codex-pair/` line; if missing, ASK the user whether to append it (don't modify `.gitignore` without consent — they may have an intentional reason for the current state, or want global gitignore instead).
+
+6. Confirm setup with a status table (same format as Phase 5 below):
+   ```
+   ✓ codex-pair active for <MARKER_DIR>
+   Next Edit/Write/MultiEdit will trigger a Codex review.
+   Pause with `/codex-pair-pause` · Resume with `/codex-pair-resume`
+   ```
+
+### Phase 4: Paused dashboard
+
+Read the sentinel file:
+```bash
+cat "$MARKER_DIR/.codex-pair/state/paused" 2>/dev/null
+```
+
+If the sentinel is **non-empty** it is an auto-pause written by the hook (quota exhaustion or consecutive failures — see #176). Parse its JSON body and render:
+
+```
+codex-pair status — <MARKER_DIR>
+
+  State:          AUTO-PAUSED ⏸
+  Paused since:   <at field from JSON>
+  Kind:           <kind field: "quota" or "failures">
+  Reason:         <reason field>
+  Resets ~        <resetHint field>  (omit this line if resetHint is absent)
+
+To resume:  /codex-pair-resume
+To remove:  rm -rf <MARKER_DIR>/.codex-pair
+```
+
+If the sentinel is **empty** it is a manual pause. Render:
+
+```
+codex-pair status — <MARKER_DIR>
+
+  State:          PAUSED ⏸
+  Paused since:   <mtime of .codex-pair/state/paused>
+  Pause reason:   <last entry in log.jsonl with verdict:"skipped" + reason starting with "paused"> (if available)
+
+To resume:  /codex-pair-resume
+To remove:  rm -rf <MARKER_DIR>/.codex-pair
+```
+
+### Phase 5: Active dashboard
+
+Render a status table:
+
+```
+codex-pair status — <MARKER_DIR>
+
+  State:           ACTIVE ✓
+  Marker model:    <model from frontmatter of context.md, or "default (gpt-5.6-sol)">
+  Surface threshold: <surfaceThreshold from frontmatter, or "med">
+  Cost/review:     varies by Codex plan and workload / ~13–50s wall-clock
+
+  Recent reviews (last 5):
+  <timestamp>  <verdict>  <file>  <H#/M#/L# concerns>
+  <timestamp>  <verdict>  <file>  <H#/M#/L# concerns>
+  ...
+
+  Ignore patterns active: <count from .codex-pair/ignore, or "none">
+  Include patterns active: <count from .codex-pair/include, or "none — reviewing all files">
+
+To pause:    /codex-pair-pause
+To exclude a file pattern: append to <MARKER_DIR>/.codex-pair/ignore
+To restrict to specific paths: create <MARKER_DIR>/.codex-pair/include
+```
+
+If recent reviews include any verdicts of `error`, `spawn_failed`, or `timeout`, add a "Recent failures" subsection with the reason field of the most recent failure.
+
+## Reference: hook behavior, when to use, configuration
+
+(Everything below this point is reference documentation for the underlying PostToolUse hook — read this when you need to explain the hook to the user, when sizing whether the hook is worth enabling, or when configuring it via env vars or frontmatter.)
+
+The hook surfaces HIGH and MED concerns to Claude on the next turn; logs everything to `.codex-pair/log.jsonl`. **Empirically catches a class of bug that confidence-filtered review structurally suppresses** — the recall improvement holds across structurally different task types (see ADR-077 for the precision-vs-recall data).
+
+## When to use this vs `/codex-review`
+
+The decision is about **code characteristics**, not project domain. Any project — payments, infra, parsers, plugins, this very repo — has both kinds of code; the recall-first hook earns its keep wherever there's a category of bug that "looks fine but runs wrong."
+
+| Use `/codex-review` (precision-first) | Use codex-pair (recall-first) |
+|---|---|
+| Routine PR review | Code with hidden invariants the model can't infer from one file |
+| Glue code, simple CRUD, refactors | Code where latent bugs cost more than per-edit review (~$0.04–0.07) |
+| You want one comprehensive report | Code evolving fast under written constraints (spec, protocol, ADR) |
+| You're cost-sensitive (~$0.04/review) | State coordination, concurrency, anything order-sensitive |
+| Default for everything | The "looks fine, runs wrong" failure mode would be expensive to catch later |
+
+The empirical finding from the 4-task benchmark (four structurally different task types — CRUD, parsing, RFC-spec implementation, stateful logic): `/codex-review`'s "confidence ≥ 80" filter structurally suppresses **looks-fine-runs-wrong** bugs — code that compiles, lints, and type-checks but produces wrong results at runtime because of an implicit invariant the model couldn't infer from a single file. codex-pair's HIGH/MED/LOW threshold catches them. Different classes of bug, not the same class with different completeness. **The recall improvement is task-agnostic** — measured across all four task types, not just one.
+
+## How to enable it
+
+**Per-project opt-in.** Create a file named `.codex-pair/context.md` in your project root with project context for the reviewer:
+
+```markdown
+# .codex-pair/context.md
+
+This is a payment-processing service. All currency calculations must use
+integer cents internally (floating-point loses precision on every charge).
+Concurrent requests are real. URL inputs are untrusted.
+
+[Add domain invariants Codex can't infer from one file in isolation.
+Examples —
+ Security: "all routes check user.role before any state read".
+ Specs: "protocol XYZ frame format must include version byte".
+ State: "cart syncs to localStorage on every mutation".
+ Concurrency: "this handler must be idempotent under retry".]
+```
+
+The hook is always loaded by the plugin, but **self-gates on this file's presence**. No file → silent no-op (zero codex calls, zero cost). File present → every Edit/Write/MultiEdit triggers a codex review.
+
+The marker file's *presence* is the switch; its *content* is the context codex needs to review intelligently. One artifact, two purposes.
+
+**Do NOT commit the `.codex-pair/` directory** — gitignore it. The marker is per-developer opt-in: each contributor's review context is their own (model preference, severity threshold, project rules they care about). One developer iterating on prompt wording shouldn't dirty the shared history. The hook itself IS project policy (it ships in the plugin); the marker is the per-developer activation switch. Per [ADR-092](../../../../docs/DECISIONS.md), every state artifact (marker, log, cache, ignore globs, pause sentinel, inflight locks) nests under the single directory, so one `.gitignore` line covers everything — including any future state files added later:
+
+```
+.codex-pair/
+```
+
+To onboard a new contributor, point them at this skill (or `apps/docs/plugin/hooks.md`) to write their own marker — or share a template via a separate (committed) `.codex-pair.example/context.md` they can copy and tweak locally.
+
+## How to pause or disable
+
+| Goal | How |
+|---|---|
+| Temporarily for this project (keep marker, keep project context) | `/codex-pair-pause` (resume with `/codex-pair-resume`) |
+| Per-file/per-directory | Add patterns to `.codex-pair/ignore` (gitignore-style globs) |
+| Permanently for this project | `rm -rf .codex-pair/` |
+| Just this session | `/plugin disable ask-llm` |
+| Just this command | `CODEX_PAIR_DISABLED=1 <whatever command>` |
+
+`/codex-pair-pause` writes a `.codex-pair/state/paused` sentinel that the hook checks on every Edit/Write/MultiEdit; while present, the hook exits silently with a `verdict:"skipped"` log entry naming the pause. `/codex-pair-resume` removes the sentinel (and the consecutive-failure counter, so a resumed project doesn't re-pause on the next single failure). The pause is per-project and per-developer — the single `.codex-pair/` gitignore entry already covers the sentinel (and every other state file) per [ADR-092](../../../../docs/DECISIONS.md).
+
+**Auto-pauses self-heal** (2026-07-02 design): a quota auto-pause expires after `CODEX_PAIR_QUOTA_PAUSE_TTL_MS` (default 6h); a failures auto-pause expires after `CODEX_PAIR_FAILURES_PAUSE_TTL_MS` (default 24h) or immediately when the plugin version changed since the pause was written. Expiry is checked at SessionStart (with a reminder or auto-resume notice injected into context) and on every edit. Manual pauses never auto-expire.
+
+## Behavior when active
+
+```
+Claude edits src/billing/charge.ts
+        │
+        ▼
+  PostToolUse hook fires
+        │
+        ├─ Walk up from cwd looking for .codex-pair/context.md
+        │
+        ├─ NOT FOUND → exit silently (no codex call, no log)
+        │
+        └─ FOUND → read marker content as project context
+                   ▼
+                   Run codex review with HIGH/MED/LOW grading
+                   ▼
+                   Surface HIGH+MED to stderr (Claude reads next turn)
+                   ▼
+                   Log every call to .codex-pair/log.jsonl (incl. NONE verdicts)
+```
+
+## Cost characteristics
+
+- Usage varies by Codex plan and workload (`gpt-5.6-sol` with reasoning tokens)
+- ~13–50s per file wall-clock
+- Files >20 KB skipped (override with `CODEX_PAIR_MAX_FILE_BYTES`)
+- node_modules, dist, lockfiles, images skipped automatically
+- A 50-edit session = ~$2–3.50 + ~10–40 cumulative minutes of codex latency
+
+For the typical opted-in project (small surface where review depth matters), this is acceptable. For routine refactor work, leave the marker file out.
+
+## Output format
+
+When codex surfaces concerns to Claude, they appear as system reminders on the next turn, prefixed with `[codex-pair]` and the file path. The full per-call log (including PASS verdicts and timing) is in `.codex-pair/log.jsonl` alongside the marker.
+
+Example concern surface:
+
+```
+[codex-pair] src/billing/charge.ts
+
+[HIGH] Monetary values are modeled as floating-point numbers
+src/billing/charge.ts:12: `price` accepts arbitrary JS numbers for money,
+which violates the stated requirement that currency uses integer cents.
+Use integer minor units such as `priceCents: z.number().int().nonnegative()`.
+```
+
+## Configuration knobs (env vars)
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CODEX_PAIR_DISABLED` | unset | Set to `1` to bypass the hook entirely (kill switch) |
+| `CODEX_PAIR_MAX_FILE_BYTES` | `20000` | Skip files larger than this many bytes |
+| `ASK_CODEX_TIMEOUT_MS` | `800000` | Per-call codex timeout (inherited from @ask-llm/codex-mcp, ADR-074) |
+| `ASK_CODEX_REASONING_EFFORT` | `medium` | Codex reasoning effort for continuous per-edit reviews; `/codex-review` and `/brainstorm` default to `high` instead. |
+| `ASK_CODEX_DEBOUNCE_MS` | `15000` | Settle window: a burst of edits to one file within this window is collapsed into a single review of the settled state (ADR-112). Set to `0` to disable debounce and review every edit synchronously. |
+| `ASK_CODEX_DEBOUNCE_MAX_MS` | `60000` | Hard cap from the first edit of a burst — forces a review even under a continuous edit stream. |
+| `CODEX_PAIR_QUOTA_PAUSE_TTL_MS` | `21600000` (6h) | Quota auto-pauses self-heal after this long. |
+| `CODEX_PAIR_FAILURES_PAUSE_TTL_MS` | `86400000` (24h) | Failure auto-pauses self-heal after this long, or immediately on a plugin-version change. |
+
+Both debounce knobs are also settable per-marker via `context.md` frontmatter (`debounceMs` / `debounceMaxMs`), which takes precedence over the env vars. With debounce on (the default), a review fires shortly *after* you stop editing a file and its verdict surfaces on your next edit or next prompt (via the `UserPromptSubmit` drain) — not synchronously on the triggering edit. Set `debounceMs: 0` in the marker frontmatter for the old synchronous behavior.
+
+## Empirical justification
+
+The design decisions in this skill (HIGH/MED/LOW grading, marker-file gate, complement-not-replacement positioning) come from a 4-task benchmark documented in detail at branch `experiment/codex-pair-poc` and in [ADR-077](../../../../docs/DECISIONS.md). The benchmark deliberately picked four **structurally different task types** so the result would generalize, not be a fluke of one domain — a todo CRUD endpoint, a URL shortener, an RFC-spec implementation (JSON Patch RFC 6902), and a stateful business-logic module. The headline 3-arm comparison from task 4:
+
+```
+Claude alone:                    2/10 probes pass
+Claude + /codex-review:          7/10
+Claude + codex-pair:            10/10
+```
+
+The three probes `/codex-review` missed exemplified the "looks fine, runs wrong" class the precision filter suppresses — numeric-precision drift, cross-cutting validation gaps, edge-case bounds errors. **The improvement reproduced across all four tasks**, not just the headline one — confirming the recall gain is task-agnostic. Wherever a project has implicit correctness invariants the model can't infer from a single file in isolation (and most projects do, somewhere), codex-pair catches them earlier than a confidence-filtered review on a finished PR.
+
+Subsequent lived-experience audit ([ADR-095](../../../../docs/DECISIONS.md)) confirmed the benchmark holds in real flow: codex-pair flagged 32 unique bugs during a single dense broker-implementation session in this very repo, including 2 BLOCKING bugs that `/multi-review` independently re-caught 5+ hours later. The benchmark is reproducible empirical evidence; ADR-095 is the field replication.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:END -->

package/skills/codex-pair-ack/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: codex-pair-ack
+description: Acknowledge a codex-pair finding by its 16-character hash and a user-owned reason. Use when the user wants to suppress a repeated finding reminder or defer a host gate where supported.
+---
+
+<!-- PORTABLE-CONTRACT:START -->
+## Portable contract
+
+Acknowledge one finding by its 16-character concern hash with a non-empty user reason. Acknowledgement suppresses that finding's reminder/gate; it does not disable future reviews or claim the concern was fixed.
+<!-- PORTABLE-CONTRACT:END -->
+
+## Host adapters
+
+### Pi adapter
+
+Run `/codex-pair-ack <hash> <reason>`. On Pi this dismisses the matching reminder; there is no blocking Stop gate.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:START -->
+### Claude Code adapter
+
+The existing detailed workflow below is the Claude Code adapter. Its Agent, MCP, hook, `CLAUDE_PLUGIN_ROOT`, and `AskUserQuestion` mechanics apply only on Claude Code; they do not override the Pi adapter above.
+
+
+
+# Acknowledge a codex-pair HIGH finding
+
+Records an ack for the given finding hash so the codex-pair Stop-gate skips it on future turn-ends. The gate prints a full 16-char hash in its block message, e.g. `[fc69d46835dfd2ab] src/auth.ts` — pass that hash verbatim.
+
+## Instructions
+
+1. **Parse args.** The first whitespace-delimited token is `<hash>` (16-char hex). The remaining text (strip enclosing quotes if present) is `<reason>`. If either is missing, print usage and stop:
+   ```
+   Usage: /codex-pair-ack <hash> "<reason>"
+   Example: /codex-pair-ack fc69d46835dfd2ab "false positive — test-only code path"
+   ```
+
+2. **Locate the `.codex-pair/` directory.** Walk up from the current working directory looking for `.codex-pair/context.md`. The directory that contains `.codex-pair/` is `<markerDir>`. If no marker is found after reaching the filesystem root, tell the user:
+   ```
+   codex-pair is not enabled in this project (no .codex-pair/context.md found). Nothing to acknowledge.
+   ```
+
+3. **Validate the hash** before using it: it must match `^[0-9a-f]{16}$`. If it does not, print the usage block from step 1 and stop (a malformed hash means the user mistyped it).
+
+4. **Record the ack** by running the Bash command below. Substitute real values for `<plugin-root>` (the absolute path of this plugin, i.e. the value of `CLAUDE_PLUGIN_ROOT`), `<markerDir>`, and `<hash>`. **Do NOT interpolate `<reason>` into the command string** — the reason is read from stdin via a single-quoted heredoc so the shell never expands `$(...)`, backticks, or quotes inside it (injection-safe). Replace the `<reason>` line with the user's reason text verbatim:
+   ```bash
+   node --input-type=module -e '
+   import { addAck } from "<plugin-root>/scripts/lib/state.mjs";
+   import { readFileSync } from "node:fs";
+   // With `node -e CODE A B`, process.argv = [node, A, B] (no script-file
+   // placeholder), so argv[1]=markerDir, argv[2]=hash.
+   addAck(process.argv[1], process.argv[2], { reason: readFileSync(0, "utf8").trim() });
+   ' "<markerDir>" "<hash>" <<'CODEX_PAIR_ACK_REASON'
+   <reason>
+   CODEX_PAIR_ACK_REASON
+   ```
+   `addAck` writes a concurrency-safe shard under `<markerDir>/.codex-pair/state/acks/` (creating the directory if needed). The hash is passed verbatim — no resolution is performed.
+
+5. **Confirm** to the user:
+   ```
+   Acknowledged `<hash>` — <reason>. The Stop-gate will skip this finding.
+   ```
+   If the node one-liner exits non-zero, surface the error output so the user can diagnose it.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:END -->

package/skills/codex-pair-pause/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: codex-pair-pause
+description: Pause codex-pair for this project without removing `.codex-pair/context.md`. Writes the shared `.codex-pair/state/paused` sentinel. Use during noisy refactors, hook dogfooding, or other temporary review pauses.
+---
+
+<!-- PORTABLE-CONTRACT:START -->
+## Portable contract
+
+Create the project-local `.codex-pair/state/paused` sentinel without removing the marker or history. This is a manual pause and remains until explicitly resumed.
+<!-- PORTABLE-CONTRACT:END -->
+
+## Host adapters
+
+### Pi adapter
+
+Run `/codex-pair-pause` or create the sentinel exactly as described by the portable contract.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:START -->
+### Claude Code adapter
+
+The existing detailed workflow below is the Claude Code adapter. Its Agent, MCP, hook, `CLAUDE_PLUGIN_ROOT`, and `AskUserQuestion` mechanics apply only on Claude Code; they do not override the Pi adapter above.
+
+
+
+# Pause codex-pair for this project
+
+Pauses the codex-pair hook for the current project without removing the `.codex-pair/context.md` marker. The marker (and its project context) stays in place — only the temporary pause sentinel is written. Resume with `/codex-pair-resume`.
+
+The hook may also pause itself automatically — on provider quota exhaustion or after
+3 consecutive review failures — writing the same sentinel with a JSON body that
+records why (`kind`, `reason`, `resetHint`). Manual and automatic pauses are resumed
+the same way.
+
+## When to use
+
+- Starting a noisy refactor where every edit would surface concerns you've already decided to accept
+- Working on docs/comments/typos where review adds no value
+- Dogfooding the hook itself (avoid recursive self-reviews)
+- Burning down a known-issues list where you don't want codex re-flagging them on every save
+
+For permanent disable, remove the `.codex-pair/` directory instead (`rm -rf .codex-pair/`). For per-file/per-directory opt-out, use `.codex-pair/ignore` (gitignore-style globs).
+
+## Instructions
+
+1. Locate the `.codex-pair/context.md` marker by walking up from the current working directory (the project ROOT is the directory holding `.codex-pair/`). If no marker is found, inform the user: "codex-pair is not enabled in this project (no `.codex-pair/context.md` marker found). Nothing to pause."
+
+2. Create the pause sentinel:
+   ```bash
+   mkdir -p <marker-dir>/.codex-pair/state
+   touch <marker-dir>/.codex-pair/state/paused
+   ```
+   Replace `<marker-dir>` with the directory containing `.codex-pair/`.
+
+3. Confirm to the user with the marker directory path:
+   ```
+   codex-pair paused for <marker-dir>
+   Resume with /codex-pair-resume (or `rm <marker-dir>/.codex-pair/state/paused`)
+   ```
+
+4. If `.gitignore` in the marker directory does not already contain `.codex-pair/`, mention it as a suggestion (do not modify the user's .gitignore without asking).
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:END -->

package/skills/codex-pair-resume/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: codex-pair-resume
+description: Resume codex-pair for this project after a previous pause. Removes `.codex-pair/state/paused` and clears failure state. Review resumes on the next supported file edit; missing state is a no-op.
+---
+
+<!-- PORTABLE-CONTRACT:START -->
+## Portable contract
+
+Remove the project-local pause sentinel and clear the consecutive-failure counter so the next successful edit can be reviewed. Missing state is a no-op.
+<!-- PORTABLE-CONTRACT:END -->
+
+## Host adapters
+
+### Pi adapter
+
+Run `/codex-pair-resume` or remove the sentinel and failure counter exactly as described by the portable contract.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:START -->
+### Claude Code adapter
+
+The existing detailed workflow below is the Claude Code adapter. Its Agent, MCP, hook, `CLAUDE_PLUGIN_ROOT`, and `AskUserQuestion` mechanics apply only on Claude Code; they do not override the Pi adapter above.
+
+
+
+# Resume codex-pair for this project
+
+Removes the pause sentinel written by `/codex-pair-pause`, restoring normal codex-pair review behavior. The `.codex-pair/context.md` marker and `.codex-pair/state/` directory are left in place (the directory holds the cache, inflight locks, and any other future state per [ADR-092](../../../../docs/DECISIONS.md)).
+
+## Instructions
+
+1. Locate the `.codex-pair/context.md` marker by walking up from the current working directory (the project ROOT is the directory holding `.codex-pair/`). If no marker is found, inform the user: "codex-pair is not enabled in this project (no `.codex-pair/context.md` marker found). Nothing to resume."
+
+2. Check whether the pause sentinel exists at `<marker-dir>/.codex-pair/state/paused`:
+   - If it does not exist, tell the user: "codex-pair was not paused — no `.codex-pair/state/paused` sentinel found. No change."
+   - If it exists and is non-empty, it is an auto-pause written by the hook itself
+     (quota exhaustion or repeated failures — see #176). `cat` it and show the user
+     the `kind`, `reason`, and `resetHint` fields before removing, so they know
+     whether the provider has likely recovered.
+   - Remove it, together with the consecutive-failure counter — resuming while
+     the counter is still at threshold would re-pause on the very next single
+     failure. Quote the paths so marker directories with spaces work:
+     ```bash
+     rm -f -- "<marker-dir>/.codex-pair/state/paused" "<marker-dir>/.codex-pair/state/failures.json"
+     ```
+
+3. Confirm to the user with the marker directory path:
+   ```
+   codex-pair resumed for <marker-dir>
+   The next Edit/Write/MultiEdit will trigger a review.
+   ```
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:END -->

package/skills/codex-review/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: codex-review
+description: Get a second opinion from OpenAI Codex on your current code changes. Analyzes staged/unstaged diffs and returns prioritized findings. Use when user asks to "review with Codex", "Codex code review", or "ask Codex to check my code".
+---
+
+<!-- PORTABLE-CONTRACT:START -->
+## Portable contract
+
+Gather the relevant staged, unstaged, and untracked code changes; build a bounded context brief; request a read-only Codex review at high reasoning effort; verify each reported finding against source; and return only prioritized, source-supported findings. Preserve the configured Sol-to-Terra fallback and disclose it.
+<!-- PORTABLE-CONTRACT:END -->
+
+## Host adapters
+
+### Pi adapter
+
+Call the native `ask-codex` tool with `reasoningEffort: "high"` and apply only the `Portable contract` section of `../../agents/codex-reviewer.md`. The review runs inline in the current host context; do not claim subagent isolation.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:START -->
+### Claude Code adapter
+
+The existing detailed workflow below is the Claude Code adapter. Its Agent, MCP, hook, `CLAUDE_PLUGIN_ROOT`, and `AskUserQuestion` mechanics apply only on Claude Code; they do not override the Pi adapter above.
+
+
+
+# Codex Code Review
+
+Review current code changes by delegating to the `codex-reviewer` agent.
+
+## When to use this vs codex-pair
+
+This skill is **precision-first**: confidence ≥ 80, "don't flag style/linter-catchable" filter. Optimized for low false-alarm rate on diff review — appropriate default for routine PRs.
+
+For **recall-first** review on hot-path code (money handling, security paths, spec-implementing code), see the [`codex-pair`](../codex-pair/SKILL.md) sibling — a PostToolUse hook that opts in per-project via a `.codex-pair/context.md` marker file. The 4-task benchmark in ADR-077 shows codex-pair catches domain-level "wrong but won't crash" issues (float-money precision, cross-cutting validation gaps, edge clamping) that this skill's confidence filter structurally suppresses. Different classes of bug, not the same class with different completeness.
+
+| Use this skill | Use codex-pair |
+|---|---|
+| Routine PR review (cheap, high precision) | Money/billing/security/spec code (deeper, costlier) |
+| You want one comprehensive report | You want every concern flagged with severity |
+| Cost-sensitive (~$0.04/PR) | Acceptable cost (~$0.20/edit pass) |
+
+## Instructions
+
+1. Gather the diff to review:
+   - Run `git diff` to get unstaged changes
+   - Run `git diff --cached` to get staged changes
+   - Combine both into a single diff
+
+2. If the diff is empty, inform the user there are no changes to review.
+
+3. Launch the `codex-reviewer` agent with the diff content. The agent handles the Codex prompt structure and output formatting, using GPT-5.6 Sol at `high` reasoning effort with automatic Terra fallback.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:END -->

package/skills/codex-verify/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: codex-verify
+description: Verifies what the assistant claims to have done — proves the work against actual state using OpenAI Codex with a read-only tool surface. Use when the user asks to "verify with Codex", "check the assistant's claims", "did Codex actually do what it said", "verify this turn", "prove the work", or wants a trust check distinct from issue review. Different from `/codex-review`, which finds new issues.
+---
+
+<!-- PORTABLE-CONTRACT:START -->
+## Portable contract
+
+Capture the prior assistant message verbatim, decompose it into atomic claims, and verify those claims against actual repository state with a read-only Codex consultation where useful. This is claim verification, not issue hunting. Preserve the Report block, five-grade confidence ladder, parser fallback, and explicit unverifiable state.
+<!-- PORTABLE-CONTRACT:END -->
+
+## Host adapters
+
+### Pi adapter
+
+Apply only the portable contract in `../../agents/codex-verifier.md` inline and call native `ask-codex` for focused claim checks. Do not claim an isolated verifier context.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:START -->
+### Claude Code adapter
+
+The existing detailed workflow below is the Claude Code adapter. Its Agent, MCP, hook, `CLAUDE_PLUGIN_ROOT`, and `AskUserQuestion` mechanics apply only on Claude Code; they do not override the Pi adapter above.
+
+
+
+# Codex Claim Verification
+
+Prove or disprove what the assistant agent claims to have done in the current turn, independently. This is a **trust check**, not an issue hunt — separate from `/codex-review`.
+
+## Why this is separate from `/codex-review`
+
+- `/codex-review` looks for new bugs in the diff (issue hunt).
+- `/codex-verify` proves the assistant's claims against actual state (trust verification).
+
+A single tool would dilute both contracts. The verifier is **structurally narrowed by design**: it does not propose fixes, does not list issues outside the assistant's claims, does not drift into "while I'm here let me also...". That narrowness is the feature — it forces every "verified" verdict to be backed by a deterministic tool output.
+
+The two skills compose. Run both when you want both questions answered. Do not merge their outputs.
+
+## Instructions
+
+### Phase 1: Gather inputs
+
+1. Combine the diff:
+   - `git diff` (unstaged changes)
+   - `git diff --cached` (staged changes)
+2. **If the diff is empty**, stop and tell the user "no changes to verify."
+3. Capture the assistant's last message — the message in the prior turn where the assistant stated what it did. This is the source of claims to verify. Pass it through verbatim — do not summarize, do not paraphrase. The agent decomposes claims directly from this text.
+
+If the conversation has no prior assistant message stating what was done (e.g., the diff exists but came from a manual edit), tell the user: "no assistant claim to verify — run `/codex-review` for issue review instead."
+
+### Phase 2: Dispatch the verifier agent
+
+Launch the `codex-verifier` agent with two inputs:
+- The combined diff
+- The assistant's last message (verbatim)
+
+The agent owns the contract: read-only tool surface, claim decomposition, per-claim deterministic verification, and the `## Report` output block. Wait for its output.
+
+### Phase 3: Defensive parse of the Report block
+
+Find the `## Report` block in the agent's output. Extract:
+
+- **`STATUS:`** — one of `verified`, `failed`, `unsure`. If missing, treat as `unsure`.
+- **`CONFIDENCE:`** — one of `PERFECT`, `VERIFIED`, `PARTIAL`, `FEEDBACK`, `FAILED`. **If missing, derive from STATUS:**
+  - `verified → VERIFIED`
+  - `failed → FEEDBACK`
+  - `unsure → FAILED`
+
+  This fallback mirrors the Pi verifier's defensive parser — LLMs occasionally drop the second adjacent metadata line, and the consumer should not abort on that.
+- The five sections: "What did you verify?", "What could you not verify?", "Corrective feedback", "What do you need to verify this next time?", "Verification metadata".
+
+### Phase 4: Present the result
+
+```markdown
+## Codex Verification — <CONFIDENCE>
+
+**Status:** <verified | failed | unsure>
+**Atomic claims:** <total> total · <V> verified · <F> failed · <U> unverifiable
+
+### Verified
+- <claim> — <evidence: file:line, command output>
+
+### Failed
+- <claim> — <evidence>
+
+### Unverifiable
+- <claim> — <reason: missing oracle/fixture/runtime>
+
+### Corrective feedback (when STATUS=failed)
+> <verbatim from the agent's report — the user can paste this back to the assistant>
+
+### What's missing for next time
+<from "What do you need to verify this next time?" — these gaps are templates/fixtures/scripts the operator should add to the project to make future verifications stronger>
+```
+
+### Phase 5: Surface the right signal for each grade
+
+- **PERFECT / VERIFIED** — Brief output. Don't bury the lede; one or two sentences confirming the claims are true.
+- **PARTIAL** — **Surface the gaps loudly.** PARTIAL is the most actionable grade for project-level investment: every unverifiable claim is a fixture or script you should consider adding. Highlight the "what's missing for next time" section.
+- **FEEDBACK** — Surface the corrective feedback verbatim. The operator can paste it back to start the next turn with a concrete fix.
+- **FAILED** — The verification harness itself is the bottleneck. Tell the user explicitly: "Codex couldn't verify — the gap is in our verification surface, not in the work." Suggest the missing pieces.
+
+## Important rules
+
+- **Do not merge `/codex-verify` and `/codex-review` outputs.** They answer different questions. If a user wants both, run them separately and present them separately.
+- **Do not rewrite the corrective feedback.** Pass it through verbatim. The agent wrote it precisely; paraphrasing dilutes the actionability.
+- **PARTIAL is a real verdict, not a softer VERIFIED.** Surface the unverifiable claims clearly — those gaps are the next thing the operator templates into the project.
+- **Don't reuse the verifier for "review my code."** That's `/codex-review`'s job. The verifier is structurally narrowed by design and will not return useful issue-hunt output.
+- **No silent drops.** If parsing the Report block fails (e.g., agent didn't emit the block, output truncated), surface that to the user with the raw agent output rather than fabricating a verdict.
+
+<!-- HOST-ADAPTER:CLAUDE-CODE:END -->