@tduyng/pi-guard 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# @tduyng/pi-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Four safety guards for pi: path reservations between parallel sessions, secret redaction on read results, git hook enforcement, and unhandled rejection handling.
+
+## Reserve
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Cloak: secret redaction
+
+A `tool_result` hook intercepts `read` tool results and redacts secrets before they enter the model's context. Three independent checks, all configurable:
+
+### Vendor key detection
+
+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:
+
+- `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
+
+Each match is replaced with a marker: the first 4 characters plus stars (minimum 8, maximum 20) plus `[REDACTED:type]`.
+
+### PEM block detection
+
+Matches `-----BEGIN ...-----` certificate and key blocks. Replaced with `[REDACTED:PEM TYPE]`.
+
+### Sensitive file types
+
+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).
+
+### Custom patterns
+
+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:
+
+- `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.
+
+When multiple patterns overlap the same span, the first applied match wins and later matches overlapping that span are skipped.
+
+Use `/cloak-status` to see whether cloak is enabled, how many custom patterns are loaded, and which built-in checks are on.
+
+### What cloak does not do
+
+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.
+
+## Git interceptor
+
+Two guards for agent-driven git commands:
+
+**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.
+
+**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.
+
+## 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.
+
+## Install
+
+```bash
+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.

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@tduyng/pi-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "security",
+    "secrets",
+    "git",
+    "safety"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-guard#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-guard"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/reserve.ts",
+      "./src/cloak.ts",
+      "./src/git-interceptor.ts",
+      "./src/reject-guard.ts"
+    ]
+  },
+  "dependencies": {
+    "ata-validator": "^1.62.1"
+  }
+}

package/src/cloak.ts

@@ -0,0 +1,396 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getAgentDir } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+const isOpenObject = new Validator(t.object({}, { additionalProperties: true })).isValidObject
+const isString = new Validator(t.string()).isValidObject
+const isNumber = new Validator(t.number()).isValidObject
+
+export const CLOAK_CONFIG_FILE = 'cloak.json'
+
+function configPath(): string {
+    return join(getAgentDir(), CLOAK_CONFIG_FILE)
+}
+
+function projectConfigPath(): string {
+    return join(process.cwd(), '.pi', CLOAK_CONFIG_FILE)
+}
+
+interface CloakPattern {
+    pattern: string
+    replace?: string
+}
+
+interface CloakRule {
+    filePattern: string | string[]
+    cloakPattern: string | CloakPattern[]
+    replace?: string
+}
+
+export interface CloakConfig {
+    enabled?: boolean
+    cloakCharacter?: string
+    cloakLength?: number | null
+    tryAllPatterns?: boolean
+    patterns?: CloakRule[]
+    vendorKeys?: boolean
+    pemBlocks?: boolean
+    sensitiveFileTypes?: boolean
+}
+
+/** What the file on disk parsed to: the two scalars below are narrowed there, once. */
+interface LoadedConfig extends CloakConfig {
+    cloakCharacter: string
+    cloakLength?: number
+}
+
+interface CompiledRegex {
+    regex: RegExp
+    replace?: string
+}
+
+interface CompiledRule {
+    fileRegex: RegExp
+    regexes: CompiledRegex[]
+}
+
+function globToRegExp(glob: string): RegExp {
+    let out = '^'
+    for (let index = 0; index < glob.length; index++) {
+        const char = glob[index]
+        if (char === undefined) break
+        const next = glob[index + 1]
+        if (char === '*' && next === '*') {
+            out += '.*'
+            index++
+            if (glob[index + 1] === '/') index++
+            continue
+        }
+        if (char === '*') {
+            out += '[^/]*'
+            continue
+        }
+        out += char.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    }
+    return new RegExp(`${out}$`)
+}
+
+function compileRule(rule: CloakRule): CompiledRule {
+    const filePatterns = Array.isArray(rule.filePattern) ? rule.filePattern : [rule.filePattern]
+    const specs: CloakPattern[] = Array.isArray(rule.cloakPattern)
+        ? rule.cloakPattern
+        : [{ pattern: rule.cloakPattern, replace: rule.replace }]
+    return {
+        fileRegex: new RegExp(filePatterns.map((pattern) => globToRegExp(pattern).source).join('|')),
+        regexes: specs.map((spec) => ({ regex: new RegExp(spec.pattern, 'gi'), replace: spec.replace }))
+    }
+}
+
+export function compileRules(patterns: CloakRule[]): CompiledRule[] {
+    const compiled: CompiledRule[] = []
+    for (const rule of patterns) {
+        try {
+            compiled.push(compileRule(rule))
+        } catch {}
+    }
+    return compiled
+}
+
+function readConfigFile(path: string): CloakConfig {
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+        return isOpenObject(parsed) && !Array.isArray(parsed) ? (parsed as CloakConfig) : {}
+    } catch {
+        return {}
+    }
+}
+
+export function mergeCloakConfig(base: CloakConfig, project: CloakConfig): CloakConfig {
+    return {
+        ...base,
+        patterns: [
+            ...(Array.isArray(base.patterns) ? base.patterns : []),
+            ...(Array.isArray(project.patterns) ? project.patterns : [])
+        ]
+    }
+}
+
+function loadConfig(): LoadedConfig {
+    try {
+        const parsed = mergeCloakConfig(readConfigFile(configPath()), readConfigFile(projectConfigPath()))
+        const length = parsed.cloakLength
+
+        return {
+            enabled: true,
+            ...parsed,
+            cloakCharacter: isString(parsed.cloakCharacter) ? parsed.cloakCharacter : '*',
+            cloakLength: isNumber(length) && Number.isFinite(length) && length >= 0 ? length : undefined,
+            patterns: Array.isArray(parsed.patterns) ? parsed.patterns : []
+        }
+    } catch {
+        return { enabled: true, cloakCharacter: '*', patterns: [] }
+    }
+}
+
+function mask(match: string, cloakChar: string, cloakLength: number | null | undefined): string {
+    const visible = match.slice(0, 1)
+    const target = cloakLength ?? Math.max(match.length, 1)
+    return visible + cloakChar.repeat(Math.max(0, target - 1))
+}
+
+interface Match {
+    start: number
+    end: number
+    replacement: string
+}
+
+interface VendorPattern {
+    name: string
+    prefix: string
+    tail: RegExp
+    wordBoundary: boolean
+}
+
+const VENDOR: VendorPattern[] = [
+    { name: 'AWS Access Key', prefix: 'AKIA', tail: /^AKIA[A-Z0-9]{16}\b/, wordBoundary: true },
+    { name: 'AWS Temp Access Key', prefix: 'ASIA', tail: /^ASIA[A-Z0-9]{16}\b/, wordBoundary: true },
+    { name: 'Bearer Token', prefix: 'Bearer', tail: /^Bearer\s+[a-zA-Z0-9._-]{20,}\b/, wordBoundary: true },
+    { name: 'OpenAI/Anthropic API Key', prefix: 'sk-', tail: /^sk-[a-zA-Z0-9._-]{20,}\b/, wordBoundary: true },
+    { name: 'Stripe Live Key', prefix: 'sk_live_', tail: /^sk_live_[a-zA-Z0-9]{20,}\b/, wordBoundary: true },
+    { name: 'Stripe Test Key', prefix: 'sk_test_', tail: /^sk_test_[a-zA-Z0-9]{20,}\b/, wordBoundary: true },
+    { name: 'GitHub Token', prefix: 'gh', tail: /^gh[pousr]_[a-zA-Z0-9]{36,}\b/, wordBoundary: true },
+    {
+        name: 'GitHub Fine-grained PAT',
+        prefix: 'github_pat_',
+        tail: /^github_pat_[a-zA-Z0-9_]{20,}\b/,
+        wordBoundary: true
+    },
+    {
+        name: 'JWT',
+        prefix: 'eyJ',
+        tail: /^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/,
+        wordBoundary: true
+    },
+    { name: 'Slack Token', prefix: 'xoxb-', tail: /^xox[baprs]-[A-Za-z0-9-]{20,}\b/, wordBoundary: true },
+    { name: 'GitLab Token', prefix: 'glpat-', tail: /^glpat-[A-Za-z0-9_-]{20,}\b/, wordBoundary: true },
+    { name: 'Google API Key', prefix: 'AIza', tail: /^AIza[A-Za-z0-9_-]{35}\b/, wordBoundary: true },
+    { name: 'npm Token', prefix: 'npm_', tail: /^npm_[a-zA-Z0-9]{36,}\b/, wordBoundary: true },
+    {
+        name: 'SendGrid API Key',
+        prefix: 'SG.',
+        tail: /^SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{32,}\b/,
+        wordBoundary: true
+    }
+]
+
+function isWordChar(c: string): boolean {
+    const code = c.charCodeAt(0)
+    return (
+        (code >= 0x30 && code <= 0x39) ||
+        (code >= 0x41 && code <= 0x5a) ||
+        (code >= 0x61 && code <= 0x7a) ||
+        code === 0x5f
+    )
+}
+
+function buildMarker(value: string, type: string): string {
+    const prefix = value.slice(0, 4)
+    const stars = '*'.repeat(Math.min(20, Math.max(8, value.length - 4)))
+    return `${prefix}${stars}[REDACTED:${type}]`
+}
+
+export function vendorScan(text: string): Match[] {
+    const matches: Match[] = []
+    for (const { name, prefix, tail, wordBoundary } of VENDOR) {
+        let idx = 0
+        while (idx < text.length) {
+            const found = text.indexOf(prefix, idx)
+            if (found === -1) break
+            if (wordBoundary) {
+                const prev = found > 0 ? text[found - 1] : ''
+                if (prev && isWordChar(prev)) {
+                    idx = found + 1
+                    continue
+                }
+            }
+            const window = text.slice(found)
+            const m = tail.exec(window)
+            if (!m) {
+                idx = found + 1
+                continue
+            }
+            const start = found
+            const end = found + m[0].length
+            matches.push({ start, end, replacement: buildMarker(m[0], name) })
+            idx = end
+        }
+    }
+    return matches
+}
+
+const PEM_BLOCK_REGEX = /-----BEGIN ([A-Z ]+)-----\r?\n([\s\S]*?)(?:\r?\n-----END \1-----|$)/g
+
+export function pemScan(text: string): Match[] {
+    const matches: Match[] = []
+    PEM_BLOCK_REGEX.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = PEM_BLOCK_REGEX.exec(text)) !== null) {
+        matches.push({ start: m.index, end: m.index + m[0].length, replacement: `[REDACTED:PEM ${m[1] ?? ''}]` })
+    }
+    return matches
+}
+
+/**
+ * A quoted JSON field whose name is a credential word, and whose value is shaped like one:
+ * no whitespace, at least 16 characters, and a digit. Without the shape the name alone
+ * masks `"tokenizers": "0.22.2"` and `"token": "ts-node -T -s scripts/cli/ts/token"`,
+ * which is most of a package.json.
+ */
+const CREDENTIAL_FIELD_REGEX =
+    /("(?:[a-z0-9_-]*(?:password|passwd|secret|token|api[_-]?key|authorization|private[_-]?key)[a-z0-9_-]*)"\s*:\s*")(?=[^"\s]{16,}")(?=[^"]*\d)[^"]+"/gi
+
+export function credentialFieldScan(text: string): Match[] {
+    const matches: Match[] = []
+    CREDENTIAL_FIELD_REGEX.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = CREDENTIAL_FIELD_REGEX.exec(text)) !== null) {
+        const start = m.index + m[1]!.length
+        matches.push({ start, end: m.index + m[0].length - 1, replacement: '[REDACTED:credential field]' })
+    }
+    return matches
+}
+
+export function applyMatches(text: string, matches: Match[]): string {
+    if (matches.length === 0) return text
+    const sorted = matches.toSorted((a, b) => a.start - b.start)
+    const parts: string[] = []
+    let cursor = 0
+    for (const m of sorted) {
+        if (m.start < cursor) continue
+        if (m.start > cursor) parts.push(text.slice(cursor, m.start))
+        parts.push(m.replacement)
+        cursor = m.end
+    }
+    if (cursor < text.length) parts.push(text.slice(cursor))
+    return parts.join('')
+}
+
+const SENSITIVE_PATH_PATTERNS: { pattern: RegExp; type: string }[] = [
+    { pattern: /\.pem$/i, type: 'PEM File' },
+    { pattern: /\.crt$/i, type: 'Certificate File' },
+    { pattern: /\.cer$/i, type: 'Certificate File' },
+    { pattern: /\.p12$/i, type: 'PKCS12 File' },
+    { pattern: /\.pfx$/i, type: 'PKCS12 File' },
+    { pattern: /(^|\/)\.ssh\/id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/i, type: 'SSH Key' },
+    { pattern: /\.ssh\/known_hosts$/i, type: 'SSH Known Hosts' },
+    { pattern: /\.ssh\/authorized_keys$/i, type: 'SSH Authorized Keys' },
+    { pattern: /\.aws\/credentials$/i, type: 'AWS Credentials' },
+    { pattern: /\.npmrc$/i, type: 'npm Config' },
+    { pattern: /\.pypirc$/i, type: 'PyPI Config' },
+    { pattern: /\.netrc$/i, type: 'Netrc File' },
+    { pattern: /\.docker\/config\.json$/i, type: 'Docker Config' },
+    { pattern: /\.kube\/config$/i, type: 'Kube Config' },
+    { pattern: /(?:^|\/)\.env(?:\.[\w-]+)?$/i, type: 'Environment File' }
+]
+
+export function matchSensitivePath(path: string): string | null {
+    for (const { pattern, type } of SENSITIVE_PATH_PATTERNS) if (pattern.test(path)) return type
+    return null
+}
+
+// Canonical copy; pi-subagent/src/redact.ts mirrors it so that package stands alone.
+const SIDE_MODEL_REDACTIONS: Array<[RegExp, string]> = [
+    [
+        /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g,
+        '[redacted private key block]'
+    ],
+    [/\bAKIA[0-9A-Z]{16}\b/g, '[redacted aws access key]'],
+    [/\bsk-[A-Za-z0-9_-]{20,}/g, '[redacted api key]'],
+    [/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, 'Bearer [redacted]'],
+    [/^(\s*(?:export\s+)?[A-Za-z_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Za-z_]*\s*=\s*)("?)[^"]+\2$/gm, '$1$2[redacted]$2']
+]
+
+export function redactSecrets(text: string): string {
+    let out = text
+    for (const [re, replacement] of SIDE_MODEL_REDACTIONS) out = out.replace(re, replacement)
+    return out
+}
+
+export default function (pi: ExtensionAPI) {
+    const config = loadConfig()
+
+    pi.registerCommand('cloak-status', {
+        description: 'Show cloak config status',
+        handler: async (_args, ctx) => {
+            const status = config.enabled === false ? 'disabled' : 'enabled'
+            ctx.ui.notify(
+                `cloak ${status}, patterns=${(config.patterns ?? []).length}, ` +
+                    `vendorKeys=${config.vendorKeys !== false}, pemBlocks=${config.pemBlocks !== false}, ` +
+                    `sensitiveFileTypes=${config.sensitiveFileTypes !== false}`,
+                'info'
+            )
+        }
+    })
+
+    if (config.enabled === false) return
+    const rules = compileRules(config.patterns ?? [])
+    const vendorKeysEnabled = config.vendorKeys !== false
+    const pemBlocksEnabled = config.pemBlocks !== false
+    const sensitiveFileTypesEnabled = config.sensitiveFileTypes !== false
+    if (rules.length === 0 && !vendorKeysEnabled && !pemBlocksEnabled && !sensitiveFileTypesEnabled) return
+
+    const cloakChar = config.cloakCharacter
+    const cloakLength = config.cloakLength ?? null
+
+    pi.on('tool_result', (event) => {
+        if (!Array.isArray(event.content)) return
+        const input = event.input as { path?: string }
+        const rawPath = event.toolName === 'read' ? (input.path ?? '') : ''
+
+        const sensitiveType = sensitiveFileTypesEnabled && rawPath ? matchSensitivePath(rawPath) : null
+        const matchingRules = rawPath ? rules.filter((rule) => rule.fileRegex.test(rawPath)) : []
+        if (!sensitiveType && matchingRules.length === 0 && !vendorKeysEnabled && !pemBlocksEnabled) return
+
+        let changed = false
+        const content = event.content.map((part) => {
+            if (part.type !== 'text') return part
+
+            if (sensitiveType) {
+                changed = true
+                return { ...part, text: `[REDACTED:Protected File (${sensitiveType})]` }
+            }
+
+            let text = part.text
+            for (const rule of matchingRules) {
+                for (const compiled of rule.regexes) {
+                    const next =
+                        compiled.replace !== undefined
+                            ? text.replace(compiled.regex, compiled.replace)
+                            : text.replace(compiled.regex, (match) => mask(match, cloakChar, cloakLength))
+                    if (next !== text) {
+                        changed = true
+                        text = next
+                    }
+                }
+                if (config.tryAllPatterns === false) break
+            }
+
+            const structuralMatches = [
+                ...(vendorKeysEnabled ? [...vendorScan(text), ...credentialFieldScan(text)] : []),
+                ...(pemBlocksEnabled ? pemScan(text) : [])
+            ]
+            if (structuralMatches.length > 0) {
+                changed = true
+                text = applyMatches(text, structuralMatches)
+            }
+
+            return changed ? { ...part, text } : part
+        })
+
+        if (!changed) return
+        return { content }
+    })
+}

package/src/git-interceptor.ts

@@ -0,0 +1,73 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+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
+
+const SENSITIVE_REASON =
+    'BLOCKED: shell access to a credential or private-key file is not allowed, and a read of one ' +
+    'comes back redacted. Ask the user for the value you need.'
+
+const BLOCK_REASON =
+    'BLOCKED: --no-verify is not allowed. Git hooks exist for a reason. ' +
+    'Do not attempt to bypass them. Instead: fix the underlying issue causing ' +
+    'the hook to fail, or ask the user for help.'
+
+const CommandInput = t.object({
+    command: t.optional(t.string()),
+    then_run: t.optional(t.union([t.string(), t.object({ command: t.string() })]))
+})
+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'
+    process.env['GIT_MERGE_AUTOEDIT'] = 'no'
+
+    pi.on('tool_call', (event) => {
+        if (!isCommandInput(event.input)) return
+        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/reject-guard.ts

@@ -0,0 +1,22 @@
+function isInstalled(): boolean {
+    return (globalThis as { __piRejectGuardInstalled?: boolean }).__piRejectGuardInstalled === true
+}
+
+function markInstalled(): void {
+    ;(globalThis as { __piRejectGuardInstalled?: boolean }).__piRejectGuardInstalled = true
+}
+
+function onUnhandledRejection(reason: {} | null | undefined): void {
+    const message = reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)
+    console.error(`[reject-guard] unhandled rejection (session kept alive): ${message}`)
+}
+
+export function listenerCount(): number {
+    return process.listeners('unhandledRejection').filter((fn) => fn === onUnhandledRejection).length
+}
+
+export default function (): void {
+    if (isInstalled()) return
+    markInstalled()
+    process.on('unhandledRejection', onUnhandledRejection)
+}

package/src/reserve.ts

@@ -0,0 +1,318 @@
+import { mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import type { ExtensionAPI, ToolCallEvent } from '@earendil-works/pi-coding-agent'
+import { Validator, type Infer } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+export const RESERVATIONS_DIR = join('.pi', 'reservations')
+
+const ReservationSchema = t.object({
+    path: t.string(),
+    dir: t.boolean(),
+    reason: t.optional(t.string())
+})
+
+const RegistrationSchema = t.object({
+    session: t.string(),
+    pid: t.number(),
+    cwd: t.string(),
+    reservations: t.array(ReservationSchema)
+})
+
+export type Reservation = Infer<typeof ReservationSchema>
+type Registration = Infer<typeof RegistrationSchema>
+const isRegistration = new Validator(RegistrationSchema).isValidObject
+
+export interface Conflict {
+    session: string
+    folder: string
+    pattern: string
+    reason?: string
+}
+
+export function isAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch {
+        return false
+    }
+}
+
+export function normalize(cwd: string, raw: string): Reservation | undefined {
+    const trimmed = raw.trim()
+    if (trimmed === '') return undefined
+    const dir = trimmed.endsWith('/')
+    return { path: resolve(cwd, dir ? trimmed.slice(0, -1) : trimmed), dir }
+}
+
+export function covers(file: string, reservation: Reservation): boolean {
+    if (!reservation.dir) return file === reservation.path
+    return file === reservation.path || file.startsWith(`${reservation.path}/`)
+}
+
+function parseRegistration(text: string): Registration | undefined {
+    try {
+        const parsed = JSON.parse(text)
+        return isRegistration(parsed) ? parsed : undefined
+    } catch {
+        return undefined
+    }
+}
+
+export function peers(cwd: string, session: string): Registration[] {
+    const dir = join(cwd, RESERVATIONS_DIR)
+    let names: string[]
+    try {
+        names = readdirSync(dir)
+    } catch {
+        return []
+    }
+    const live: Registration[] = []
+    for (const name of names) {
+        if (!name.endsWith('.json')) continue
+        try {
+            const record = parseRegistration(readFileSync(join(dir, name), 'utf8'))
+            if (record === undefined || record.session === session || !isAlive(record.pid)) continue
+            live.push(record)
+        } catch {
+            continue
+        }
+    }
+    return live
+}
+
+export function conflictsFor(cwd: string, session: string, file: string): Conflict[] {
+    return conflictsIn(peers(cwd, session), cwd, file)
+}
+
+function conflictsIn(records: Registration[], cwd: string, file: string): Conflict[] {
+    const target = resolve(cwd, file)
+    const found: Conflict[] = []
+    for (const record of records) {
+        for (const reservation of record.reservations) {
+            if (!covers(target, reservation)) continue
+            found.push({
+                session: record.session,
+                folder: basename(record.cwd) || record.cwd,
+                pattern: reservation.dir ? `${reservation.path}/` : reservation.path,
+                reason: reservation.reason
+            })
+        }
+    }
+    return found
+}
+
+const SHELL_MUTATIONS =
+    /(^|[\s;&|(])(sed\s+-i\w*|truncate|tee|rm|mv|cp|patch|git\s+(?:add|checkout|restore|mv|rm|reset|revert|stash|clean|apply|am))(?![\w-])/
+
+const REDIRECT = />>?\s*("[^"]+"|'[^']+'|\S+)/g
+
+function stripQuotes(token: string): string {
+    return token.replace(/^["']|["']$/g, '')
+}
+
+/**
+ * A path a shell command writes. `cat a > b` writes b and only reads a, so a redirect makes the
+ * redirect targets the writes and nothing else counts. Without one, a known mutating verb means
+ * every path token in the command could be the target.
+ */
+function writtenPaths(command: string): string[] {
+    const redirects = [...command.matchAll(REDIRECT)].map((match) => stripQuotes(match[1] ?? ''))
+    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[] {
+    const found: Conflict[] = []
+    const seen = new Set<string>()
+    const candidates = writtenPaths(command)
+    if (candidates.length === 0) return found
+    const records = peers(cwd, session)
+    for (const candidate of candidates) {
+        for (const conflict of conflictsIn(records, cwd, candidate)) {
+            const key = `${conflict.session}:${conflict.pattern}`
+            if (seen.has(key)) continue
+            seen.add(key)
+            found.push(conflict)
+        }
+    }
+    return found
+}
+
+function declaredPath(event: ToolCallEvent): string | undefined {
+    if (event.toolName !== 'edit' && event.toolName !== 'write') return undefined
+    return isPathInput(event.input) ? event.input.path : undefined
+}
+
+function bashCommand(event: ToolCallEvent): string | undefined {
+    if (event.toolName !== 'bash') return undefined
+    return isCommandInput(event.input) ? event.input.command : undefined
+}
+
+function blockReason(file: string, conflicts: Conflict[]): string {
+    const held = conflicts[0] as Conflict
+    const lines = [file, `Reserved by session ${held.session} (in ${held.folder})`, `Reservation: ${held.pattern}`]
+    if (held.reason !== undefined) lines.push(`Reason: "${held.reason}"`)
+    lines.push(
+        '',
+        'Ask that session to release it, reserve a different path, or delegate the work with isolation "worktree".'
+    )
+    return lines.join('\n')
+}
+
+const PathInput = t.object({ path: t.string() })
+const isPathInput = new Validator(PathInput).isValidObject
+
+const CommandInput = t.object({ command: t.string() })
+const isCommandInput = new Validator(CommandInput).isValidObject
+
+const Action = t.union([t.literal('reserve'), t.literal('release'), t.literal('list')])
+
+function renderPeers(cwd: string, session: string, own: Reservation[]): string {
+    const lines = [`${cwd} (${RESERVATIONS_DIR})`, `this session: ${session}`]
+    if (own.length > 0) {
+        lines.push('  held by this session:')
+        for (const reservation of own) {
+            lines.push(`    ${reservation.dir ? `${reservation.path}/` : reservation.path}`)
+        }
+    }
+    const others = peers(cwd, session)
+    if (others.length === 0) {
+        lines.push('  no other live session holds reservations here')
+        return lines.join('\n')
+    }
+    lines.push('  other live sessions:')
+    for (const record of others) {
+        const folder = basename(record.cwd) || record.cwd
+        lines.push(`    ${record.session} (${folder}, pid ${record.pid})`)
+        for (const reservation of record.reservations) {
+            lines.push(`      ${reservation.dir ? `${reservation.path}/` : reservation.path}`)
+        }
+    }
+    return lines.join('\n')
+}
+
+export default function reserveExtension(pi: ExtensionAPI): void {
+    let session = ''
+    let cwd = ''
+    let held: Reservation[] = []
+
+    function registryPath(): string {
+        return join(cwd, RESERVATIONS_DIR, `${session}.json`)
+    }
+
+    function flush(): void {
+        if (session === '') return
+        mkdirSync(join(cwd, RESERVATIONS_DIR), { recursive: true })
+        const record: Registration = { session, pid: process.pid, cwd, reservations: held }
+        const target = registryPath()
+        const temporary = `${target}.${process.pid}.tmp`
+        writeFileSync(temporary, `${JSON.stringify(record)}\n`, 'utf8')
+        renameSync(temporary, target)
+    }
+
+    pi.on('session_start', (_event, ctx) => {
+        session = ctx.sessionManager.getSessionId()
+        cwd = ctx.cwd
+        flush()
+    })
+
+    pi.on('session_shutdown', () => {
+        if (session === '') return
+        try {
+            unlinkSync(registryPath())
+        } catch {
+            // Already gone, which is the state this wants.
+        }
+    })
+
+    pi.on('tool_call', (event) => {
+        const file = declaredPath(event)
+        if (file !== undefined) {
+            const conflicts = conflictsFor(cwd, session, file)
+            if (conflicts.length === 0) return
+            return { block: true, reason: blockReason(file, conflicts) }
+        }
+        const command = bashCommand(event)
+        if (command === undefined) return
+        const conflicts = commandConflicts(cwd, session, command)
+        if (conflicts.length === 0) return
+        return { block: true, reason: blockReason(command, conflicts) }
+    })
+
+    pi.registerTool({
+        name: 'reserve',
+        label: 'Reserve Paths',
+        description:
+            'Claim files or directories in this folder so parallel pi sessions do not edit them at the same time. Another live session holding a reservation is blocked from writing that path until it releases. A trailing slash reserves a whole subtree.',
+        promptSnippet: 'Reserve paths so parallel pi sessions do not write the same files',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        },
+        exposure: 'deferred',
+        namespace: {
+            name: 'guard',
+            description: 'Cross-session safety: path reservations between parallel pi sessions.'
+        },
+        promptGuidelines: [
+            'Reserve a path before a long edit run in a folder other pi sessions are using, and release it when the work lands.'
+        ],
+        parameters: t.object({
+            action: Action,
+            paths: t.optional(
+                t.array(t.string(), { description: 'Paths to reserve or release. Omit on release for all.' })
+            ),
+            reason: t.optional(t.string({ description: 'Why the path is held, shown to the blocked session.' }))
+        }),
+        async execute(_id, params, _signal, _onUpdate, _ctx) {
+            const text = (value: string) => ({ content: [{ type: 'text' as const, text: value }], details: {} })
+            if (session === '') return text('No session id yet. Reservations need a live session.')
+
+            if (params.action === 'list') return text(renderPeers(cwd, session, held))
+
+            if (params.action === 'reserve') {
+                const added: Reservation[] = []
+                for (const raw of params.paths ?? []) {
+                    const reservation = normalize(cwd, raw)
+                    if (reservation === undefined) continue
+                    if (held.some((other) => covers(other.path, reservation) || covers(reservation.path, other))) {
+                        continue
+                    }
+                    held.push({ ...reservation, reason: params.reason })
+                    added.push(reservation)
+                }
+                flush()
+                if (added.length === 0)
+                    return text('Nothing to reserve: every path given is already held by this session.')
+                return text(
+                    `Reserved:\n${added
+                        .map((reservation) => `  ${reservation.dir ? `${reservation.path}/` : reservation.path}`)
+                        .join('\n')}`
+                )
+            }
+
+            const paths = params.paths ?? []
+            const before = held.length
+            if (paths.length === 0) {
+                held = []
+            } else {
+                const wanted = paths.map((raw) => normalize(cwd, raw)?.path)
+                held = held.filter((reservation) => !wanted.includes(reservation.path))
+            }
+            flush()
+            return text(
+                held.length === before ? 'No reservation matched those paths.' : `Released ${before - held.length}.`
+            )
+        }
+    })
+}