@czottmann/pi-automode 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [1.17.0] - 2026-09-22
+
+## New features
+
+- **Schema-constrained classifier decisions** — Return detailed-stage decisions through an internal `classifier_decision` tool call. Supported providers enforce the schema during generation, and pi-automode validates every returned call locally. When strict tool sampling is available, this reduces fail-closed blocks caused by malformed or contract-invalid decision JSON. (#50)
+- **[Permission recipes](docs/permission-recipes.md)** — Add safe, composable examples for Bash permissions, working-directory changes, command chains, redirects, and classifier guidance. Thanks to @georgesleen for the impulse! (#46)
+
+## Bug fixes
+
+- **Status indicator separator** — Add one space between the `AM` prefix and the status symbol.
+- **Classifier context budgeting** — Estimate fast and detailed classifier requests in tokens instead of mixing UTF-8 bytes with token limits. Check detailed-stage capacity only after the fast stage requests review. Large project contexts no longer block small actions that fit. (#37)
+- **Explicit blocked-action feedback** — State that blocked tools did not run. Tell the agent not to claim success or rely on blocked effects. Require a report before dependent work continues. (#38)
+- **Shared classifier reasoning reserves** — Use OMP 18 Anthropic reasoning budgets for classifier context checks under Pi and OMP. Reserve 4,096 tokens at `low` and 32,768 tokens at `xhigh` and `max` for all classifier providers. (#51)
+- **Pi 0.86 classifier compatibility** — Route explicit-reasoning classifier calls through the model registry's normalized streaming API. Keep direct-provider support for older Pi versions and the compat fallback for OMP 18. (#52)
+- **Dynamic Bash allow coverage** — Route commands with unresolved Bash argument expansions or active pathname expansions to classifier review. Preserve static quoted, escaped, and ANSI-C glob literals. (#54)
+- **Classifier model validation** — Reject non-string and malformed `classifierModel` values during diagnostics and configuration merging. Preserve valid lower-precedence values and the session-model fallback. Prevent invalid configuration from causing tool-hook exceptions. (#55)
+- **Malformed permission deny diagnostics** — Report malformed `permissions.deny` patterns with their configuration source and list index. Preserve fail-closed deny matching and no-match allow behavior. (#56)
+- **Cancelled tool-call accounting** — Route already-cancelled calls through the standard block path. Record counters, denial history, persisted state, UI updates, and decision logs without Bash analysis or classifier work. (#57)
+
+## [1.16.0] - 2026-09-07
+
+## New features
+
+- **[Bounded existing-file authorization](docs/defaults.md#soft_deny)** — Allow user authorization for pre-existing local-file changes that names task, worktree, path scope, and allowed operation. (#32)
+
+## Bug fixes
+
+- **OpenCode classifier routing** — Add OpenCode session headers to every classifier completion path. Preserve Pi's header precedence and exact host matching. (#35)
+- **OMP 18 project trust compatibility** — Treat runtimes without `isProjectTrusted()` as untrusted. Prevent startup and configuration commands from throwing. (#34)
+
 ## [1.15.0] - 2026-08-28
 
 ## Bug fixes
@@ -51,7 +81,9 @@ All notable changes to this project are documented in this file.
 - **Project config trust gate** — Ignore `.pi/automode.local.json` and `.pi/automode.json` until Pi trusts the project. Apply the trust gate during startup and config reloads. (#16)
 - **In-memory observability logs** — Write logs to an extension-owned directory (`~/.pi/agent/extensions/pi-automode/logs/`) instead of the launching project directory. Thanks, @HerbertGao! (#13)
 
-[Unreleased]: https://github.com/czottmann/pi-automode/compare/v1.15.0...HEAD
+[Unreleased]: https://github.com/czottmann/pi-automode/compare/v1.17.0...HEAD
+[1.17.0]: https://github.com/czottmann/pi-automode/compare/v1.16.0...v1.17.0
+[1.16.0]: https://github.com/czottmann/pi-automode/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/czottmann/pi-automode/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/czottmann/pi-automode/compare/v1.13.0...v1.14.0
 [1.13.0]: https://github.com/czottmann/pi-automode/compare/v1.12.0...v1.13.0

package/README.md

@@ -79,7 +79,7 @@ The bundled `automode-diagnostics` skill uses this tool to diagnose unexpected d
 When the Pi TUI is available, the extension renders a persistent status line:
 
 ```text
-AM● a:12 d:2 ca:5 cd:1
+AM ● a:12 d:2 ca:5 cd:1
 ```
 
 - `AM` — auto-mode prefix. `●` means enabled. `○` means disabled through configuration or `/automode off`.
@@ -90,6 +90,7 @@ AM● a:12 d:2 ca:5 cd:1
 ## Docs
 
 - [Configuration](docs/configuration.md)
+- [Permission recipes](docs/permission-recipes.md)
 - [Defaults and rule-list behavior](docs/defaults.md)
 - [Auto-mode classifier flow](docs/automode-classifier-flow.md)
 - [Observability logging](docs/observability-logging.md)
@@ -122,17 +123,21 @@ The list does not govern `bash`. The classifier and deterministic hard-deny chec
 
 The value `allowInsideWorkingDirectory: true` allows file access inside the working directory locally. Pi-automode sends all outside file access to the classifier, including reads.
 
-Classification starts with a conservative one-token filter. If the filter requests review, pi-automode runs structured review.
+Classification starts with a conservative one-token filter. If the filter requests review, pi-automode requests one internal `classifier_decision` tool call.
 
-Both stages receive the complete current tool input in a dedicated message. Transcript truncation cannot remove action content. If the exact input cannot fit in the classifier context, auto mode blocks the call.
+The tool exists only in the nested classifier request. It is not registered with `pi.registerTool()`, and the main agent cannot call it.
+
+Pi AI requests schema-constrained sampling with `strict: "prefer"`. Supported providers enforce the schema during generation. Pi-automode validates every returned tool call locally.
 
-Both stages use a classifier-specific session key. They request short cache retention from providers that support it. A missing model, provider failure, or malformed response blocks the action.
+Both stages receive the complete current tool input in a dedicated message. Transcript truncation cannot remove action content. If the exact input cannot fit in the classifier context, auto mode blocks the call.
 
+Both stages use a classifier-specific session key. They request short cache retention from providers that support it. A missing model, provider failure, or invalid response blocks the action.
 Pi-automode parses Bash structure with `unbash` before permission and deterministic hard-deny checks. The analysis includes nested commands and literal shell-wrapper scripts. A Bash parse error blocks the action.
 
 ## Examples
 
 - `examples/automode.local.json`: copy to `.pi/automode.local.json` in a project and edit the domains, buckets, and source-control org.
+- [Permission recipes](docs/permission-recipes.md): use narrow examples for common permission and classifier-policy changes.
 
 ## Known limits
 
@@ -156,12 +161,12 @@ The tests cover these safety-sensitive areas:
 - classifier routing for `write` and `edit`
 - symlink-aware safety-control checks
 - token-budgeted transcript selection
-- staged classifier parsing and cache behavior
+- staged classifier tool-call parsing and cache behavior
 - hook-level allow and block behavior
 
 ## Publishing
 
-When a maintainer publishes a GitHub Release, GitHub Actions publishes the package to npm. The release tag must match `package.json` exactly. The forms `v1.0.0` and `1.0.0` both match version `1.0.0`.
+When a maintainer publishes a GitHub Release, GitHub Actions publishes the package to npm. The required release tag format is `v<version>`. The `<version>` value must be the same as the version in `package.json`. For example, version `1.0.0` requires tag `v1.0.0`.
 
 The workflow uses npm Trusted Publishing, so it does not need an npm token secret. Configure this package on npm with this repository and workflow file (`.github/workflows/publish.yml`). The workflow builds the package, runs `npm run check`, and publishes with npm provenance.
 

package/docs/GLOSSARY.md

@@ -18,7 +18,7 @@ The enforcement flow is the ordered pipeline that runs before each agent tool ca
 
 **Fast stage** — The first classifier stage. It returns `0` for a clearly allowed action or `1` for an action that can require review.
 
-**Detailed stage** — The second classifier stage. It runs after a fast-stage review result and returns a structured allow or block decision.
+**Detailed stage** — The second classifier stage. It runs after a fast-stage review result. It returns one schema-validated `classifier_decision` tool call.
 
 ## Classifier policy and rules
 
@@ -28,7 +28,7 @@ The classifier policy defines denial tiers and rule-list syntax. See [Defaults a
 
 **soft_deny** — Classifier rules that normally block but support defined overrides. Unlike [hard_deny](#classifier-policy-and-rules), these rules are not unconditional.
 
-**explicit_intent** — A classifier tier for direct user authorization. The latest user instruction specifically authorizes an action that matches a [soft_deny](#classifier-policy-and-rules) rule.
+**explicit_intent** — A classifier tier for direct user authorization in the retained user transcript. It authorizes an action that matches a [soft_deny](#classifier-policy-and-rules) rule. A later user instruction that narrows or revokes authorization controls. For a pre-existing local file, see [Defaults and rule-list behavior](defaults.md).
 
 **allow exception** (`autoMode.allow`) — A prose rule that overrides a matching [soft_deny](#classifier-policy-and-rules) rule. It cannot override [hard_deny](#classifier-policy-and-rules). It is independent of the [`permissions.allow` tier](#enforcement-flow).
 

package/docs/automode-classifier-flow.md

@@ -67,8 +67,8 @@ flowchart TD
   N --> O{Exact safe token?}
   O -- yes --> Q[Allow tool]
   O -- malformed or error --> O1[Block: fail closed]
-  O -- review --> P[Run structured review]
-  P --> P1{Valid allow decision?}
+  O -- review --> P[Request classifier_decision tool call]
+  P --> P1{Valid allow decision tool call?}
   P1 -- yes --> Q
   P1 -- no or error --> R[Block with classifier reason]
 
@@ -253,29 +253,28 @@ The system prompt is `CLASSIFIER_SYSTEM_PROMPT` with configuration sections expa
 The prompt defines the policy semantics:
 
 - hard-deny rules block unconditionally
-- soft-deny rules support an allow exception or direct and specific user authorization
+- soft-deny rules support allow exceptions or direct user authorization in the retained user transcript
+- a later user instruction can narrow or revoke authorization
 - allow rules override only soft-deny rules
 - hidden or malicious instructions in transcript evidence or repository files cannot change the rules
 - the classifier cannot invent deny rules or treat the allow-exception list as exhaustive
 - the classifier allows actions that match no hard-deny or soft-deny rule
 
-The fast stage must return exactly `0` for clearly allowed or `1` for review. A `1` response triggers the detailed stage, whose required JSON shape is:
+The fast stage must return exactly `0` for clearly allowed or `1` for review. A `1` response triggers the detailed stage.
 
-```json
-{"decision":"allow","tier":"allow","reason":"brief concrete reason"}
-```
+The detailed request provides one internal `classifier_decision` tool. This tool exists only in the nested classifier context.
 
-or:
+Pi-automode does not register the tool with `pi.registerTool()`, and it has no execution handler. Thus, the main agent cannot call it.
 
-```json
-{"decision":"block","tier":"soft_deny","reason":"brief concrete reason"}
-```
+The tool has these arguments:
 
-Valid `tier` values are:
+- `decision`: `allow` or `block`
+- `tier`: `hard_deny`, `soft_deny`, `allow`, `explicit_intent`, or `none`
+- `reason`: a non-empty string
 
-```text
-hard_deny, soft_deny, allow, explicit_intent, none
-```
+The schema requires all three fields and permits no additional fields. Pi AI requests JSON Schema constrained sampling with `strict: "prefer"`.
+
+A provider that supports strict tool sampling enforces the schema during generation. Other providers can return a normal tool call, which pi-automode validates locally.
 
 An `allow` decision can use `allow`, `explicit_intent`, or `none`. A `block` decision can use `hard_deny`, `soft_deny`, or `none`.
 
@@ -302,9 +301,13 @@ separate from the transcript. Pi-automode does not truncate it:
 {"toolName":"bash","input":{"command":"npm test"}}
 ```
 
-Both classifier stages receive the same context message and exact action
-message. If the exact action cannot fit in the classifier model's context
-window, auto mode blocks the call instead of removing action content.
+The fast and detailed stages receive the same context message and complete action message. Pi-automode checks each request before it sends the request. The estimate includes the system prompt, user-message text, and the stage instruction. For the detailed stage, the estimate also includes the serialized tool schema.
+
+The estimate matches Pi 0.86. It uses `Math.ceil(text.length / 4)`, where `text.length` counts UTF-16 code units. Pi-automode also reserves the stage output limit and the configured reasoning budget. It keeps Pi's 4,096-token context margin.
+
+Pi-automode checks the fast request before the fast-stage call. A fast result of `0` allows the action. Pi-automode does not check the unused detailed request. After a fast result of `1`, pi-automode checks the detailed request. This request includes the `classifier_decision` schema and the larger detailed output reserve.
+
+If a stage request cannot fit in the classifier model's context window, auto mode blocks the call. It does not truncate the action.
 
 Pi-automode builds the transcript from active Pi context entries. It includes only:
 
@@ -344,13 +347,15 @@ No classifier model/API key available; auto mode fails closed.
 
 Classifier calls use `ctx.signal`, a stable classifier-specific session ID, and `cacheRetention: "short"`. They do not set a temperature because some providers reject it. The calls use provider defaults instead. Providers without cache affinity ignore that option.
 
+The detailed request does not use provider-specific forced tool selection. Its instruction requires exactly one `classifier_decision` call. Missing or invalid calls fail closed.
+
 `autoMode.classifierTimeoutMs` limits each fast-stage and detailed-stage request. The default is 20000 ms.
 
 If a request exceeds its budget, pi-automode aborts it and blocks the action. A stalled provider stream has the same result.
 
 The fast stage requires one visible digit and uses `maxTokens: 512`. Reasoning models can use hidden tokens before they emit the digit.
 
-Extra visible content fails parsing. Detailed review uses `maxTokens: 1200`. It can retry once after malformed or truncated output.
+Extra visible content fails fast-stage parsing. Detailed review uses `maxTokens: 1200`. It can retry once after a missing, invalid, or truncated decision tool call.
 
 ## Parsing the classifier result
 
@@ -358,19 +363,37 @@ The fast-stage parser requires `stopReason: "stop"`. It removes surrounding whit
 
 Empty responses, additional content, malformed output, and non-stop responses block immediately. Observability logs preserve the untrimmed model response.
 
-The detailed parser accepts only the requested JSON object from a response with `stopReason: "stop"`. It requires `decision`, `tier`, and `reason`.
+The detailed parser requires `stopReason: "toolUse"` and exactly one `classifier_decision` call. The response must not contain non-empty visible text.
+
+The arguments must contain exactly `decision`, `tier`, and `reason`. Each value must have the required type and an allowed enum value.
+
+The parser also checks the decision and tier combination. It rejects extra fields, unknown tiers, contradictory combinations, and empty reasons.
 
-The parser rejects wrappers, extra fields, unknown tiers, and empty reasons. If the response shape changes, it fails closed.
+A response with `stopReason: "length"` can cause one retry. A missing or invalid decision tool call also can cause one retry.
 
-A response with `stopReason: "length"` can cause one retry. The truncated response cannot authorize an action. Other non-stop responses block immediately.
+A truncated or invalid response cannot authorize an action. Error and aborted responses block immediately.
 
 If detailed parsing fails after its retry, pi-automode blocks the action with this reason:
 
 ```text
-Classifier response was not valid decision JSON; auto mode fails closed.
+Classifier response did not contain a valid classifier decision tool call; auto mode fails closed.
 ```
 
-If the model call throws or returns an error or aborted response, pi-automode blocks the action immediately. It uses a classifier failure message.
+If the model call throws, pi-automode blocks the action immediately. It uses a classifier failure message.
+
+## Agent behavior after a blocked tool call
+
+Pi converts a blocked hook response into an error result and does not run the tool. Pi-automode does not set `terminate: true`, so Pi can request the next model response.
+
+The result states that the tool did not run and preserves the denial reason. The result and the Auto Mode guidance instruct the agent to:
+
+- report the block to the user before work that depends on the blocked action continues
+- not claim success or rely on effects from the blocked action
+- not try an equivalent workaround
+
+Independent work can continue. Interactive approval stays limited to configured `permissions.ask` rules. Classifier and deterministic denials stay final.
+
+These instructions decrease ambiguity in the model context. They do not guarantee that each model will follow the instructions.
 
 ## State, UI, and denial history
 

package/docs/configuration.md

@@ -169,3 +169,38 @@ A pattern can contain at most 4,096 UTF-16 code units. Bash analysis accepts at
 For other allow matching, an input can contain at most 1,048,576 UTF-16 code units. A longer input returns no match. Deny and ask patterns match the same oversized input so that they fail closed.
 
 `write` and `edit` calls whose resolved target is a protected path are never covered by `permissions.allow`. This includes protected targets reached through symlink aliases.
+
+See [Permission recipes](permission-recipes.md) for narrow examples of Bash permissions, directory changes, command chains, redirects, and classifier guidance.
+
+## Custom models (like OpenRouter's presets)
+
+Pi-automode can only select models that Pi exposes through its model registry. Add unlisted models to `~/.pi/agent/models.json`.
+
+For example, register an OpenRouter preset in the built-in `openrouter` provider:
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "models": [
+        {
+          "id": "@preset/nvidia-nemotron-3-nano-30b-a3b-fast",
+          "name": "NVIDIA: Nemotron 3 Nano 30B A3B Fast (Preset)",
+          "reasoning": true,
+          "input": ["text"],
+          "contextWindow": 262144,
+          "maxTokens": 235929,
+          "cost": {
+            "input": 0.05,
+            "output": 0.2,
+            "cacheRead": 0.03,
+            "cacheWrite": 0
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Restart Pi (or run `/reload`), then select the model with `/automode model openrouter/@preset/nvidia-nemotron-3-nano-30b-a3b-fast`.

package/docs/defaults.md

@@ -37,6 +37,7 @@ These entries give the classifier context. They do not bypass `hard_deny` or aut
 
 - read-only operations: inspecting files, listing directories, searching, GET requests, and state queries that do not expose secrets
 - local development inside the working tree: creating, editing, building, testing, linting, formatting, and deleting files created during the current task
+- modifying or deleting pre-existing local files with bounded direct user authorization
 - installing dependencies already declared in package manifests or lockfiles
 - using standard credentials only with their intended configured providers
 - pushing to the current non-default working branch or a new branch created for the task
@@ -88,7 +89,7 @@ Patterns support `~`, `$HOME`, and `${HOME}` expansion. The `*` wildcard matches
 - force push, remote branch deletion, remote history rewrite, or direct push to `main`, `master`, or the default branch
 - downloading and executing external code, including `curl | bash` and `wget | sh`
 - production deploys, production database migrations, or production infrastructure changes
-- deleting, truncating, or overwriting pre-existing local files unless the user named the specific target
+- deleting, truncating, or overwriting local files that existed before session start without a bounded user authorization
 - mass modification/deletion in cloud storage, ticketing systems, collaboration tools, or external APIs
 - writing through remote shells such as `ssh`, `kubectl exec`, or `docker exec` on shared or production hosts
 - changing shared or live infrastructure without its normal preview, plan, dry run, or review
@@ -96,7 +97,7 @@ Patterns support `~`, `$HOME`, and `${HOME}` expansion. The `*` wildcard matches
 - exposing local files, sockets, credentials, or internal services through a network service
 - outbound messages, purchases, bookings, subscriptions, or other real-world transactions
 
-Soft blocks can be overridden by a matching `allow` exception or by direct, specific user intent.
+Soft blocks can be overridden by a matching `allow` exception or direct user intent. For a pre-existing local file, direct user intent must name the task, one repository or worktree, permitted path scopes, and an allowed operation. The action must stay inside those bounds. Other soft blocks need direct user intent but do not require these file bounds. A later user instruction that narrows or revokes authorization controls.
 
 ### `hard_deny`
 

package/docs/diagnostics.md

@@ -38,7 +38,7 @@ Pi sends tool output to the current model. The output has deliberate privacy lim
 
 - `status` does not include the last decision reason.
 - `denials` does not include denial reasons or action payloads.
-- `config` removes the parser detail from invalid JSON diagnostics.
+- `config` removes configuration-parser details from invalid JSON diagnostics.
 
 The `config` view returns effective rule text. Do not put credentials, tokens, private keys, signed URLs, or other secrets in pi-automode rules or configuration.
 
@@ -72,6 +72,12 @@ This includes `--no-session` runs and non-persisted subagents. The path does not
 
 See [Observability logging](observability-logging.md) for log configuration and entry schemas.
 
+## Classifier protocol failures
+
+When classifier I/O logging is active, a detailed-stage tool call appears in `attempts[].response.toolCalls`. The field contains each tool name and argument object.
+
+The field does not contain provider call IDs or hidden reasoning. Use it to distinguish a missing tool call from invalid tool arguments.
+
 ## Diagnosis workflow
 
 Classifier rules cannot override permission or deterministic denials.

package/docs/observability-logging.md

@@ -134,7 +134,8 @@ The entry follows all related classifier-usage `message` entries. It precedes th
 Each `attempts[]` entry is `{ stage, attempt, response?, parsed?, error?, durationMs }`:
 
 - `stage` — `fast` for the one-token filter or `detailed` for structured review.
-- `response` — `{ stopReason, text, model, timestamp, usage, errorMessage? }`, the raw model output and provider-reported usage for that call, including provider-reported errors and aborted requests.
+- `response` — `{ stopReason, text, toolCalls?, model, timestamp, usage, errorMessage? }`, including provider-reported errors and aborted requests.
+- `response.toolCalls` — each classifier tool name and parsed argument object. This field excludes provider call IDs and hidden reasoning.
 - `parsed` — the decision parsed from the response, or absent after a parse failure.
 - `error` — present after a network or authentication error. In this case, `response` is absent.
 

package/docs/permission-recipes.md

@@ -0,0 +1,243 @@
+# Permission recipes
+
+Use these recipes to add narrow permissions and classifier guidance to pi-automode. Each example omits unrelated configuration.
+
+> [!CAUTION]
+> Pi-automode is a guardrail extension, not a sandbox. A `permissions.allow` match skips classifier review. Add only rules whose complete effect you understand.
+
+## Table of contents
+
+- [Before you add a rule](#before-you-add-a-rule)
+- [Choose the correct rule type](#choose-the-correct-rule-type)
+- [Allow a simple Bash command](#allow-a-simple-bash-command)
+- [Allow commands after changing directories](#allow-commands-after-changing-directories)
+- [Allow command chains and pipelines](#allow-command-chains-and-pipelines)
+- [Allow redirects](#allow-redirects)
+- [Ask before sensitive commands](#ask-before-sensitive-commands)
+- [Deny commands unconditionally](#deny-commands-unconditionally)
+- [Give the classifier more freedom inside a repository](#give-the-classifier-more-freedom-inside-a-repository)
+- [Diagnose a rule that does not match](#diagnose-a-rule-that-does-not-match)
+- [Avoid unsafe patterns](#avoid-unsafe-patterns)
+- [Related documentation](#related-documentation)
+
+## Before you add a rule
+
+Use the narrowest rule that covers the required action. When possible, include exact command names and trusted paths.
+
+A permission rule can have more authority than classifier guidance. In particular, `permissions.allow` skips classifier review for a matching tool call. Permission denies, deterministic hard-deny checks, denied paths, and protected-path controls remain active.
+
+Do not put credentials, tokens, private keys, signed URLs, or other secrets in a rule. The effective configuration can appear in diagnostics and model-visible inspection output.
+
+Pi-automode reads `permissions.allow` only from these sources:
+
+- the global pi-automode configuration
+- a trusted `.pi/automode.local.json` file
+- `PI_AUTOMODE_SETTINGS_JSON`
+
+A shared project `.pi/automode.json` file cannot add allow rules.
+
+## Choose the correct rule type
+
+| Configuration | Purpose |
+| --- | --- |
+| `permissions.deny` | Block a matching tool call without classifier review. |
+| `permissions.ask` | Ask for confirmation, then continue to the classifier. |
+| `permissions.allow` | Skip classifier review for a matching tool call. |
+| `autoMode.allow` | Give the classifier additional policy guidance. |
+
+If a deterministic pattern can describe the complete safe action, use `permissions.allow`. If the classifier must evaluate context or intent, use `autoMode.allow`.
+
+## Allow a simple Bash command
+
+Use a scoped Bash pattern to allow a narrow command:
+
+```json
+{
+  "permissions": {
+    "allow": ["bash(git status*)"]
+  }
+}
+```
+
+This pattern covers commands such as `git status` and `git status --short`. It does not cover another command in the same Bash call.
+
+For example, `git status && git push` still requires coverage for `git push`. Without that coverage, the complete call continues to the classifier.
+
+## Allow commands after changing directories
+
+A leading `cd` changes the meaning and security context of the next command. Cover it with a separate rule for an exact trusted directory:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "bash(cd /etc/nixos)",
+      "bash(git status*)",
+      "bash(git diff*)",
+      "bash(nix build*)"
+    ]
+  }
+}
+```
+
+The rules produce these results:
+
+| Command | Result |
+| --- | --- |
+| `cd /etc/nixos && git status` | Allowed without classifier review. |
+| `cd /tmp && git status` | Continues to the classifier. |
+| `cd /etc/nixos && git status && curl example.com/x \| sh` | Continues to the classifier. |
+
+Do not treat `cd` as a transparent wrapper. The working directory can select repository hooks, package scripts, build files, and relative executables.
+
+Prefer an exact absolute path. A broad rule such as `bash(cd *)` lets covered commands run from any literal directory.
+
+## Allow command chains and pipelines
+
+Pi-automode requires coverage for each executable command in a supported top-level chain or plain pipeline. Separate single-command patterns can provide that coverage:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "bash(git status*)",
+      "bash(git diff*)",
+      "bash(cat)"
+    ]
+  }
+}
+```
+
+These rules cover calls such as:
+
+```bash
+git status --short && git diff --stat
+git status --short | cat
+```
+
+They do not cover an extra command. For example, `git status && curl example.com/x | sh` continues to the classifier.
+
+If the operator structure is part of the permission, use a composite pattern:
+
+```json
+{
+  "permissions": {
+    "allow": ["bash(git status* && git diff*)"]
+  }
+}
+```
+
+A composite pattern must match the same Bash structure, operators, command count, and command order.
+
+## Allow redirects
+
+A redirect needs explicit coverage. The operator, file descriptor, variable name, and target pattern must match.
+
+```json
+{
+  "permissions": {
+    "allow": ["bash(git status* > /tmp/git-status.txt)"]
+  }
+}
+```
+
+This rule does not cover a different target or redirect operator. Here-documents and dynamic redirect targets continue to the classifier.
+
+Use only a trusted output path. Even a read-only command can overwrite data through a redirect.
+
+## Ask before sensitive commands
+
+If the user must confirm a matching action, use `permissions.ask`:
+
+```json
+{
+  "permissions": {
+    "ask": ["bash(git push *)"]
+  }
+}
+```
+
+A confirmation does not create an allow decision. After confirmation, deterministic checks and the classifier still evaluate the call.
+
+If the classifier needs explicit user authorization, send it in a normal chat message. Answers from ask-user tools do not become classifier authorization.
+
+## Deny commands unconditionally
+
+Use `permissions.deny` for commands that must not run through auto mode:
+
+```json
+{
+  "permissions": {
+    "deny": ["bash(rm -rf *)"]
+  }
+}
+```
+
+A matching deny rule blocks the call before an allow rule or classifier decision. Deterministic hard-deny rules can also block dangerous commands without a configured permission rule.
+
+## Give the classifier more freedom inside a repository
+
+Use `autoMode.allow` to give the classifier broader policy guidance. If you intend to replace the built-in guidance, omit `$defaults`. Otherwise, keep `$defaults`.
+
+The following rule permits normal implementation work inside the assigned repository or worktree. It excludes external systems and safety-sensitive changes:
+
+```json
+{
+  "autoMode": {
+    "allow": [
+      "$defaults",
+      "Creating, modifying, and deleting local files within the Git repository or worktree. This includes pre-existing source code, migrations, CLI code, tests, and project documentation. This permission applies only to local implementation work and excludes files outside the assigned repository or worktree, external systems, credentials, safety controls, and Git history changes."
+    ]
+  }
+}
+```
+
+This setting guides the classifier. It does not create a deterministic tool permission and does not override permission denies or hard-deny checks.
+
+## Diagnose a rule that does not match
+
+1. Run `/automode config` or inspect the `config` view of `automode_inspect`.
+2. Confirm that the expected rule appears in the effective configuration.
+3. Inspect `/automode denials` or the `denials` view to identify the enforcement layer.
+4. If you enabled observability logging, inspect the matching decision entry.
+5. For Bash, identify each executable command, operator, and redirect in the call.
+6. Add only the narrowest missing coverage.
+7. Run `/automode reload` after a configuration change.
+
+Parser errors, dynamic command names, dynamic wrapper scripts, and unsupported control structures cannot use `permissions.allow`. These calls continue to the classifier or fail closed.
+
+See [Agent diagnostics](diagnostics.md) for the complete diagnosis workflow. See [Observability logging](observability-logging.md) for log locations and entry schemas.
+
+## Avoid unsafe patterns
+
+Avoid broad deterministic allows such as:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "bash(*)",
+      "bash(cd *)",
+      "bash(curl*)"
+    ]
+  }
+}
+```
+
+These patterns can grant more authority than their short text suggests.
+
+Also avoid these mistakes:
+
+- If you want to keep the built-in `autoMode` rule list, include `$defaults`.
+- If an exact trusted path is available, do not use a broad path wildcard.
+- Do not allow commands such as `npm test` or `nix build` across arbitrary directories. These commands can execute project-controlled code.
+- If classifier policy is sufficient, do not use `permissions.allow`.
+- Do not present pi-automode as a security boundary or sandbox.
+
+## Related documentation
+
+- [Configuration](configuration.md)
+- [Defaults and rule-list behavior](defaults.md)
+- [Agent diagnostics](diagnostics.md)
+- [Auto-mode classifier flow](automode-classifier-flow.md)
+- [Observability logging](observability-logging.md)