@itc-steve/pi-ask-complete 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+First public release.
+
+- Bottom-panel `ask_user` (multi-question, transcript stays visible)
+- Permission gate for `bash` / `write` / `edit` with path wildcards
+- `permission.json` rules (bash / tools / paths); seeds from example when missing
+- Session / permanent allow; deny with reason
+- Chain / substitution unit checks; path-deny on bash args; sudo → `sudo_run` redirect
+- `/yolo` session mode: auto-approve every gate **ask** (including globs); **deny** and sudo redirect still enforced; `ask_user` untouched
+- `/permissions` lists allows/denies and YOLO state
+- Herdr attention: ding only when the pane is backgrounded

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InfoTrust Corporation
+
+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,147 @@
+# pi-ask-complete
+
+Bottom-panel **ask_user** + **permission gate** (bash / write / edit + path wildcards) for the [Pi coding agent](https://pi.dev).
+
+## Gate
+
+| Tool | Behavior |
+| --- | --- |
+| `bash` | Every unit (segments, `$(...)`, backticks) is **checked**; path deny args block. **One prompt per tool call** (not per unit). Session/permanent allow applies to each unique base that needed approval |
+| `write` / `edit` | Path rules first, then tool rule, else ask |
+| `read` | Allowed by default; only auto-**deny** on matching path deny rules — never prompts for normal reads |
+
+### Default bash allows
+
+Seeded `permission.json` allows non-destructive **explore / troubleshoot** commands
+out of the box (listing, read/print text, search, process/system info, network
+diagnostics, checksums, git read-only subcommands). `find`/`awk`/`curl`/`fd` etc are
+**ask** (not allow) — they are general exec engines.
+Path **deny** rules still block secret files even when the binary is allowed
+(`cat .env` → deny).
+
+Still **ask** (not pre-allowed): writers and mutators — `rm`, `mv`, `cp`, `mkdir`,
+`touch`, `sed`, `tee`, `chmod`, package managers, `git push` / `commit` / `reset`,
+shells (`bash`/`python`/`node`), etc. Catastrophic commands stay **deny**:
+`mkfs`, `dd`, `shutdown`, `reboot`, `poweroff`, `halt`.
+
+Panel options: **Allow this** · **Allow for this session** · **Allow permanently** · **Deny with reason**
+
+- **Session** — in-memory until the agent session ends (not written to disk).
+  For a bash pipeline, remembers **every** real base that still needed approval.
+- **Permanent** — live immediately + written to `permission.json`
+  - bash → **primary base only** (`herdr … | python3 … | sed …` → only `herdr`)
+  - write/edit → **exact file path** in `paths`
+
+## Path wildcards
+
+```
+*     any chars except /
+**    any chars including /
+?     one char except /
+```
+
+**Most-specific pattern wins.** The pattern that pins more of the filename tail
+takes precedence regardless of allow/deny, so `**/.env` **deny** beats a broad
+`Projects/**` **allow** for `Projects/app/.env`. Exact-specificity ties → deny wins.
+
+Bash commands are decomposed for **policy**: chains (`;` `|` `&&`) and substitutions
+each become a unit that must independently pass. Path-like args are checked against
+path deny rules — so `ls; rm -rf x` and `cat .env` no longer slip through an allowed
+prefix. The user still sees **one** prompt for the whole line; choosing session or
+permanent allow covers every base that still needed approval.
+(Heuristic, not a full shell parser — `$VAR` expansion isn't resolved.)
+
+| Path | With example config |
+| --- | --- |
+| `.env` | deny |
+| `prod.env` | deny |
+| `.env.example` | **allow** |
+| `.ssh/id_rsa` | deny |
+| `src/main.ts` | ask (no rule) |
+
+## permission.json
+
+All policy is in JSON — **nothing is hard-blocked in code**.
+
+`~/.pi/agent/permission.json` (or `$PI_CODING_AGENT_DIR/permission.json`).
+
+If the file is **missing** (deleted or never created), load seeds it from
+`permission.json.example` and re-creates the file on disk so you can edit it.
+If the file is **present**, it is obeyed verbatim — even a single rule or an
+empty `{}`. Existing files are never merged with, unioned against, or
+overwritten by the example defaults.
+
+`sudo_run` (from pix-sudo) is **not** gated here — its PAM password prompt is the
+approve/deny step. Raw `sudo`/`doas` in bash is redirected to `sudo_run`.
+
+```json
+{
+  "bash": {
+    "ls": "allow",
+    "cat": "allow",
+    "rg": "allow",
+    "git status*": "allow",
+    "dd": "deny"
+  },
+  "tools": {
+    "read": "allow",
+    "write": "ask"
+  },
+  "paths": {
+    "**/.env.example": "allow",
+    "**/*.env": "deny",
+    "/home/you/Projects/**": "allow"
+  }
+}
+```
+
+Full starter list: `permission.json.example`.
+
+## Install
+
+```bash
+pi install npm:@itc-steve/pi-ask-complete
+```
+
+Or from a local checkout:
+
+```bash
+pi install /path/to/pi-ask-complete
+# packages entry: "npm:@itc-steve/pi-ask-complete"
+# or: "../../Projects/pi-ask-complete"
+```
+
+`/reload` after changes. `/permissions` shows current allows.
+
+## `/yolo`
+
+Session-scoped mode that auto-approves everything that would otherwise **ask**
+(bash / write / edit / unresolved globs — the permission panel stays quiet).
+
+- **Does:** skip the permission panel for every gate `ask` (including globs/`$VAR`).
+- **Does not bypass:** path/bash/tool **deny** rules, or the `sudo`/`doas` → `sudo_run` redirect.
+- **Does not touch:** `ask_user` (model questions still prompt you).
+- **Dies with the session** — memory only; nothing written to `permission.json`. Cleared on `session_start`.
+
+`/yolo` toggles · `/yolo on` · `/yolo off`. When on, `/permissions` shows the YOLO line.
+
+## ask_user
+
+LLM-callable multi-question bottom panel (`overlay: false` — transcript stays visible). Prefer this over plain-text multi-choice.
+
+## Threat model / limits
+
+This is a **heuristic agent gate**, not a sandbox or seccomp profile. The model is still the adversary; the gate reduces accidents and casual exfil, it does not stop a determined local process.
+
+| Covered | Not a full guarantee |
+| --- | --- |
+| Chain / pipe / `&&` units each checked | Full shell AST / exotic quoting |
+| `$(…)`, backticks, process subs as units | Nested quote mazes |
+| Path deny on args, redirects, `if=`, `@file`, git `rev:path` | Paths only after real `$VAR` expansion |
+| Glued operators (`cat .env;true`) cleaned | Every future shell metacharacter |
+| Unresolved globs / braces / `$''` → **ask** | Interpreter `-c` payloads (permanent-allow `python3`/`bash` is high blast radius) |
+| Any unit starting with `sudo`/`doas` → redirect | Root via other helpers |
+| Corrupt / non-object `permission.json` keeps last good rules | First load of a corrupt file (everything asks) |
+| Missing `permission.json` re-seeds from example (fail closed) | Broken install with no example (path deny-all via noPolicy) |
+
+**Allow permanently** stores a **binary base** (e.g. all `cat`) or an **exact file path** for write/edit. Prefer session allow for interpreters.

package/index.ts

@@ -0,0 +1,34 @@
+/**
+ * pi-ask-complete
+ *
+ * Bottom-panel ask_user (transcript stays visible) + bash permission gate
+ * that reuses the same panel for Allow / Allow permanently / Deny with reason.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAskUser } from "./src/ask-user.ts";
+import { bindHerdrAttention } from "./src/herdr-attention.ts";
+import { registerPermission } from "./src/permission.ts";
+import { PermissionStore } from "./src/permission-store.ts";
+
+export default function piCompleteAsk(pi: ExtensionAPI) {
+  const store = new PermissionStore();
+
+  // Herdr dings only when this pane is backgrounded (see herdr-attention.ts).
+  bindHerdrAttention(pi.events);
+  registerAskUser(pi);
+  registerPermission(pi, store);
+
+  // Nudge the model to use ask_user / sudo_run correctly.
+  pi.on("before_agent_start", async (event) => {
+    const tip =
+      "\n\n# User interaction tools\n" +
+      "- Use `ask_user` whenever you need the user to choose between options, confirm a decision, or answer a clarifying question. Do not present multi-choice questions as plain text when `ask_user` is available.\n" +
+      "- System shell commands are gated automatically; you do not need to call `ask_permission` for normal bash — the user will be prompted.\n" +
+      "- Never run `sudo`/`doas` via bash. Use `sudo_run` with the command (no sudo prefix) and a short reason; the user will approve and enter their password.\n";
+
+    return {
+      systemPrompt: (event.systemPrompt ?? "") + tip,
+    };
+  });
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@itc-steve/pi-ask-complete",
+  "version": "0.1.0",
+  "description": "Pi extension: bottom-panel ask_user + bash permission gate (Allow / Allow permanently / Deny with reason) writing ~/.pi/agent/permission.json",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "ask-user",
+    "permissions",
+    "yolo"
+  ],
+  "author": {
+    "name": "itc-steve",
+    "url": "https://github.com/itc-steve"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itc-steve/pi-ask-complete.git"
+  },
+  "bugs": {
+    "url": "https://github.com/itc-steve/pi-ask-complete/issues"
+  },
+  "homepage": "https://github.com/itc-steve/pi-ask-complete#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "./index.ts",
+  "files": [
+    "index.ts",
+    "src",
+    "permission.json.example",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "prepublishOnly": "npm test"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": { "optional": true },
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
+  }
+}

package/permission.json.example

@@ -0,0 +1,299 @@
+{
+  "bash": {
+    "ls": "allow",
+    "dir": "allow",
+    "vdir": "allow",
+    "tree": "allow",
+    "eza": "allow",
+    "exa": "allow",
+    "lsd": "allow",
+    "pwd": "allow",
+    "cd": "allow",
+    "pushd": "allow",
+    "popd": "allow",
+    "dirs": "allow",
+    "locate": "allow",
+    "which": "allow",
+    "type": "allow",
+    "whereis": "allow",
+    "file": "allow",
+    "stat": "allow",
+    "namei": "allow",
+    "readlink": "allow",
+    "realpath": "allow",
+    "basename": "allow",
+    "dirname": "allow",
+    "pathchk": "allow",
+    "du": "allow",
+    "df": "allow",
+    "dust": "allow",
+    "duf": "allow",
+    "free": "allow",
+    "lsblk": "allow",
+    "blkid": "allow",
+    "lsattr": "allow",
+    "getfacl": "allow",
+    "findmnt": "allow",
+    "lscpu": "allow",
+    "lsmem": "allow",
+    "lsipc": "allow",
+    "lslogins": "allow",
+    "lspci": "allow",
+    "lsusb": "allow",
+    "lshw": "allow",
+    "ps": "allow",
+    "procs": "allow",
+    "pgrep": "allow",
+    "pidof": "allow",
+    "top": "allow",
+    "htop": "allow",
+    "btop": "allow",
+    "pstree": "allow",
+    "lsof": "allow",
+    "fuser": "allow",
+    "uname": "allow",
+    "hostname": "allow",
+    "arch": "allow",
+    "nproc": "allow",
+    "id": "allow",
+    "whoami": "allow",
+    "groups": "allow",
+    "who": "allow",
+    "w": "allow",
+    "last": "allow",
+    "lastlog": "allow",
+    "uptime": "allow",
+    "date": "allow",
+    "cal": "allow",
+    "vmstat": "allow",
+    "iostat": "allow",
+    "mpstat": "allow",
+    "sar": "allow",
+    "dmesg": "allow",
+    "journalctl": "allow",
+    "getconf": "allow",
+    "getent": "allow",
+    "locale": "allow",
+    "ss": "allow",
+    "netstat": "allow",
+    "ping": "allow",
+    "ping6": "allow",
+    "traceroute": "allow",
+    "traceroute6": "allow",
+    "tracepath": "allow",
+    "mtr": "allow",
+    "dig": "allow",
+    "nslookup": "allow",
+    "host": "allow",
+    "ip": "allow",
+    "cat": "allow",
+    "tac": "allow",
+    "head": "allow",
+    "tail": "allow",
+    "less": "allow",
+    "more": "allow",
+    "bat": "allow",
+    "batcat": "allow",
+    "wc": "allow",
+    "nl": "allow",
+    "od": "allow",
+    "hexdump": "allow",
+    "xxd": "allow",
+    "strings": "allow",
+    "grep": "allow",
+    "egrep": "allow",
+    "fgrep": "allow",
+    "rg": "allow",
+    "ag": "allow",
+    "ack": "allow",
+    "cut": "allow",
+    "sort": "allow",
+    "uniq": "allow",
+    "tr": "allow",
+    "column": "allow",
+    "paste": "allow",
+    "join": "allow",
+    "comm": "allow",
+    "diff": "allow",
+    "diff3": "allow",
+    "sdiff": "allow",
+    "cmp": "allow",
+    "colordiff": "allow",
+    "jq": "allow",
+    "yq": "allow",
+    "fold": "allow",
+    "fmt": "allow",
+    "expand": "allow",
+    "unexpand": "allow",
+    "rev": "allow",
+    "tput": "allow",
+    "printf": "allow",
+    "echo": "allow",
+    "true": "allow",
+    "false": "allow",
+    "test": "allow",
+    "expr": "allow",
+    "seq": "allow",
+    "md5sum": "allow",
+    "sha1sum": "allow",
+    "sha224sum": "allow",
+    "sha256sum": "allow",
+    "sha384sum": "allow",
+    "sha512sum": "allow",
+    "cksum": "allow",
+    "sum": "allow",
+    "b2sum": "allow",
+    "crc32": "allow",
+    "zcat": "allow",
+    "zless": "allow",
+    "zgrep": "allow",
+    "bzcat": "allow",
+    "bzgrep": "allow",
+    "xzcat": "allow",
+    "xzgrep": "allow",
+    "lzcat": "allow",
+    "zstdcat": "allow",
+    "zstdless": "allow",
+    "tar -t*": "allow",
+    "tar --list*": "allow",
+    "unzip -l*": "allow",
+    "gzip -l*": "allow",
+    "env": "allow",
+    "printenv": "allow",
+    "export": "allow",
+    "set": "allow",
+    "declare": "allow",
+    "alias": "allow",
+    "history": "allow",
+    "help": "allow",
+    "man": "allow",
+    "info": "allow",
+    "whatis": "allow",
+    "apropos": "allow",
+    "compgen": "allow",
+    "strace": "allow",
+    "ltrace": "allow",
+    "nm": "allow",
+    "objdump": "allow",
+    "readelf": "allow",
+    "ldd": "allow",
+    "git status*": "allow",
+    "git log*": "allow",
+    "git diff*": "allow",
+    "git show*": "allow",
+    "git rev-parse*": "allow",
+    "git rev-list*": "allow",
+    "git ls-files*": "allow",
+    "git ls-tree*": "allow",
+    "git ls-remote*": "allow",
+    "git blame*": "allow",
+    "git describe*": "allow",
+    "git remote -v": "allow",
+    "git remote show*": "allow",
+    "git branch": "allow",
+    "git branch -a": "allow",
+    "git branch -v*": "allow",
+    "git branch --show-current": "allow",
+    "git stash list*": "allow",
+    "git config --get*": "allow",
+    "git config --list*": "allow",
+    "git config -l*": "allow",
+    "git tag": "allow",
+    "git tag -l*": "allow",
+    "git shortlog*": "allow",
+    "git reflog*": "allow",
+    "git cat-file*": "allow",
+    "git name-rev*": "allow",
+    "git symbolic-ref*": "allow",
+    "git check-ignore*": "allow",
+    "mkfs": "deny",
+    "mkfs.fat": "deny",
+    "mkfs.vfat": "deny",
+    "mkfs.exfat": "deny",
+    "mkfs.ext2": "deny",
+    "mkfs.ext3": "deny",
+    "mkfs.ext4": "deny",
+    "mkfs.xfs": "deny",
+    "mkfs.btrfs": "deny",
+    "mkfs.ntfs": "deny",
+    "mkfs.f2fs": "deny",
+    "mkfs.minix": "deny",
+    "dd": "deny",
+    "shutdown": "deny",
+    "reboot": "deny",
+    "poweroff": "deny",
+    "halt": "deny",
+    "fdisk": "deny",
+    "parted": "deny",
+    "sgdisk": "deny",
+    "wipefs": "deny",
+    "shred": "deny",
+    "mkswap": "deny",
+    "blkdiscard": "deny"
+  },
+  "tools": {
+    "read": "allow",
+    "write": "ask",
+    "edit": "ask"
+  },
+  "paths": {
+    "**/.env.example": "allow",
+    "**/*.env.example": "allow",
+    "**/.env.sample": "allow",
+    "**/.env.template": "allow",
+    "**/.env.sample.*": "allow",
+    "**/env.example": "allow",
+    "**/id_rsa.pub": "allow",
+    "**/id_ed25519.pub": "allow",
+    "**/id_ecdsa.pub": "allow",
+    "**/id_dsa.pub": "allow",
+    "**/.env": "deny",
+    "**/*.env": "deny",
+    "**/.env.local": "deny",
+    "**/.env.development": "deny",
+    "**/.env.production": "deny",
+    "**/.env.staging": "deny",
+    "**/.env.test": "deny",
+    "**/.env.rc": "deny",
+    "**/.env.*.local": "deny",
+    "**/*.pem": "deny",
+    "**/*.key": "deny",
+    "**/*.p12": "deny",
+    "**/*.pfx": "deny",
+    "**/*.jks": "deny",
+    "**/id_rsa": "deny",
+    "**/id_ed25519": "deny",
+    "**/id_ecdsa": "deny",
+    "**/id_dsa": "deny",
+    "**/.ssh/**": "deny",
+    "**/.aws/**": "deny",
+    "**/.gnupg/**": "deny",
+    "**/.netrc": "deny",
+    "**/.npmrc": "deny",
+    "**/.pypirc": "deny",
+    "**/credentials.json": "deny",
+    "**/credentials.yml": "deny",
+    "**/credentials.yaml": "deny",
+    "**/service-account*.json": "deny",
+    "**/secrets.json": "deny",
+    "**/secrets.yml": "deny",
+    "**/secrets.yaml": "deny",
+    "**/*-credentials.json": "deny",
+    "/etc/shadow": "deny",
+    "/etc/gshadow": "deny",
+    "/etc/sudoers": "deny",
+    "/etc/sudoers.d/**": "deny",
+    "/etc/ssh/ssh_host_*_key": "deny",
+    "**/.docker/config.json": "deny",
+    "**/kubeconfig": "deny",
+    "**/.kube/config": "deny",
+    "**/*.tfstate": "deny",
+    "**/.git-credentials": "deny",
+    "**/.config/gh/hosts.yml": "deny",
+    "**/.bash_history": "deny",
+    "**/.zsh_history": "deny",
+    "**/.mysql_history": "deny",
+    "**/.psql_history": "deny",
+    "**/.python_history": "deny"
+  }
+}