@czottmann/pi-automode 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Carlo Zottmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# pi-automode
+
+Claude Code-style auto mode for Pi.
+
+This is a guardrail extension. It intercepts agent tool calls before execution and blocks actions that match permission deny rules, deterministic hard-deny checks, or the auto-mode classifier's block decision.
+
+It is not a sandbox. Extensions run in the Pi process, and a determined malicious extension can do anything your user account can do. It also does not guard user `!` / `!!` shell commands; by design, it guards agent tool calls only. Use this to reduce unsafe autonomous tool use, not as an OS security boundary.
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:@czottmann/pi-automode
+```
+
+From a local checkout:
+
+```bash
+pi install .
+```
+
+For one run from a local checkout:
+
+```bash
+pi -e ./extensions/auto-mode.ts
+```
+
+## Commands
+
+```text
+/automode status    # current state, rules, and classifier
+/automode on        # re-enable for this session
+/automode off       # disable for this session
+/automode reload    # reload config from disk
+/automode reset     # reset denial counters only
+/automode defaults  # print the built-in rule lists
+/automode config    # current effective config + diagnostics
+/automode denials   # denial history for this session
+/automode model     # open classifier model selector
+/automode model provider/model-id # set classifier directly
+```
+
+`/auto-mode` is an alias.
+
+## Configuration
+
+The extension follows Claude Code's documented config model where Pi can support it.
+
+It reads `autoMode` from Pi-owned config only:
+
+- `~/.pi/automode.json`
+- `.pi/automode.local.json`
+- `PI_AUTOMODE_SETTINGS_JSON`
+
+It deliberately does not read `autoMode` from shared project `.pi/automode.json`, because a checked-in repo should not be able to weaken auto-mode rules. Shared project config may still contribute `permissions.deny` and `permissions.ask`.
+
+Example:
+
+```json
+{
+  "autoMode": {
+    "environment": [
+      "$defaults",
+      "Source control: github.example.com/acme-corp and all repos under it",
+      "Trusted internal domains: *.corp.example.com"
+    ],
+    "allow": ["$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 *)"]
+  }
+}
+```
+
+### `$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.
+
+#### `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
+
+#### `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
+- 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`.
+
+#### `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 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
+- 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 by direct, specific user intent.
+
+#### `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 config, 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.
+
+#### Replacement behavior
+
+Use `$defaults` when you want to keep the built-ins and add your own entries:
+
+```json
+{
+  "autoMode": {
+    "allow": [
+      "$defaults",
+      "Running the staging deploy script is allowed."
+    ]
+  }
+}
+```
+
+That means: use all built-in `allow` entries, plus 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."
+    ]
+  }
+}
+```
+
+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`, or `environment`.
+
+`$defaults` is not used in `permissions.deny` or `permissions.ask`. Those lists contain only explicit Pi tool patterns.
+
+### Permission patterns
+
+Permission patterns use Pi tool names, for example `bash(...)`, `write(...)`, `edit(...)`, `read(...)`. The parser accepts capitalized names like `Bash(...)` for convenience, but the documented form is lowercase because Pi tool names are lowercase.
+
+## What is enforced before the classifier
+
+The extension blocks these before any allow or classifier decision:
+
+- `permissions.deny` matches
+- declined `permissions.ask` matches
+- shell profile writes
+- SSH `authorized_keys` writes
+- cron, launch agent, and system service persistence
+- TLS/certificate/auth weakening patterns
+- root, home, and system-path destructive deletes
+- edits to `.pi/automode*`, `.pi` auto-mode files, and this extension's safety-control files
+
+Read-only Pi tools (`read`, `grep`, `find`, `ls`) are allowed after those checks.
+
+Everything else goes to the classifier. If the classifier is missing, fails, or returns invalid JSON, the action is blocked.
+
+## Examples
+
+- `examples/automode.local.json`: copy to `.pi/automode.local.json` in a project and edit the domains, buckets, and source-control org.
+
+## Development
+
+```bash
+npm run check
+npm test
+npm pack --dry-run
+```
+
+The tests cover the risky parts: scoped permission matching, config-source precedence, `$defaults` behavior, config diagnostics, deterministic hard-deny checks, shell parsing for risky bash fragments, classifier JSON parsing, hook-level blocking/allowing, and classifier mocking.
+
+## Known limits
+
+Claude Code's real classifier and exact built-in rules are private. This package implements the documented precedence and configuration behavior, with a local classifier prompt and deterministic hard-deny checks.

package/examples/automode.local.json

@@ -0,0 +1,32 @@
+{
+  "autoMode": {
+    "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": {
+    "ask": [
+      "bash(git push *)"
+    ],
+    "deny": [
+      "bash(git push --force*)",
+      "edit(.env*)",
+      "write(.env*)"
+    ]
+  }
+}