rippletide-package 0.1.0

package/reviewer/src/integrations/codex/prepare.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  DEFAULT_EVIDENCE_BUDGET,
+  collectAgentContext,
+} from "../../connect/evidence.js";
+
+function usage() {
+  return `Rippletide Codex Native
+
+Usage:
+  rippletide-codex prepare [path] [--evidence-budget 140000]
+
+What it does:
+  Collects local agent evidence and writes Codex-ready review artifacts.
+  It does not call Rippletide APIs or external model APIs.
+`;
+}
+
+function getOptionValue(args, name) {
+  const equalsPrefix = `${name}=`;
+  const inline = args.find((arg) => arg.startsWith(equalsPrefix));
+  if (inline) return inline.slice(equalsPrefix.length);
+
+  const index = args.indexOf(name);
+  if (index >= 0 && args[index + 1] && !args[index + 1].startsWith("-")) {
+    return args[index + 1];
+  }
+
+  return null;
+}
+
+function getTargetPath(args) {
+  const optionValues = new Set();
+  const evidenceBudget = getOptionValue(args, "--evidence-budget");
+  if (evidenceBudget) optionValues.add(evidenceBudget);
+  return args.find((arg) => !arg.startsWith("-") && !optionValues.has(arg)) ?? ".";
+}
+
+function displayPath(filePath) {
+  const relative = path.relative(process.cwd(), filePath);
+  if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    return relative;
+  }
+  return filePath;
+}
+
+function createRunId() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function reviewerInstructions() {
+  return `# Rippletide Codex-Native Reviewer Instructions
+
+You are running Rippletide inside Codex.
+
+Use the evidence pack as the source of truth. First, silently understand the agent:
+- identity
+- intended job
+- instructions
+- tools/actions
+- permissions and credentials
+- runtime behavior
+- memory/context
+- gates and policies
+- proof/tests/evals
+- business/system footprint
+
+Do not show a long dossier unless the user explicitly asks for it.
+
+Your user-facing job is to produce useful findings only.
+
+Good findings:
+- are specific to this agent
+- connect the agent's intended job to what the code can actually do
+- avoid obvious facts the builder already knows
+- name a concrete mismatch, missing proof, unclear gate, or behavior boundary
+- cite exact file:line evidence
+- include the smallest useful next action
+- sound like a senior teammate, not a compliance report
+- lead with impact, not implementation detail
+- help the user decide what to do next in under 30 seconds
+
+Hard rules:
+- Do not invent runtime proof.
+- Do not create findings from absence alone; tie each finding to an expected action shown in the evidence.
+- Do not use generic advice like "add tests" or "validate inputs" unless it is grounded in this agent's behavior.
+- Return at most 3 findings.
+- Keep each finding short: title plus 4 compact fields.
+- Use backticks only in the evidence line unless a code symbol is essential for understanding.
+- Do not make the title a raw code symptom like "env var is string"; make it an impact statement like "Search limits can be misread at runtime."
+- If there are no strong findings, say so and explain what evidence would be needed.
+
+Return this shape:
+
+Rippletide Review
+
+Agent:
+Found: <N> findings worth your attention.
+Summary: <one sentence about what kind of agent this is and what matters most before shipping>
+
+[1] <impact-first title>
+Impact: <what can break, surprise a user, cost money/time, mutate external systems, lose trust, or hide a real failure>
+Why it happens: <plain-language mechanism, no dense code narration>
+Evidence: <2-4 compact file:line citations>
+Suggested action: <smallest proof or fix>
+
+[2] ...
+
+Next: Which finding should I propose a fix for? Reply 1, 2, 3, or skip.
+
+After the review, mention the saved Rippletide artifact folder in one short line.`;
+}
+
+function actionInstructions() {
+  return `# Rippletide Codex-Native Action Instructions
+
+Use this only after the user chooses a finding or asks you to act.
+
+Inputs:
+- selected finding
+- evidence-pack.md
+- reviewer-instructions.md
+- relevant source files from the target agent repo
+
+Goal:
+Propose the smallest useful edit or manual check for the selected finding.
+
+Rules:
+- Do not broaden scope beyond the selected finding.
+- Do not rewrite architecture.
+- Do not make cosmetic/doc-only edits unless the finding is a documentation mismatch.
+- If the finding needs product judgment, external credentials, a live account, or runtime proof, return a manual check instead of editing.
+- Before editing in Codex-native mode, show the proposed action and wait for user approval unless the user already explicitly asked you to apply it.
+- The approval question is the MVP action hook: the user can apply, comment, refuse, or skip.
+- When editing, use Codex's normal file-edit tools and report exactly what changed.
+- After editing, run the smallest safe local proof you can actually execute.
+- Prefer behavior proof: a test/eval/demo assertion that exercises the changed agent behavior.
+- Treat syntax/type/compile checks as code checks only; do not call them behavior proof.
+- If no safe local proof exists, say "not proven" and give the manual check. Do not claim the finding is fixed from reasoning alone.
+- After proof, offer to re-run Rippletide Codex prepare/review to see whether findings changed.
+
+Use this shape when proposing an action:
+
+Rippletide Action
+
+Finding: <title>
+Confidence: high|medium|low
+Impact: <why acting on this matters>
+Proposed edit: <smallest edit or manual check>
+Files: <files likely touched>
+Proof: <behavior|code|manual, passed|failed|not proven, command or manual check>
+
+Decision: Apply this edit, comment, refuse, or skip?`;
+}
+
+function readme({ root, runDir, evidencePath, reviewInstructionsPath, actionInstructionsPath }) {
+  return `# Rippletide Codex Run
+
+Mode: Codex-native
+Agent root: ${root}
+
+This run prepared local evidence for Codex. It did not call Rippletide APIs or external model APIs.
+
+## Files
+
+- Evidence pack: ${evidencePath}
+- Reviewer instructions: ${reviewInstructionsPath}
+- Action instructions: ${actionInstructionsPath}
+
+## Next
+
+Codex should read the reviewer instructions and evidence pack, then produce the user-facing Rippletide Review.
+
+If the user chooses a finding to fix, Codex should read the action instructions before proposing edits.
+
+Run folder: ${runDir}
+`;
+}
+
+async function prepare(targetPath, options = {}) {
+  const evidenceBudget = options.evidenceBudget ?? DEFAULT_EVIDENCE_BUDGET;
+  const context = await collectAgentContext(targetPath, {
+    evidenceBudget,
+    title: "Rippletide Codex Evidence Pack",
+    description: "This is local evidence for Codex-native agent review. It was prepared without calling Rippletide APIs or external model APIs.",
+    citationRule: "Citation rule: cite facts as `path/to/file.ext:line` using the line numbers shown in the excerpts.",
+  });
+  const runDir = path.join(context.root, ".rippletide", "codex", createRunId());
+  await mkdir(runDir, { recursive: true });
+
+  const evidencePath = path.join(runDir, "evidence-pack.md");
+  const reviewInstructionsPath = path.join(runDir, "reviewer-instructions.md");
+  const actionInstructionsPath = path.join(runDir, "action-instructions.md");
+  const readmePath = path.join(runDir, "README.md");
+  const metaPath = path.join(runDir, "run.json");
+
+  await writeFile(evidencePath, context.evidencePack, "utf8");
+  await writeFile(reviewInstructionsPath, reviewerInstructions(), "utf8");
+  await writeFile(actionInstructionsPath, actionInstructions(), "utf8");
+  await writeFile(readmePath, readme({
+    root: context.root,
+    runDir,
+    evidencePath,
+    reviewInstructionsPath,
+    actionInstructionsPath,
+  }), "utf8");
+  await writeFile(metaPath, `${JSON.stringify({
+    mode: "codex-native",
+    root: context.root,
+    filesFound: context.files.length,
+    excerptsIncluded: context.sources.length,
+    evidenceBudget,
+    runDir,
+    evidencePath,
+    reviewInstructionsPath,
+    actionInstructionsPath,
+    createdAt: new Date().toISOString(),
+  }, null, 2)}\n`, "utf8");
+
+  return {
+    ...context,
+    actionInstructionsPath,
+    evidencePath,
+    readmePath,
+    reviewInstructionsPath,
+    runDir,
+  };
+}
+
+async function main() {
+  const [, , command, ...args] = process.argv;
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(usage());
+    return;
+  }
+
+  if (command !== "prepare") {
+    console.error(`Unknown command: ${command}\n`);
+    console.error(usage());
+    process.exit(1);
+  }
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(usage());
+    return;
+  }
+
+  const evidenceBudgetValue = getOptionValue(args, "--evidence-budget");
+  const evidenceBudget = evidenceBudgetValue ? Number(evidenceBudgetValue) : DEFAULT_EVIDENCE_BUDGET;
+
+  if (!Number.isFinite(evidenceBudget) || evidenceBudget < 10_000) {
+    throw new Error("--evidence-budget must be a number greater than or equal to 10000.");
+  }
+
+  const result = await prepare(getTargetPath(args), { evidenceBudget });
+
+  console.log("Rippletide Codex Native");
+  console.log(`Mode: Codex-native, no Rippletide API call`);
+  console.log(`Agent: ${displayPath(result.root)}`);
+  console.log(`Collected: ${result.files.length} source/config/doc files and ${result.sources.length} readable excerpts`);
+  console.log(`Saved: ${displayPath(result.runDir)}`);
+  console.log("");
+  console.log("Next for Codex:");
+  console.log(`1. Read ${displayPath(result.reviewInstructionsPath)}`);
+  console.log(`2. Read ${displayPath(result.evidencePath)}`);
+  console.log("3. Produce the Rippletide Review for the user");
+  console.log(`4. For fixes, read ${displayPath(result.actionInstructionsPath)}`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/tide/README.md

@@ -0,0 +1,128 @@
+# tide — plain-English runtime policy for coding agents
+
+> Feature flag: `--tide` on `rippletide-package`. **Status: draft / v1 scoped to Codex.**
+> See [`PRD.md`](PRD.md) for the full design.
+
+## What it is
+
+Write your guardrails in plain English in a `POLICY.md`. `rippletide --tide` compiles
+that policy — **once**, with an LLM — into deterministic, reviewable rules, and then
+**enforces them at the agent's tool-call boundary at runtime** (no LLM in the hot path).
+
+It's the [`tide-test`](https://github.com/rippletideco/tide-test) model (prose → rules →
+deterministic `allow`/`deny`/`escalate` before an action runs), but applied to an agent's
+**native tools** (shell, file writes, network) instead of the **MCP transport** — so it
+covers the actions that actually matter, and doesn't depend on the agent using MCP.
+
+**v1 enforces on Codex.** Claude Code, OpenCode, and Pi ship as documented adapter
+placeholders (same interface, stubbed).
+
+```
+POLICY.md  ──compile (gpt-5.4, once)──►  rules.policy.yaml + ontology + golden tests
+                                                    │
+                                         enforce (deterministic)
+                                                    │
+                                   Codex PreToolUse hook → allow / deny / escalate
+```
+
+## Two phases
+
+1. **Compile (authoring, LLM once).** `POLICY.md` + the agent's tool manifest → `gpt-5.4`
+   → `ontology/actions.yaml`, `policies/rules.policy.yaml`, `tests/golden.scenarios.yaml`,
+   `findings.md` (the `tide-test` schema). Validated with `compile` + `test`; you review.
+2. **Enforce (runtime, deterministic).** A ported `tide-test` engine evaluates the rules on
+   every Codex tool call via a `PreToolUse` hook. **No LLM is called at runtime.**
+
+## ⚠️ The LLM step: whose key & compute?
+
+The **compile** step (phase 1 only) calls an LLM (`gpt-5.4`) to turn prose into rules. This
+is a **one-time authoring** call — **enforcement never calls an LLM**. Still, it raises a
+real question: whose API key runs it, and where does the policy + tool data go? Three
+options, each with a different trust/cost profile:
+
+### Option 1 — user's key, on the user's machine  ✅ **chosen for v1**
+The package uses the **user's own** `gpt-5.4` key and makes the call **locally**.
+- **Pros:** nothing leaves the user's environment except to *their own* OpenAI account; no
+  Rippletide compute cost; simplest to ship.
+- **Cons:** the user must have a `gpt-5.4` key; their `POLICY.md` and tool manifest are sent
+  to OpenAI under their account (acceptable for most, but it *is* egress).
+
+### Option 2 — send to Rippletide, generate server-side
+The package uploads `POLICY.md` + the tool manifest to Rippletide, which runs the LLM and
+returns the compiled bundle.
+- **Pros:** no user key needed; one consistent model + prompt; we can improve generation
+  quality centrally and version it.
+- **Cons:** the user's policy and tool inventory **leave their machine to us** — a real
+  privacy/trust ask, especially for enterprises; we bear the compute cost; adds a network
+  dependency to setup.
+
+### Option 3 — Rippletide's key & compute, executed on the user's side
+We ship a scoped/short-lived Rippletide key (or a thin proxy) so the call runs locally on
+the user's machine but on *our* account.
+- **Pros:** no user key required; policy/tool data stays local (goes only to OpenAI, not to
+  us); we control the model.
+- **Cons:** key management and leakage risk (a shipped key is exposed on the client);
+  cost-attribution and abuse concerns; more moving parts.
+
+**Decision for v1: Option 1.** It's the least surprising and keeps the user in full control
+of both their key and their data. We can revisit Option 2/3 once there's demand for
+key-less setup or centrally-managed policy generation — the compile step is isolated behind
+one interface, so switching later is a contained change.
+
+## Usage (v1 — Codex)
+
+Node package (unified with the `rippletide` npm CLI). Locally: `cd tide && npm install`,
+then use `node bin/tide.js <cmd>` (or the `tide` bin). Wired into the parent it's
+`rippletide tide <cmd>`.
+
+```bash
+tide compile --policy POLICY.md --project .tide   # POLICY.md -> rules (LLM) + golden tests
+tide test    --project .tide                        # run the golden scenarios (deterministic)
+tide check   --project .tide --command "rm -rf x"   # try a single command -> ALLOW/DENY
+tide install --project .tide                        # install the Codex PreToolUse hook
+tide status  --project .tide                        # is it live? + allowed/blocked tally
+```
+
+Then run Codex:
+- **App:** *Settings → Hooks → Trust* the hook, then start a new chat.
+- **CLI:** `codex --dangerously-bypass-hook-trust -c features.hooks=true`
+
+Now a command that violates the policy is **blocked before it runs** (the reason is shown to
+the model, which adapts); everything else passes. The compiled policy lives in `.tide/`
+(`rules.policy.yaml`, `ontology/actions.yaml`, `tests/golden.scenarios.yaml`, `findings.md`)
+— all human-readable and reviewable. `.tide/.runtime/events.jsonl` records every firing.
+
+**Identity is simple — no export needed.** `tide compile` auto-detects the OpenAI
+credential you already use — your `OPENAI_API_KEY` env var, or **your Codex login**
+(`~/.codex/auth.json`) — and asks before reusing it:
+
+```
+tide: detected you're already using OpenAI via your Codex login (~/.codex/auth.json), model gpt-5.5 (key sk-pro…6H0A).
+      Use the same to build your rules? [Y/n]
+```
+
+It also matches the model your Codex uses. The key is read locally and used only for the
+one-time compile call; it never leaves your machine except to OpenAI under your own account.
+Override with `--api-key` / `--model`, or decline the prompt to skip the LLM. Enforcement is
+local and needs no credentials.
+
+## Status
+
+- **v1 shipped — Codex (Node):** compile (your key, model auto-matched) → deterministic
+  engine → PreToolUse hook. Verified end-to-end against real `codex` instances:
+  file-modifying commands **and** `apply_patch` edits are blocked; reads run; unit +
+  golden + e2e tests pass. Implemented in Node/ESM (`src/`) to unify with the `rippletide`
+  npm package — one dependency (`js-yaml`).
+- **Placeholders:** Claude Code / OpenCode / Pi adapters are stubbed with their target seam
+  (see [`PRD.md`](PRD.md) §8). **Escalate** currently holds by blocking-with-reason (a live
+  approval queue is future work).
+
+**Requirements:** Node ≥ 18, Codex installed. Tests: `tide/tests/engine.test.mjs`
+(`node --test`, deterministic) and `tide/tests/e2e_codex.mjs` (spawns real `codex`; needs
+an OpenAI credential).
+
+## Related
+
+- [`tide-test`](https://github.com/rippletideco/tide-test) — the original MCP-gateway prototype (schema + deterministic engine we reuse).
+- [`tototozip/x-ray`](https://github.com/tototozip/x-ray) — the X-ray `tide` package; its Codex `PreToolUse` hook is the basis for the Codex adapter here.
+- `rippletide-platform` — the hosted Tide decision path (`/v1/tide/:agentId/decisions`), same `allow/deny/escalate` contract.

package/tide/bin/tide.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Tide CLI entry. Also the `--tide` feature entry point for the parent rippletide package.
+import { main } from "../src/cli.js";
+process.exit(await main(process.argv.slice(2)));

package/tide/examples/no-file-writes/POLICY.md

@@ -0,0 +1,3 @@
+# AC Agent policy
+
+Do not modify any files. The agent may read files and run read-only commands, but it must not create, edit, overwrite, move, or delete any file.

package/tide/src/cli.js

@@ -0,0 +1,173 @@
+// The `tide` CLI — and the `--tide` feature entry point for the parent rippletide package.
+//   tide compile | test | check | install | uninstall | status
+// The parent wires `rippletide --tide <args>` to `main(args)`.
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import * as codex from "./codex.js";
+import { compilePolicy, DEFAULT_MODEL } from "./compile.js";
+import { Engine } from "./engine.js";
+import { detectOpenAI, maskKey } from "./credentials.js";
+import { DEFAULT_DIR, loadBundle, loadScenarios, writeBundle } from "./schema.js";
+
+const PLACEHOLDER_SEAMS = {
+  claude_code: "PreToolUse hook in settings.json -> permissionDecision allow/deny/ask",
+  opencode: "permission rules (its hooks can't block) -> DeniedError",
+  pi: "a pi.on('tool_call') extension returning {block, reason}",
+};
+
+function adapter(agent) {
+  if (agent === "codex") return codex;
+  const seam = PLACEHOLDER_SEAMS[agent];
+  if (seam) throw new Error(`the tide adapter for '${agent}' is a placeholder in v1. Planned seam: ${seam}. Only 'codex' is supported so far.`);
+  throw new Error(`unknown agent '${agent}' (supported: codex; planned: ${Object.keys(PLACEHOLDER_SEAMS).join(", ")})`);
+}
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  const opts = { agent: "codex", project: DEFAULT_DIR, policy: "POLICY.md", model: null, apiKey: null, command: null };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    if (a === "--agent") opts.agent = next();
+    else if (a === "--project") opts.project = next();
+    else if (a === "--policy") opts.policy = next();
+    else if (a === "--model") opts.model = next();
+    else if (a === "--api-key") opts.apiKey = next();
+    else if (a === "--command") opts.command = next();
+  }
+  return { cmd, opts };
+}
+
+function confirm(question) {
+  if (!process.stdin.isTTY) return Promise.resolve(true); // auto-yes when non-interactive
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(`${question} [Y/n] `, (ans) => {
+    rl.close();
+    resolve((ans.trim().toLowerCase() || "y") === "y" || ans.trim().toLowerCase() === "yes");
+  }));
+}
+
+async function resolveCredential(opts) {
+  if (opts.apiKey) return { apiKey: opts.apiKey, model: opts.model };
+  const det = detectOpenAI();
+  if (!det) return { apiKey: null, model: opts.model };
+  const modelTxt = det.model ? `, model ${det.model}` : "";
+  console.log(`tide: detected you're already using OpenAI via ${det.source}${modelTxt} (key ${maskKey(det.apiKey)}).`);
+  if (await confirm("      Use the same to build your rules?")) {
+    return { apiKey: det.apiKey, model: opts.model || det.model };
+  }
+  console.log("tide: ok — not using it. Pass --api-key or set OPENAI_API_KEY, or rules fall back to heuristics.");
+  return { apiKey: null, model: opts.model };
+}
+
+function runScenarios(bundle, scenarios) {
+  const engine = new Engine(bundle);
+  let passed = 0;
+  const failures = [];
+  for (const s of scenarios) {
+    const d = engine.decide(s.action, s.params, s.context, s.session);
+    let ok = d.verdict === s.expect;
+    if (s.expect_rules?.length) {
+      const seen = [...d.fired, ...d.shadow].map((f) => f.id);
+      ok = ok && s.expect_rules.every((r) => seen.includes(r));
+    }
+    if (ok) passed++;
+    else failures.push(`${s.name}: expected ${s.expect}, got ${d.verdict} on ${JSON.stringify(s.params)}`);
+  }
+  return { passed, total: scenarios.length, failures };
+}
+
+async function cmdCompile(opts) {
+  const { apiKey, model } = await resolveCredential(opts);
+  if (!apiKey) console.log("tide: no OpenAI credential — using local heuristics for now.");
+  const { bundle, scenarios, diagnostics, source, findings } =
+    await compilePolicy({ policyPath: opts.policy, agent: opts.agent, projectDir: opts.project, model, apiKey });
+  writeBundle(opts.project, bundle, scenarios, findings);
+  console.log(`tide: compiled ${bundle.rules.length} rule(s) from ${opts.policy} via ${source} -> ${opts.project}/`);
+  for (const r of bundle.rules) console.log(`  - ${r.id}  [${r.mode}/${r.verdict}]  ${r.when || "requires " + JSON.stringify(r.requires)}`);
+  const errs = diagnostics.filter((d) => d.level === "error");
+  if (errs.length) { console.log(`\ntide: ${errs.length} validation error(s):`); for (const d of errs) console.log(`  ! ${d.where}: ${d.message}`); return 1; }
+  const { passed, total, failures } = runScenarios(bundle, scenarios);
+  console.log(`\ntide: golden tests ${passed}/${total} passed`);
+  for (const f of failures) console.log(`  ! ${f}`);
+  console.log(`tide: review ${opts.project}/findings.md, then \`tide install\`.`);
+  return failures.length ? 1 : 0;
+}
+
+function cmdTest(opts) {
+  const scenarios = loadScenarios(opts.project);
+  if (!scenarios.length) { console.log(`tide: no golden scenarios in ${opts.project}/tests/. Run \`tide compile\` first.`); return 1; }
+  const { passed, total, failures } = runScenarios(loadBundle(opts.project), scenarios);
+  console.log(`tide: ${passed}/${total} golden tests passed`);
+  for (const f of failures) console.log(`  ! ${f}`);
+  return failures.length ? 1 : 0;
+}
+
+function cmdCheck(opts) {
+  if (!opts.command) { console.error("tide: --command is required"); return 1; }
+  const bundle = loadBundle(opts.project);
+  const action = "shell" in bundle.actions ? "shell" : opts.agent;
+  const d = new Engine(bundle).decide(action, { command: opts.command }, {}, []);
+  console.log(`${d.verdict.toUpperCase()}  ${opts.command}`);
+  if (d.reasons.length) console.log(`  reason: ${d.reasons.join("; ")}`);
+  if (d.fired.length) console.log(`  rules: ${d.fired.map((f) => f.id).join(", ")}`);
+  return d.verdict === "allow" ? 0 : 2;
+}
+
+function cmdInstall(opts) {
+  if (!fs.existsSync(path.join(opts.project, "policies", "rules.policy.yaml"))) {
+    console.log(`tide: no compiled policy at ${opts.project}/. Run \`tide compile\` first.`); return 1;
+  }
+  const p = adapter(opts.agent).install(opts.project);
+  console.log(`tide: enforcement installed for ${opts.agent} -> ${p}`);
+  console.log(`tide: policy project = ${path.resolve(opts.project)}`);
+  console.log("\nTo run your agent with the guard active:");
+  console.log("  - Codex app: open Settings -> Hooks and click Trust, then start a new chat.");
+  console.log("  - Codex CLI: codex --dangerously-bypass-hook-trust -c features.hooks=true");
+  return 0;
+}
+
+function cmdUninstall(opts) { adapter(opts.agent).uninstall(); console.log(`tide: enforcement removed for ${opts.agent}`); return 0; }
+
+function cmdStatus(opts) {
+  const installed = adapter(opts.agent).isInstalled();
+  console.log(`tide: enforcement for ${opts.agent}: ${installed ? "INSTALLED" : "not installed"}`);
+  try { const b = loadBundle(opts.project); console.log(`tide: ${b.rules.length} rule(s) in ${path.resolve(opts.project)}`); }
+  catch { console.log("tide: no compiled policy found"); }
+  const events = path.join(opts.project, ".runtime", "events.jsonl");
+  const tally = { allow: 0, deny: 0, escalate: 0, error: 0 };
+  const recent = [];
+  if (fs.existsSync(events)) {
+    for (const line of fs.readFileSync(events, "utf8").split("\n")) {
+      if (!line.trim()) continue;
+      try { const e = JSON.parse(line); tally[e.decision] = (tally[e.decision] || 0) + 1; recent.push(e); } catch { /* skip */ }
+    }
+  }
+  console.log(`tide: firings — allowed ${tally.allow} · blocked ${tally.deny} · escalated ${tally.escalate} · errors ${tally.error}`);
+  for (const e of recent.slice(-5)) {
+    const mark = { allow: "✓", deny: "⛔", escalate: "✋", error: "!" }[e.decision] || "?";
+    console.log(`  ${mark} ${e.decision.padEnd(9)} ${(e.command || "").split("\n")[0].slice(0, 70)}`);
+  }
+  return 0;
+}
+
+const HELP = `tide — compile a plain-English POLICY.md into deterministic guardrails on a coding agent's tool calls.
+
+Usage: tide <command> [--policy POLICY.md] [--project .tide] [--agent codex] [--model M] [--api-key K]
+  compile    POLICY.md + tools -> rules (uses your OpenAI credential; auto-detected)
+  test       run the golden scenarios through the deterministic engine
+  check      --command "..."  evaluate a single command -> ALLOW/DENY
+  install    install the enforcement hook into the agent (codex)
+  uninstall  remove the hook
+  status     show enforcement state + pass/block tally`;
+
+export async function main(argv) {
+  const { cmd, opts } = parseArgs(argv);
+  const cmds = { compile: cmdCompile, test: cmdTest, check: cmdCheck, install: cmdInstall, uninstall: cmdUninstall, status: cmdStatus };
+  if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") { console.log(HELP); return cmd ? 0 : 1; }
+  if (!cmds[cmd]) { console.error(`tide: unknown command '${cmd}'\n\n${HELP}`); return 1; }
+  try { return await cmds[cmd](opts); }
+  catch (e) { console.error(`tide: ${e.message}`); return 1; }
+}

package/tide/src/codex.js

@@ -0,0 +1,65 @@
+// Codex adapter — install/remove the Tide PreToolUse hook (from x-ray's tide.js).
+// Writes a PreToolUse hook into $CODEX_HOME/hooks.json that runs this package's hook.js
+// under the current Node, pointed at the compiled policy via TIDE_PROJECT.
+//
+// Codex 0.142 requires persisted hook trust:
+//   app: Trust the hook in Settings -> Hooks (one click);
+//   CLI/exec/tests: pass --dangerously-bypass-hook-trust.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HOOK_PATH = fileURLToPath(new URL("./hook.js", import.meta.url));
+const MARKER = "rippletide-tide";
+
+export function codexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+}
+export function hooksPath() {
+  return path.join(codexHome(), "hooks.json");
+}
+
+function shq(s) { return `'${String(s).replace(/'/g, "'\\''")}'`; }
+
+export function hookCommand(projectDir) {
+  // marker lets us recognise our own hook; TIDE_PROJECT points at the compiled policy
+  return `TIDE_PROJECT=${shq(path.resolve(projectDir))} ${shq(process.execPath)} ${shq(HOOK_PATH)} --${MARKER}`;
+}
+
+export function install(projectDir) {
+  const home = codexHome();
+  fs.mkdirSync(home, { recursive: true });
+  const p = hooksPath();
+  if (fs.existsSync(p)) {
+    const existing = fs.readFileSync(p, "utf8");
+    if (!existing.includes(MARKER) && !fs.existsSync(p + ".tide-bak")) {
+      fs.writeFileSync(p + ".tide-bak", existing);
+    }
+  }
+  const entry = {
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: "command", command: hookCommand(projectDir),
+                    statusMessage: "Tide: checking this command against your policy" }] },
+      ],
+    },
+  };
+  fs.writeFileSync(p, JSON.stringify(entry, null, 2));
+  return p;
+}
+
+export function uninstall() {
+  const p = hooksPath();
+  if (!fs.existsSync(p)) return;
+  if (!fs.readFileSync(p, "utf8").includes(MARKER)) return; // not ours
+  const bak = p + ".tide-bak";
+  if (fs.existsSync(bak)) { fs.copyFileSync(bak, p); fs.rmSync(bak); }
+  else fs.rmSync(p);
+}
+
+export function isInstalled() {
+  const p = hooksPath();
+  return fs.existsSync(p) && fs.readFileSync(p, "utf8").includes(MARKER);
+}