@herbertgao/pi-extensions 2026.9.5 → 2026.9.7

package/node_modules/@czottmann/pi-automode/docs/automode-classifier-flow.md

@@ -1,428 +0,0 @@
-# Auto-mode classifier flow
-
-This document describes how `pi-automode` decides whether an agent tool call can run. The classifier is only one part of the flow. Several checks happen before any model call, and some tool calls never reach the classifier at all.
-
-## Short version
-
-For each Pi `tool_call` event, the extension does this:
-
-1. Load the effective auto-mode configuration for the current session.
-2. If auto mode is disabled, ignore the call.
-3. If the agent turn was cancelled, block the call.
-4. Block a matching `permissions.deny` rule.
-5. If a `permissions.ask` rule matches, ask the user.
-6. If the user declines or no UI is available, block the call.
-7. Mark an accepted ask call for required classifier review.
-8. Run deterministic hard-deny checks.
-9. If no accepted ask rule requires review, let the extension-owned `automode_inspect` tool run locally.
-10. Run path-deny checks, including recursive search scopes and symlink aliases.
-11. If an ask rule was accepted, skip all deterministic allow tiers.
-12. Otherwise, apply the inside-working-directory, `permissions.allow`, and read-only tiers in that order.
-13. Send every remaining action through a one-token conservative filter.
-14. If the filter requests review, run structured classifier review.
-15. Persist state and update the UI status and denial history.
-
-The default posture is fail-closed. If model resolution, authentication, a classifier call, or response parsing fails, pi-automode blocks the action.
-
-## Diagram
-
-```mermaid
-flowchart TD
-  A[Pi emits tool_call] --> B[Build effective config]
-  B --> C{Auto-mode enabled?}
-  C -- no --> Z[Let tool run]
-  C -- yes --> D{Agent turn cancelled?}
-  D -- yes --> X[Block: cancelled]
-  D -- no --> F{Matches permissions.deny?}
-  F -- yes --> F1[Block locally]
-  F -- no --> G{Matches permissions.ask?}
-
-  G -- yes --> H{UI available?}
-  H -- no --> H1[Block locally]
-  H -- yes --> I[Ask user]
-  I -- declined --> I1[Block locally]
-  I -- accepted --> J[Require classifier review]
-  G -- no --> J0[Continue normally]
-
-  J --> K{Deterministic hard-deny?}
-  J0 --> K
-  K -- yes --> K1[Block locally]
-  K -- no --> E{Extension-owned automode_inspect?}
-  E -- yes --> E2{Classifier required by ask?}
-  E2 -- no --> E1[Allow without state or log changes]
-  E2 -- yes --> N[Run one-token filter]
-  E -- no --> K2{Path denied or recursive scope unsafe?}
-
-  K2 -- yes --> K1
-  K2 -- no --> K3{Classifier required by ask?}
-  K3 -- yes --> N
-  K3 -- no --> K4{Inside-CWD allow tier?}
-  K4 -- yes, non-protected --> L1[Allow locally]
-  K4 -- no or protected --> K5{Matches permissions.allow?}
-  K5 -- yes, non-protected --> L1
-  K5 -- no or protected --> L{Read-only built-in fast path?}
-  L -- yes --> L1
-  L -- no --> N
-
-  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?}
-  P1 -- yes --> Q
-  P1 -- no or error --> R[Block with classifier reason]
-
-  X --> S[Persist state and update UI]
-  F1 --> S
-  H1 --> S
-  I1 --> S
-  K1 --> S
-  O1 --> S
-  R --> S
-  L1 --> T[Persist allow state and update UI]
-  Q --> T
-```
-
-## Configuration loading
-
-Pi-automode loads global and inline configuration during extension initialization. It loads project configuration on `session_start`. `/automode reload` reloads the effective configuration.
-
-The effective configuration combines these sources:
-
-- `~/.pi/agent/extensions/pi-automode/config.json`
-- `.pi/automode.local.json` for trusted projects
-- `PI_AUTOMODE_SETTINGS_JSON`
-- shared `.pi/automode.json` for trusted projects, but only for `permissions.deny` and `permissions.ask`
-
-Before `session_start`, pi-automode loads only global and inline configuration. If `ctx.isProjectTrusted()` returns `true`, it reads project configuration during `session_start` and `/automode reload`.
-
-For an untrusted project, pi-automode ignores both project files. `/automode config` reports each ignored file that exists.
-
-Shared `.pi/automode.json` cannot change `autoMode` rules or add `permissions.allow`. A checked-in file must not reduce classifier coverage. If shared configuration contains `permissions.allow`, `/automode config` reports a diagnostic.
-
-Deny and ask patterns use this source order: global, shared project, project-local, inline. Allow patterns use this source order: global, project-local, inline.
-
-To disable pi-automode for the current project, set `autoMode.enabled` to `false` in `.pi/automode.local.json`:
-
-```json
-{
-  "autoMode": {
-    "enabled": false
-  }
-}
-```
-
-This affects only the trusted project-local configuration. Shared project `.pi/automode.json` cannot disable auto mode.
-
-List fields such as `allow`, `soft_deny`, `hard_deny`, `environment`, and `protectedPaths` support `$defaults`. Omitting `$defaults` replaces the built-ins for that section only. See [Defaults and rule-list behavior](defaults.md).
-
-## Context captured before classification
-
-On `before_agent_start`, the extension appends `AUTO_MODE_GUIDANCE` to the system prompt. This text states that auto mode is active. It also prohibits bypasses or weaker controls.
-
-The same hook extracts context files from Pi's `systemPromptOptions.contextFiles`. The extracted text becomes `loadedContext`. Pi-automode formats each context file as follows:
-
-```text
-# path/to/file
-<truncated content>
-```
-
-Pi-automode truncates the middle of each file to 4000 UTF-16 code units.
-
-## Local checks before the classifier
-
-### `permissions.deny`
-
-Pi-automode checks `permissions.deny` first. A matching rule blocks immediately. Pi-automode does not call the classifier.
-
-Example rule:
-
-```json
-"bash(git push --force*)"
-```
-
-Permission patterns apply to a Pi tool and its primary argument. `bash` uses `input.command`. `read`, `write`, `edit`, `find`, and `ls` use the normalized resolved `input.path`.
-
-`grep` uses `input.pattern`. If the applicable argument is absent, the matcher uses the serialized input object.
-
-The `*` wildcard matches zero or more characters, including newlines and path separators. Matching is case-insensitive and uses a bounded linear-time algorithm. A configured pattern can contain at most 4,096 UTF-16 code units. A primary argument can contain at most 1,048,576 UTF-16 code units. A longer argument conservatively matches a scoped deny or ask rule.
-
-### `permissions.ask`
-
-`permissions.ask` runs after `permissions.deny`.
-
-If a rule matches without an available UI, pi-automode blocks the action. If a UI is available, pi-automode shows a confirmation dialog.
-
-The dialog contains the matched rule and the action summary.
-
-Approving that dialog does not run the tool directly. Deterministic denial checks continue first. After these checks pass, the classifier reviews the call. The call cannot use `allowInsideWorkingDirectory`, `permissions.allow`, or the read-only fast path.
-
-### `permissions.allow`
-
-`permissions.allow` is a deterministic allow tier. It uses the same patterns as `deny` and `ask`. Thus, it covers built-in, MCP, and extension tools:
-
-```json
-"permissions": { "allow": ["bash(git status*)", "example-extension-tool"] }
-```
-
-The matcher understands primary arguments for `bash`, the file tools, and `grep`. It uses the serialized input object for other tools.
-
-Use a bare tool name for an MCP or extension tool. An argument pattern compares against the serialized input object.
-
-A match skips only the classifier call. The tier cannot override permission denials, hard-deny checks, path denials, or protected-path controls. An accepted ask rule also disables this tier for the current call.
-
-Pi-automode reads allow entries from global, trusted project-local, and inline configuration. It ignores allow entries in shared project configuration and reports a diagnostic.
-
-A configured pattern can contain at most 4,096 UTF-16 code units. An input can contain at most 1,048,576 UTF-16 code units for allow matching. A longer input returns no match and continues to classifier review. Deny and ask matching uses the opposite overflow result so these rules fail closed.
-
-The default list is empty. Thus, behavior does not change without explicit user configuration. Decision logs use `kind: permissions.allow`.
-
-`/automode status` reports the rule count. `/automode config` shows the resolved patterns.
-
-[ADR-001](adr/ADR-001-permission-precedence-and-trust-boundaries.md) records the precedence and trust-boundary rationale.
-
-### Deterministic hard-deny checks
-
-Some actions are too risky to leave to the classifier. Pi-automode blocks these actions before classifier review.
-
-Current deterministic blocks include these actions:
-
-- writes to shell profile files
-- writes to `~/.ssh/authorized_keys`
-- edits to auto-mode or Pi permission safety-control files
-- weaker TLS or certificate verification
-- persistence changes such as cron jobs, launch agents, and system service enablement
-- dangerous recursive deletes of root, home, or system paths
-- selected system or SSH permission mutations
-
-The `bash` checks use the `unbash` abstract syntax tree. They inspect chains, pipelines, compound commands, substitutions, redirects, and literal shell-wrapper scripts.
-
-Recursive-delete checks hard-deny `/`, the user home root, and top-level system roots. They exempt subpaths of the user home because these paths contain user data.
-
-Some distributions store `HOME` under `/var`. Fedora Silverblue uses `/var/home/<user>`, for example. Pi-automode does not treat `rm -rf` on this home subtree as a system-path delete. It still blocks `rm -rf ~`.
-
-### Read-only bypass and the path gate
-
-Pi-automode allows read-only built-in tools after the prior checks and the `permissions.allow` tier. `classifyReadOnlyTools: true` sends them to the classifier instead.
-
-The read-only tool set is:
-
-```text
-read, grep, find, ls
-```
-
-Pi-automode still allows reads to protected paths.
-
-Two optional fields change the deterministic tier. `deniedPaths` blocks matching file-tool paths before classifier review or an allow tier.
-
-`allowInsideWorkingDirectory: true` allows file access inside the working directory without classifier review. This access includes writes and edits. Pi-automode sends all out-of-tree file access to the classifier, including reads.
-
-Protected in-tree writes and edits do not use the local allow tier. They still reach the classifier.
-
-By default, both fields are off and `permissions.allow` is empty. Thus, every write and edit reaches the classifier.
-
-## Protected paths
-
-The protected-path configuration identifies safety-sensitive targets. Examples include `.git`, `.pi`, editor directories, shell profiles, package-manager files, and hook files.
-
-By default, every write and edit reaches the classifier. Thus, no direct-write allow path can bypass classifier policy.
-
-Two optional features add a direct-write path for non-protected targets. `allowInsideWorkingDirectory: true` allows non-protected in-tree writes. A matching `permissions.allow` pattern has the same result.
-
-Both features keep protected targets on the classifier route. `deniedPaths` can block these targets before classifier review.
-
-Deterministic safety-control checks still resolve paths canonically before classification. This catches writes through symlinks to auto-mode controls, shell profiles, and SSH authorization files without relying on the model.
-
-## What is sent to the classifier
-
-The classifier call is made by `defaultClassifyAction`.
-
-The model receives a stable system policy, a shared context message, and a final stage instruction. Both stages use the same shared prefix. Thus, supported providers can reuse it.
-
-To inspect each classifier request and raw response, enable `autoMode.log.classifierIo`. See [Observability logging](observability-logging.md).
-
-### System prompt
-
-The system prompt is `CLASSIFIER_SYSTEM_PROMPT` with configuration sections expanded into bullet lists:
-
-- trusted environment
-- allow exceptions
-- soft-deny rules
-- hard-deny rules
-
-The prompt defines the policy semantics:
-
-- hard-deny rules block unconditionally
-- 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:
-
-```json
-{"decision":"allow","tier":"allow","reason":"brief concrete reason"}
-```
-
-or:
-
-```json
-{"decision":"block","tier":"soft_deny","reason":"brief concrete reason"}
-```
-
-Valid `tier` values are:
-
-```text
-hard_deny, soft_deny, allow, explicit_intent, none
-```
-
-An `allow` decision can use `allow`, `explicit_intent`, or `none`. A `block` decision can use `hard_deny`, `soft_deny`, or `none`.
-
-If an exception or user instruction authorizes a soft-denied action, the tier must state why the classifier allows it. It cannot remain `soft_deny`.
-
-### User messages
-
-The first user message contains shared context:
-
-```text
-<loaded-project-instructions>
-${loadedContext || "(none)"}
-</loaded-project-instructions>
-
-<classifier-transcript>
-${buildClassifierTranscript(...) || "(none)"}
-</classifier-transcript>
-```
-
-The next user message contains the complete current action as JSON. It is
-separate from the transcript. Pi-automode does not truncate it:
-
-```json
-{"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.
-
-Pi-automode builds the transcript from active Pi context entries. It includes only:
-
-- user text
-- assistant tool-call names and payloads
-
-Pi-automode excludes assistant prose, hidden reasoning, and tool results. User evidence and tool-call evidence have separate approximate-token budgets. Both budgets default to 4000.
-
-The selector keeps the first and latest user messages. It fills the remaining budget from the newest eligible entries. It renders retained evidence in chronological order. It also marks omitted or truncated evidence.
-
-Transcript truncation does not change the dedicated current-action message.
-
-## Classifier model resolution
-
-Pi-automode selects the classifier model in this order:
-
-1. `autoMode.classifierModel` from configuration
-2. the current Pi session model.
-
-`/automode model provider/model-id` and the interactive model picker save `autoMode.classifierModel` to `~/.pi/agent/extensions/pi-automode/config.json`. Project-local `.pi/automode.local.json` can still override that global choice.
-
-`autoMode.classifierReasoningLevel` can request `low`, `medium`, `high`, `xhigh`, or `max` reasoning for both stages.
-
-When the key is absent, classifier calls omit a reasoning preference. The server then selects its default. When the key is present, classifier calls use the normalized Pi AI path.
-
-Pi AI clamps the request to the nearest supported level. Models without reasoning support resolve to `off`. They remain on the normalized path without a reasoning preference.
-
-Reasoning does not increase the stage token limits. A high level can use all stage tokens before it produces valid visible output. Truncation fails closed.
-
-The fast-stage limit is 512 tokens. The detailed-stage limit is 1200 tokens. `low` matches the reasoning effort of Codex Auto Review.
-
-The extension asks Pi's model registry for API credentials. If the model cannot be found or credentials are unavailable, classification returns a blocking decision:
-
-```text
-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.
-
-`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.
-
-## Parsing the classifier result
-
-The fast-stage parser requires `stopReason: "stop"`. It removes surrounding whitespace and accepts only `0` or `1`.
-
-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 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. The truncated response cannot authorize an action. Other non-stop 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.
-```
-
-If the model call throws or returns an error or aborted response, pi-automode blocks the action immediately. It uses a classifier failure message.
-
-## State, UI, and denial history
-
-Every checked action increments `checkedActions`.
-
-Allowed actions store:
-
-- `lastDecision: "allow"`
-- `lastReason`
-
-Blocked actions also increment `blockedActions` and add a denial record. Each denial record contains:
-
-- timestamp
-- tool name
-- reason
-- action summary
-- denial kind
-
-Recent denial history has a limit of 12 entries. Pi-automode persists state with `pi.appendEntry("pi-automode-state", state)`. Thus, state survives reloads and session restoration.
-
-When UI is available, the extension updates the footer status and shows a warning notification for blocked actions.
-
-## Agent inspection tool
-
-`automode_inspect` exposes `status`, `config`, `defaults`, and `denials` views to the agent. The extension verifies the source of the registered tool before it applies the exemption.
-
-A tool from another extension with the same name still uses normal enforcement. Every view is read-only. After local checks pass, the hook returns before classifier routing and state updates.
-
-Pi sends tool output to the model. Therefore, the `status` and `denials` views omit denial reasons and action summaries.
-
-The `config` view contains effective rule text. Do not store secrets in automode rules.
-
-No state-changing command has a tool equivalent. The user must run `/automode on`, `/automode off`, `/automode reload`, `/automode reset`, and `/automode model` directly. See [Agent diagnostics](diagnostics.md) for the inspection contract, privacy limits, and diagnosis workflow.
-
-## Command interactions
-
-The classifier flow can be inspected or changed through slash commands:
-
-```text
-/automode status
-/automode on
-/automode off
-/automode reload
-/automode reset
-/automode defaults
-/automode config
-/automode denials
-/automode model
-/automode model provider/model-id
-```
-
-`/auto-mode` is an alias.
-
-`/automode off` disables the whole flow for the current session. `/automode on` re-enables it. `/automode model` saves the classifier model to `~/.pi/agent/extensions/pi-automode/config.json`.

package/node_modules/@czottmann/pi-automode/docs/configuration.md

@@ -1,171 +0,0 @@
-# Configuration
-
-The extension follows the documented Claude Code configuration model where Pi supports it.
-
-It reads `autoMode` only from Pi-owned configuration sources:
-
-- `~/.pi/agent/extensions/pi-automode/config.json`
-- `.pi/automode.local.json` for trusted projects
-- `PI_AUTOMODE_SETTINGS_JSON`
-
-At startup, pi-automode moves a legacy `~/.pi/agent/automode.json` file to the new global path. If both files exist, it uses the new file and reports the conflict. If migration fails, it uses the legacy file for that session and reports the error.
-
-It does not read project configuration until Pi trusts the project. For an untrusted project, it ignores `.pi/automode.local.json` and `.pi/automode.json`. `/automode config` reports each ignored file that exists.
-
-Shared project `.pi/automode.json` cannot weaken auto mode. For a trusted project, it can add `permissions.deny` and `permissions.ask` rules.
-
-The shared file cannot set `autoMode` or add `permissions.allow` rules. If the file contains `permissions.allow`, `/automode config` reports a diagnostic.
-
-To disable pi-automode for the current project, create or edit `.pi/automode.local.json`:
-
-```json
-{
-  "autoMode": {
-    "enabled": false
-  }
-}
-```
-
-This file is project-local. Pi reads it only after project trust. Do not commit this file. Shared project `.pi/automode.json` cannot disable auto mode.
-
-Set a global default classifier model in `~/.pi/agent/extensions/pi-automode/config.json`. For a trusted project, override it in `.pi/automode.local.json`.
-
-`classifierReasoningLevel` requests `low`, `medium`, `high`, `xhigh`, or `max` reasoning for both classifier stages. If the key is absent, pi-automode sends no reasoning preference. The server then selects the level.
-
-Pi AI clamps an unsupported value to the nearest level that the selected model supports. A model without reasoning support resolves to `off`. `low` matches the reasoning effort of Codex Auto Review.
-
-Higher levels can use all 512 or 1200 stage tokens before they produce visible output. In this case, the classifier fails closed. If truncation occurs before the required `0` or `1` digit, increase `fastClassifierMaxTokens`. The default is 512, and the minimum is 16.
-
-`classifierTimeoutMs` limits each classifier request in milliseconds. The default is 20000, and the minimum is 1000. The fast and detailed stages have separate budgets.
-
-If a request stalls or exceeds its budget, pi-automode aborts it. Then auto mode fails closed and blocks the action.
-
-`allowInsideWorkingDirectory` adds a deterministic allow tier for the file tools. The default value is `false`. The file tools are `read`, `write`, `edit`, `grep`, `find`, and `ls`.
-
-The value `allowInsideWorkingDirectory: true` allows access to paths inside the working directory without classifier review. Pi-automode sends access to outside paths to the classifier. This rule also applies to read calls.
-
-This tier takes precedence over `classifyReadOnlyTools`. If both configuration fields are enabled, pi-automode still allows in-tree file access locally. `classifyReadOnlyTools: true` does not change this behavior.
-
-Protected in-tree targets do not use this allow tier. Writes and edits to `.git/hooks`, `.pi` controls, shell profiles, and configuration files still reach the classifier.
-
-`deniedPaths` is a list of path glob patterns. The default list is `[]`. A matching pattern blocks a file-tool call before classifier review or an allow tier.
-
-Patterns support `~`, `$HOME`, and `${HOME}` expansion. The `*` wildcard matches all characters, including `/`. Thus, `**/id_rsa` matches a private key at any depth.
-
-Each pattern can contain at most 4,096 UTF-16 code units. Pi-automode matches the typed path and its symlink-resolved form. It also resolves the fixed path prefix of each pattern. Thus, a symlink alias cannot bypass a denied target.
-
-If a recursive `grep` or `find` scope can contain a denied path, pi-automode blocks the call. A broad pattern such as `*.env` blocks these tools for every directory scope.
-
-A matching path blocks the call without classifier review or an override. The list applies only to file tools. The classifier governs `bash` path access. Both keys use the normal scalar and array precedence.
-
-`allowInsideWorkingDirectory` uses scalar precedence: global, then project-local, then `PI_AUTOMODE_SETTINGS_JSON`. `deniedPaths` entries accumulate across these configuration sources.
-
-Shared project `.pi/automode.json` cannot set either field. Omitting either field at a higher-precedence source does not clear a lower-source value.
-
-Example:
-
-```json
-{
-  "autoMode": {
-    "classifierModel": "provider/model-id",
-    "classifierReasoningLevel": "low",
-    "classifyReadOnlyTools": false,
-    "fastClassifierMaxTokens": 512,
-    "classifierTimeoutMs": 20000,
-    "allowInsideWorkingDirectory": false,
-    "deniedPaths": [],
-    "maxUserTranscriptTokens": 4000,
-    "maxToolTranscriptTokens": 4000,
-    "environment": [
-      "$defaults",
-      "Source control: github.example.com/acme-corp and all repos under it",
-      "Trusted internal domains: *.corp.example.com, git.example.com",
-      "Trusted cloud buckets: s3://acme-dev-artifacts, gs://acme-ci-cache",
-      "Key internal services: staging deploy API at deploy.corp.example.com"
-    ],
-    "allow": ["$defaults"],
-    "protectedPaths": ["$defaults"],
-    "soft_deny": ["$defaults"],
-    "hard_deny": [
-      "$defaults",
-      "Never send repository contents to third-party code-review APIs"
-    ]
-  },
-  "permissions": {
-    "deny": ["bash(rm -rf *)"],
-    "ask": ["bash(git push *)"],
-    "allow": ["bash(git status*)", "example-extension-tool"]
-  }
-}
-```
-
-`maxUserTranscriptTokens` and `maxToolTranscriptTokens` are approximate budgets for each category. Both default to 4000 and accept integers of at least 32.
-
-Pi-automode does not support the former `maxTranscriptLines` field. Evidence selection now uses token budgets instead of line counts.
-
-## Ask-user tools and explicit authorization
-
-Classifier evidence includes normal user messages and assistant tool-call inputs. It excludes assistant prose and all tool results. This exclusion includes answers from ask-user tools such as `@vanillagreen/pi-questions`.
-
-Selecting "Yes" in that tool helps the agent select its next action. Pi-automode does not treat the result as authorization to override a soft deny.
-
-Send the authorization as a normal chat message. Then the agent can retry the action. Tool results remain excluded because they can contain untrusted or prompt-injected content.
-
-## `$defaults`
-
-See [Defaults and rule-list behavior](defaults.md) for built-in `environment`, `allow`, `protectedPaths`, `soft_deny`, and `hard_deny` entries. The document also explains replacement behavior after omission of `$defaults`.
-
-## Observability logging
-
-Auto mode can write a JSONL observability log for decisions and classifier usage. Persisted sessions use a sidecar next to the Pi session file. In-memory sessions use a global application directory. Logging is off by default.
-
-```json
-{
-  "autoMode": {
-    "log": {
-      "enabled": true,
-      "classifierIo": false
-    }
-  }
-}
-```
-
-With logging enabled, persisted-session sidecars also contain ccusage-compatible entries for every classifier response. When `classifierIo` is off, `ccusage pi` still reports a separate `-pi-automode` session. In-memory logs use the same entry shape but live outside the normal Pi session tree.
-
-See [Observability logging](observability-logging.md) for the log file location, entry schema, and the `classifierIo` privacy tradeoff. Run `/automode config` to see the resolved log file path.
-
-## Permission patterns
-
-Permission patterns use Pi tool names. Examples include `bash(...)`, `write(...)`, `edit(...)`, and `read(...)`. The parser accepts capitalized names such as `Bash(...)`. The documented form is lowercase because Pi tool names are lowercase.
-
-`permissions.allow` is a deterministic allow tier. The default list is `[]`. A matching rule skips classifier review.
-
-Use this tier for a narrow command such as `bash(git status*)`. You can also use it for a side-effect-free extension or MCP tool.
-
-The matcher understands primary arguments for `bash`, the file tools, and `grep`. For file tools, it uses the resolved `input.path`. For `grep`, it uses `input.pattern`.
-
-For `bash`, pi-automode parses `input.command` with `unbash`. Deny and ask rules inspect each executable command in the Bash syntax tree. This includes pipelines, logical chains, compound commands, substitutions, and literal scripts passed to `bash -c`, `sh -c`, or `eval`. The analysis also follows these literal shell scripts through transparent `command`, `exec`, and `env` dispatch.
-
-The matcher normalizes whitespace between Bash tokens. It preserves whitespace and quoting inside each token. Thus, `bash(git push*)` matches `git  push origin main`. Quoted operators do not create extra commands.
-
-A Bash allow decision requires coverage for each executable command. A multi-command pattern must match the same AST structure and operators. This structure check also applies to one command inside a group, wrapper, control structure, or background statement. Separate single-command patterns only cover top-level foreground chains and plain pipelines. Other supported structure requires one matching structural pattern. A multi-command pattern must match the same number of commands in the same order. Each pattern command must match its corresponding input command. One wildcard cannot hide an additional command or a different operator.
-
-A redirect requires explicit coverage in the allow pattern. The redirect operator, file descriptor, variable name, and target pattern must match. Here-documents and dynamic redirect targets continue to the classifier. Parser errors, dynamic command names, and dynamic wrapper scripts cannot use `permissions.allow`.
-
-Control nodes with unrepresented semantic values cannot use `permissions.allow`. This includes loops, functions, coprocesses, case statements, test commands, and arithmetic commands. These scripts continue to the classifier.
-
-Pi-automode does not execute shell expansions. It cannot resolve aliases, variables, generated scripts, or dynamic `eval` input. These calls continue to the classifier unless a deterministic rule blocks them.
-
-For other tools, the matcher uses the serialized input object. Use a bare tool name for an MCP or extension tool. For example, `example-extension-tool` matches every call to that tool.
-
-The providing extension or MCP server defines the Pi tool name. Pi-automode does not need a predefined list.
-
-A match skips only the classifier call. It cannot skip `permissions.deny`, deterministic hard-deny checks, `deniedPaths`, or protected-path controls. An accepted `permissions.ask` rule also takes precedence. After confirmation, the call continues through deterministic checks and then reaches the classifier. It cannot use `permissions.allow`, the inside-working-directory tier, or the read-only fast path.
-
-Pi-automode reads `permissions.allow` only from global configuration, trusted `.pi/automode.local.json`, and `PI_AUTOMODE_SETTINGS_JSON`. Shared `.pi/automode.json` cannot add allow rules.
-
-A pattern can contain at most 4,096 UTF-16 code units. Bash analysis accepts at most 1,048,576 UTF-16 code units. A longer Bash input is blocked before parsing.
-
-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.