Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ A monorepo of benchmarked/minimal overhead tools I've built for Pi & Herdr:
| [pi-subagents](./pi-subagents/) | Tiny, benchmarked subagent harness with 88% less token overhead ([benchmarks](./benchmarks/README.md)). | `pi install npm:@gagansd/pi-subagents` |
| [pi-web-search](./pi-web-search/) | Cited public web and code search. Keyless by default with optional ranking. | `pi install npm:@gagansd/pi-web-search` |
| [pi-ask](./pi-ask/) | Structured interactive TUI interviews for human-in-the-loop decisions. | `pi install npm:@gagansd/pi-ask` |
| [pi-automode](./pi-automode/) (beta) | Permission gate for Pi: risky calls stop for a local decision, protected paths block, exact rules cut repeated asks. | `pi install npm:@gagansd/pi-automode` |
| [pi-automode](./pi-automode/) (beta) | Permission gate for Pi: command/path rules, optional thresholded safety review, local approvals, and protected-path blocks. | `pi install npm:@gagansd/pi-automode` |

### Install Pi extensions

Expand Down
31 changes: 31 additions & 0 deletions pi-automode/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,37 @@

## Unreleased

- Replace Details with a clean Settings editor: seven numeric tuning values,
contextual help, seconds/percent inputs, validation, draft Save/Cancel, and a
reset-to-defaults action that preserves models, consent, rules, and on/off state.
Match Pi's native full-width selectors with horizontal separators and a stable
reserved help area; edit values inline without opening another dialog.
Tab applies and advances; Ctrl+S saves.

- Render permission prompts, model catalogues, and Inspect details without
styling the entire body as a title. Add scrollable JSON-highlighted inspection
and remove its misleading Back option.
- Default approval waits to 60 seconds and model confidence to 0.67. An unanswered
local approval may run once only with an eligible safe probability > 0.50
meeting the confidence guard; otherwise decline. Explicit declines, lifecycle
cancellation, privacy restrictions, hard blocks, and revalidation remain final.

- Replace natural-language/message rules with command allowlist/blocklist rules:
exact commands, `*` globs, and an explicit safe regex mode. Legacy command
entries migrate; message entries produce a visible configuration error.
- Add built-in command defaults in a separate source file. All blocklists
precede allowlists; built-in read-only allows still require verified evidence.
- Index literal command prefixes rather than scanning every command pattern;
keep matching full-string and resistant to pathological backtracking.
- Activate optional safety decisions for unmatched eligible calls. Only a
validated `safe` answer meeting the configured threshold may authorize;
failures and uncertainty fall back to local approval, never a hard-block override.
- Require current-version disclosure consent before command-bearing review;
old metadata-only/shadow consent cannot silently expand.
- Add **Always Allow** with model-selected generalized command patterns and
explicit local scope confirmation before persistence. Remove the main
approval dialog's **Why:** line; retain reasons in details and audit records.

## 0.2.0

Release the current extension updates together.
Expand Down
9 changes: 7 additions & 2 deletions pi-automode/IMPLEMENTATION.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Implementation plan

> **Historical build record (through 0.2.0).** The contracts, shadow-only
> behavior, and message-rule design below describe the earlier beta, not the
> current command-rule rework. See the [README](README.md) for current behavior
> and [verification record](docs/verification.md) for dated test evidence.

> **Build record.** The package lives in
> [`coding-agent-toolkit/pi-automode`](https://github.com/GaganSD/coding-agent-toolkit/tree/main/pi-automode)
> and is published as `@gagansd/pi-automode` (MIT).
Expand All @@ -23,7 +28,7 @@ Two entry points: the ordinary Pi extension, explicitly supervised because the h
All TypeScript modules use ESM `.js` import specifiers. Pure/core modules do not import Pi at runtime.

- `Rule`: `{ type: "message" | "command"; text: string; enabled?: boolean }`.
- `AutomodeSettings`: `{ version: 1; enabled: boolean; decisionModel: { provider: string; model: string } | null; disclosureConsent: "none" | "approved" | "declined"; disclosureProvider: string | null; disclosureModel: string | null; disclosureEndpoint: string | null; disclosureWorkspace: string | null; allowlist: Rule[]; blocklist: Rule[]; logRetentionDays: number; logMaxEntries: number; reviewTimeoutMs: number; reviewMaxRequests: number; approvalTimeoutMs: number }`. Numeric limits/defaults are validated. Disclosure binds to the exact selected provider/model pair, the selected model's credential-free endpoint, and the canonical workspace; a missing binding cannot authorize upload, a selected provider/model that differs from the bound pair is not consent, and selecting a different decision model replaces all four bindings in the same single-step picker action. Older files may default missing bindings to null, but their unbound approved value is not valid consent. Defaults Off, no consent, null provider/model/endpoint/workspace binding, empty rules, seven days/500 entries, 2-second review deadline, 100 requests/session, 10-minute approval deadline. Every exposed setting is in this JSON. Unknown fields are rejected, including credentials.
- `AutomodeSettings`: `{ version: 1; enabled: boolean; decisionModel: { provider: string; model: string } | null; disclosureConsent: "none" | "approved" | "declined"; disclosureProvider: string | null; disclosureModel: string | null; disclosureEndpoint: string | null; disclosureWorkspace: string | null; allowlist: Rule[]; blocklist: Rule[]; logRetentionDays: number; logMaxEntries: number; reviewTimeoutMs: number; reviewMaxRequests: number; approvalTimeoutMs: number }`. Numeric limits/defaults are validated. Disclosure binds to the exact selected provider/model pair, the selected model's credential-free endpoint, and the canonical workspace; a missing binding cannot authorize upload, a selected provider/model that differs from the bound pair is not consent, and selecting a different decision model replaces all four bindings in the same single-step picker action. Older files may default missing bindings to null, but their unbound approved value is not valid consent. Defaults Off, no consent, null provider/model/endpoint/workspace binding, empty rules, seven days/500 entries, 2-second review deadline, 100 requests/session, 60-second approval deadline and 0.67 default confidence guard. Every exposed setting is in this JSON. Unknown fields are rejected, including credentials.
- `Action`: `{ requestId: string; tool: string; args: Record<string, unknown>; cwd: string }`.
- `ActionEvidence`: `{ action: Action; workspace: string; canonicalPath?: string; protectedReason?: string; sensitive: boolean; complete: boolean; fingerprint: string; reason?: string; snapshots: FileSnapshot[] }`. `FileSnapshot` and additional evidence fields belong to the core worker. Fingerprints bind exact arguments, cwd, canonical targets and relevant evidence; request IDs are not authority.
- `Decision`: `{ outcome: "allow" | "ask" | "block"; source: string; reason: string; matchedRule?: Rule }`.
Expand All @@ -40,7 +45,7 @@ All TypeScript modules use ESM `.js` import specifiers. Pure/core modules do not
3. Precedence: supported route/integrity → protected writes → exact block commands → unresolved message block (Ask) → workspace file floor and narrowly supported exact shell allows → Ask. Protected/sensitive reads are local Ask, never hosted. Path containment includes lexical protected names and canonical/symlink targets, new descendants and hard-link handling; unprovable cases ask/block.
4. No blanket shell prefixes. Exact command rule matching preserves every byte. Opaque scripts, interpreters and compositions still Ask if executable evidence is incomplete. Explain this conservative beta limitation rather than pretending a matching command proves effects.
5. All pending calls invalidate on policy/settings drift, On/Off changes, abort, session switch/tree/reload/shutdown. Off never releases held calls. Revalidate exact identity and filesystem evidence immediately before execution; consume one-shot approval once. Policy changes/decline cannot turn into a new automatic dialog loop.
6. Only a live local TUI can approve or mutate settings. Stock Pi runs slash commands before its input event and supplies no command-origin authentication: command invocation alone never authorizes anything outside that live dispatch. Toggles and decision model selection are single-step: the live TUI dispatch itself is the operator decision, so any TUI-context command dispatch — including one another extension starts through `sendUserMessage` — applies them; rule saves/deletes, log clearing and re-verify use an explicit host-owned terminal confirmation. RPC/print and model-generated answers cannot approve. Approval defaults to Decline; Escape/timeout/error means no execution.
6. Only a live local TUI can approve or mutate settings. Stock Pi runs slash commands before its input event and supplies no command-origin authentication: command invocation alone never authorizes anything outside that live dispatch. Toggles and decision model selection are single-step: the live TUI dispatch itself is the operator decision, so any TUI-context command dispatch — including one another extension starts through `sendUserMessage` — applies them; rule saves/deletes, log clearing and re-verify use an explicit host-owned terminal confirmation. RPC/print and model-generated answers cannot approve. Approval defaults to Decline; Escape/error means no execution. An unanswered local approval timeout may authorize once only with an eligible completed safe judgment, probability strictly above 0.50 and confidence meeting the configured guard. It retains lifecycle/settings epochs and full final revalidation, never lifting hard blocks or privacy restrictions.
7. Invalid or externally changed configuration visibly halts On operation until the operator re-verifies. Changing decision model selection resets disclosure consent. No keys in extension JSON, no project override widening authority.
8. Jev uses the native registry only, with consent for the selected provider/model/endpoint. Do not send source bodies or secret-bearing arguments just because a scanner found nothing. Shadow results remain local records and do not relax policy. `jev-latest` is not a verified provider-resolved pin.
9. Gate failures and logging/storage errors must not silently become permission. UI and logs escape terminal-control characters, preserve original local action text, and report actual decisions without invented chain-of-thought.
Expand Down
Loading
Loading