@tduyng/pi-guard 0.0.3 → 0.0.4

package/README.md

@@ -1,48 +1,47 @@
 # @tduyng/pi-guard
 
-Four guards that cost nothing until something goes wrong: parallel sessions off each other's files, secrets out of read results, git never hanging on an editor, and a stray rejection never killing the session.
+Four guards for the ways a session ends badly. Three are hooks and spawn no schema, so a session that never needs them pays nothing.
 
-## What it costs
+| Guard | Failure it prevents |
+| --- | --- |
+| `reserve` | A peer session edits a file this session is working on |
+| `cloak` | A key file lands in the transcript and goes to the provider |
+| `git-interceptor` | Git opens an editor and hangs the turn, or `--no-verify` skips a hook |
+| `reject-guard` | One unhandled promise takes down the session |
 
-`reserve` is a deferred tool at 215 tokens in the sessions that load it. The other three are event hooks and spawn no schema at all, so a session that never reserves a path pays nothing for this package.
+Only sessions that load `reserve` pay for it, at 215 tokens.
 
-The failures it prevents are the expensive kind. A session killed mid task costs the whole turn, and a credential in a transcript costs a rotation.
+## Sessions in one folder
 
-## Reserve
+Pi serializes writes inside one process. Two sessions in one folder do not see each other, so the second overwrites a file the first is halfway through reshaping.
 
-Pi serializes writes inside one process, so two sessions in one folder still overwrite each other. This is the cross-session half.
+A session writes what it holds to `.pi/reservations/<session>.json`. A `tool_call` hook refuses `edit` and `write` against a path a live peer holds, and it checks `bash` too, so `sed -i`, `git checkout` and a redirect into a reserved path are turned away while a read-only command passes.
 
-A session records what it holds in `.pi/reservations/<session>.json`, and a `tool_call` hook refuses `edit` and `write` against a path a live peer holds. Reserving `extensions/pi-goal/src/` takes the whole subtree, and an exact path takes one file. `release` with no paths gives everything back, and `list` prints every live session with what it holds.
-
-Liveness is `process.kill(pid, 0)`, so a killed session takes its reservations with it. Nothing to keep alive, no heartbeat, no daemon.
-
-`bash` is checked too: a command that writes a reserved path is turned away, whether it says `sed -i`, `git checkout`, or redirects into the path, while a command that only reads it is left alone.
-
-What this cannot see is a mutation that names no path, so `git add -A` and a bare `git commit` still take whatever is staged. Two sessions committing in one repo also race on `.git/index.lock`, and no reservation covers that. Delegate the commit with `isolation: "worktree"` on `subagent`, which works in a checkout of its own, and the branch it names outlives the checkout.
-
-## Cloak
-
-A `tool_result` hook redacts secrets out of `read` results before they enter the model's context. Three checks, each switchable.
-
-### Vendor keys
-
-Known API key shapes by fixed literal prefix, with a word boundary so a substring inside a longer identifier does not match. No entropy scanning and no shape guessing.
+```text
+reserve({action: "reserve", paths: ["extensions/pi-goal/src/"]})
+reserve({action: "list"})
+reserve({action: "release"})
+```
 
-`AKIA` and `ASIA` for AWS, `sk-` for OpenAI and Anthropic, `sk_live_` and `sk_test_` for Stripe, `ghp_` `gho_` `ghs_` `ghr_` and `github_pat_` for GitHub, `eyJ` for JWTs, `xoxb-` `xoxp-` `xoxa-` `xoxr-` `xoxs-` for Slack, `glpat-` for GitLab, `AIza` for Google, `npm_` for npm, `SG.` for SendGrid, and `Bearer` followed by a token.
+A directory reserves its whole subtree, an exact path reserves one file, and `release` with no paths gives everything back. The refusal names the holder, so the other session is one that can be inspected.
 
-Each match becomes the first 4 characters, then stars (minimum 8, maximum 20), then `[REDACTED:type]`.
+Liveness is `process.kill(pid, 0)`, so a killed session takes its reservations with it. No heartbeat and no daemon. Writes go through a temp file and a rename, so two sessions reserving at once cannot leave a half-written file.
 
-### PEM blocks
+A mutation that names no path is invisible to this, so `git add -A` and a bare `git commit` still take whatever is staged. Two sessions committing in one repository also race on `.git/index.lock`, and no reservation covers that. Commit from a `subagent` with `isolation: "worktree"` instead, whose checkout is its own.
 
-`-----BEGIN ...-----` certificate and key blocks are replaced with `[REDACTED:PEM TYPE]`.
+## Secrets in the transcript
 
-### Sensitive file types
+A `tool_result` hook cleans `read` results on their way into the model. Three checks, each switchable:
 
-A path that matches a sensitive pattern replaces the whole read with one marker, such as `[REDACTED:Protected File (SSH Key)]`. The list covers `.pem`, `.crt`, `.cer`, `.p12`, `.pfx`, SSH keys and `known_hosts` and `authorized_keys`, `.aws/credentials`, `.npmrc`, `.pypirc`, `.netrc`, `.docker/config.json`, and `.kube/config`.
+| Check | Catches | Replacement |
+| --- | --- | --- |
+| Vendor keys | AWS, OpenAI, Anthropic, Stripe, GitHub, Slack, GitLab, Google, npm, SendGrid, JWTs, `Bearer` | First 4 characters, stars, `[REDACTED:type]` |
+| PEM blocks | `-----BEGIN ...-----` certificates and keys | `[REDACTED:PEM TYPE]` |
+| Sensitive paths | `.pem`, `.crt`, `.p12`, SSH keys, `.aws/credentials`, `.npmrc`, `.netrc`, `.docker/config.json`, `.kube/config` | The whole read becomes `[REDACTED:Protected File (...)]` |
 
-### Rules of your own
+Secrets have known prefixes, so `AKIA`, `sk-`, `ghp_`, `glpat-`, `xoxb-`, `AIza` and a dozen more are matched as literals with a word boundary. An earlier version scanned by entropy and flagged nix store hashes and `sha256` digests in derivations, so that check is gone.
 
-`cloak.json` in the agent directory, or `.pi/cloak.json` in a project, adds patterns. A project file overrides the scalar keys and appends its `patterns` to the agent dir ones.
+Custom rules go in `<agent-dir>/cloak.json` or `.pi/cloak.json`. A project file overrides the scalar keys and appends its `patterns`.
 
 | Key | Default | Meaning |
 | --- | --- | --- |
@@ -50,28 +49,24 @@ A path that matches a sensitive pattern replaces the whole read with one marker,
 | `cloakCharacter` | `*` | Masking character |
 | `cloakLength` | `null` | Fixed replacement length, null keeps the original |
 | `tryAllPatterns` | `true` | Apply every matching rule, not just the first |
-| `patterns` | `[]` | Rules with `filePattern` (glob), `cloakPattern` (regex), and optional `replace` |
+| `patterns` | `[]` | Rules with `filePattern` (glob), `cloakPattern` (regex), optional `replace` |
 | `vendorKeys` | `true` | Built-in prefix detection |
 | `pemBlocks` | `true` | PEM detection |
-| `sensitiveFileTypes` | `true` | Whole-file redaction for sensitive paths |
-
-When two matches overlap the same span, the first applied wins and later overlapping matches are skipped. `/cloak-status` shows whether cloak is on, how many custom patterns loaded, and which built-in checks are active.
+| `sensitiveFileTypes` | `true` | Whole-file redaction |
 
-A nix store hash, a `narHash` field, or a sha256 digest in a derivation will not false-positive, because nothing scans by entropy. The hook does not touch the outbound provider payload, the assistant's reply, or any tool other than `read`. A custom `patterns` match replaces only the matched spans, while a sensitive file type replaces the whole read.
+When two matches overlap, the first rule applied wins. A custom pattern replaces only its matched spans, while a sensitive file type replaces the whole read. `/cloak-status` shows whether cloak is on, how many custom patterns loaded, and which built-in checks are active.
 
-## Git interceptor
+## Git in a non-interactive turn
 
-Two guards for agent-driven git.
+`GIT_EDITOR=true`, `GIT_SEQUENCE_EDITOR=true` and `GIT_MERGE_AUTOEDIT=no` go on `process.env`. Pi builds a child's environment by spreading `process.env`, so one assignment covers the bash tool, `bg`, and every other spawn.
 
-Editor hang prevention sets `GIT_EDITOR=true`, `GIT_SEQUENCE_EDITOR=true`, and `GIT_MERGE_AUTOEDIT=no` on `process.env`. Pi builds a child's environment by spreading `process.env`, so one assignment covers the bash tool, `bg`, and every other spawn.
+The extension blocks a bash command containing `--no-verify`, because the agent should fix what the hook complains about or ask. The check is string matching, best effort, and not a security boundary.
 
-Hook bypass prevention blocks any bash command containing `--no-verify`. The agent should fix what the hook is complaining about, or ask you. This is string matching and best effort, not a security boundary.
+## The rejection that kills a session
 
-## Reject guard
+Pi installs an `uncaughtException` handler and no `unhandledRejection` handler, so one unhandled rejected promise tears down the session. The guard adds the missing listener, logs the reason with a stack trace to stderr prefixed `[reject-guard] unhandled rejection (session kept alive):`, and the turn continues.
 
-Pi registers an `uncaughtException` handler but no `unhandledRejection` handler, so one unhandled rejected promise tears down the whole session. This guard adds the missing listener, logs the reason with a stack trace to stderr, and keeps the session alive. The line starts with `[reject-guard] unhandled rejection (session kept alive):`.
-
-The listener installs once. `/reload` re-evaluates the module, and an install flag on `globalThis` keeps a second registration from logging every rejection twice.
+It installs once. `/reload` re-evaluates the module, and a flag on `globalThis` stops a second registration from logging every rejection twice.
 
 ## Install
 
@@ -81,4 +76,10 @@ pi install npm:@tduyng/pi-guard
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-guard`
 
-All four guards activate on install with no configuration. Customize redaction through `cloak.json`.
+All four guards activate on install. Add `cloak.json` when a rule fires too widely or misses a secret shape.
+
+## Limits
+
+- Cloak reads the `read` result on its way into the model. It does not touch the outbound provider payload, the assistant's reply, or any tool other than `read`, and it does not redact a file pasted into a prompt.
+- A reservation is advisory between pi sessions. A shell opened by hand is outside it.
+- `--no-verify` blocking can be worked around by anyone who wants to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tduyng/pi-guard",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Secret redaction, cross-session path reservations, git safety, and a rejection guard. Three of the four add no schema at all.",
   "keywords": [
     "pi",