@herbertgao/pi-extensions 2026.9.5 → 2026.9.6

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

@@ -1,178 +0,0 @@
-# Defaults and rule-list behavior
-
-## `$defaults`
-
-`$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`
-
-`$defaults` expands to:
-
-- trusted repo: the repository Pi started in and its configured git remotes
-- source control: the trusted repo and its configured remotes only
-- trusted internal domains: none configured
-- trusted cloud buckets: none configured
-- key internal services: none configured
-
-If the classifier needs information about trusted company infrastructure, add entries such as these:
-
-```json
-{
-  "autoMode": {
-    "environment": [
-      "$defaults",
-      "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"
-    ]
-  }
-}
-```
-
-These entries give the classifier context. They do not bypass `hard_deny` or automatically allow every action involving those services.
-
-### `allow`
-
-`$defaults` expands to allow exceptions for:
-
-- 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
-- bootstrapping language/toolchain installers from official sources
-
-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. 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 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.
-
-Protected in-tree writes and edits still require classification. All out-of-tree file access also requires classification.
-
-### `deniedPaths`
-
-`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`
-
-`$defaults` expands to soft blocks for:
-
-- 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 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
-- 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
-
-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`
-
-`$defaults` expands to unconditional blocks for:
-
-- weakening TLS, certificate validation, authentication, authorization, audit logging, or other security controls
-- adding persistence such as SSH keys, shell profile edits, cron jobs, launch agents, login items, or background agents
-- 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 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
-
-Hard-deny rules cannot be overridden by `allow` or by user intent.
-
-### Classifier transcript budgets
-
-Classifier evidence has separate approximate-token budgets for user messages and assistant tool-call payloads:
-
-- `maxUserTranscriptTokens`: 4000
-- `maxToolTranscriptTokens`: 4000
-
-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 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
-
-If you want to keep the built-ins and add entries, use `$defaults`:
-
-```json
-{
-  "autoMode": {
-    "allow": [
-      "$defaults",
-      "Running the staging deploy script is allowed."
-    ]
-  }
-}
-```
-
-This configuration uses all built-in `allow` entries and the staging rule.
-
-If you omit `$defaults`, you replace the built-ins for that section:
-
-```json
-{
-  "autoMode": {
-    "allow": [
-      "Running the staging deploy script is allowed."
-    ]
-  }
-}
-```
-
-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.
-
-`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/node_modules/@czottmann/pi-automode/docs/diagnostics.md

@@ -1,90 +0,0 @@
-# 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/node_modules/@czottmann/pi-automode/docs/observability-logging.md

@@ -1,160 +0,0 @@
-# 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. Logging fails open, so a write error never changes an allow or block decision.
-
-## Enabling
-
-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
-{
-  "autoMode": {
-    "log": {
-      "enabled": true,
-      "classifierIo": false
-    }
-  }
-}
-```
-
-- `enabled` — write one `decision` line per tool-call decision and one ccusage-compatible `message` line per classifier model response.
-- `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.
-
-Shared project `.pi/automode.json` cannot set `log`. The shared file cannot set any `autoMode` field. `/automode config` reports an invalid shape.
-
-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
-
-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-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.
-
-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`
-
-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 related `classifier` entry. Local decisions have no related entry. |
-| `sessionId` | Pi session id |
-| `cwd` | working directory |
-| `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`, `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 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:
-
-```json
-{"mode":"server-default"}
-```
-
-or an explicit request after model-level clamping:
-
-```json
-{"mode":"explicit","requestedLevel":"max","effectiveLevel":"xhigh"}
-```
-
-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)
-
-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 |
-| --- | --- |
-| `timestamp` | ISO timestamp from the classifier response |
-| `message.role` | always `assistant` |
-| `message.model` | model ID returned by the classifier provider |
-| `message.usage` | provider-reported input, output, cache, total-token, and cost fields |
-
-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`
-
-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, 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 |
-| `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) |
-| `durationMs` | total classifier time |
-| `parsed` | the final decision that was acted on (`{ decision, tier, reason }`) |
-
-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.
-- `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.
-
-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` 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. 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.
-
-`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/node_modules/@czottmann/pi-automode/examples/automode.local.json

@@ -1,44 +0,0 @@
-{
-  "autoMode": {
-    "classifierReasoningLevel": "low",
-    "classifierTimeoutMs": 20000,
-    "allowInsideWorkingDirectory": false,
-    "deniedPaths": [
-      "*.env",
-      "~/.ssh/*",
-      "/etc/*"
-    ],
-    "environment": [
-      "$defaults",
-      "Source control: github.example.com/acme-corp and all repos under it",
-      "Trusted internal domains: *.corp.example.com, api.internal.example.com",
-      "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-dev-scratch"
-    ],
-    "allow": [
-      "$defaults",
-      "Deploying to the staging namespace is allowed when the command names staging explicitly."
-    ],
-    "soft_deny": [
-      "$defaults",
-      "Never run database migrations except through the project's migrations CLI."
-    ],
-    "hard_deny": [
-      "$defaults",
-      "Never send repository contents to third-party code-review APIs."
-    ]
-  },
-  "permissions": {
-    "allow": [
-      "bash(git status*)",
-      "example-extension-tool"
-    ],
-    "ask": [
-      "bash(git push *)"
-    ],
-    "deny": [
-      "bash(git push --force*)",
-      "edit(.env*)",
-      "write(.env*)"
-    ]
-  }
-}