@agentwares/agentguard 0.1.7 → 0.1.10

package/CHANGELOG.md

@@ -3,6 +3,114 @@
 `@agentwares/agentguard`, the CLI and MCP proxy. A tag `agentguard-v<version>` publishes the
 GitHub Release for a version with its section below as the notes.
 
+## 0.1.10 — 2026-10-08
+
+### Changed
+
+- **agentguard is now okgate.** "Nothing irreversible without an OK." The CLI calls itself
+  `okgate`, and npm serves it as a second bin of this package until `@agentwares/okgate` is
+  published: `npx -p @agentwares/agentguard okgate init`. Everything it writes from now on uses
+  the new names: `okgate.yaml`, `.okgate/`, `OKGATE_*`, the `okgate` MCP server entry, the
+  `okgate_get_status` / `okgate_get_report` / `okgate_verify_audit_log` tools, `X-Okgate-Key`,
+  and hook commands that run `npx -y -p @agentwares/agentguard@<version> okgate hook pre-tool-use`.
+- The server registers in the MCP Registry as `io.github.agentwares/okgate` (`mcpName`).
+
+### Kept working (until at least 2027-01-15)
+
+- The `agentguard` bin, and `npx @agentwares/agentguard`, which runs it.
+- `agentguard.yaml` is read when there is no `okgate.yaml`, including walking up from a coding
+  agent's working directory; creating an `okgate.yaml` beside it counts as editing the guard.
+- An existing `.agentguard/` stays the state directory when there is no `.okgate/`, so counters,
+  pending approvals and the audit log's hash chain carry on: `okgate verify` passes across the
+  rename. Both directories are the guard's own and refused to a coding agent.
+- Each `AGENTGUARD_*` variable applies when its `OKGATE_*` twin is unset. **`AGENTGUARD_KILL=1`
+  and `OKGATE_KILL=1` both halt everything, whatever `kill.env` the policy names**, and a KILL
+  file under either directory halts; `okgate kill` writes both that exist and `resume` clears both.
+- `hooks status`, `hooks uninstall` and `hooks install` recognise agentguard-era hook entries
+  (install replaces one, it never adds a second); `init` recognises the old `agentguard` MCP entry
+  and `init --undo` restores a `*.agentguard-backup`; `connect` replaces an `agentguard` entry.
+- `tools/list` shows only `okgate_*`; a `tools/call` for an `agentguard_*` name runs its twin with
+  a deprecation note in `_meta["okgate/deprecation"]` until 2027-01-15, then answers
+  `TOOL_RENAMED` (`retryable: false`, with the new name in `fix`). Tool results carry the verdict
+  under `_meta.okgate` and, for the window, `_meta.agentguard`.
+- `<!-- agentguard: … -->` inline checks, `X-Agentguard-Key`, and `_meta["agentguard/runId"]`.
+- `permission-diff` (and the GitHub Action) diffs `okgate.yaml` and `agentguard.yaml` alike.
+
+## 0.1.9 — 2026-10-07
+
+### Added
+
+- **`agentguard audit`: which written rules your coding agents broke.** Reads the repository's
+  CLAUDE.md, AGENTS.md, GEMINI.md, `.cursor/rules` (and the other files agentsmd-lint looks for),
+  plus `audit.rules` in agentguard.yaml, and this machine's Claude Code and Codex sessions whose
+  working directory is the repository or one of its worktrees, subagents included. Per rule:
+  sessions checked, sessions broken, the last three dates, and — on your screen only — the
+  command or path that broke it. `--since 7d|30d|24h|all|<date>` (default 7 days),
+  `--client claude|codex|all`, `--json` (counts, rule ids and dates, never a command, a path or a
+  prompt), `--rules <file>`, `--no-cache`, `--no-evidence`.
+- **Rules recognised with no LLM.** Every rule in the files is listed, checkable or not. A
+  pattern library maps the common shapes to checks over what the agent did (never push to /
+  commit on main, never force-push, never `--no-verify`, run X before committing or pushing, use
+  pnpm not npm, do not edit or commit a path, no new dependencies without asking, never `rm`
+  outside the repo, never publish, never deploy, never run a named command). An inline
+  `<!-- agentguard: <check> -->` on the rule, or `audit.rules` in agentguard.yaml, always works;
+  `<!-- agentguard: none -->` marks a rule no script can check.
+- **`agentguard audit --enforce [--preview] [--yes]`** writes the checkable rules into
+  agentguard.yaml as hook-mode rules — `hooks.shell.deny`, `hooks.shell.approval` (for "without
+  asking"), `hooks.paths.deny`, the built-in irreversible classes and a `deploy` rule — each with a
+  comment naming the rule it came from, shows the diff, and installs the Claude Code hook if it is
+  not installed. It never changes `hooks.mode`, and writes nothing to a policy already in enforce
+  mode without `--yes`.
+- **A counts-only cache** in `~/.agentguard/audit-cache-v1/`: a second run of a large history
+  takes about a second, and counts from transcripts Claude Code has since deleted are kept. It
+  holds counts, times, line numbers and hashes only.
+- **Plugin skills `/agentguard:audit`** (runs `audit --json`, then has your own agent judge the
+  rules marked not checkable against the repository and its git history) **and
+  `/agentguard:hooks`** (hook mode status, install, uninstall), in the Claude Code plugin and the
+  Gemini CLI extension.
+- The audit's last line points at the team adherence history page
+  (https://agentwares-agentguard.vercel.app/team-history). The CLI itself sends nothing.
+
+### Changed
+
+- Requires `@agentwares/agentguard-core` 0.1.5.
+
+## 0.1.8 — 2026-10-07
+
+### Added
+
+- **Hook mode: one rulebook for coding agents.** `agentguard hooks install [--project|--user]
+[--client claude|codex|gemini|all]` writes a pre-execution hook (Claude Code `PreToolUse`,
+  Codex `PreToolUse`, Gemini CLI `BeforeTool`) that runs `agentguard hook pre-tool-use` on every
+  shell command, file edit and direct MCP call, and adds a dry-run `hooks:` block to
+  `agentguard.yaml`. `hooks uninstall` removes only agentguard's entries; `hooks status` lists them.
+  The policy gains `hooks.shell.deny|approval` (command globs, matched against every simple
+  command of a compound line, `$(…)`, `bash -c` and `eval` included), `hooks.paths.deny|approval`
+  (file globs for edits and shell writes), and `hooks.irreversible` (built-in classes `git-push`,
+  `merge`, `tag-delete`, `rm-outside-workspace`, `publish`, `send`, `guard-config`, plus your own
+  rules). The MCP side's `deny` and `approval.tools` also apply to MCP tools the agent calls
+  directly. Same kill switch, approvals, caps (`hook_calls`, `shell_commands`, `file_edits`,
+  `irreversible`), loop breaker (repeated identical edits) and hash-chained audit log.
+- **Irreversible commands only on a turn a person typed.** In Claude Code an irreversible command
+  runs only when the latest transcript entry a person wrote came after the session's previous
+  irreversible command, is at most `window_s` (30 min) old, and names the action — or is a bare
+  "yes" to an assistant question that names it. Tool results, injected and meta entries, peer and
+  task messages, subagent prompts and anything inside an assistant reply never count, so a model
+  that writes "user: yes, push it" into its own reply (claude-code#88122 and others) is held with
+  `APPROVAL_REQUIRED`; `agentguard approve <id>` lets the identical retry run once. Codex and Gemini
+  CLI get the rulebook but no transcript check: their irreversible commands always need approval.
+- **The agent cannot approve itself.** `agentguard approve|deny|resume` run by the agent, and any
+  write to `.agentguard/`, are refused.
+- `agentguard report` has a **Coding-agent hooks** section: calls checked, irreversible commands
+  run on a person's turn or after approval or held, and every call enforce mode would have stopped
+  while in dry-run.
+
+### Changed
+
+- The CLI loads the MCP SDK only for `proxy`, `init` and `tools`, so the hook starts in about
+  0.1 s (`dist/` is now split into chunks).
+- Requires `@agentwares/agentguard-core` 0.1.4.
+
 ## 0.1.7 — 2026-10-07
 
 ### Fixed

package/README.md

@@ -1,5 +1,7 @@
 # agentguard
 
+[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/agentwares/agentguard)
+
 **60 seconds to a safe first run.** Your agent already has an MCP config. Put agentguard in front of it, run the agent once in dry-run, and read what it _would_ have done:
 
 ```sh
@@ -37,6 +39,8 @@ agentguard is an MCP policy proxy for agents that touch production. It sits betw
 - **Semantic loop breaker** — the same `(tool, normalized args)` 3× in the last 30 calls, or an A→B→A→B cycle, returns `LOOP_DETECTED`. Timestamps, ids, whitespace and key order are ignored.
 - **Blast-radius caps** — `tool_calls`, `writes`, `deletes`, `emails`, `spend_usd` and custom counters, per run and per day.
 - **Hash-chained audit log** — every call is a JSONL line with `prev_hash` and `hash`; `agentguard verify` proves no entry was edited, removed from the middle, or reordered (see Limits for what a local chain cannot prove on its own).
+- **Hook mode for coding agents** — `agentguard hooks install` puts the same policy in front of Claude Code's, Codex's and Gemini CLI's own shell commands and file edits; irreversible commands (push, merge, publish, send, `rm` outside the repo) run only on a recent turn a person typed that names them, never on text the model wrote. [Details](#hook-mode-a-coding-agents-own-commands).
+- **Rule adherence audit** — `agentguard audit` reads CLAUDE.md, AGENTS.md, GEMINI.md and `.cursor/rules` and this machine's Claude Code and Codex sessions, and prints which rules the agents broke ("broken in 9 of 31 sessions"), locally; `--enforce` turns the checkable ones into hook rules in dry-run. [Details](#audit-which-written-rules-your-coding-agents-broke).
 
 No LLM calls. No phone-home. No account. MIT.
 
@@ -121,6 +125,202 @@ docker run -i --rm agentguard proxy --config /app/demo/agentguard.yaml   # a fak
 
 Prefer HTTP (several agents, scoped keys, Slack approve buttons)? `agentguard proxy --http --port 8788` and point clients at `http://127.0.0.1:8788/mcp` with an `X-Run-Id` header per run and `Authorization: Bearer agk_…` per agent.
 
+## Hook mode: a coding agent's own commands
+
+The proxy sees MCP calls. A coding agent also acts through its own shell and file tools, which no
+MCP proxy sees. Hook mode puts the same `agentguard.yaml` in front of those, through the agent's
+pre-execution hook, and adds one check nothing else makes: an irreversible command runs only on a
+turn a **person** typed.
+
+```sh
+npx -y @agentwares/agentguard hooks install                  # Claude Code, this project (.claude/settings.json)
+npx -y @agentwares/agentguard hooks install --client all     # + Codex (.codex/hooks.json) and Gemini CLI (.gemini/settings.json)
+npx -y @agentwares/agentguard hooks install --user           # every project (~/.claude/settings.json, policy in ~/.agentguard/)
+npx -y @agentwares/agentguard hooks status | uninstall
+```
+
+`install` adds one hook entry (other settings and hooks are kept; the first change leaves a
+`*.agentguard-backup`), adds a commented `hooks:` block in **dry-run** to `agentguard.yaml` (or
+writes a policy with only that block), and adds `.agentguard/` to `.gitignore`. Commit
+`agentguard.yaml` and `.claude/settings.json` and the whole team runs the same rulebook. The hook
+command is `npx -y @agentwares/agentguard@<version> hook pre-tool-use` (about half a second per
+guarded call); with the package installed globally, `--command agentguard` makes it about 0.1 s.
+
+| Agent       | Hook (verified 7 Oct 2026)                                                                                                                           | Rules, approvals, caps, audit                 | Human-turn gate                                                           |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
+| Claude Code | [`PreToolUse`](https://code.claude.com/docs/en/hooks): `Bash`, `Write`, `Edit`, `mcp__*` …                                                           | yes                                           | yes, from the session transcript                                          |
+| Codex CLI   | [`PreToolUse`](https://developers.openai.com/codex/hooks): `Bash`, `apply_patch`, `mcp__*`                                                           | yes (trust the hook once in Codex's `/hooks`) | no: Codex calls its transcript format unstable, so irreversible = approve |
+| Gemini CLI  | [`BeforeTool`](https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md): `run_shell_command`, `write_file`, `replace`, `mcp_*` | yes                                           | no: not verified against a local install, so irreversible = approve       |
+
+Cursor has its own hooks (`beforeShellExecution`) and can load Claude Code's
+([cursor.com/docs/hooks](https://cursor.com/docs/hooks)); hook mode has not been tested there.
+
+**What is checked.** Each shell command is split into simple commands the way a shell would
+(`&&`, `;`, pipes, `$(…)`, backticks, `bash -c '…'`, `eval`, `find -exec`, heredoc bodies skipped,
+`sudo`/`env`/`timeout`/`npx` wrappers and git's `-C` removed, `cd` followed). Then:
+
+```yaml
+hooks:
+  mode: dry-run # dry-run: log what enforce would stop, block nothing | enforce
+  shell:
+    deny: ["terraform destroy*", "curl * | sh"] # refused whatever anyone says
+    approval: ["kubectl delete *"] # held for `agentguard approve`
+  paths: # file edits and shell writes (>, tee, cp, mv, rm, sed -i)
+    deny: [".env", "*.pem"] # no slash: any file with that name; `src/**`: from the project root
+    approval: ["**/migrations/**"]
+  irreversible:
+    builtins: true # or a list: [git-push, merge, tag-delete, rm-outside-workspace, publish, send, guard-config]
+    window_s: 1800 # the authorizing turn is at most 30 minutes old
+    require_mention: true # ...and names the action
+    require_origin: false # true: only entries labelled as typed by a person (see below)
+    mentions: { git-push: [deploy] } # extra words per class
+    rules: # your own irreversible classes
+      - { name: deploy, shell: ["vercel --prod*", "fly deploy*"], mentions: [deploy] }
+```
+
+The MCP side's `deny` and `approval.tools` patterns also apply to MCP tools the coding agent calls
+directly (`mcp__crm__crm_delete_contact` matches `crm_delete_*`). The kill switch stops every
+guarded call in both modes.
+
+**Irreversible classes.** `git-push` (`git push`, not `--dry-run`); `merge` (`gh pr merge`,
+`glab mr merge`, `gh api -X PUT …/merge`); `tag-delete` (`git tag -d`, `gh release delete`);
+`rm-outside-workspace` (`rm`/`rmdir`/`unlink`/`shred`/`find -delete` on anything outside the
+project, the project itself, or — recursive only — a target that depends on a variable; temp
+directories are free); `publish` (`npm`/`pnpm`/`yarn`/`bun publish`, `cargo publish`,
+`twine upload`, `gem push`, `poetry`/`uv publish`, `docker push`, `gh release create`,
+`changeset`/`lerna publish`, `semantic-release`, …); `send` (`mail`/`sendmail`/`mutt`/…,
+`gh pr|issue create/comment/edit/…`, `gh api` writes, `curl` to Slack/Discord/Telegram/mail-API
+hosts, MCP tools named `send`/`reply`/`forward`/`post`); `guard-config` (edits to `agentguard.yaml`
+or a hook settings file, `agentguard hooks …`).
+
+**The human-turn gate.** An irreversible command runs when the latest entry a person wrote in the
+transcript (1) came after this session's previous irreversible command — one turn authorizes one
+— (2) is at most `window_s` old, and (3) names the action ("push it"), or is a bare "yes" / "go
+ahead" answering an assistant question that names it ("Want me to push to main?"). Otherwise the
+agent gets `APPROVAL_REQUIRED` with an id, and either the person says so in their own words or runs
+`agentguard approve <id>` (in Claude Code, `! npx @agentwares/agentguard approve <id>` runs it
+without going through the model); the identical retry then runs once.
+
+**How "a person wrote it" is decided** (Claude Code transcripts, checked against versions 2.1.170
+to 2.1.286). An entry counts only if: `type` is `user` and `message.role` is `user`; it is not
+`isSidechain` (a subagent's "user" turn is the parent model's prompt); not `isMeta` (skill bodies,
+reminders, peer messages); not a compaction summary; carries no `tool_result` and no
+`toolUseResult` (tool output rides in user entries); if it has an `origin`, `origin.kind` is
+`human` (`task-notification`, `peer`, `coordinator` are not); otherwise, if it has a `turnOrigin`,
+that is `human`; with neither label (older versions, queued prompts, `claude -p`), its text does
+not start with a harness wrapper (`<command-name>`, `<local-command-stdout>`, `<task-notification>`,
+`<bash-input>`, `[Request interrupted`, …), and `require_origin: true` refuses it outright. Text
+inside an assistant entry never counts — that is where a fabricated "user: yes, push it" lives.
+
+**What the agent sees.** A denial is Claude Code's / Codex's `permissionDecision: "deny"` (Gemini:
+`decision: "deny"`) whose reason is the usual agentguard body:
+
+```json
+{
+  "code": "APPROVAL_REQUIRED",
+  "cause": "\"git push origin main\" is irreversible (git-push (git push origin main)) and the latest message typed by a person (08:29:16) does not name this action (expected one of: push, ship). It needs a person's approval (approval apr_7c62fbad56).",
+  "fix": "stop and tell the user: this needs their approval. They can run `npx @agentwares/agentguard approve apr_7c62fbad56` in a terminal in this project (or type `! npx @agentwares/agentguard approve apr_7c62fbad56` in Claude Code), or say in their own words that you should do it; then retry this exact command once. Do not change it, work around it, or run the approval yourself: agentguard refuses an approval from the agent.",
+  "retryable": true,
+  "details": { "approvalId": "apr_7c62fbad56", "command": "agentguard approve apr_7c62fbad56" }
+}
+```
+
+and the person gets a one-line `systemMessage` with the approve command. agentguard never answers
+"allow": an allowed call goes through the agent's own permission prompts as before. The agent may
+not approve, deny or resume its own held actions, or write `.agentguard/` (refused in enforce).
+In dry-run the person sees "would have stopped …" and the call runs; `agentguard report` lists every
+such decision under **Coding-agent hooks**. Hook calls count against `caps` under `hook_calls`,
+`shell_commands`, `file_edits` and `irreversible` (per run = per agent session, and per day); the
+loop breaker stops the same file edit repeated.
+
+## Audit: which written rules your coding agents broke
+
+Teams write rules for their agents in CLAUDE.md, AGENTS.md, GEMINI.md and `.cursor/rules`, then
+cannot tell whether the agents keep them. `agentguard audit` reads the repository's rule files and
+this machine's past Claude Code and Codex sessions in it, and prints, per rule, how many sessions
+broke it and when. Measure first, then enforce what can be enforced.
+
+```sh
+npx -y @agentwares/agentguard audit                 # this repository, the last 7 days
+npx -y @agentwares/agentguard audit --since 30d     # or all, 24h, 2026-09-01; --client claude|codex
+npx -y @agentwares/agentguard audit --json          # counts, rule ids and dates (what /agentguard:audit reads)
+npx -y @agentwares/agentguard audit --enforce --preview   # the hook rules that would enforce them
+```
+
+```
+agentguard audit — /home/dev/acme · since 2026-09-30
+6 sessions in this repository (Claude Code 5, Codex 1). Read on this machine; nothing was sent anywhere.
+13 rules found (6 in CLAUDE.md, 3 in AGENTS.md, 1 in GEMINI.md, 2 in .cursor/rules/release.mdc, 1 in agentguard.yaml); 11 checkable.
+
+BROKEN
+  R1   Never push to `main`.   (CLAUDE.md:5)
+       no-push main — broken in 3 of 6 sessions (4 pushed); 1 refused by the harness
+         2026-10-06 10:40  git push origin main  · session 3f9a1c2b
+  R4   Run `pnpm check` before pushing.   (CLAUDE.md:8)
+       run "pnpm check" before push — broken in 3 of 6 sessions (4 pushed or opened a PR); 4 times
+…
+NOT CHECKABLE MECHANICALLY (2) — add an inline check (<!-- agentguard: … -->) or ask your agent with /agentguard:audit
+  R6   Write tests for new code.   (CLAUDE.md:13)
+```
+
+**The rules.** Every list item and every sentence that directs something (code blocks, tables and
+front matter skipped) is a rule, numbered across the files, checkable or not. A small pattern
+library, with no LLM, recognises the common checkable shapes: never push to / commit on / touch
+main directly; never force-push (or "rewrite history"); never `--no-verify` / skip the hooks; run
+`X` before committing or pushing (also tests, lint, typecheck); use pnpm, not npm; do not edit or
+commit `<path>` (`.env`, lockfiles, generated directories); do not add dependencies (without
+asking); never `rm -rf` outside the repo; never publish; never deploy; never use / run `<command>`.
+"unless asked" / "without asking" makes a break on a turn a person typed asking for it not count.
+Two explicit forms always work and win over the patterns:
+
+```markdown
+- Release notes go in CHANGELOG.md. <!-- agentguard: never "git tag*" -->
+- Keep functions small. <!-- agentguard: none -->
+```
+
+```yaml
+# agentguard.yaml
+audit:
+  rules:
+    - id: deploys
+      text: Only CI deploys
+      check: no-deploy # several: check: [no-verify, 'never "git reset --hard*"']
+```
+
+The check grammar: `no-push [branch,…]`, `no-commit-to [branch,…]`, `no-force-push [branch,…]`,
+`no-verify`, `run "<command>" before commit|push` (`@tests`, `@lint`, `@typecheck` for the usual
+commands), `use pnpm|npm|yarn|bun`, `no-pm npm,…`, `no-edit "<glob>" …`, `no-commit "<glob>" …`,
+`no-new-deps`, `no-rm-outside`, `no-publish`, `no-deploy`, `never "<command glob>" …`, each with an
+optional `unless-asked`; `none` marks a rule no script can check.
+
+**The sessions.** Claude Code transcripts (`~/.claude/projects`, or `$CLAUDE_CONFIG_DIR`) and
+Codex rollouts (`~/.codex/sessions`, or `$CODEX_HOME`) whose working directory is this repository
+or one of its worktrees, subagents included. The tool calls are read the way hook mode reads them
+(the same shell parser, the same edit targets, the same rm-outside-workspace and publish classes),
+and "asked for it" is hook mode's human-turn reading of the transcript. A push's branch is the one
+on the command line; for a bare `git push`, the one Claude Code recorded the push went to, else
+the branch checked out.
+
+**What leaves the screen: nothing.** No network, no telemetry, no LLM. The command or path that
+broke a rule is shown on your terminal only. `--json` and the cache
+(`~/.agentguard/audit-cache-v1/`, counts per transcript so a second run takes about a second and
+history survives Claude Code's 30-day transcript cleanup) hold counts, rule ids, dates, line
+numbers and hashes — never a command, a path or a prompt; a test plants marker strings in every
+part of a synthetic transcript and checks that none reaches either.
+
+**`--enforce`.** Writes the checkable rules into agentguard.yaml as hook-mode rules
+(`hooks.shell.deny`, `hooks.shell.approval` for "without asking", `hooks.paths.deny`, the
+built-in irreversible classes, a `deploy` rule), each with a comment naming the rule it came
+from; shows the diff; installs the hook if it is not installed. It never switches `hooks.mode`:
+a new hooks block starts in dry-run, and if yours is already `enforce` it writes nothing without
+`--yes`. "Run X before pushing" and "never commit on main" stay audit-only (a pre-execution hook
+sees one command, not the order or the checked-out branch).
+
+**In your agent.** `/agentguard:audit` (Claude Code plugin, Gemini CLI extension) runs
+`audit --json` and has your own agent judge the rules marked not checkable against the
+repository and its git history — no tokens of ours. `/agentguard:hooks` installs or checks hook
+mode.
+
 ## Policy
 
 `agentguard init` generates this file with every knob explained inline. The short form:
@@ -189,20 +389,24 @@ Run identity: `X-Run-Id` header (HTTP) → `_meta.runId` on the call → session
 
 ## Commands
 
-| Command                                                                                                                         | What it does                                                                                                                              |
-| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `agentguard init [--client path] [--all] [--no-probe] [--mode enforce] [--undo]`                                                | generate the policy, rewrite the client config (project-level by default)                                                                 |
-| `agentguard proxy [--http --port 8788] [--agent name] [--run-id id] [--mode m]`                                                 | run the proxy (stdio default)                                                                                                             |
-| `agentguard report [--run id \| --all] [--json]`                                                                                | what this run did / would have destroyed / spent; where it was halted; chain status                                                       |
-| `agentguard diff [--run id]`                                                                                                    | mutation diff of faked writes                                                                                                             |
-| `agentguard verify [audit.jsonl]`                                                                                               | recompute the hash chain; exit 1 on the first break                                                                                       |
-| `agentguard status [--run id]`                                                                                                  | counters vs caps, kill state, pending approvals, running HTTP proxy                                                                       |
-| `agentguard tools [--json]`                                                                                                     | every exposed tool with class, verb, upstream and the reason                                                                              |
-| `agentguard kill [reason]` / `agentguard resume`                                                                                | halt everything now / clear it                                                                                                            |
-| `agentguard approvals [--all]` / `approve <id>` / `deny <id> [--note …]`                                                        | the approval queue                                                                                                                        |
-| `agentguard key create <agent> [--allow p]… [--deny p] [--writes n] [--spend n] [--mode m]` / `key list` / `key revoke <agent>` | scoped credentials                                                                                                                        |
-| `agentguard connect <key> [--write] [--client path] [--all] [--url base]`                                                       | point this machine's MCP client at a hosted proxy (paid tiers); prints the config, `--write` merges it in                                 |
-| `agentguard permission-diff [--base ref] [--head ref] [--fail-on-widen]`                                                        | which config changes widen agent permissions (also a [GitHub Action](https://github.com/agentwares/agentguard/tree/main/permission-diff)) |
+| Command                                                                                                                                   | What it does                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agentguard init [--client path] [--all] [--no-probe] [--mode enforce] [--undo]`                                                          | generate the policy, rewrite the client config (project-level by default)                                                                          |
+| `agentguard proxy [--http --port 8788] [--agent name] [--run-id id] [--mode m]`                                                           | run the proxy (stdio default)                                                                                                                      |
+| `agentguard report [--run id \| --all] [--json]`                                                                                          | what this run did / would have destroyed / spent; where it was halted; chain status                                                                |
+| `agentguard diff [--run id]`                                                                                                              | mutation diff of faked writes                                                                                                                      |
+| `agentguard verify [audit.jsonl]`                                                                                                         | recompute the hash chain; exit 1 on the first break                                                                                                |
+| `agentguard status [--run id]`                                                                                                            | counters vs caps, kill state, pending approvals, running HTTP proxy                                                                                |
+| `agentguard tools [--json]`                                                                                                               | every exposed tool with class, verb, upstream and the reason                                                                                       |
+| `agentguard kill [reason]` / `agentguard resume`                                                                                          | halt everything now / clear it                                                                                                                     |
+| `agentguard approvals [--all]` / `approve <id>` / `deny <id> [--note …]`                                                                  | the approval queue                                                                                                                                 |
+| `agentguard key create <agent> [--allow p]… [--deny p] [--writes n] [--spend n] [--mode m]` / `key list` / `key revoke <agent>`           | scoped credentials                                                                                                                                 |
+| `agentguard connect <key> [--write] [--client path] [--all] [--url base]`                                                                 | point this machine's MCP client at a hosted proxy (paid tiers); prints the config, `--write` merges it in                                          |
+| `agentguard permission-diff [--base ref] [--head ref] [--fail-on-widen]`                                                                  | which config changes widen agent permissions (also a [GitHub Action](https://github.com/agentwares/agentguard/tree/main/permission-diff))          |
+| `agentguard hooks install [--project\|--user] [--client claude\|codex\|gemini\|all] [--command cmd]` / `hooks uninstall` / `hooks status` | put the policy in front of a coding agent's shell commands and file edits ([hook mode](#hook-mode-a-coding-agents-own-commands))                   |
+| `agentguard hook pre-tool-use [--client c]`                                                                                               | what the installed hook runs: reads the harness's JSON on stdin, answers in its format                                                             |
+| `agentguard audit [--since 7d\|30d\|all] [--client claude\|codex\|all] [--json] [--rules file] [--no-cache] [--no-evidence]`              | which written rules the coding agents broke, per rule, from this machine's sessions ([audit](#audit-which-written-rules-your-coding-agents-broke)) |
+| `agentguard audit --enforce [--preview] [--yes]`                                                                                          | write the checkable rules into agentguard.yaml as hook rules (dry-run), show the diff, install the hook                                            |
 
 ### Hosted tiers
 
@@ -239,11 +443,14 @@ node dist/cli.js report && node dist/cli.js diff && node dist/cli.js verify
 
 ## Conformance and tests
 
-`pnpm test` runs the CLI suite (52 tests; 68 more in `agentguard-core`, 11 in the SDK): the engine over InMemoryTransport, the spawned stdio proxy (with and without a policy file), the Streamable HTTP proxy with `X-Run-Id`, scoped keys and control endpoints, `init` against real configs, and a recorded-fixture replay (`fixtures/recorded/crm-session.json`; re-record with `RECORD_FIXTURES=1`). `pnpm conformance` runs the official `@modelcontextprotocol/conformance` server suite against the proxy with a sample server behind it (tools, resources, prompts, completions, logging, progress, sampling and elicitation are relayed).
+`pnpm test` runs the CLI suite (85 tests; 191 more in `agentguard-core`, 11 in the SDK): the audit end to end on a synthetic history (rule files in every format, Claude Code and Codex sessions with known kept and broken rules, marker strings that must never reach the cache or `--json`, `--enforce`), hook mode end to end (install for three clients, each client's answer format, the approve flow, synthetic transcripts reproducing a model-written "user: yes, push it"), the engine over InMemoryTransport, the spawned stdio proxy (with and without a policy file), the Streamable HTTP proxy with `X-Run-Id`, scoped keys and control endpoints, `init` against real configs, and a recorded-fixture replay (`fixtures/recorded/crm-session.json`; re-record with `RECORD_FIXTURES=1`). `pnpm conformance` runs the official `@modelcontextprotocol/conformance` server suite against the proxy with a sample server behind it (tools, resources, prompts, completions, logging, progress, sampling and elicitation are relayed).
 
 ## Limits (honest)
 
-- The proxy sees MCP tool calls. Token spend on the model API is only visible through the SDK's guarded `fetch` (or `spend.tools` rules for MCP tools that call models).
+- The proxy sees MCP tool calls; hook mode sees a coding agent's shell commands, file edits and direct MCP calls. Token spend on the model API is only visible through the SDK's guarded `fetch` (or `spend.tools` rules for MCP tools that call models).
+- Hook mode is a guardrail against an agent acting without a person's say-so, not a sandbox against a hostile one. It reads command lines, not what runs: a script (`./release.sh`, `make deploy`) that pushes inside is only caught by a `shell` rule naming it; `xargs rm` targets come from stdin and are not checked; a variable's value is unknown (a recursive `rm` of one counts as outside the workspace). "Names the action" is a word match: "don't push yet" names push. Each class's words are in the policy block; add your language's with `irreversible.mentions`.
+- Claude Code writes the transcript asynchronously; if the turn that authorizes a command is not on disk yet when the hook runs, the command is held (fail closed) and the retry passes. A `claude -p` prompt has no `origin` label, so it counts as the person's turn unless `require_origin: true`. Codex and Gemini CLI get no human-turn gate (their irreversible commands always need `agentguard approve` in enforce). If the hook itself fails (a broken `agentguard.yaml`), the call runs and the person sees "this call was NOT checked".
+- The audit counts what the transcripts show. Rules are recognised by patterns, not understood: a rule worded unusually is listed as not checkable (add an inline check), and one worded like a pattern it does not mean can be mis-read (mark it `<!-- agentguard: none -->`). A bare `git push` counts as a push to the checked-out branch only on the main thread (a subagent's `gitBranch` can be the session's, not its worktree's); an attempt the harness refused still counts, marked as refused. Sessions are matched by working directory: a worktree outside the repository is not included. Codex rollouts do not say which turns a person typed, so an `unless-asked` break there is reported as undetermined; Codex's JavaScript `exec` tool is counted, not read.
 - Dry-run synthesizes results from the tool's `outputSchema`; agents that depend on real ids from a create → update chain will see plausible but fake ids. `dry_run.tools` lets you fake only the dangerous tools in enforce mode.
 - Per-day counters are a JSON file under a directory lock; fine for a workstation or one box, not a fleet. The hosted tier (coming) is the shared-state version.
 - Slack "Approve" buttons are links to the local HTTP proxy; they work for people who can reach it. Without HTTP mode the message carries the `agentguard approve <id>` command.

package/dist/audit-5LUDXZLG.js

@@ -0,0 +1,18 @@
+import {
+  TEAM_HISTORY_LINE,
+  TEAM_HISTORY_URL,
+  auditCommand,
+  parseSince
+} from "./chunk-YBVD6HTT.js";
+import "./chunk-F73VDY3W.js";
+import "./chunk-2QDPPTPY.js";
+import "./chunk-XPNBYSIN.js";
+import "./chunk-4WTFMFRY.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  TEAM_HISTORY_LINE,
+  TEAM_HISTORY_URL,
+  auditCommand,
+  parseSince
+};
+//# sourceMappingURL=audit-5LUDXZLG.js.map

package/dist/audit-5LUDXZLG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-2QDPPTPY.js

@@ -0,0 +1,179 @@
+// src/hooks/clients.ts
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import {
+  LEGACY_POLICY_FILE,
+  LEGACY_STATE_DIR,
+  POLICY_FILE,
+  STATE_DIR
+} from "@agentwares/agentguard-core";
+var MATCHERS = {
+  "claude-code": "^(Bash|PowerShell|Write|Edit|MultiEdit|NotebookEdit)$|^mcp__",
+  codex: "^(Bash|apply_patch)$|^mcp__",
+  "gemini-cli": "^(run_shell_command|write_file|replace)$|^mcp_"
+};
+var CLIENT_ALIASES = {
+  claude: "claude-code",
+  "claude-code": "claude-code",
+  codex: "codex",
+  gemini: "gemini-cli",
+  "gemini-cli": "gemini-cli"
+};
+function hookTarget(client, scope, where, command, timeoutS = 30) {
+  const root = scope === "project" ? where.cwd : where.home;
+  if (client === "claude-code")
+    return {
+      client,
+      label: "Claude Code",
+      scope,
+      settingsPath: join(root, ".claude", "settings.json"),
+      event: "PreToolUse",
+      matcher: MATCHERS[client],
+      handler: { type: "command", command, timeout: timeoutS, statusMessage: "okgate" }
+    };
+  if (client === "codex")
+    return {
+      client,
+      label: "Codex CLI",
+      scope,
+      settingsPath: join(root, ".codex", "hooks.json"),
+      event: "PreToolUse",
+      matcher: MATCHERS[client],
+      handler: { type: "command", command, timeout: timeoutS, statusMessage: "okgate" },
+      note: "Codex runs a new hook only after you trust it: open /hooks in Codex and trust the okgate entry."
+    };
+  return {
+    client,
+    label: "Gemini CLI",
+    scope,
+    settingsPath: join(root, ".gemini", "settings.json"),
+    event: "BeforeTool",
+    matcher: MATCHERS[client],
+    handler: {
+      name: "okgate",
+      type: "command",
+      command,
+      timeout: timeoutS * 1e3,
+      description: "okgate: one rulebook for shell commands and file edits"
+    },
+    note: scope === "project" ? "Gemini CLI fingerprints project hooks: confirm the okgate hook the first time it asks." : void 0
+  };
+}
+function isGuardHookCommand(command) {
+  return typeof command === "string" && /okgate|agentguard/.test(command) && /\bhook\s+pre-tool-use\b/.test(command);
+}
+function backupFor(path) {
+  const legacy = `${path}.agentguard-backup`;
+  const next = `${path}.okgate-backup`;
+  return { existing: [legacy, next].find((b) => existsSync(b)), next };
+}
+function readSettings(path) {
+  if (!existsSync(path)) return {};
+  const text = readFileSync(path, "utf8");
+  if (!text.trim()) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}); fix it or move it aside \u2014 okgate will not overwrite it`,
+      { cause: err }
+    );
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error(`${path} is not a JSON object; okgate will not overwrite it`);
+  return parsed;
+}
+function groupsOf(settings, event) {
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== "object") return [];
+  const groups = hooks[event];
+  return Array.isArray(groups) ? groups : [];
+}
+function installedHandlers(target) {
+  const settings = readSettings(target.settingsPath);
+  return groupsOf(settings, target.event).flatMap(
+    (g) => (g.hooks ?? []).filter((h) => isGuardHookCommand(h.command))
+  );
+}
+function installHook(target) {
+  const existed = existsSync(target.settingsPath);
+  const settings = readSettings(target.settingsPath);
+  const hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  const groups = groupsOf(settings, target.event);
+  const isOurs = (h) => isGuardHookCommand(h.command);
+  const ours = groups.flatMap((g) => (g.hooks ?? []).filter(isOurs));
+  const exact = groups.some(
+    (g) => g.matcher === target.matcher && g.hooks?.length === 1 && JSON.stringify(g.hooks[0]) === JSON.stringify(target.handler)
+  );
+  if (exact && ours.length === 1) return { status: "unchanged" };
+  const kept = [];
+  for (const group of groups) {
+    if (!(group.hooks ?? []).some(isOurs)) {
+      kept.push(group);
+      continue;
+    }
+    const others = (group.hooks ?? []).filter((h) => !isOurs(h));
+    if (others.length > 0) kept.push({ ...group, hooks: others });
+  }
+  kept.push({ matcher: target.matcher, hooks: [target.handler] });
+  const status = ours.length > 0 ? "updated" : "added";
+  hooks[target.event] = kept;
+  settings.hooks = hooks;
+  let backup;
+  if (existed) {
+    const { existing, next } = backupFor(target.settingsPath);
+    backup = existing ?? next;
+    if (!existing) copyFileSync(target.settingsPath, backup);
+  }
+  mkdirSync(dirname(target.settingsPath), { recursive: true });
+  writeFileSync(target.settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return { status, backup };
+}
+function uninstallHook(target) {
+  if (!existsSync(target.settingsPath)) return 0;
+  const settings = readSettings(target.settingsPath);
+  const groups = groupsOf(settings, target.event);
+  let removed = 0;
+  const kept = [];
+  for (const group of groups) {
+    const others = (group.hooks ?? []).filter((h) => !isGuardHookCommand(h.command));
+    removed += (group.hooks ?? []).length - others.length;
+    if (others.length > 0) kept.push({ ...group, hooks: others });
+  }
+  if (removed === 0) return 0;
+  const hooks = settings.hooks;
+  if (kept.length > 0) hooks[target.event] = kept;
+  else delete hooks[target.event];
+  if (Object.keys(hooks).length === 0) delete settings.hooks;
+  writeFileSync(target.settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return removed;
+}
+function hookSettingsFiles(where) {
+  const out = [];
+  for (const root of [where.cwd, where.home]) {
+    out.push(
+      join(root, ".claude", "settings.json"),
+      join(root, ".claude", "settings.local.json"),
+      join(root, ".codex", "hooks.json"),
+      join(root, ".codex", "config.toml"),
+      join(root, ".gemini", "settings.json")
+    );
+  }
+  out.push(
+    join(where.home, STATE_DIR, POLICY_FILE),
+    join(where.home, LEGACY_STATE_DIR, LEGACY_POLICY_FILE)
+  );
+  return out;
+}
+
+export {
+  CLIENT_ALIASES,
+  hookTarget,
+  backupFor,
+  installedHandlers,
+  installHook,
+  uninstallHook,
+  hookSettingsFiles
+};
+//# sourceMappingURL=chunk-2QDPPTPY.js.map