@tduyng/pi-guard 0.0.1 → 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.1",
-  "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",

package/src/cloak.ts

@@ -111,7 +111,6 @@ function readConfigFile(path: string): CloakConfig {
 export function mergeCloakConfig(base: CloakConfig, project: CloakConfig): CloakConfig {
     return {
         ...base,
-        ...project,
         patterns: [
             ...(Array.isArray(base.patterns) ? base.patterns : []),
             ...(Array.isArray(project.patterns) ? project.patterns : [])

package/src/git-interceptor.ts

@@ -2,8 +2,6 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { Validator } from 'ata-validator'
 import { t } from 'ata-validator/t'
 
-const NO_VERIFY_RE = /--no-verify\b|\bgit\b[^;\n]*\bcommit\b[^;\n]*(?:^|\s)-[A-Za-z]*n[A-Za-z]*(?:\s|=|$)/
-
 const SENSITIVE_COMMAND_RE =
     /(?:^|[\s"'=:~]|\/)\.env(?:\.[A-Za-z0-9_-]+)?(?=$|[\s"';&|),\]} ])|(?:^|[\s"'=:~]|\/)(?:[^\s"';&|]*\/)?(?:id_rsa|id_dsa|id_ecdsa|id_ed25519)(?=$|[\s"';&|),\]} ])|(?:^|[\s"'=:~]|\/)[^\s"';&|]*\.(?:pem|key|p12|pfx)(?=$|[\s"';&|),\]} ])/i
 
@@ -24,6 +22,41 @@ const isCommandInput = new Validator(CommandInput).isValidObject
 const isThenRunCommand = new Validator(t.object({ command: t.string() })).isValidObject
 const isThenRunText = new Validator(t.string()).isValidObject
 
+function words(segment: string): string[] {
+    const found = segment.match(/"(?:[^"\\]|\\.)*"|'[^']*'|[^\s]+/g) ?? []
+    return found.map((word) => word.replace(/^(["'])(.*)\1$/, '$2'))
+}
+
+function blocksHooks(command: string): boolean {
+    if (!/\bgit\b/.test(command)) return false
+    for (const segment of command.split(/[;&|\n]+/)) {
+        const tokens = words(segment)
+        const git = tokens.findIndex((token) => token === 'git' || token.endsWith('/git'))
+        if (git === -1) continue
+        const args = tokens.slice(git + 1)
+        const commit = args.findIndex((token) => token === 'commit')
+        if (commit === -1) continue
+        if (args.includes('--no-verify')) return true
+        if (args.some((token, index) => token === '-c' && (args[index + 1]?.startsWith('core.hooksPath=') ?? false)))
+            return true
+        const after = args.slice(commit + 1)
+        const message = after.findIndex(
+            (token) => token === '-m' || token === '--message' || token.startsWith('--message=')
+        )
+        const flags = message === -1 ? after : after.slice(0, message)
+        if (flags.some((token) => /^-[A-Za-z]*n[A-Za-z]*$/.test(token))) return true
+    }
+    return false
+}
+
+function commands(input: { command?: string; then_run?: string | { command: string } }): string[] {
+    const found: string[] = []
+    if (input.command !== undefined) found.push(input.command)
+    if (isThenRunCommand(input.then_run)) found.push(input.then_run.command)
+    else if (isThenRunText(input.then_run)) found.push(input.then_run)
+    return found
+}
+
 export default function (pi: ExtensionAPI) {
     process.env['GIT_EDITOR'] = 'true'
     process.env['GIT_SEQUENCE_EDITOR'] = 'true'
@@ -31,20 +64,10 @@ export default function (pi: ExtensionAPI) {
 
     pi.on('tool_call', (event) => {
         if (!isCommandInput(event.input)) return
-        const input = event.input
-        let command = input.command
-        if (command === undefined && input.then_run !== undefined) {
-            if (isThenRunCommand(input.then_run)) command = input.then_run.command
-            else if (isThenRunText(input.then_run)) command = input.then_run
-            else return
-        }
-        if (!command) return
-
-        if (/\bgit\b/.test(command) && NO_VERIFY_RE.test(command)) {
-            return { block: true, reason: BLOCK_REASON }
-        }
-        if (SENSITIVE_COMMAND_RE.test(command)) {
-            return { block: true, reason: SENSITIVE_REASON }
+        for (const command of commands(event.input)) {
+            if (command.trim() === '') continue
+            if (blocksHooks(command)) return { block: true, reason: BLOCK_REASON }
+            if (SENSITIVE_COMMAND_RE.test(command)) return { block: true, reason: SENSITIVE_REASON }
         }
     })
 }

package/src/reserve.ts

@@ -119,12 +119,14 @@ function stripQuotes(token: string): string {
  */
 function writtenPaths(command: string): string[] {
     const redirects = [...command.matchAll(REDIRECT)].map((match) => stripQuotes(match[1] ?? ''))
-    if (redirects.length > 0) return redirects
-    if (!SHELL_MUTATIONS.test(command)) return []
-    return command
+    const mutates = SHELL_MUTATIONS.test(command)
+    if (redirects.length > 0 && !mutates) return redirects
+    if (!mutates) return []
+    const tokens = command
         .split(/[\s;&|<>()]+/)
         .map(stripQuotes)
         .filter((token) => token !== '' && !token.startsWith('-'))
+    return [...new Set([...redirects, ...tokens])]
 }
 
 export function commandConflicts(cwd: string, session: string, command: string): Conflict[] {