bash-classify 0.9.1__tar.gz → 0.11.0__tar.gz

{bash_classify-0.9.1 → bash_classify-0.11.0}/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "bash-classify-hook",
       "description": "Auto-allows low-risk bash commands in Claude Code using bash-classify",
-      "version": "0.9.1",
+      "version": "0.11.0",
       "author": {
         "name": "Filip Procházka",
         "url": "https://github.com/fprochazka"

{bash_classify-0.9.1 → bash_classify-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: bash-classify
-Version: 0.9.1
+Version: 0.11.0
 Summary: Classify bash commands as READONLY, WRITE, DANGEROUS, or UNKNOWN
 Project-URL: Homepage, https://github.com/fprochazka/bash-classify
 Project-URL: Repository, https://github.com/fprochazka/bash-classify
@@ -61,6 +61,66 @@ $ echo 'find . -name "*.pyc" -delete' | bash-classify | jq '.classification'
 "DANGEROUS"
 ```
 
+## Matching command shapes
+
+Classification answers "how risky is this?". A deny hook usually has a narrower question:
+"does this expression run command shape X?" `bash-classify match` answers that one. It
+parses the expression, walks every invocation at every depth, and reports which of the
+shapes in a rules file were actually invoked — so a heredoc body, an `echo` string, a
+`#` comment or a `grep` pattern that merely *names* the command does not count.
+
+```yaml
+# blocked-commands.yaml
+rules:
+  - name: mr-discussions-api
+    command: [glab, api]
+    any_arg_matches: 'merge_requests/[^/?]+/(discussions|notes)(/|\?|$)'
+
+  - name: mr-view-comments
+    command: [glab, mr, view]
+    any_option: [--comments, -c]
+
+  - name: mr-note
+    command: [glab, mr, note]
+    except: [[glab, mr, note, list]]
+```
+
+```bash
+$ echo 'sudo glab mr note 42 -m hi' | bash-classify match --rules blocked-commands.yaml
+{
+  "matches": [
+    {
+      "rule": "mr-note",
+      "command": ["glab", "mr", "note"],
+      "argv": ["glab", "mr", "note", "42", "-m", "hi"],
+      "via": ["sudo"]
+    }
+  ],
+  "parse_warnings": []
+}
+```
+
+Within one rule every condition given must hold; rules are independent of each other, and
+one invocation can match several. `command` is a prefix match against the *resolved*
+command path, so `/usr/bin/glab --repo x mr note` still resolves to `glab mr note`.
+`any_option` looks at the options actually present, with values stripped and declared
+clusters expanded (`-wc` carries `-c`). `any_arg_matches` is a Python `re.search` over
+every argument token — a pattern written for `grep -E` needs `\S` rather than
+`[^[:space:]]`. `via` lists the enclosing wrappers, outermost first.
+
+**Two things a caller has to check.** First, `parse_warnings` is always present: when it
+is non-empty the expression could not be fully parsed, so an empty `matches` proves nothing
+and the caller should fall back to whatever it did before. Second, check that the output
+actually has a `matches` key. A `bash-classify` older than this mode does not reject the
+unknown `match` argument — it ignores it, classifies stdin and exits 0, so the caller gets
+a normal classification JSON with no `matches` key. Treat a non-zero exit, unparseable
+output, or output without a `matches` key as "cannot answer" and fall back; never read a
+missing `matches` as "nothing matched".
+
+Exit codes are `0` whether or not anything matched, `1` for empty input or no input within
+5 seconds, and `2` for bad arguments, an unreadable or invalid rules file, or an internal
+error.
+
 ## Claude Code plugin
 
 The repo includes a Claude Code plugin that auto-allows low-risk bash commands via a `PreToolUse` hook.
@@ -120,6 +180,7 @@ Risk defaults are derived from classification (`READONLY`→LOW, `LOCAL_EFFECTS`
 - **Tree-sitter parsing** -- bash expressions are parsed into an AST for accurate command extraction, handling pipes, subshells, and command substitution
 - **YAML command database** -- each command has classification rules with subcommand and option matching
 - **Subcommand matching** -- `kubectl get` and `kubectl delete` can have different classifications
+- **Subcommand aliases** -- a subcommand can declare other names for itself, so `glab pipeline view` resolves to `glab ci view` and any rule written for the canonical name catches the aliased spelling
 - **Multi-goal build tools** -- `subcommand_mode: match_all` handles commands like `mvn clean install` and `gradle clean build test` where multiple goals can be combined in any order
 - **Delegation for wrappers** -- commands like `xargs`, `sudo`, and `env` delegate classification to the inner command
 - **File path detection** -- redirect operators (`>`, `>>`, `<`) are parsed into `write_paths`/`read_paths` in the output; writes to `/tmp` and `/var/tmp` stay at LOW risk
@@ -134,6 +195,41 @@ print(result.classification)  # Classification.READONLY
 print(result.risk)            # Risk.LOW
 ```
 
+Each command result carries the options it actually uses and the positionals left after parsing. Option values
+are stripped, so `--key=value` shows up as `--key` and `-fvalue` as `-f`:
+
+```python
+command = classify_expression("git commit --amend -m 'wip'").commands[0]
+print(command.command)      # ['git', 'commit']
+print(command.options)      # ['--amend', '-m']
+print(command.positionals)  # []
+```
+
+`iter_invocations` walks every invocation in an expression depth-first — top-level commands and, recursively,
+the inner commands that wrappers such as `sudo`, `timeout` or `bash -c` delegate to. It yields each invocation
+with its `via` chain: the enclosing wrappers, outermost first, empty at the top level.
+
+```python
+from bash_classify import classify_expression, iter_invocations
+
+for invocation, via in iter_invocations(classify_expression("sudo timeout 5 ls")):
+    print(via, invocation.command)
+# [] ['sudo']
+# ['sudo'] ['timeout']
+# ['sudo', 'timeout'] ['ls']
+```
+
+`load_rules` and `match_expression` are the same thing from Python:
+
+```python
+from bash_classify import load_rules, match_expression
+
+rules = load_rules("blocked-commands.yaml")
+result = match_expression('cat > brief.md <<"EOF"\nmentions glab mr note\nEOF', rules)
+print(result.matches)         # [] - the heredoc body is data, not a command
+print(result.parse_warnings)  # []
+```
+
 See [SPEC.md](SPEC.md) for the full specification.
 
 ## Development

{bash_classify-0.9.1 → bash_classify-0.11.0}/README.md

@@ -32,6 +32,66 @@ $ echo 'find . -name "*.pyc" -delete' | bash-classify | jq '.classification'
 "DANGEROUS"
 ```
 
+## Matching command shapes
+
+Classification answers "how risky is this?". A deny hook usually has a narrower question:
+"does this expression run command shape X?" `bash-classify match` answers that one. It
+parses the expression, walks every invocation at every depth, and reports which of the
+shapes in a rules file were actually invoked — so a heredoc body, an `echo` string, a
+`#` comment or a `grep` pattern that merely *names* the command does not count.
+
+```yaml
+# blocked-commands.yaml
+rules:
+  - name: mr-discussions-api
+    command: [glab, api]
+    any_arg_matches: 'merge_requests/[^/?]+/(discussions|notes)(/|\?|$)'
+
+  - name: mr-view-comments
+    command: [glab, mr, view]
+    any_option: [--comments, -c]
+
+  - name: mr-note
+    command: [glab, mr, note]
+    except: [[glab, mr, note, list]]
+```
+
+```bash
+$ echo 'sudo glab mr note 42 -m hi' | bash-classify match --rules blocked-commands.yaml
+{
+  "matches": [
+    {
+      "rule": "mr-note",
+      "command": ["glab", "mr", "note"],
+      "argv": ["glab", "mr", "note", "42", "-m", "hi"],
+      "via": ["sudo"]
+    }
+  ],
+  "parse_warnings": []
+}
+```
+
+Within one rule every condition given must hold; rules are independent of each other, and
+one invocation can match several. `command` is a prefix match against the *resolved*
+command path, so `/usr/bin/glab --repo x mr note` still resolves to `glab mr note`.
+`any_option` looks at the options actually present, with values stripped and declared
+clusters expanded (`-wc` carries `-c`). `any_arg_matches` is a Python `re.search` over
+every argument token — a pattern written for `grep -E` needs `\S` rather than
+`[^[:space:]]`. `via` lists the enclosing wrappers, outermost first.
+
+**Two things a caller has to check.** First, `parse_warnings` is always present: when it
+is non-empty the expression could not be fully parsed, so an empty `matches` proves nothing
+and the caller should fall back to whatever it did before. Second, check that the output
+actually has a `matches` key. A `bash-classify` older than this mode does not reject the
+unknown `match` argument — it ignores it, classifies stdin and exits 0, so the caller gets
+a normal classification JSON with no `matches` key. Treat a non-zero exit, unparseable
+output, or output without a `matches` key as "cannot answer" and fall back; never read a
+missing `matches` as "nothing matched".
+
+Exit codes are `0` whether or not anything matched, `1` for empty input or no input within
+5 seconds, and `2` for bad arguments, an unreadable or invalid rules file, or an internal
+error.
+
 ## Claude Code plugin
 
 The repo includes a Claude Code plugin that auto-allows low-risk bash commands via a `PreToolUse` hook.
@@ -91,6 +151,7 @@ Risk defaults are derived from classification (`READONLY`→LOW, `LOCAL_EFFECTS`
 - **Tree-sitter parsing** -- bash expressions are parsed into an AST for accurate command extraction, handling pipes, subshells, and command substitution
 - **YAML command database** -- each command has classification rules with subcommand and option matching
 - **Subcommand matching** -- `kubectl get` and `kubectl delete` can have different classifications
+- **Subcommand aliases** -- a subcommand can declare other names for itself, so `glab pipeline view` resolves to `glab ci view` and any rule written for the canonical name catches the aliased spelling
 - **Multi-goal build tools** -- `subcommand_mode: match_all` handles commands like `mvn clean install` and `gradle clean build test` where multiple goals can be combined in any order
 - **Delegation for wrappers** -- commands like `xargs`, `sudo`, and `env` delegate classification to the inner command
 - **File path detection** -- redirect operators (`>`, `>>`, `<`) are parsed into `write_paths`/`read_paths` in the output; writes to `/tmp` and `/var/tmp` stay at LOW risk
@@ -105,6 +166,41 @@ print(result.classification)  # Classification.READONLY
 print(result.risk)            # Risk.LOW
 ```
 
+Each command result carries the options it actually uses and the positionals left after parsing. Option values
+are stripped, so `--key=value` shows up as `--key` and `-fvalue` as `-f`:
+
+```python
+command = classify_expression("git commit --amend -m 'wip'").commands[0]
+print(command.command)      # ['git', 'commit']
+print(command.options)      # ['--amend', '-m']
+print(command.positionals)  # []
+```
+
+`iter_invocations` walks every invocation in an expression depth-first — top-level commands and, recursively,
+the inner commands that wrappers such as `sudo`, `timeout` or `bash -c` delegate to. It yields each invocation
+with its `via` chain: the enclosing wrappers, outermost first, empty at the top level.
+
+```python
+from bash_classify import classify_expression, iter_invocations
+
+for invocation, via in iter_invocations(classify_expression("sudo timeout 5 ls")):
+    print(via, invocation.command)
+# [] ['sudo']
+# ['sudo'] ['timeout']
+# ['sudo', 'timeout'] ['ls']
+```
+
+`load_rules` and `match_expression` are the same thing from Python:
+
+```python
+from bash_classify import load_rules, match_expression
+
+rules = load_rules("blocked-commands.yaml")
+result = match_expression('cat > brief.md <<"EOF"\nmentions glab mr note\nEOF', rules)
+print(result.matches)         # [] - the heredoc body is data, not a command
+print(result.parse_warnings)  # []
+```
+
 See [SPEC.md](SPEC.md) for the full specification.
 
 ## Development

{bash_classify-0.9.1 → bash_classify-0.11.0}/SPEC.md

@@ -186,12 +186,90 @@ $ echo 'sh -c "ls /tmp | grep log"' | bash-classify
 }
 ```
 
+### match mode
+
+```
+$ echo 'sudo glab mr note 42 -m hi' | bash-classify match --rules blocked-commands.yaml
+```
+
+```json
+{
+  "matches": [
+    {
+      "rule": "mr-note",
+      "command": ["glab", "mr", "note"],
+      "argv": ["glab", "mr", "note", "42", "-m", "hi"],
+      "via": ["sudo"]
+    }
+  ],
+  "parse_warnings": []
+}
+```
+
+`match` answers a narrower question than classification: which of the command shapes
+declared in a rules file does this expression actually invoke? Shell text that only names
+a command — a heredoc body, an `echo` or `printf` argument, a `#` comment, a
+`git commit -m` message, a `grep` pattern — is not an invocation and does not match.
+
+#### The rules file
+
+```yaml
+rules:
+  - name: mr-note                       # required, unique within the file
+    command: [glab, mr, note]           # required; prefix match on the resolved path
+    except: [[glab, mr, note, list]]    # optional; prefix paths excluded from the match
+    any_option: [--comments, -c]           # optional; at least one of these is present
+    any_arg_matches: 'merge_requests/[^/?]+/notes'   # optional; Python re.search
+```
+
+Within one rule every condition that is given must hold (AND). Rules are independent of
+each other (OR), and one invocation may match several rules; each match is reported.
+
+| Field | Meaning |
+|---|---|
+| `name` | Reported back on every match; must be unique within the file |
+| `command` | Prefix match against `command` — the *resolved* path, so `/usr/bin/glab --repo x mr note` matches `[glab, mr, note]` |
+| `except` | Prefix paths excluded from the match, so `[glab, mr, note]` can spare `glab mr note list` |
+| `any_option` | At least one of these must appear in `options`: as typed, values stripped, `--key=value` counting as `--key` and a declared cluster `-wc` counting as `-w` and `-c`. Tokens after `--` are positionals and never match |
+| `any_arg_matches` | Python `re.search` applied to every argument token: `argv[1:]` with the resolved subcommand words removed once each. Option flags, option values and positionals are all included; `argv[0]` and the subcommand words are not. A pattern written for `grep -E` needs `\S` instead of `[^[:space:]]` |
+
+A rule matches an invocation at any depth: top-level commands and, recursively, the inner
+commands that wrappers delegate to (`sudo`, `timeout`, `xargs`, `bash -c`, `find -exec`,
+`eval`, `exec`). Commands inside `$(...)` are top-level invocations in their own right.
+`via` lists the enclosing wrappers, outermost first, each as its resolved path joined by
+spaces; it is empty at the top level.
+
+`parse_warnings` is **always** present in match output, even when empty, because a caller
+has to check it: a non-empty list means the expression could not be fully parsed, so an
+empty `matches` list proves nothing.
+
+#### Exit codes for `match`
+
+- `0` — ran successfully, whether or not anything matched
+- `1` — empty input, or no input on stdin within 5 seconds
+- `2` — bad arguments, a missing or invalid rules file (the message names the file and the
+  offending rule), or an internal error
+
+A caller cannot rely on the exit code alone to detect an old binary. Versions before this
+mode parsed `sys.argv` by hand and ignored anything they did not recognize, so
+`bash-classify match --rules f.yaml` on such a binary classifies stdin and exits `0`,
+printing an ordinary classification document with no `matches` key. The check that works is
+the output shape: require a `matches` key, and treat a non-zero exit, unparseable output or
+a missing `matches` key alike as "cannot answer" — fall back rather than reading it as
+"nothing matched".
+
 ### Exit codes
 
 - `0` — successfully classified
-- `1` — parse error (invalid bash syntax)
+- `1` — empty input, or no input arrived on stdin within 5 seconds
 - `2` — internal error
 
+A bash syntax error does **not** change the exit code. The parse is best-effort: the tool still exits `0`, records the
+problem in `parse_warnings`, and returns whatever commands it could extract from the partial parse. Consumers rely on
+this — check `parse_warnings` to decide whether the `commands` list can be trusted, not the exit code.
+
+`match` mode has its own, slightly different set — see [Exit codes for `match`](#exit-codes-for-match) above.
+
 ### Classification levels
 
 | Level | Meaning |
@@ -299,7 +377,7 @@ The parser walks the CST and extracts a list of `CommandInvocation` objects, eac
 | Command substitution `$(cmd)` | Inner command extracted recursively |
 | Process substitution `<(cmd)` / `>(cmd)` | Inner command extracted recursively |
 | Subshells `(cmd)` | Inner command extracted recursively |
-| Heredocs `<<EOF` | Content captured but not parsed as commands |
+| Heredocs `<<EOF` | Body is dropped entirely — it is never parsed as commands and never appears in any `argv`; only the operator and the delimiter are recorded as a redirect. Commands written *after* the opener on the same line (`cat <<EOF \| wc -l`, `cat <<EOF && rm x`) are extracted like any other pipeline or list member — tree-sitter nests them inside the heredoc node, but they are real commands. A `;` or `&` in that position is a tree-sitter parse error: the follower cannot be recovered and a `parse_warnings` entry says so |
 | Variable assignments `X=1 cmd` | Prefix assignments stripped, `cmd` extracted |
 | Backgrounding `cmd &` | Classified as EXTERNAL_EFFECTS (side effect: background process) |
 
@@ -307,18 +385,20 @@ The parser walks the CST and extracts a list of `CommandInvocation` objects, eac
 
 | Construct | Reason |
 |---|---|
-| `eval "..."` | Arbitrary code execution, unparseable |
-| `sh -c "..."` / `bash -c "..."` | Nested shell, unparseable |
-| `source file` / `. file` | Executes external script |
+| `eval "..."` | Arbitrary code execution. The argument is still parsed and the inner command exposed, but a `min_classification: DANGEROUS` floor keeps both the inner and `eval` itself DANGEROUS |
+| `exec cmd` | Replaces the shell with `cmd`. The inner command is exposed, with the same DANGEROUS floor |
+| `source file` / `. file` | Executes external script, whose contents are never visible |
 | Unquoted variable expansion in command position (`$CMD args`) | Command identity unknown at parse time |
 
+`sh` and `bash` are **not** in this table. Their base classification is DANGEROUS, which is what a bare `sh` or `bash` gets, but `-c` is a `flag_value_is_expression` delegation with no `min_classification`: the expression is parsed, the inner commands are exposed, and the wrapper base is erased, so `sh -c "ls"` classifies READONLY.
+
 ## Command Matching Algorithm
 
 This is the core of the tool. Given an `argv` like `["kubectl", "--context=prod", "get", "pods", "-n", "kube-system"]`, the matcher must:
 
 1. **Look up the binary** (`kubectl`) in the database
 2. **Separate global options** from the rest of `argv`, using the database definition of which options are global and whether they take a value
-3. **Match the subcommand chain** from the remaining tokens (e.g. `get` → resolve to `kubectl.get`)
+3. **Match the subcommand chain** from the remaining tokens (e.g. `get` → resolve to `kubectl.get`), resolving any declared subcommand alias to its canonical name
 4. **Classify remaining options** against the matched subcommand's option definitions
 5. **Determine the final classification** based on subcommand default + any option overrides
 
@@ -371,6 +451,14 @@ The default mode. Subcommands are matched as a greedy chain through nested subco
 
 Example: `kubectl rollout status` matches `kubectl` → `rollout` → `status`, walking the tree.
 
+#### Subcommand aliases
+
+A subcommand may declare `aliases`. Every alias is another name for the same definition, so matching a word against a subcommand dictionary tries the canonical names and the aliases alike. What is reported is always the canonical name: `glab pipeline view 1000` yields `command: ["glab", "ci", "view"]` and `matched_rule: "glab.ci.view"`, while `argv` keeps `["glab", "pipeline", "view", "1000"]` — the word that was actually typed. Classification, options and `strict` behaviour are the canonical subcommand's, since it is literally the same definition.
+
+This matters to `match` mode: a rule written as `command: [glab, ci, view]` catches the aliased spelling too, without listing it.
+
+Aliases live in one namespace with their siblings. An alias that names a sibling subcommand, or that two siblings both claim, is rejected when the database file is loaded — the error names the file and the alias.
+
 #### `match_all`
 
 Each positional argument is matched independently against the **same** top-level subcommand dictionary. This is designed for build tools like Maven and Gradle where multiple goals/tasks appear as positional arguments in any order.
@@ -841,6 +929,7 @@ The `delegates_to` field defines how a command (or option like `find -exec`) han
 | `after_separator` | Everything after the `separator` token forms the inner argv. | `kubectl exec pod -- ls -la` → inner: `["ls", "-la"]` |
 | `terminated_argv` | Tokens after the flag up to `terminator` form the inner argv. `{}` tokens are stripped (they are `find` placeholders). | `find . -exec rm {} \;` → inner: `["rm"]` |
 | `flag_value_is_expression` | The value of the specified `flag` is a complete shell expression string, parsed from scratch through the bash parser (not just tokenized as argv). | `sh -c "ls \| grep foo"` → inner expression: `ls \| grep foo` (two piped commands) |
+| `args_are_expression` | Every token after the command word is joined with single spaces and the result is parsed as a complete shell expression, the way `eval` concatenates its arguments before running them. Option-looking tokens are included, because a command using this mode has no options of its own. Invocations the parser cannot recover yield no inner command. | `eval "glab mr list"` and `eval glab mr list` → inner: `["glab", "mr", "list"]` |
 
 #### Delegation fields
 
@@ -871,6 +960,14 @@ When command-level delegation resolves at least one inner command (and no option
 | `subcommand_mode` | `enum` | How subcommands are matched: `hierarchical` (default, chained tree walk) or `match_all` (each positional arg matched independently) |
 | `delegates_to` | `object` | How this command delegates execution to an inner command (see delegation modes) |
 
+#### Subcommand level
+
+A subcommand entry takes the same fields as the command level, minus `command` and `global_options` — its name is the key it is filed under — plus:
+
+| Field | Type | Description |
+|---|---|---|
+| `aliases` | `list[str]` | Alternative names for this subcommand (e.g. `pipe` and `pipeline` for `glab ci`). Each alias resolves to this same definition; the resolved `command` path and `matched_rule` name the canonical subcommand, while `argv` keeps the word that was typed. An alias that collides with a sibling subcommand, or that two siblings both claim, is a load-time error. |
+
 #### Option level
 
 | Field | Type | Description |
@@ -909,14 +1006,15 @@ Directories are reported as-is (not resolved) since variable expansion may be in
 
 ## Special-cased Commands
 
-Most delegation behavior is expressed in the database via `delegates_to`. Only shell builtins that cannot be modeled as regular commands need hardcoded handling:
+Most delegation behavior is expressed in the database via `delegates_to`. Only shell builtins that cannot be modeled as regular commands need hardcoded handling — the full set is three short lists in `matcher.py`:
 
 | Command | Special handling |
 |---|---|
 | `cd`, `pushd`, `popd` | Directory tracking; classified as `READONLY` |
-| `eval` | Always `DANGEROUS` — argument is arbitrary code, no delegation possible |
-| `source`, `.` | Always `DANGEROUS` — executes external script |
-| `exec` (builtin) | Always `DANGEROUS` — replaces the current process |
+| `[`, `[[`, `test` | Always `READONLY` — condition evaluation with no side effects |
+| `source`, `.` | Always `DANGEROUS` — executes an external script whose contents are never visible |
+
+`eval` and `exec` are **not** in that set. They are ordinary database entries (`commands/eval.yaml`, `commands/exec.yaml`) that delegate: `eval` via `args_are_expression`, `exec` via `rest_are_argv`, each with `min_classification: DANGEROUS`. So their inner command is parsed and reported in `inner_commands`, while the floor keeps both the inner and the wrapper at `DANGEROUS`/`HIGH`.
 
 Everything else (`sudo`, `env`, `xargs`, `sh -c`, `nice`, `nohup`, `timeout`, `time`, `find -exec`, `kubectl exec --`, etc.) is handled via `delegates_to` in the database — no special code needed.
 
@@ -930,7 +1028,30 @@ Python 3.12+. Dependencies:
 
 ## Output Schema
 
-The `commands` list is recursive — any command entry can contain `inner_commands` when the command delegates execution to another command (via `delegates_to` in the database).
+This is the schema of the default mode. `match` mode has its own, much smaller one:
+
+```json
+{
+  "matches": [
+    {
+      "rule": "string — the name of the rule that matched",
+      "command": ["string — the resolved command path of the invocation"],
+      "argv": ["string — the full argv of the invocation"],
+      "via": ["string — enclosing wrapper commands, outermost first; empty at top level"]
+    }
+  ],
+  "parse_warnings": ["string — non-fatal issues encountered during parsing"]
+}
+```
+
+Both keys are always present in match output, `matches` as `[]` when nothing matched and
+`parse_warnings` as `[]` on a clean parse. As in the default mode, `parse_warnings` covers
+nested expressions: a syntax error inside `bash -c "..."` or `eval "..."` surfaces here too.
+A caller must check both: a non-empty `parse_warnings` means an empty `matches` proves
+nothing, and a *missing* `matches` key means the output came from a binary that predates
+this mode.
+
+The `commands` list below is recursive — any command entry can contain `inner_commands` when the command delegates execution to another command (via `delegates_to` in the database).
 
 ```json
 {
@@ -945,6 +1066,8 @@ The `commands` list is recursive — any command entry can contain `inner_comman
       "argv": ["string — full original argv for this command"],
       "classification": "READONLY | LOCAL_EFFECTS | EXTERNAL_EFFECTS | DANGEROUS | UNKNOWN",
       "matched_rule": "string — dotted path in database, or null",
+      "options": ["string — every option present, canonical flag only, no values; always present, empty when none"],
+      "positionals": ["string — non-option tokens left after subcommand and option parsing; always present, empty when none"],
       "ignored_options": ["string — global options that were stripped"],
       "remaining_options": ["string — options that were not in database"],
       "classification_reason": "string — why this classification was chosen",
@@ -959,6 +1082,8 @@ The `commands` list is recursive — any command entry can contain `inner_comman
           "argv": ["..."],
           "classification": "...",
           "matched_rule": "...",
+          "options": ["... — same meaning as on the enclosing command"],
+          "positionals": ["... — same meaning as on the enclosing command"],
           "inner_commands": ["... — recursive, can nest further"]
         }
       ]
@@ -971,10 +1096,37 @@ The `commands` list is recursive — any command entry can contain `inner_comman
       "affects_classification": "bool"
     }
   ],
-  "parse_warnings": ["string — non-fatal issues encountered during parsing"]
+  "parse_warnings": ["string — non-fatal issues encountered during parsing. A non-empty list means the parse was best-effort and the commands list may be incomplete."]
 }
 ```
 
+`parse_warnings` covers **nested** expressions as well as the outer one. A syntax error inside
+`bash -c "..."`, `sh -c`, `zsh -c` or `eval "..."` surfaces here at any wrapper depth
+(`sudo bash -c '...'`, `find . -exec bash -c '...' \;`), and the warning text names the nested
+expression it came from, so a caller can tell which part of the command could not be read.
+Identical warnings are reported once.
+
+#### `options` and `positionals`
+
+`options` records which options an invocation actually carries, with option values stripped and each option in
+its canonical form: `--key=value` contributes `--key`, `-fvalue` contributes `-f`, and a cluster whose every
+character is declared in the database (`-wc`) contributes each character (`-w`, `-c`). Options the database does
+not model are included too — present means present. Tokens after `--` are positionals and contribute nothing.
+
+Two consequences of matching against a database that models only part of a real CLI. In a cluster whose first
+character is declared but a later one is not (`-wx` with only `-w` declared), the undeclared characters are not
+reported anywhere — not in `options`, not in `remaining_options` — so a check against `options` can miss such an
+option but can never falsely fire on one. In the other direction, an option the database does not model but that
+really takes a value has its value reported as a second option (`-e -foo` yields `-e` and `-foo`, because nothing
+says `-e` consumes the next token), so `options` errs toward over-reporting for unmodelled options. Declaring the
+option in the database fixes both.
+
+`positionals` holds the non-option tokens that remain once the subcommand chain and the options have been
+consumed, including `--` itself and everything after it.
+
+Both are always serialized, as `[]` when the command has none. Results that never reach option parsing — shell
+builtins, an unknown binary, an empty argv — carry `null` internally and serialize as `[]`.
+
 ### Recursive classification rules
 
 1. A command's `classification` is the **maximum** of:
@@ -990,14 +1142,13 @@ The `commands` list is recursive — any command entry can contain `inner_comman
 
 ## Non-goals
 
-- **Not a sandbox.** This is a classifier, not an enforcer. It does not execute or block anything.
+- **Not a sandbox.** This is a classifier, not an enforcer. It does not execute or block anything. `match` mode is no exception: it reports which declared command shapes an expression invokes, and the caller decides what to do about it.
 - **No awk/sed/perl script analysis.** These are classified as a whole command; their embedded programs are opaque. They should simply not be in the READONLY allowlist.
 - **No variable resolution.** `$DIR`, `$(cmd)` in command position → UNKNOWN. We classify what we can see statically.
-- **No alias/function resolution.** We classify the literal command name as written.
+- **No shell alias/function resolution.** We classify the literal command name as written.
 
 ## Future extensions
 
-- `--format=decision` — output only the classification string (for use in hooks)
 - `--database=/path` — custom database directory
 - `--explain` — verbose output showing the matching steps
 - Interactive database builder — run `command --help` and generate a skeleton YAML definition

{bash_classify-0.9.1 → bash_classify-0.11.0}/coding-agent-plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bash-classify-hook",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Auto-allows low-risk bash commands in Claude Code using bash-classify",
   "author": {
     "name": "Filip Prochazka"

{bash_classify-0.9.1 → bash_classify-0.11.0}/docs/classification-guidance.md

@@ -84,6 +84,25 @@ options:                            # options that affect classification
 | `subcommands` | map | -- | Nested subcommand definitions (recursive) |
 | `delegates_to` | object | -- | How the command hands off to an inner command |
 
+#### Subcommand fields
+
+A subcommand takes the same fields as the top level, minus `command`, `description` and `global_options`, plus:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `aliases` | list | Alternative names for this subcommand (e.g. `pipe` and `pipeline` for `glab ci`) |
+
+An alias is another name for the same definition, not a copy of it: `glab pipeline view` classifies exactly as `glab ci view` and is reported as `["glab", "ci", "view"]`, while `argv` keeps the word that was typed. Declare aliases only for names the tool itself accepts (`glab ci --help` lists `pipe` and `pipeline`), and never a name a sibling subcommand already uses — that is rejected when the file loads.
+
+```yaml
+subcommands:
+  ci:
+    aliases: [pipe, pipeline]
+    subcommands:
+      list:
+        classification: READONLY
+```
+
 #### Option fields
 
 | Field | Type | Description |
@@ -330,20 +349,43 @@ options:
   -c: {takes_value: true}
 ```
 
+### `args_are_expression`
+
+Every argument is joined with single spaces and the result is parsed as a complete shell expression. This is what
+`eval` does: it concatenates its arguments and runs the concatenation as shell source, so `eval ls -la` and
+`eval "ls -la"` are the same command. Unlike `flag_value_is_expression`, no flag selects the expression -- every
+token after the binary is part of it, so a command using this mode must not declare options of its own.
+
+**eval:** `eval "git push --force"` -- the string `git push --force` is parsed as a full expression, producing one
+inner command.
+
+```yaml
+command: eval
+classification: DANGEROUS
+strict: false
+delegates_to:
+  mode: args_are_expression
+  min_classification: DANGEROUS   # eval stays DANGEROUS even when the inner is READONLY
+```
+
+The `min_classification` floor is not optional here. Command-level delegation erases the wrapper's own base
+classification once it resolves an inner command, so without the floor `eval "ls"` would classify READONLY.
+
 ### Delegation fields
 
 | Field | Type | Applies to | Description |
 |-------|------|-----------|-------------|
-| `mode` | enum | all | One of the four modes above |
+| `mode` | enum | all | One of the modes above |
 | `separator` | string | `after_separator` | Token that separates wrapper args from inner args |
 | `terminator` | string | `terminated_argv` | Token that ends the inner argv |
 | `flag` | string | `flag_value_is_expression` | Which flag's value to parse as an expression |
+| `skip_leading_positionals` | integer | `rest_are_argv` | Positional tokens belonging to the wrapper itself before the inner command starts (e.g. `timeout DURATION COMMAND...` uses `1`) |
 | `strip_assignments` | boolean | `rest_are_argv` | Strip leading `KEY=VALUE` tokens before inner command |
 | `min_classification` | enum | all | Floor classification for the inner command |
 
 ### `min_classification`
 
-Forces the inner command to be classified at least at the given level. sudo uses this to ensure that even `sudo ls` is at least EXTERNAL_EFFECTS -- because running anything under elevated privileges is not a no-op.
+Forces the inner command to be classified at least at the given level. sudo uses this to ensure that even `sudo ls` is at least EXTERNAL_EFFECTS -- because running anything under elevated privileges is not a no-op. `eval` and `exec` use it the same way, with a `DANGEROUS` floor.
 
 ## 7. Special Cases
 
@@ -362,9 +404,14 @@ These cannot be modeled as database entries because they are shell builtins with
 | Builtin | Classification | Reason |
 |---------|---------------|--------|
 | `cd`, `pushd`, `popd` | READONLY | Directory navigation only |
-| `eval` | DANGEROUS | Arbitrary code execution, argument is unparseable |
-| `source`, `.` | DANGEROUS | Executes an external script |
-| `exec` (builtin) | DANGEROUS | Replaces the current process |
+| `[`, `[[`, `test` | READONLY | Condition evaluation, no side effects |
+| `source`, `.` | DANGEROUS | Executes an external script, whose contents are never visible |
+
+`eval` and `exec` used to be in this list. They are database entries now -- `commands/eval.yaml`
+delegates via `args_are_expression`, `commands/exec.yaml` via `rest_are_argv`, both with
+`min_classification: DANGEROUS`. Modelling them in YAML exposes the inner command instead of
+hiding it, and the floor is what keeps them DANGEROUS even when the inner command is READONLY.
+Reach for a hardcoded builtin only when the command's argument is genuinely not a command line.
 
 ### Path-qualified commands