prae-cli 0.9.2 → 0.10.1

package/lib/docs/pilot-claude-code.md

@@ -0,0 +1,192 @@
+# Pilot: PRAE on one Claude Code laptop
+
+PRAE runs as a Claude Code `PreToolUse` hook. Before every tool call (built-in
+tools such as `Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`, and
+every MCP tool `mcp__<server>__<tool>`), Claude Code runs `prae hook
+claude-code`. The hook judges the call against a policy pack with the same
+kernel the other PRAE harnesses use, and appends the verdict to a signed,
+hash-chained ledger on this machine.
+
+It starts in **shadow mode**. Shadow mode records every verdict and blocks
+nothing. When the record looks right, one command switches it to **enforce**.
+
+There is no cloud account, no open port, no network call and no service to run.
+
+**Verified on Claude Code 2.1.233**, from a fresh clone, by following this
+guide in a temporary project:
+
+- **Shadow.** One headless session made 10 tool calls: `Read`, `Write`, `Edit`,
+  `Bash`, `Glob`, `Grep`, `WebFetch` and `mcp__prae__read_file`. All 10 ran,
+  and each one was sealed with its verdict. The `.env` read was sealed as a
+  shadow deny (`BASE-005`), and `rm -rf` as a shadow hold (`BASE-002`).
+- **Enforce.** Claude Code refused these: the `.env` read, the same read
+  through the MCP tool, a fetch to an unlisted host, edits to the pack and
+  to the hook settings, a shell command truncating the pack, and a read of
+  the signing key. `rm -rf` and a write outside the workspace were held, and
+  `claude -p` refused them. Nothing protected changed on disk.
+- **Record.** `prae verify` passed the chain, with 25 of 25 signatures.
+
+## 1. Install
+
+You need Node 22.19 or later. Install the CLI globally, then preview the
+change and apply it:
+
+```bash
+npm install -g prae-cli                       # prae-cli 0.10.0 or later carries the hook
+prae init claude-code --scope user            # prints the settings diff, writes nothing
+prae init claude-code --scope user --apply    # installs, shadow mode
+```
+
+Install globally rather than with `npx prae-cli init …`: the settings entry
+runs the `prae` it was installed from, and an `npx` copy lives in npm's
+temporary cache, which npm may clear — the hook would then stop running, and
+Claude Code 2.1.233 lets every call through when a hook cannot start.
+
+You must name a target. `--scope user` is `~/.claude/settings.json`, which
+covers every project. `--scope project` is `./.claude/settings.json`.
+`--settings <file>` is any file you name, for example
+`.claude/settings.local.json`. Nothing is written without `--apply`. The file
+is written back as 2-space JSON, the format Claude Code itself writes, so a
+hand-formatted file shows layout changes in the diff. Its values do not change.
+
+`init` adds one entry and leaves every other setting and hook as it was:
+
+```json
+"PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "timeout": 10,
+  "command": "'/opt/homebrew/bin/node' '…/lib/node_modules/prae-cli/lib/bin.js' hook claude-code --shadow --pack '~/.prae/claude-code/prae-baseline.prae.json' --ledger '~/.prae/claude-code/ledger.jsonl' --key '~/.prae/claude-code/prae-signing.pem' --settings '~/.claude/settings.json'" }] }]
+```
+
+The real file holds absolute paths. The command names the node binary and
+PRAE's own script by absolute path, so it does not depend on `PATH`. If you
+upgrade or reinstall prae-cli, or switch Node versions, run `init` again. Claude Code reloads settings on its own,
+so new tool calls go through PRAE without a restart.
+
+Options:
+
+- `--pack <file>`: use your own pack. The default copies the built-in baseline
+  (13 rules: download-and-execute, `rm -rf`, privilege escalation, block devices,
+  credential files, writes outside the workspace, force-push, publishes, and
+  credential stores — the macOS Keychain through `security` and its files,
+  `.netrc`, `.git-credentials`, `.npmrc`, Docker, kube, GnuPG, gh and gcloud
+  config — read directly or named in a shell command).
+  `prae check <file>` summarises a pack.
+- `--ledger <file>`: write the ledger somewhere else.
+- `--dir <dir>`: keep PRAE's state somewhere other than `~/.prae/claude-code/`.
+
+## 2. What it records, and where
+
+Everything lives in `~/.prae/claude-code/`, which is created with mode 0700:
+
+| File | What it is |
+| --- | --- |
+| `ledger.jsonl` | One row for each tool call. Every Claude Code session on the machine appends to this one file, under a lock, so parallel tool calls and parallel sessions stay one chain. |
+| `prae-signing.pem` | The Ed25519 key that signs each row. It is generated once with mode 0600. |
+| `prae-signing.pub.pem` | The public half. Give it to whoever verifies the record. |
+| `prae-baseline.prae.json` | The pack in force, unless you passed `--pack`. |
+
+Each row holds the time, the Claude Code `session_id`, the `tool_use_id` (as
+`correlation`), the tool, its capability (`fs:read`, `fs:write`,
+`proc:spawn`, `net:fetch`), the subject, the verdict, the rule and its reason,
+the pack's name, version and sha256, and, in shadow mode, `shadow: true`. The
+subject is the path or URL only. A shell call is stored as its program word
+and a hash, never the command line. File contents and tool output are never
+stored.
+
+Read the record:
+
+```bash
+P=~/.prae/claude-code
+prae verify  $P/ledger.jsonl --key $P/prae-signing.pub.pem
+prae report  $P/ledger.jsonl --pack $P/prae-baseline.prae.json --out report.html
+prae console $P/ledger.jsonl --pack $P/prae-baseline.prae.json --out console/
+```
+
+In the report and the console, a shadow verdict is marked `· SHADOW`. It is
+never counted as vetoed or held.
+
+## 3. From shadow to enforce
+
+```bash
+prae init claude-code --scope user --enforce --apply
+```
+
+This replaces PRAE's entry. It does not add a second one. In enforce mode:
+
+| Verdict | What Claude Code does |
+| --- | --- |
+| allow | The hook prints nothing. Claude Code's own permission flow decides, as before. PRAE never answers `allow`, because that would skip your permission prompt. |
+| deny | `permissionDecision: "deny"`. The call does not run, and Claude reads the reason, for example `PRAE BASE-005: … (ledger row 12)`. |
+| ask | `permissionDecision: "ask"`. You get a permission prompt. In a headless `claude -p` run nobody can answer it, so Claude Code refuses the call (verified on 2.1.233). |
+| gate error | The pack does not parse, the ledger cannot be written, the key is unreadable, the payload is broken, or the ledger lock is held for more than 3 seconds. The hook refuses the call (exit 2) and records the error in the ledger when it can. |
+
+In shadow mode a gate error lets the call run. It shows a `systemMessage`
+warning and records a `PRAE-ERROR` row marked `shadow`.
+
+## 4. Uninstall
+
+```bash
+prae init claude-code --scope user --remove --apply
+```
+
+This removes PRAE's hook entry and nothing else. The ledger and the key stay
+in place, because they are the evidence of what ran. Delete
+`~/.prae/claude-code/` yourself when you no longer need them.
+
+## 5. Privacy
+
+Nothing leaves the machine. The hook reads the payload Claude Code passes on
+stdin, reads the pack, appends to a local file, and exits. It opens no port
+and makes no network request. A `WebFetch` is judged by its URL and is never
+fetched by PRAE. For credential checks the gate reads the file the agent is
+about to read, in its own process, and only the finding (type, line,
+confidence) reaches the ledger.
+
+## 6. Limits, stated plainly
+
+- **A hook that cannot start does not block, on current Claude Code.** In
+  enforce mode, PRAE refuses whenever it runs and fails: a bad pack, an
+  unwritable ledger, an exception, its own 3 s lock deadline, or broken
+  input. Before Claude Code 2.1.295, though, a hook that cannot start at all
+  (node or the checkout moved) or that hits Claude Code's 10 s timeout lets
+  the call through. This was checked on 2.1.233. Enforce writes
+  `onFailure: "block"`, which Claude Code 2.1.295 and later honour, and
+  which 2.1.233 ignores.
+- **The shell is judged by its command line, not by its effect.** The baseline
+  stops `Read` of `.env`, but `cat .env` in `Bash` is a different call, and
+  no path rule sees it. Write shell rules (`command`) for the programs you care
+  about. PRAE does not yet screen tool output in Claude Code. A `PostToolUse`
+  hook can only replace output in each tool's exact output shape, which this
+  release does not take on.
+- **PRAE's own files are protected only against plain attempts.** Writes to the
+  pack, the ledger and the hook settings are refused (`PRAE-SELF`), and so are
+  reads of the signing key. Shell commands that name the pack, the settings or
+  the key are refused too, even read-only ones such as `wc -c <pack>`. But the agent runs as you. A shell can spell a path
+  in ways no string check sees, so a determined agent with `Bash` can still
+  edit them. An edited ledger breaks its chain and its signatures. A wholesale
+  rewrite by someone who holds the key needs an external checkpoint
+  (`prae checkpoint`) to catch.
+- **What the hook never sees.** Files you attach with `@` in a prompt are read
+  without a tool call, so no hook fires. Managed settings can switch user hooks
+  off (`allowManagedHooksOnly`, `disableAllHooks`).
+- **Coverage depends on knowing what a tool does.** Built-in tools map to
+  capabilities by name. MCP tools map by their tool name: the reference
+  `filesystem` and `fetch` servers' tools, and `prae mcp`'s own, are
+  recognised. Any other MCP tool is recorded and matched only by rules that
+  name the tool. `WebSearch` has a query, not a URL, so host rules do not
+  apply to it. A path that only appears inside an array (for example
+  `read_multiple_files`) is not path-checked.
+- **What happens after a hold is not recorded.** The row says the call was
+  held (`ask`). Whether you then approved it in the prompt is not written
+  back, because a `PreToolUse` hook gets no outcome. The report lists every
+  enforced hold under "awaiting human".
+- **The agent's own account is not evidence.** In the verification runs the
+  model twice reported a refused call as having run. The ledger, Claude
+  Code's `permission_denials` and the file system agreed with each other, and
+  they are what to read.
+- **Budgets cost a ledger read.** A pack with a `count` rule makes each call
+  count this session's earlier rows in the ledger. Packs without one never
+  read the ledger.
+- **Latency.** Each tool call starts one node process. Measured on an M-series
+  Mac, the built `lib/bin.js` took 30 ms at p50 and 34 ms at p95. Run from
+  `src/bin.ts` with Node's type stripping, it took 60 ms at p50 and 64 ms at
+  p95. A bare `node -e 0` takes 20 ms on the same machine.