@seanmozeik/tripwire 0.6.7 → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Mozeik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,220 +1,233 @@
 # Tripwire
 
-[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![runtime: bun](https://img.shields.io/badge/runtime-bun-f9f1e1.svg)](https://bun.sh)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![runtime: Bun 1.4](https://img.shields.io/badge/runtime-Bun%201.4-f9f1e1.svg)](https://bun.sh)
 
-A deterministic safety layer between an AI coding agent and your shell. Tripwire runs as a hook on every tool call, evaluates the command against a rule set, and blocks or rewrites the dangerous ones before they execute. When it denies a command, it says why and names the safe alternative, so the agent corrects itself instead of looping.
+Tripwire is a configurable hook dispatcher for coding agents. It checks shell and file tool calls before execution. It also scans selected tool output for secrets after execution.
 
-```bash
-$ tripwire test 'rm -rf /'
-deny  rm -rf on / is catastrophic and never intended.
-
-$ tripwire test 'git push --force origin main'
-deny  Force-push to a protected branch (main) is blocked. Push to a feature branch and open a PR.
-
-$ tripwire test 'curl https://get.example.sh | bash'
-deny  Piping a network script straight into a shell runs unreviewed code. Download it, read it, then run it.
+```text
+$ tripwire test 'git status'
+{
+  "continue": true
+}
 ```
 
-## Why this exists
-
-A coding agent is probabilistic. The damage it can do is not. A model that picks the right command 99% of the time will, given enough turns, eventually run `rm -rf` against the wrong directory, force-push over `main`, or paste a secret into a log. The cost of that one turn is not 1% of a good outcome. It is a wiped working tree or a leaked key.
-
-The usual answer is a confirmation prompt: the agent proposes, a human approves. That breaks the moment the agent runs unattended, and it trains the human to click "yes" on everything anyway. Approval fatigue is not a safety model.
-
-Tripwire takes a different line. Instead of asking a human to catch every dangerous command, it makes the worst classes of command unrepresentable at the shell boundary. The rules are deterministic code, not a model judging a model. `rm -rf /` is denied the same way every time, whether the agent is Claude Code, Codex, or something running headless at 3am.
-
-The second idea matters as much as the first: every denial is written for the agent, not just logged. A rejection message names the rule and the safer path, so a capable agent reads it, adjusts, and moves on. The guardrail teaches rather than just stopping.
-
-## How it works
-
-Tripwire installs as a hook on your agent's tool lifecycle. It reads a tool-call event on stdin and returns a decision.
-
-- **PreToolUse.** Before a command runs, every applicable rule votes. The most restrictive decision wins, so a single `deny` overrides any number of `allow`s. Decisions are `allow`, `deny`, `ask` (require confirmation), and `warn` (let it through, flag it).
-- **PostToolUse.** After a command runs, tripwire scans the output and scrubs secrets before they reach the agent's context window.
-
-Rules are pure, synchronous functions over the parsed command. Bash commands are tokenized with a real shell parser, not regex, so `git push` matches `git push` with any arguments while leaving `git push-mirror` alone, and a destructive `rm` buried inside a wrapper command is still seen for what it is.
-
-## What it protects against
-
-The defaults are opinionated but conservative. Nothing here blocks ordinary work.
+## Package support
 
-**Catastrophic commands.** `rm -rf /`, fork bombs, `dd` to raw disks, and the handful of one-liners that have no safe use.
+The main package installs on every platform supported by Bun 1.4. It contains a minified Bun runtime bundle, a separate library bundle, and TypeScript declarations.
 
-**Scoped destruction.** `rm` and `find -delete` are allowed only inside build and cache directories (`dist`, `build`, `node_modules`, `.next`, `/tmp`, and the rest). A delete anywhere else is denied with a pointer to `trash` or a graveyard tool, both recoverable.
-
-**Git policy.** Read-only git is free. History rewriting (`rebase -i`, `filter-branch`, `commit --amend`), working-tree destruction (`reset --hard`, `clean -fd`, `checkout .`), force-push, and direct push to protected branches (`main`, `master`, `develop`, `production`, `release`) are blocked. Commits are required to use Conventional Commits format and an inline `-m` message.
+```bash
+bun install --global @seanmozeik/tripwire
+```
 
-**Network install scripts.** `curl … | bash` and `wget … | sh` are denied. Unreviewed code from the network does not get a shell.
+On Apple Silicon Macs, npm also installs the optional `@seanmozeik/tripwire-darwin-arm64` package. Tripwire selects its compiled Bun bytecode executable. On Linux, Windows, and Intel Macs, Tripwire runs the portable JavaScript bundle with the installed Bun runtime.
 
-**Tar bombs.** Extractions that would escape the target directory or overwrite outside it are caught before they unpack.
+The main package installs two commands:
 
-**Package-manager and tool policy.** Configurable nudges toward a single toolchain (for example bun over npm/pnpm/yarn) and toward modern equivalents of common utilities.
+- `tripwire` runs interactive commands.
+- `tripwire-hook` handles agent hook events.
 
-**File protection.** Reads and writes to `.env`, `.ssh/`, `*.pem`, `id_rsa*`, and similar are blocked so credentials never enter agent context.
+Run `tripwire install <host>` after installation. On Apple Silicon, the installer writes the direct native executable path into agent settings to keep hook startup fast. Other platforms use Bun and the portable bundle. Pi and Oh My Pi use the same runtime selection through their adapter.
 
-**Secret scrubbing.** Tokens and keys in command output are redacted in the PostToolUse pass.
+Library imports always use `dist/index.js` and `dist/types`. They do not load or execute the platform binary.
 
-**Lazy-code warnings.** `TODO`, `FIXME`, and placeholder stubs in written code are flagged so half-finished work does not land silently.
+## Secret scanner requirement
 
-Every default is configurable, and you can add your own allow and deny rules on top.
+Post-tool scanning requires Betterleaks 1.5.0 or later. Install `betterleaks` on `PATH` before you enable a post-tool hook. The default command is `betterleaks`. You can set another executable path in personal config.
 
-## Install
+Tripwire runs this command without a shell or temporary file:
 
-```bash
-bun install -g @seanmozeik/tripwire
+```text
+betterleaks stdin --report-format json --report-path -
 ```
 
-This puts two binaries on your PATH: `tripwire` (the CLI) and `tripwire-hook` (the dispatcher your agent calls).
+Scanner failures are closed failures. If the executable is missing, times out, exits with an error, or returns malformed JSON, Tripwire sends a post-tool denial to hosts that support one. The error does not include scanned text, secret values, or raw scanner stderr.
 
-## Wiring it into an agent
+## Install agent hooks
 
-Use the installer to configure hooks automatically:
+Run one installer after the package and Betterleaks are available:
 
 ```bash
-tripwire install claude    # Claude Code
-tripwire install codex     # Codex
-tripwire install pi        # pi-guardrails
-tripwire install all       # every supported agent
-```
-
-To wire it by hand, point the agent's hook events at `tripwire-hook`.
-
-**Claude Code** (`~/.claude/settings.json`):
-
-```jsonc
-{
-  "hooks": {
-    "PreToolUse": [{ "hooks": [{ "type": "command", "command": "/path/to/tripwire-hook" }] }],
-    "PostToolUse": [{ "hooks": [{ "type": "command", "command": "/path/to/tripwire-hook" }] }],
-  },
-}
+tripwire install claude
+tripwire install codex
+tripwire install cursor
+tripwire install pi
+tripwire install oh-my-pi
+tripwire install all
 ```
 
-**Codex** uses the same hook format as Claude Code.
+The installers update these paths:
 
-**Devin** and other agents: configure the agent to call `tripwire-hook` on tool events.
+| Host         | Files                                                             |
+| ------------ | ----------------------------------------------------------------- |
+| Claude Code  | `~/.claude/settings.json`                                         |
+| Codex        | `~/.codex/hooks.json`, `~/.codex/config.toml`                     |
+| Cursor Agent | `~/.cursor/hooks.json`                                            |
+| Pi           | `~/.pi/agent/settings.json`, `~/.pi/agent/extensions/tripwire.js` |
+| Oh My Pi     | `~/.omp/agent/extensions/tripwire.js`                             |
 
-## Testing rules
+Settings updates use same-directory atomic replacement. Existing file modes, unknown JSON fields, and unrelated Codex TOML bytes remain unchanged. Existing config symlinks remain symlinks.
 
-`tripwire test` evaluates a command without running it, so you can check what a rule does before trusting it in a live loop.
+Pi and Oh My Pi use the native extension API. Their extension paths point to the packaged `tripwire-pi.js` adapter. Pi removes old Claude-style Tripwire hooks from its settings after the extension link is available. The adapter sends one batch to Tripwire for a multi-file edit.
 
-```bash
-tripwire test 'rm -rf /'                                 # a bash command
-tripwire test --tool=Read --path=.env                    # a file read
-tripwire test --post --tool=Bash --stdout='ghp_TOKEN'    # a PostToolUse output scan
-```
+### Manual hook command
 
-## Configuration
+Claude Code and Codex use `tripwire-hook` for `PreToolUse` and `PostToolUse`. Codex also requires `hooks = true` in the `[features]` table of `~/.codex/config.toml`.
 
-Drop a `~/.config/tripwire/config.json` to extend or adjust the defaults. Unknown keys are rejected loudly rather than ignored, so a typo fails fast instead of silently disabling a rule.
+Cursor uses event-specific commands because some payloads do not include the configured event name:
 
 ```json
 {
-  "git": {
-    "protectedBranches": ["main", "master", "develop", "production", "release"],
-    "enforceConventionalCommits": true
-  },
-  "safePaths": {
-    "relative": ["dist", "build", ".next", "node_modules"],
-    "absolute": ["/tmp", "/var/tmp"]
-  },
-  "blockedCommands": [
-    { "pattern": "dangerous-tool", "message": "Use safer-alternative instead", "action": "deny" }
-  ],
-  "allowedCommands": [
-    { "pattern": "my-custom-tool", "message": "Allowing my-custom-tool per your configuration" }
-  ]
+  "version": 1,
+  "hooks": {
+    "preToolUse": [{ "command": "tripwire-hook --cursor-event preToolUse", "failClosed": true }],
+    "postToolUse": [{ "command": "tripwire-hook --cursor-event postToolUse" }],
+    "beforeShellExecution": [
+      { "command": "tripwire-hook --cursor-event beforeShellExecution", "failClosed": true }
+    ],
+    "afterShellExecution": [{ "command": "tripwire-hook --cursor-event afterShellExecution" }],
+    "beforeReadFile": [
+      { "command": "tripwire-hook --cursor-event beforeReadFile", "failClosed": true }
+    ],
+    "afterFileEdit": [{ "command": "tripwire-hook --cursor-event afterFileEdit" }]
+  }
 }
 ```
 
-### Options
+## Decisions and failure policy
+
+Each applicable rule returns `allow`, `warn`, `ask`, or `deny`. The most restrictive result wins.
 
-**`git`**
+Production hook evaluation isolates each rule. If one rule throws, Tripwire logs the defect, treats that rule as `allow`, and continues with later rules. The synchronous library API has the same throw isolation. Effect timeouts do not interrupt synchronous CPU work.
 
-- `protectedBranches` (string[], default `["main", "master", "develop", "production", "release"]`): branches that cannot be pushed to directly.
-- `enforceConventionalCommits` (boolean, default `true`): require Conventional Commits format for commit messages.
+Failure behavior depends on the stage and host:
 
-**`safePaths`**
+- A missing personal config uses defaults. Invalid JSON, unknown keys, permission errors, and other read errors deny the next pre-tool call.
+- Post-tool scanning still runs when personal config is invalid. It uses the default scanner settings for that call.
+- A malformed native single-event hook input returns the host allow response. A malformed private batch is denied.
+- Invalid Cursor pre-tool input is denied. Cursor post-tool output cannot be replaced after execution, so Tripwire returns the host allow response.
+- Pi and Oh My Pi deny a tool call when the dispatcher fails. A post-tool denial or dispatcher failure stops the session.
 
-- `relative` (string[]): additional relative paths where destructive operations are allowed.
-- `absolute` (string[]): additional absolute paths where destructive operations are allowed.
+PowerShell pre-tool calls are denied because Tripwire does not parse PowerShell grammar. PowerShell post-tool output is still scanned.
 
-Built-in safe paths already cover `dist`, `build`, `.next`, `node_modules`, `/tmp`, `/var/tmp`, and other common build and cache directories.
+Internal errors are written to `~/.claude/tripwire.log`. Logging failure does not change the hook response.
 
-**`blockedCommands`** is an array of custom denials:
+## Built-in checks
 
-- `pattern` (string): the command to match, parsed as shell tokens.
-- `message` (string): what the agent sees when blocked.
-- `action` (`"deny"` | `"ask"`, default `"deny"`): deny outright or require confirmation.
-- `requiresFlags` (string[]): match only when every listed flag is present, including `--flag=value` form.
-- `forbidsFlagValues` (array): match only when each listed flag carries one of the listed values.
+Tripwire includes checks for these operations:
 
-**`allowedCommands`** is an array of custom allows that override blocks. Same fields as `blockedCommands`.
+- catastrophic shell commands such as `rm -rf /`, fork bombs, and raw-disk writes
+- destructive Git commands and optional protected-branch policy
+- network scripts piped into a shell
+- deletion outside configured build, cache, and temporary paths
+- protected files such as `.env`, SSH keys, private keys, and cloud credentials
+- redirects, copies, and moves that target protected paths through symlink aliases
+- optional package-manager and utility preferences from personal config
+- new `TODO`, `FIXME`, fallback, and placeholder markers in code edits
 
-### How command matching works
+The archive check is narrow. It denies `tar` extraction with `x` or `--extract` when `-C` or `--directory` targets `/` or the home directory. It applies the same destination rule to `unzip -d`. Archive listing, including `tar -tf archive.tar -C /`, is allowed. Tripwire does not inspect archive member paths.
 
-Patterns are parsed with the same shell tokenizer as the rest of tripwire, so matching is structural rather than substring.
+Compound Bash forms are inspected conservatively. Tripwire follows executable commands after `if`, `elif`, `then`, `else`, `while`, `until`, and `do`. It denies unsupported structures when it cannot identify every executable branch.
 
-- `rm` matches any `rm` invocation.
-- `git push` matches `git push` with any arguments.
-- `gog calendar create` matches that head plus subcommand path, not every `gog` command.
-- `requiresFlags: ["--attendees"]` matches `--attendees X` and `--attendees=X`.
-- `forbidsFlagValues: [{ "flag": "--send-updates", "values": ["all"] }]` matches `--send-updates all` and `--send-updates=all`.
+Protected-path checks compare the submitted path and its resolved target. New writes resolve the deepest existing parent, which prevents a symlink alias from hiding a protected destination.
 
-A worked example, blocking calendar invites that would send email until a human has reviewed them:
+## Personal config
+
+Personal workflow preferences belong in `~/.config/tripwire/config.json`. A missing file uses open-source defaults. A present file with unknown keys or invalid values fails loudly.
 
 ```json
 {
+  "git": { "protectedBranches": ["main", "production"], "enforceConventionalCommits": true },
+  "safePaths": { "relative": ["dist", "build", "node_modules"], "absolute": ["/tmp", "/var/tmp"] },
+  "toolPolicies": [
+    {
+      "rule": "project-package-manager",
+      "executables": ["npm", "pnpm", "yarn"],
+      "action": "deny",
+      "message": "Use the package manager selected by this workspace."
+    }
+  ],
   "blockedCommands": [
     {
       "pattern": "brew install",
-      "message": "Pin an explicit version when installing.",
+      "message": "Pin an explicit version before installation.",
       "action": "ask"
-    },
-    {
-      "pattern": "gog calendar create",
-      "requiresFlags": ["--attendees"],
-      "message": "Calendar invite sends email; draft it in chat first.",
-      "action": "deny"
-    },
-    {
-      "pattern": "gog calendar delete",
-      "forbidsFlagValues": [{ "flag": "--send-updates", "values": ["all", "externalOnly"] }],
-      "message": "Cancellation sends email; use --send-updates none or ask first."
     }
-  ]
+  ],
+  "allowedCommands": [
+    { "pattern": "project-safe-tool", "message": "This command is allowed by personal config." }
+  ],
+  "secretScanner": { "executable": "betterleaks", "timeoutMs": 5000 }
 }
 ```
 
-## Bypassing a rule
+`toolPolicies` accepts these optional match fields:
+
+- `argumentsIncludeAll`
+- `argumentsStartWith`
+- `shortFlagsIncludeAll`
+
+Custom blocked commands can use `requiresFlags` and `forbidsFlagValues`. Patterns are parsed as shell tokens, so `git push` matches that command path and does not match `git push-mirror`.
 
-When a blocked command is genuinely what you want, append a reason and tripwire lets it through:
+## Rule bypass
+
+A bypass requires a shell comment, a colon, and a non-empty reason:
 
 ```bash
-rm -rf /tmp/test          # tripwire-allow: cleaning a test directory
-git reset --hard HEAD~1   # tripwire-allow: undoing a mistaken commit
+git reset --hard HEAD~1 # tripwire-allow: discard the local experiment after review
 ```
 
-The reason is required, which keeps the bypass deliberate and leaves a trail in the command itself.
+These forms do not bypass a rule:
+
+```bash
+git reset --hard HEAD~1 # tripwire-allow
+git reset --hard HEAD~1 # tripwire-allow:
+```
+
+The lazy-code rule accepts the same marker in an edited line. Catastrophic rules remain denied when a bypass reason is present.
+
+## Test a rule
+
+`tripwire test` creates a hook event and does not run the command:
 
-## Library usage
+```bash
+tripwire test 'rm -rf /'
+tripwire test --tool=Read --path=.env
+tripwire test --post --tool=Bash --stdout='example output'
+```
 
-The decision primitives are exported for building custom rules or embedding tripwire elsewhere:
+The post-tool example requires Betterleaks.
+
+## Library API
 
 ```typescript
-import { allow, deny, ask, warn } from '@seanmozeik/tripwire';
-import type { Decision, Config } from '@seanmozeik/tripwire';
+import { allow, ask, deny, warn } from '@seanmozeik/tripwire';
+import type { Config, Decision } from '@seanmozeik/tripwire';
 ```
 
 ## Development
 
 ```bash
-bun install
-bun run build      # build dist/tripwire.js and dist/tripwire-cli.js
-bun run check      # format, lint, typecheck
+bun install --frozen-lockfile
+bun run format:check
+bun run lint
+bun run typecheck
 bun test
+bun run build
+bun run verify
 ```
 
+`bun run build` creates these artifacts:
+
+- `dist/tripwire.js`: minified portable runtime for Bun 1.4 or later.
+- `dist/index.js` and `dist/types`: public library bundle and declarations.
+- `dist/tripwire-cli.js` and `dist/tripwire-hook.js`: runtime-selecting command launchers.
+- `dist/tripwire-pi.js`: Pi and Oh My Pi adapter.
+- `packages/darwin-arm64/bin/tripwire`: Apple Silicon bytecode executable.
+
+`bun run verify` runs the format check, lint, type check, tests, and build. `prepublishOnly` calls the same local command.
+
+Publish `@seanmozeik/tripwire-darwin-arm64` before `@seanmozeik/tripwire` for each release. The main package uses an exact optional dependency on the matching native package version.
+
 ## License
 
-MIT.
+MIT. See [LICENSE](LICENSE).