@czottmann/pi-automode 1.11.0 → 1.13.0

package/docs/configuration.md

@@ -0,0 +1,171 @@
+# 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.

package/docs/defaults.md

@@ -2,7 +2,7 @@
 
 ## `$defaults`
 
-`$defaults` expands to this plugin's built-in entries for the section where it appears. It is section-local: `$defaults` in `allow` means the built-in allow rules, not the built-in hard-deny rules.
+`$defaults` expands to the built-in entries for its section. It is section-local. In `allow`, it means the built-in allow rules, not the built-in hard-deny rules.
 
 ### `environment`
 
@@ -14,7 +14,7 @@
 - trusted cloud buckets: none configured
 - key internal services: none configured
 
-Add your own entries when the classifier should know about trusted company infrastructure:
+If the classifier needs information about trusted company infrastructure, add entries such as these:
 
 ```json
 {
@@ -46,17 +46,40 @@ These are exceptions to `soft_deny`, not to `hard_deny`.
 
 ### `protectedPaths`
 
-`$defaults` expands to safety-sensitive paths. In the default configuration every `write` and `edit` call goes to the classifier, so `protectedPaths` does not change whether a model call occurs; it remains part of the resolved configuration for compatibility and inspection. With `allowInsideWorkingDirectory: true`, non-protected in-tree file access takes the deterministic allow tier, but writes and edits to these protected paths still reach the classifier; `allow` rules cannot override a classifier hard-deny decision.
+`$defaults` expands to safety-sensitive paths. In the default configuration, every `write` and `edit` call goes to the classifier. Thus, `protectedPaths` does not change classifier routing by default. Pi-automode retains the list for compatibility and inspection.
+
+The value `allowInsideWorkingDirectory: true` sends non-protected in-tree file access to the deterministic allow tier. Writes and edits to protected paths still reach the classifier. Classifier `allow` rules cannot override a classifier hard-deny decision.
 
 Protected directories: `.git`, `.config/git`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, `.mvn`, `.pi`.
 
-Protected files: `.gitconfig`, `.gitmodules`, `.gitignore`, `.gitattributes`, shell profiles (`.bashrc`, `.zshrc`, `.profile`, etc.), `.envrc`, package manager configs (`.npmrc`, `.yarnrc`, `.yarnrc.yml`, `.pnp.cjs`, `bunfig.toml`, etc.), Bazel configs (`.bazelrc`, `.bazelversion`, `.bazeliskrc`), hook configs (`.pre-commit-config.yaml`, `lefthook.yml`), Gradle/Maven wrappers, `.devcontainer.json`, `.ripgreprc`, `pyrightconfig.json`, `.mcp.json`.
+Protected files include:
+
+- Git files: `.gitconfig`, `.gitmodules`, `.gitignore`, and `.gitattributes`
+- Bash files: `.bashrc`, `.bash_profile`, `.bash_login`, `.bash_aliases`, and `.bash_logout`
+- Zsh files: `.zshrc`, `.zprofile`, `.zshenv`, `.zlogin`, and `.zlogout`
+- other shell files: `.profile` and `.envrc`
+- package-manager files: `.npmrc`, `.yarnrc`, `.yarnrc.yml`, `.pnp.cjs`, `.pnp.loader.mjs`, and `.pnpmfile.cjs`
+- Bun files: `bunfig.toml` and `.bunfig.toml`
+- Bazel files: `.bazelrc`, `.bazelversion`, and `.bazeliskrc`
+- hook files: `.pre-commit-config.yaml`, `lefthook.yml`, `lefthook.yaml`, `.lefthook.yml`, and `.lefthook.yaml`
+- wrapper files: `gradle-wrapper.properties` and `maven-wrapper.properties`
+- other control files: `.devcontainer.json`, `.ripgreprc`, `pyrightconfig.json`, and `.mcp.json`
+
+Read-only tools remain locally allowed after permission and deterministic checks. These tools are `read`, `grep`, `find`, and `ls`.
+
+In the default configuration, all writes and edits require classification. The value `allowInsideWorkingDirectory: true` allows non-protected in-tree access locally.
 
-Read-only tools (`read`, `grep`, `find`, `ls`) remain locally allowed after permission and deterministic checks. In the default configuration writes and edits always require classification, regardless of their target; with `allowInsideWorkingDirectory` enabled, only protected targets still require it.
+Protected in-tree writes and edits still require classification. All out-of-tree file access also requires classification.
 
 ### `deniedPaths`
 
-`deniedPaths` is a separate opt-in list (default `[]`, no built-in entries, so `$defaults` is a no-op; it is accepted for consistency with the other rule lists) of path glob patterns that are hard-denied for the file tools (`read`, `write`, `edit`, `grep`, `find`, `ls`) before any classifier or fast-path decision. Use it for secrets and system paths that must never reach the model through the file tools; `bash` access to such paths remains classifier-governed. Patterns support `~`/`$HOME`/`${HOME}` expansion and `*` (matches any characters, including `/`). Matching checks both the typed path and its symlink-resolved form. `deniedPaths` only restricts; it never grants access.
+`deniedPaths` is an optional list of path glob patterns. The default list is empty, and it has no built-in entries. Thus, `$defaults` has no effect in this list.
+
+A matching pattern blocks a file-tool call before classifier review or an allow tier. The file tools are `read`, `write`, `edit`, `grep`, `find`, and `ls`.
+
+Use this list for secrets and system paths that file tools must not send to the model. The classifier continues to govern `bash` access.
+
+Patterns support `~`, `$HOME`, and `${HOME}` expansion. The `*` wildcard matches all characters, including `/`. Pi-automode matches the typed path and its symlink-resolved form. `deniedPaths` can only restrict access.
 
 ### `soft_deny`
 
@@ -68,7 +91,7 @@ Read-only tools (`read`, `grep`, `find`, `ls`) remain locally allowed after perm
 - deleting, truncating, or overwriting pre-existing local files unless the user named the specific target
 - 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 live/shared infrastructure without a preview, plan, dry-run, or review when one normally exists
+- changing shared or live infrastructure without its normal preview, plan, dry run, or review
 - killing other users' processes, cancelling shared jobs, or disrupting shared infrastructure
 - exposing local files, sockets, credentials, or internal services through a network service
 - outbound messages, purchases, bookings, subscriptions, or other real-world transactions
@@ -84,7 +107,7 @@ Soft blocks can be overridden by a matching `allow` exception or by direct, spec
 - granting admin, owner, IAM, RBAC, repository, or production access
 - exfiltrating repository contents, secrets, credentials, private keys, tokens, or internal data to untrusted places
 - scanning for credentials, tokens, private keys, or secrets beyond what the task requires
-- tampering with logs, audit trails, security monitoring, permission rules, auto-mode config, or safety-control files
+- tampering with logs, audit trails, security monitoring, permission rules, auto-mode configuration, or safety-control files
 - creating services, endpoints, workflows, or autonomous agents that execute arbitrary code without meaningful approval
 - posting or updating public/external content that is fabricated, misleading, impersonating a user, or claiming approval/action that did not happen
 
@@ -97,13 +120,25 @@ Classifier evidence has separate approximate-token budgets for user messages and
 - `maxUserTranscriptTokens`: 4000
 - `maxToolTranscriptTokens`: 4000
 
-The selector keeps the first and latest user messages as intent anchors, then fills remaining space from the newest eligible entries. Individual entries are capped, and omitted or truncated evidence is marked in the classifier transcript. Assistant prose and tool results are excluded.
+The selector keeps the first and latest user messages as intent anchors. It fills the remaining space from the newest eligible entries.
+
+The selector limits individual entries. It marks omitted or truncated evidence in the classifier transcript. It excludes assistant prose and tool results.
 
-These are approximate limits based on character counts, not provider-tokenizer guarantees. Override either value with an integer of at least 32 in a Pi-owned `autoMode` config. The former `maxTranscriptLines` setting is no longer supported.
+These limits use approximate character counts. They do not guarantee the same result as a provider tokenizer.
+
+To change a limit, set an integer of at least 32 in a Pi-owned `autoMode` configuration source. Pi-automode does not support the former `maxTranscriptLines` field.
+
+### Classifier request timeout
+
+`classifierTimeoutMs` limits each classifier request in milliseconds. The fast and detailed stages have separate budgets. The default is 20000.
+
+If a request exceeds its budget, pi-automode aborts the attempt. Then auto mode fails closed and blocks the action.
+
+To change the timeout, set an integer of at least 1000 in a Pi-owned `autoMode` configuration source.
 
 ### Replacement behavior
 
-Use `$defaults` when you want to keep the built-ins and add your own entries:
+If you want to keep the built-ins and add entries, use `$defaults`:
 
 ```json
 {
@@ -116,7 +151,7 @@ Use `$defaults` when you want to keep the built-ins and add your own entries:
 }
 ```
 
-That means: use all built-in `allow` entries, plus the staging rule.
+This configuration uses all built-in `allow` entries and the staging rule.
 
 If you omit `$defaults`, you replace the built-ins for that section:
 
@@ -130,7 +165,13 @@ If you omit `$defaults`, you replace the built-ins for that section:
 }
 ```
 
-That means: use only that one `allow` entry. The built-in `allow` entries are not used. Replacing `allow` does not replace `soft_deny`, `hard_deny`, `protectedPaths`, or `environment`.
+This configuration uses only the staging rule. It does not use the built-in `allow` entries.
+
+Replacing `allow` does not replace `soft_deny`, `hard_deny`, `protectedPaths`, or `environment`.
+
+`permissions.deny`, `permissions.ask`, and `permissions.allow` do not support `$defaults`. These lists contain only explicit Pi tool patterns. All three lists default to `[]`.
+
+Global, project-local, and inline configuration can add all three permission lists. Shared project configuration can add only deny and ask rules.
 
-`$defaults` is not used in `permissions.deny` or `permissions.ask`. Those lists contain only explicit Pi tool patterns.
+`autoMode.allow` and `permissions.allow` are different. `autoMode.allow` contains prose exceptions that the classifier weighs against soft-deny rules. `permissions.allow` contains tool patterns that skip classifier review.
 

package/docs/diagnostics.md

@@ -0,0 +1,90 @@
+# Agent diagnostics
+
+`automode_inspect` is a model-callable, read-only tool. An agent can use it to inspect active pi-automode state without copied slash-command output.
+
+Use this tool to investigate an unexpected allow or block. Do not use it to change a safety control or to bypass a denial.
+
+## Inspection views
+
+The tool accepts one `action` value.
+
+| Action | Purpose | Result |
+| --- | --- | --- |
+| `status` | Inspect active state and counters. | A readable status summary and the enabled override, last decision, and action counters. |
+| `config` | Inspect the effective configuration. | The active configuration, the resolved observability log path, and configuration diagnostics. |
+| `defaults` | Inspect built-in rule lists. | The built-in environment, allow, protected-path, soft-deny, and hard-deny lists. |
+| `denials` | Find recent rejected actions. | Reverse-chronological timestamps, enforcement kinds, and tool names. |
+
+The tool reads the same in-memory configuration and state that pi-automode enforces. Configuration changes take effect after session start or `/automode reload`.
+
+## Enforcement behavior
+
+An inspection call is not an unrestricted escape hatch.
+
+1. `permissions.deny` runs first.
+2. `permissions.ask` runs next.
+3. Deterministic hard-deny checks run next.
+4. The extension bypasses classifier routing only for its own registered `automode_inspect` tool.
+
+If a local check blocks the call, pi-automode records it as a blocked action. If the call passes, inspection does not change counters, state, or logs.
+
+The extension verifies the registered tool source before it applies the bypass. A tool from another extension with the same name does not receive this exemption.
+
+The tool cannot enable or disable auto mode, reload configuration, reset state, select a model, or edit configuration. The user must run the related `/automode` command directly.
+
+## Model-visible data
+
+Pi sends tool output to the current model. The output has deliberate privacy limits:
+
+- `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.
+
+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.
+
+The tool serializes output defensively. Arrays longer than 30 entries become an object with these fields:
+
+```json
+{
+  "$truncatedArray": true,
+  "items": ["first entries"],
+  "omittedEntries": 18,
+  "totalEntries": 48
+}
+```
+
+String values and the complete serialized result also have size limits. Treat a truncated result as incomplete. An omitted rule can still exist.
+
+## Observability log path
+
+Use the `config` view to get the log path for the current session. Its `logFile` value uses the same resolution as observability logging:
+
+- A persisted session uses a sidecar beside its Pi session file.
+- An in-memory session uses the application-owned log directory for the effective session working directory.
+
+For in-memory sessions, pi-automode uses this default location:
+
+```text
+~/.pi/agent/extensions/pi-automode/logs/<encoded-session-cwd>/YYYY-MM-DD/<session-id>-pi-automode.jsonl
+```
+
+This includes `--no-session` runs and non-persisted subagents. The path does not use the launching process working directory.
+
+See [Observability logging](observability-logging.md) for log configuration and entry schemas.
+
+## Diagnosis workflow
+
+Classifier rules cannot override permission or deterministic denials.
+
+1. Call `automode_inspect` with `status`, `config`, and `denials`.
+2. If observability logging is enabled, use the reported log path.
+3. Read a matching decision entry before you propose a rule change.
+4. Identify the enforcement layer before you change a rule.
+5. If a configuration change is necessary, explain the change.
+6. Ask the user to run `/automode off`.
+7. Make only the requested configuration change during that maintenance window.
+8. Ask the user to run `/automode reload` and `/automode on`.
+9. Use `automode_inspect` to make sure that auto mode is enabled.
+10. Retry only an action that you know is safe.
+
+Do not replay an unsafe action because auto mode is off. Do not print sensitive tool input or log content in a diagnosis report.

package/docs/observability-logging.md

@@ -1,10 +1,12 @@
 # Observability logging
 
-Auto mode can write a JSONL observability log next to the current Pi session file, so you can inspect decisions and classifier usage. It is off by default and fail-open: a write error never changes an allow/block decision.
+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. Logging fails open, so a write error never changes an allow or block decision.
 
 ## Enabling
 
-Set `autoMode.log` in any Pi-owned config source (`~/.pi/agent/automode.json`, `.pi/automode.local.json`, or `PI_AUTOMODE_SETTINGS_JSON`):
+Set `autoMode.log` in a Pi-owned configuration source. These sources include `~/.pi/agent/extensions/pi-automode/config.json`, trusted `.pi/automode.local.json`, and `PI_AUTOMODE_SETTINGS_JSON`.
 
 ```json
 {
@@ -18,44 +20,62 @@ Set `autoMode.log` in any Pi-owned config source (`~/.pi/agent/automode.json`, `
 ```
 
 - `enabled` — write one `decision` line per tool-call decision and one ccusage-compatible `message` line per classifier model response.
-- `classifierIo` — also write the classifier's prompt, raw model responses, and parsed decision for classifier-routed actions. Off by default; see [Privacy](#privacy) below.
+- `classifierIo` — also write the classifier prompt, raw responses, and parsed decision for classifier-routed actions. The default is `false`. See [Privacy](#privacy).
+
+Fields merge independently across configuration sources. For example, set `enabled` globally and set `classifierIo` for a trusted project.
 
-Fields merge independently across config scopes (set `enabled` globally and `classifierIo` per project, for example). Shared project `.pi/automode.json` cannot set `log` — it follows the same `autoMode` exclusion as the rest of the config. Shape is validated and reported by `/automode config`.
+Shared project `.pi/automode.json` cannot set `log`. The shared file cannot set any `autoMode` field. `/automode config` reports an invalid shape.
 
-Logging only writes entries while auto-mode is **enabled**. With auto-mode off, no tool calls reach the hook, so no entries are produced.
+Pi-automode writes log entries only while auto mode is **enabled**. With auto mode off, no tool calls reach the hook. Thus, pi-automode writes no entries.
 
 ## Log file location
 
-The log file is colocated with the current Pi session file, with `-pi-automode` inserted before the extension:
+Pi-automode stores the log next to the current Pi session file. It inserts `-pi-automode` before the extension:
 
 ```text
 <session-file>                       →  <dir>/<id>.jsonl
 <session-file>-pi-automode.jsonl     →  <dir>/<id>-pi-automode.jsonl
 ```
 
-For example: `~/.pi/agent/sessions/<slug>/<id>-pi-automode.jsonl`. If no session file is set, it falls back to `<sessionDir>/<sessionId>-pi-automode.jsonl`. Run `/automode config` to see the resolved path.
+For example, pi-automode can use `~/.pi/agent/sessions/<slug>/<id>-pi-automode.jsonl`.
+
+If a custom session manager provides an absolute session directory without a session file, pi-automode uses `<sessionDir>/<sessionId>-pi-automode.jsonl`.
+
+Pi in-memory sessions have no session file or session directory. These sessions include `--no-session` and non-persisted subagents. Their logs use this absolute application path:
+
+```text
+~/.pi/agent/extensions/pi-automode/logs/<encoded-session-cwd>/YYYY-MM-DD/<session-id>-pi-automode.jsonl
+```
+
+The project directory uses the same `--path-with-dashes--` encoding as normal Pi session directories. The date partition uses UTC.
+
+A custom session manager can supply an absolute `sessionDir` without a session file. In this case, pi-automode continues to use that directory. Run `/automode config` to see the resolved path.
 
-There is one combined file per session. Each line is one JSON object with a `type` discriminator. Entries for the same tool call share a `decisionId`.
+Persisted sessions use one combined file per session. In-memory sessions use one file for each session ID and UTC day.
+
+If a session crosses midnight, pi-automode continues in the file for the next day. Each line contains one JSON object with a `type` discriminator. Entries for the same tool call share a `decisionId`.
+
+For persisted sessions, `ccusage pi` reports the sidecar as a separate `-pi-automode` session. Inspect in-memory logs directly because they are outside the normal Pi session tree.
 
 ## Entry types
 
 ### `decision`
 
-One per tool-call decision. Every allow and every block goes through exactly one of these.
+Pi-automode writes one `decision` entry for each tool-call decision. Each allowed or blocked call has exactly one entry.
 
 | field | meaning |
 | --- | --- |
 | `ts` | ISO timestamp |
-| `decisionId` | links to the `classifier` entry (if any) for the same call |
+| `decisionId` | links to the related `classifier` entry. Local decisions have no related entry. |
 | `sessionId` | Pi session id |
 | `cwd` | working directory |
-| `tool` | tool name, e.g. `bash`, `write` |
+| `tool` | tool name, for example `bash` or `write` |
 | `summary` | `actionSummary` — tool name + input JSON (truncated) |
-| `kind` | enforcement path: `permissions.deny`, `permissions.ask`, `deterministic-hard-deny`, `classifier`, or `read-only` |
+| `kind` | enforcement path: `permissions.deny`, `permissions.ask`, `deterministic-hard-deny`, `deterministic-path-deny`, `permissions.allow`, `inside-working-directory`, `classifier`, `read-only`, or `setup` |
 | `outcome` | `allow` or `block` |
 | `reason` | the reason string (classifier reason, or the deterministic/permission reason) |
-| `classifierModel` | the configured classifier model, when relevant |
-| `reasoning` | classifier reasoning mode and requested/effective level; see below |
+| `classifierModel` | the configured classifier model for a classifier-routed decision |
+| `reasoning` | classifier reasoning mode and requested or effective level. See the examples below. |
 
 The reasoning field records either server-default mode:
 
@@ -69,11 +89,17 @@ or an explicit request after model-level clamping:
 {"mode":"explicit","requestedLevel":"max","effectiveLevel":"xhigh"}
 ```
 
-Classifier-routed decisions contain the effective level once the configured model resolves, even when `classifierIo` is off or authentication then fails. If the configured model itself cannot be resolved, an explicit entry records `requestedLevel` without `effectiveLevel` because no model-supported level exists. A local permission, deterministic, or read-only decision does not run the classifier and likewise may omit `effectiveLevel`. In `server-default` mode, the concrete server-selected level is not observable and is not inferred.
+Classifier-routed decisions contain the effective level after model resolution. If `classifierIo` is off or authentication fails later, this field still exists.
+
+If pi-automode cannot resolve the model, the entry contains `requestedLevel` without `effectiveLevel`. In this case, no model-supported level exists.
+
+Local permission, deterministic, `permissions.allow`, and read-only decisions do not run the classifier. These decisions can omit `effectiveLevel`. Pi-automode cannot observe or infer the server-selected level in `server-default` mode.
 
 ### `message` (classifier usage)
 
-One per classifier model response, including malformed responses that trigger a retry. Written whenever logging is enabled, before the matching `decision` line. Its shape is intentionally compatible with `ccusage pi`:
+Pi-automode writes one `message` entry for each classifier response. This includes a malformed response that causes a retry.
+
+When logging is enabled, pi-automode writes this entry before the matching `decision` line. The entry shape is compatible with `ccusage pi`:
 
 | field | meaning |
 | --- | --- |
@@ -82,20 +108,23 @@ One per classifier model response, including malformed responses that trigger a
 | `message.model` | model ID returned by the classifier provider |
 | `message.usage` | provider-reported input, output, cache, total-token, and cost fields |
 
-`ccusage` reports this sidecar as a separate `-pi-automode` session. This entry contains no prompt or response text, so it is written even when `classifierIo` is off.
+For persisted sessions, `ccusage` reports this sidecar as a separate `-pi-automode` session. This entry contains no prompt or response text. When `classifierIo` is off, pi-automode still writes it.
 
 ### `classifier`
 
-Written only for classifier-routed actions, and only when `classifierIo: true`. It follows any classifier-usage `message` entries and precedes the matching `decision` line in the file.
+If `classifierIo: true`, pi-automode writes a `classifier` entry. It writes this entry only for classifier-routed actions.
+
+The entry follows all related classifier-usage `message` entries. It precedes the matching `decision` entry.
 
 | field | meaning |
 | --- | --- |
 | `ts` | ISO timestamp |
 | `decisionId` | matches the `decision` entry for the same call |
-| `model` | classifier model used, e.g. `anthropic/claude-haiku-4` |
+| `model` | classifier model, for example `anthropic/claude-haiku-4` |
 | `reasoning` | `server-default`, or the explicit requested and effective model-supported level |
 | `prompt.system` | the full system policy with `environment`/`allow`/`soft_deny`/`hard_deny` rules interpolated |
-| `prompt.context` | the shared context message: loaded project instructions + classifier transcript + action |
+| `prompt.context` | the shared context message: loaded project instructions + classifier transcript |
+| `prompt.action` | the complete, untruncated current tool action JSON |
 | `prompt.fastInstruction` | the exact one-token filter instruction |
 | `prompt.detailedInstruction` | the exact structured-review instruction |
 | `attempts` | one entry per classifier model call (see below) |
@@ -106,20 +135,26 @@ Each `attempts[]` entry is `{ stage, attempt, response?, parsed?, error?, durati
 
 - `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.
-- `parsed` — the decision parsed from the response, or absent if it did not parse.
-- `error` — present when the call threw (network/auth); `response` is then absent.
+- `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.
 
-This records both stages, retries, and fail-closed cases verbatim. A fast allow has one entry. A review followed by malformed detailed JSON and a successful retry has three entries.
+The array records both stages, retries, and fail-closed cases. A fast allow has one entry. A review with one successful retry has three entries.
 
 ## Privacy
 
-`prompt.context` is the shared content sent to both classifier stages: loaded project instructions, selected transcript evidence, and the action being classified. The stage-specific final instructions are logged separately. See [Auto-mode classifier flow → What is sent to the classifier](automode-classifier-flow.md#what-is-sent-to-the-classifier) for how the evidence is assembled and truncated.
+`prompt.context` contains project instructions and transcript evidence for both classifier stages. `prompt.action` contains the separate, untruncated current action. Pi-automode logs the final stage instructions separately.
+
+See [Auto-mode classifier flow → What is sent to the classifier](automode-classifier-flow.md#what-is-sent-to-the-classifier) for the evidence assembly rules.
 
-The log records this payload locally, but the same data is also sent to the classifier model endpoint on every classifier-routed call. If `classifierModel` points at a cloud provider, that payload leaves the machine. Enable `classifierIo` when debugging classifier behavior or tuning rules; leave it off for routine outcome logging.
+The log records this payload locally. Pi-automode also sends the same data to the classifier endpoint for each classifier-routed call.
+
+If `classifierModel` uses a cloud provider, the payload leaves the machine. Enable `classifierIo` only for classifier diagnosis or rule tuning. Leave it off for routine outcome logging.
 
 ## Sizing
 
 - `decision` line: ~0.4–2 KB (driven by `summary`, which carries the tool input, capped at 6 KB).
 - `classifier` line: ~5 KB fixed policy plus loaded project instructions, selected transcript evidence, stage instructions, and recorded responses.
 
-Transcript evidence is bounded separately by `autoMode.maxUserTranscriptTokens` and `autoMode.maxToolTranscriptTokens`, both 4000 approximate tokens by default. Assistant prose and tool results are not included. Provider cache hits can reduce billed or processed input where supported, but the log still records the full classifier payload.
+`autoMode.maxUserTranscriptTokens` and `autoMode.maxToolTranscriptTokens` limit transcript evidence separately. Both fields default to approximately 4000 tokens.
+
+Pi-automode excludes assistant prose and tool results. Provider cache hits can reduce processed or billed input. The log still records the full classifier payload.

package/examples/automode.local.json

@@ -1,6 +1,7 @@
 {
   "autoMode": {
     "classifierReasoningLevel": "low",
+    "classifierTimeoutMs": 20000,
     "allowInsideWorkingDirectory": false,
     "deniedPaths": [
       "*.env",
@@ -27,6 +28,10 @@
     ]
   },
   "permissions": {
+    "allow": [
+      "bash(git status*)",
+      "example-extension-tool"
+    ],
     "ask": [
       "bash(git push *)"
     ],