feat: add /passthru:list and /passthru:remove commands (#10)

Author: nnemirovsky

.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "owner": {
     "name": "nnemirovsky"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "passthru",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Regex-based permission rules for Claude Code via hooks",
   "license": "MIT"
 }

CLAUDE.md

@@ -12,6 +12,8 @@ commands/
   bootstrap.md         /passthru:bootstrap slash command (wraps scripts/bootstrap.sh with dry-run + confirm)
   add.md               /passthru:add slash command (prompt-based)
   suggest.md           /passthru:suggest slash command (prompt-based)
+  list.md              /passthru:list slash command (wraps scripts/list.sh)
+  remove.md            /passthru:remove slash command (wraps scripts/remove-rule.sh)
   verify.md            /passthru:verify slash command (prompt-based)
   log.md               /passthru:log slash command (prompt-based)
 hooks/
@@ -37,7 +39,9 @@ scripts/
                        Supported shapes: Bash(prefix:*) | Bash(exact) | mcp__* | WebFetch(domain:X)
                        | WebSearch | Read/Edit/Write(path[/**]) | Skill(name). Others -> [WARN] skip.
   write-rule.sh        atomic write wrapper: backup + append + verify + rollback
-  verify.sh            rule verifier CLI (also invoked by write-rule.sh and /passthru:verify)
+  remove-rule.sh       atomic remove wrapper: backup + splice + verify + rollback. Authored-only.
+  list.sh              rule list viewer CLI with scope/list/source/index annotations
+  verify.sh            rule verifier CLI (also invoked by write-rule.sh/remove-rule.sh and /passthru:verify)
   log.sh               audit-log viewer CLI + sentinel toggle
 tests/
   fixtures/            JSON fixture files used by bats tests
@@ -133,11 +137,12 @@ Checks performed (in order, across the merged set):
 ## Write-wrapper locking
 
 `scripts/write-rule.sh` (also called by `bootstrap.sh --write` and the
-`/passthru:add`, `/passthru:suggest` commands) serializes concurrent writers
-via a single user-scope lock directory at
-`~/.claude/passthru.write.lock.d`. The lock uses `mkdir`, which is atomic on
-every POSIX filesystem we target (local Linux/macOS plus NFS), works without
-any extra dependency, and polls at 100 ms intervals while waiting.
+`/passthru:add`, `/passthru:suggest` commands) and `scripts/remove-rule.sh`
+(called by `/passthru:remove`) serialize concurrent mutations via a single
+user-scope lock directory at `~/.claude/passthru.write.lock.d`. The lock
+uses `mkdir`, which is atomic on every POSIX filesystem we target (local
+Linux/macOS plus NFS), works without any extra dependency, and polls at
+100 ms intervals while waiting.
 
 The lock-acquisition timeout is 5 seconds by default and is configurable via
 `PASSTHRU_WRITE_LOCK_TIMEOUT=<seconds>` in the environment. Both

README.md

@@ -46,6 +46,8 @@ All commands are plugin-namespaced under `/passthru:`.
 | `/passthru:bootstrap` | One-shot importer: reviews your existing `permissions.allow` entries, shows the proposed rules, asks to confirm, then writes `passthru.imported.json`. Runs the verifier afterwards. |
 | `/passthru:add` | Add a rule without hand-editing `passthru.json`. Supports `--deny` and `--field`. |
 | `/passthru:suggest` | Propose a generalized rule from a recent tool call in the conversation, then write it on confirmation. |
+| `/passthru:list` | Show every rule across user and project scopes, grouped by `(scope, list, source)` with 1-based indexes. Filter by `--scope`, `--list`, `--source`, or `--tool`. |
+| `/passthru:remove` | Remove an authored rule by `<scope> <list> <index>`. Indexes match the numbering from `/passthru:list`. Imported (bootstrap-generated) rules are not removable here; edit `settings.json` and re-run bootstrap instead. |
 | `/passthru:verify` | Validate every rule file. Surfaces parse errors, schema violations, invalid regex, duplicates, and allow/deny conflicts. |
 | `/passthru:log` | Read the audit log with filters. Also toggles the audit sentinel on/off. |
 
@@ -195,6 +197,30 @@ Propose a generalized rule from a recent tool call in the conversation. The comm
 /passthru:suggest gh api
 ```
 
+### `/passthru:list`
+
+Show every rule across user and project scopes. Rules are grouped by `(scope, list, source)` and numbered with 1-based indexes that match what `/passthru:remove` expects.
+
+```
+/passthru:list
+/passthru:list --scope user --list deny
+/passthru:list --source imported
+/passthru:list --tool '^Bash$'
+/passthru:list --flat
+/passthru:list --format json
+```
+
+### `/passthru:remove`
+
+Remove an authored rule by `<scope> <list> <index>`. Run `/passthru:list` first to see the indexes.
+
+```
+/passthru:remove user allow 3
+/passthru:remove project deny 1
+```
+
+Imported rules (written by `/passthru:bootstrap`) are not removable here because bootstrap regenerates them on every run. To drop one, remove the corresponding `permissions.allow` entry from `settings.json` and re-run bootstrap.
+
 ### `/passthru:verify`
 
 Validate every rule file. Surfaces parse errors, schema violations, invalid regex, duplicates, and allow+deny conflicts.

commands/list.md

@@ -0,0 +1,111 @@
+---
+description: List passthru rules with scope, source, list, and index annotations
+argument-hint: "[--scope user|project|all] [--list allow|deny|all] [--source authored|imported|all] [--tool <regex>] [--format table|json|raw] [--flat]"
+---
+
+# /passthru:list
+
+Show every passthru rule across user and project scopes, grouped by
+`(scope, list, source)` with 1-based indexes that match the numbering
+`/passthru:remove` expects.
+
+Rules come from up to four files:
+
+* `~/.claude/passthru.json` - user-authored
+* `~/.claude/passthru.imported.json` - user-imported (written by
+  `scripts/bootstrap.sh`)
+* `$PWD/.claude/passthru.json` - project-authored
+* `$PWD/.claude/passthru.imported.json` - project-imported
+
+## What you must do
+
+You are Claude. Shell out to the list script with `$ARGUMENTS` passed
+verbatim, then present the output. Do not paraphrase table rows; quote
+them verbatim.
+
+### 1. Run the list viewer
+
+Invoke exactly:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/list.sh $ARGUMENTS
+```
+
+Capture stdout, stderr, and the exit code. The script accepts:
+
+* `--scope user|project|all` - default `all`.
+* `--list allow|deny|all` - default `all`.
+* `--source authored|imported|all` - default `all`. Useful to see only
+  bootstrap imports, or to check the hand-curated authored set.
+* `--tool <regex>` - perl regex matched against the `.tool` field.
+* `--format table|json|raw` - default `table` (colorized when stdout is
+  a tty), `json` emits an array of annotated rule objects (scope,
+  source, list, index, path, rule), `raw` emits one rule JSON per line
+  with annotations stripped.
+* `--flat` - skip grouped rendering and emit one flat table with
+  `scope`, `list`, `source`, `#` columns in front.
+
+### 2. Present the result
+
+Branch on the exit code:
+
+**Exit 0, stdout has rows:** show the grouped (or flat) table verbatim.
+Optionally add a one-liner summarizing the filter that was applied so
+the user knows which rules they are looking at.
+
+**Exit 0, stderr says `no rules found`:** no rule files exist yet, or
+the filter matched nothing. Suggest `/passthru:add` to add a first rule
+or `/passthru:bootstrap` to import from native settings.
+
+**Exit 2:** the user passed a bad `--tool` regex or an unknown flag.
+Surface stderr verbatim and suggest re-running with `--help`.
+
+### 3. Guidance
+
+* Point the user at `/passthru:remove <scope> <list> <index>` when they
+  ask how to delete a rule. The indexes in this command's output line
+  up with what `remove` expects.
+* Imported rules are regenerated by `/passthru:bootstrap`. If the user
+  wants to edit them, they should change the underlying
+  `permissions.allow` entries in their `settings.json` and re-run
+  bootstrap, not hand-edit the imported file.
+* `--format raw` is the right choice for piping into `jq` for custom
+  queries without quoting hassle.
+
+## Examples
+
+* Show everything (default grouping):
+
+  ```
+  /passthru:list
+  ```
+
+* Show only deny rules in the user scope:
+
+  ```
+  /passthru:list --scope user --list deny
+  ```
+
+* Show only what was imported by bootstrap:
+
+  ```
+  /passthru:list --source imported
+  ```
+
+* Filter by tool:
+
+  ```
+  /passthru:list --tool '^Bash$'
+  ```
+
+* Emit a flat table for easy grepping:
+
+  ```
+  /passthru:list --flat
+  ```
+
+* JSON for scripting:
+
+  ```
+  /passthru:list --format json
+  ```

commands/remove.md

@@ -0,0 +1,91 @@
+---
+description: Remove an authored passthru rule by scope, list, and 1-based index
+argument-hint: "<scope> <list> <index>"
+---
+
+# /passthru:remove
+
+Remove a single authored passthru rule by scope, list, and 1-based
+index. Imported rules (written by `scripts/bootstrap.sh`) are not
+removable here because bootstrap regenerates them on every run. To
+drop an imported rule, remove the corresponding `permissions.allow`
+entry from your `settings.json` and re-run bootstrap.
+
+Run `/passthru:list` first to see the indexes.
+
+## What you must do
+
+You are Claude. Parse `$ARGUMENTS` and shell out to the remove script.
+Do not invent behaviour. Surface errors verbatim.
+
+### 1. Tokenize `$ARGUMENTS`
+
+Three positional tokens are required, in this order:
+
+1. `scope` - must be `user` or `project`.
+2. `list` - must be `allow` or `deny`.
+3. `index` - positive integer, 1-based, from the `#` column of
+   `/passthru:list` under the matching `(scope, list, authored-source)`
+   group.
+
+If any are missing or malformed, tell the user:
+`usage: /passthru:remove <scope> <list> <index>` and stop.
+
+### 2. Invoke the remove wrapper
+
+Run exactly:
+
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/remove-rule.sh <scope> <list> <index>
+```
+
+Capture stdout, stderr, and the exit code.
+
+### 3. Handle the result
+
+**Exit 0:** the script prints
+`removed <scope>/<list>/<index>: <tool-summary>` on stdout. Echo that
+back to the user plus a reminder that the file is now one rule
+shorter. Optionally offer to run `/passthru:list` to confirm.
+
+**Exit 1:** invalid args, rule not found, or the user tried to remove
+an imported rule. Surface stderr verbatim. If the message mentions
+`cannot remove imported rule`, explain that bootstrap-managed rules
+are regenerated from `settings.json` and suggest editing that file
+followed by `/passthru:bootstrap --write`.
+
+**Exit 2:** the verifier rejected the post-remove state. The remove
+script has already restored the backup. Show the verifier's stderr
+verbatim and suggest `/passthru:verify` for a full report. This is
+rare in practice since removing a rule cannot introduce a new
+violation.
+
+### 4. Guidance
+
+* Recommend `/passthru:list` before `/passthru:remove` so the user
+  sees live indexes. Indexes shift down after a remove, so consecutive
+  removes should re-check the list.
+* Remember that `remove` only operates on authored files
+  (`passthru.json`), never on imported ones.
+
+## Examples
+
+* Remove the 3rd authored allow rule from the user scope:
+
+  ```
+  /passthru:remove user allow 3
+  ```
+
+* Remove the first authored deny rule from the project scope:
+
+  ```
+  /passthru:remove project deny 1
+  ```
+
+* Typical workflow:
+
+  ```
+  /passthru:list
+  /passthru:remove user allow 2
+  /passthru:list        # confirm the remaining rules
+  ```