@tduyng/pi-guard 0.0.2 → 0.0.3

package/README.md

@@ -1,85 +1,77 @@
 # @tduyng/pi-guard
 
-Four safety guards for pi: path reservations between parallel sessions, secret redaction on read results, git hook enforcement, and unhandled rejection handling.
+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.
 
-## Reserve
+## What it costs
+
+`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.
 
-Pi serializes writes inside one process, so two sessions in one folder still overwrite each other. This guard is the cross-session half. 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.
+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.
 
-Reserving `extensions/pi-goal/src/` takes the whole subtree and an exact path takes one file, while `release` with no paths gives everything back and `list` prints every live session with what it holds.
+## Reserve
 
-Liveness is `process.kill(pid, 0)`, so a session that is killed takes its reservations with it. Nothing to keep alive, no heartbeat, no daemon.
+Pi serializes writes inside one process, so two sessions in one folder still overwrite each other. This is the cross-session half.
 
-Reservations cover files, and `bash` is checked too: a command that writes a reserved path is
-turned away, whether it says `sed -i`, `git checkout`, or redirects into it. A command that only
-reads a reserved path is left alone. What this cannot see is a mutation that names no path at
-all, 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. The branch is named in the result and its commits outlive the checkout.
+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.
 
-## Cloak: secret redaction
+Liveness is `process.kill(pid, 0)`, so a killed session takes its reservations with it. Nothing to keep alive, no heartbeat, no daemon.
 
-A `tool_result` hook intercepts `read` tool results and redacts secrets before they enter the model's context. Three independent checks, all configurable:
+`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.
 
-### Vendor key detection
+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.
 
-Matches known API key shapes by fixed literal prefix. No entropy or shape scanning. Each prefix has a word boundary check so a substring inside a longer identifier does not false-positive. Patterns:
+## Cloak
 
-- `AKIA` and `ASIA` (AWS access keys)
-- `sk-` (OpenAI/Anthropic)
-- `sk_live_` and `sk_test_` (Stripe)
-- `ghp_`, `gho_`, `ghs_`, `ghr_`, `github_pat_` (GitHub)
-- `eyJ` (JWTs, three-part base64 structure)
-- `xoxb-`, `xoxp-`, `xoxa-`, `xoxr-`, `xoxs-` (Slack)
-- `glpat-` (GitLab)
-- `AIza` (Google)
-- `npm_` (npm)
-- `SG.` (SendGrid)
-- `Bearer` followed by a token
+A `tool_result` hook redacts secrets out of `read` results before they enter the model's context. Three checks, each switchable.
 
-Each match is replaced with a marker: the first 4 characters plus stars (minimum 8, maximum 20) plus `[REDACTED:type]`.
+### Vendor keys
 
-### PEM block detection
+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.
 
-Matches `-----BEGIN ...-----` certificate and key blocks. Replaced with `[REDACTED:PEM TYPE]`.
+`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.
 
-### Sensitive file types
+Each match becomes the first 4 characters, then stars (minimum 8, maximum 20), then `[REDACTED:type]`.
 
-If the file path matches a sensitive pattern, the entire read is replaced with a single marker like `[REDACTED:Protected File (SSH Key)]`. Each pattern carries a type label used in the marker. Patterns include `.pem` (PEM File), `.crt` and `.cer` (Certificate File), `.p12` and `.pfx` (PKCS12 File), `.ssh/id_rsa`, `.ssh/id_ed25519`, `.ssh/id_ecdsa`, and `.ssh/id_dsa` (SSH Key), `.ssh/known_hosts` (SSH Known Hosts), `.ssh/authorized_keys` (SSH Authorized Keys), `.aws/credentials` (AWS Credentials), `.npmrc` (npm Config), `.pypirc` (PyPI Config), `.netrc` (Netrc File), `.docker/config.json` (Docker Config), `.kube/config` (Kube Config).
+### PEM blocks
 
-### Custom patterns
+`-----BEGIN ...-----` certificate and key blocks are replaced with `[REDACTED:PEM TYPE]`.
 
-Place a `cloak.json` in the agent directory (`getAgentDir()`) or in a project's `.pi/cloak.json` to add your own rules. A project file overrides the scalar keys and appends its `patterns` to the agent dir ones. Keys:
+### Sensitive file types
+
+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`.
 
-- `enabled` (boolean, default `true`): master switch.
-- `cloakCharacter` (string, default `*`): masking character.
-- `cloakLength` (number or null): fixed replacement length. Null preserves original length.
-- `tryAllPatterns` (boolean, default `true`): apply all matching rules, not just the first.
-- `patterns` (array): custom rules with `filePattern` (glob), `cloakPattern` (regex), and optional `replace`.
-- `vendorKeys` (boolean, default `true`): built-in vendor prefix detection.
-- `pemBlocks` (boolean, default `true`): PEM block detection.
-- `sensitiveFileTypes` (boolean, default `true`): whole-file redaction for sensitive paths.
+### Rules of your own
 
-When multiple patterns overlap the same span, the first applied match wins and later matches overlapping that span are skipped.
+`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.
 
-Use `/cloak-status` to see whether cloak is enabled, how many custom patterns are loaded, and which built-in checks are on.
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch |
+| `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` |
+| `vendorKeys` | `true` | Built-in prefix detection |
+| `pemBlocks` | `true` | PEM detection |
+| `sensitiveFileTypes` | `true` | Whole-file redaction for sensitive paths |
 
-### What cloak does not do
+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.
 
-The extension does not scan by entropy or shape. A nix store hash, a `narHash` field, or a sha256 digest in a Nix derivation will not false-positive. The hook does not touch the outbound provider payload, the assistant's reply, or tools other than `read`. For files matching custom `patterns`, only the matched spans are replaced. Sensitive file types replace the entire read.
+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.
 
 ## Git interceptor
 
-Two guards for agent-driven git commands:
+Two guards for agent-driven git.
 
-**Editor hang prevention**: sets `GIT_EDITOR=true`, `GIT_SEQUENCE_EDITOR=true`, and `GIT_MERGE_AUTOEDIT=no` on `process.env`. Pi builds a child's env by spreading `process.env`, so this one assignment covers the bash tool, `bg`, and any other spawn. Git never spawns an interactive editor.
+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.
 
-**Hook bypass prevention**: blocks any bash command containing `--no-verify`. The agent should fix the underlying issue causing the hook to fail, or ask the human for help. This is string matching, best-effort, 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.
 
 ## Reject guard
 
-Pi registers an `uncaughtException` handler but no `unhandledRejection` handler. An unhandled rejected promise tears down the whole session. This guard adds an `unhandledRejection` listener that logs the rejection reason (with stack trace when available) to stderr and keeps the session alive. The log line starts with `[reject-guard] unhandled rejection (session kept alive):`. The listener installs once. A `/reload` re-evaluates the module, and an install flag on `globalThis` keeps a second registration from logging every rejection twice.
+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.
 
 ## Install
 
@@ -89,6 +81,4 @@ pi install npm:@tduyng/pi-guard
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-guard`
 
-## Configure
-
-No configuration required. All four guards activate on install. Customize redaction via `cloak.json` as described above.
+All four guards activate on install with no configuration. Customize redaction through `cloak.json`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-guard",
-  "version": "0.0.2",
-  "description": "Four guards: keep parallel pi sessions off each other's files, redact secrets out of read results, keep a stray rejected promise from killing the session, and stop git from hanging on an editor or skipping hooks.",
+  "version": "0.0.3",
+  "description": "Secret redaction, cross-session path reservations, git safety, and a rejection guard. Three of the four add no schema at all.",
   "keywords": [
     "pi",
     "pi-package",