@vitos-pizza/vitos-pizza 0.3.1 → 0.4.1

package/AGENTS.md

@@ -7,7 +7,7 @@ Inspired by Vito's Pizzeria from Garfield — one brand, one install.
 ## Structure
 
 - **Repo root** — The distribution. `package.json` is the pi-package manifest.
-- **`packages/<module>/`** — Built-in modules (e.g. `@vitos-pizza/agent-mode`, `@vitos-pizza/question`, `@vitos-pizza/session-title`, `@vitos-pizza/permission-system`, `@vitos-pizza/subagents`, `@vitos-pizza/keybindings`). Not installed separately by users.
+- **`packages/<module>/`** — Built-in modules (e.g. `@vitos-pizza/agent-mode`, `@vitos-pizza/hypa`, `@vitos-pizza/question`, `@vitos-pizza/session-title`, `@vitos-pizza/permission-system`, `@vitos-pizza/subagents`, `@vitos-pizza/keybindings`). Not installed separately by users.
 - **`scripts/sync-pi-manifest.mjs`** — Scans `packages/*`, merges `piBundled` npm packages, and updates root `dependencies` + `pi` manifest. Honors `pi.requires` for extension load order.
 
 ## Bundled third-party Pi packages
@@ -18,7 +18,7 @@ Declare npm pi packages in root `package.json`:
 - `bundledDependencies` — include in the distribution tarball
 - `piBundled` — list read by `sync-pi-manifest.mjs` to merge `node_modules/<pkg>/` paths into the root `pi` manifest
 
-Extension load order: topological sort of `pi.requires`, with `LOCAL_ORDER` tie-break. Default: `permission-system` → `settings-preset` → `question` → `ui-enhancements` → `subagents` → `websearch` → `session-title` → `keybindings` → `agent-mode` → `todoist`. (`agent-mode` requires `keybindings` so shortcut actions register after the keybindings listener is ready.)
+Extension load order: topological sort of `pi.requires`, with `LOCAL_ORDER` tie-break. Default: `permission-system` → `settings-preset` → `hypa` → `question` → `ui-enhancements` → `subagents` → `websearch` → `session-title` → `keybindings` → `agent-mode` → `todoist`. (`agent-mode` requires `keybindings` so shortcut actions register after the keybindings listener is ready.) `piBundled` packages (e.g. `@hypabolic/pi-hypa`) load before local modules.
 
 ## Agent mode
 

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to vitos-pizza are documented here.
 
+## [Unreleased]
+
+## [0.4.1] - 2026-07-12
+
+### Added
+
+- **Multi-select questions** — `question` tool `selectType: "multi"` (Space toggle, Enter submit)
+- **Multi-question tabs** — `questions: [...]` for tabbed prompts (Tab/←→ switch; per-tab single or multi)
+
+### Changed
+
+- **Subagent hypa-only reads** — scout / planner / worker drop builtin `read`/`grep`/`find`/`ls`; exploration uses `hypa_*` only (`bash`/`edit`/`write` unchanged)
+- Plan mode footer: **Worth considering** (gaps/adjacent capabilities) replaces **Next** (no mode-switch verbs)
+- Subagent question forwarding: subprocess children use **file channel only** (skip in-process RPC)
+
+### Fixed
+
+- **Subagent question false cancel** — child no-UI RPC no longer replies `cancelled`; parent TUI receives forwarded prompts
+- **Resize recovery** — after Windows/Cursor reports `columns`/`rows` as 0 (or the border TUI is not ready yet), retry invalidate+full redraw for up to 1s so the UI recovers when size settles without another resize event
+
+## [0.4.0] - 2026-07-11
+
+### Added
+
+- **Hypa context compression** — bundles `@hypabolic/pi-hypa` (additive mode; MCP proxy off); `@vitos-pizza/hypa` seeds `~/.hypa-pi/config.json`
+- Plan mode / scout / planner / worker: `hypa_read` / `hypa_grep` / `hypa_find` / `hypa_ls` allowlisted alongside builtins
+- `scripts/sync-pi-manifest.mjs` reads root `piBundled` and merges third-party Pi package extensions
+- README **Architecture** capability map (`assets/architecture.svg` / `.png`)
+
+### Acknowledgments
+
+- [Hypa](https://github.com/Hypabolic/Hypa) / `@hypabolic/pi-hypa` (FSL-1.1-ALv2) — shell output compression and `hypa_*` tools
+
 ## [0.3.1] - 2026-07-11
 
 ### Changed
@@ -35,7 +68,7 @@ All notable changes to vitos-pizza are documented here.
 
 - **`@vitos-pizza/todoist`** — in-memory task list with TUI widget, `/todo` command, and LLM tools (`todo_add` / `todo_update` / `todo_complete` / `todo_delete`)
 - Terminal **resize recovery** in ui-enhancements — debounce + full redraw after resize (fixes blank/corrupt TUI on Windows)
-- Plan-mode **Next** footer guidance and optional scout (skip recon when context is enough; parallel scouts for independent areas)
+- Plan-mode **Worth considering** footer (gaps/adjacent capabilities; not next-steps) and optional scout (skip recon when context is enough; parallel scouts for independent areas)
 
 ### Changed
 
@@ -55,15 +88,13 @@ All notable changes to vitos-pizza are documented here.
 - Pi distribution layout: repo root as single install entry
 - `scripts/sync-pi-manifest.mjs` module assembler
 - Original logo at `assets/logo.svg`
+- Built-in modules: agent-mode, question, session-title, permission-system, subagents, keybindings, ui-enhancements, websearch
+- Agent modes: `agent` / `plan` / `execute` with `/mode` and cycle shortcuts
+- Structured `question` tool with subagent parent-session forwarding
+- Session auto-title from first meaningful user message
 
-### Removed
-
-- Nested `packages/xin-pi` aggregator
-- `@xin-pi/core`, template scaffold, postinstall symlink hack
-
-### Publishing
+### Acknowledgments
 
-- GitHub Actions publishes `@vitos-pizza/vitos-pizza` via **npm Trusted Publishing (OIDC)** — no long-lived `NPM_TOKEN`
-- Workflow: `.github/workflows/publish.yml` (triggers on `v*` tags / `workflow_dispatch`)
-- `scripts/prepare-publish.mjs` rewrites `file:` workspace deps for the npm tarball
-- First package version must be published once manually (or as a stub) before Trusted Publisher can be configured on npmjs.com
+- [Pi](https://pi.dev/) / [@earendil-works/pi-coding-agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+- [@gotgenes/pi-permission-system](https://www.npmjs.com/package/@gotgenes/pi-permission-system)
+- Pi official `question` and subagent examples

package/README.md

@@ -12,6 +12,26 @@
 
 Inspired by [Vito's Pizzeria](https://garfield.fandom.com/wiki/Vito_Cappelletti) from Garfield — Garfield's favorite pizza place.
 
+## Architecture
+
+![vitos-pizza architecture](./assets/architecture.png)
+
+Typical flow: **plan** → optional **scout** → **planner** → confirm → **execute** / **worker**. Shell output is compressed via Hypa bash rewrite; scout/planner/worker explore with `hypa_*` only (main session may still use builtin reads).
+
+| Capability | Module | What you get |
+|------------|--------|--------------|
+| Modes | `@vitos-pizza/agent-mode` | `agent` / `plan` / `execute` — `/mode`, Ctrl+. / Alt+M |
+| Permissions | `@vitos-pizza/permission-system` | allow / ask / deny presets per mode |
+| Context compression | `@hypabolic/pi-hypa` + `@vitos-pizza/hypa` | bash rewrite, `hypa_*` tools, `/hypa` (MCP proxy off) |
+| Subagents | `@vitos-pizza/subagents` | scout · planner · worker (+ title internally) |
+| Structured questions | `@vitos-pizza/question` | `question` tool |
+| Web | `@vitos-pizza/websearch` | `web_search` / `web_read` |
+| Tasks | `@vitos-pizza/todoist` | `/todo` + LLM tools |
+| Session titles | `@vitos-pizza/session-title` | auto-name after first turn |
+| TUI | `@vitos-pizza/ui-enhancements` | border status, execute prompt chrome |
+| Shortcuts | `@vitos-pizza/keybindings` | centralized `vitos-shortcuts.json` |
+| Defaults | `@vitos-pizza/settings-preset` | seed Pi settings on first session |
+
 ## Prerequisites
 
 - Node.js >= 22.19.0
@@ -21,14 +41,16 @@ Inspired by [Vito's Pizzeria](https://garfield.fandom.com/wiki/Vito_Cappelletti)
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent
 ```
 
+Context compression uses bundled [Hypa](https://github.com/Hypabolic/Hypa) (`@hypabolic/pi-hypa`). The matching platform binary comes from npm optionalDependencies (Linux / macOS / Windows, x64 / arm64). Use `/hypa` in a session for diagnostics. MCP proxy stays **off** (this distribution does not use MCP).
+
 ## Install
 
 ```bash
 # npm (recommended)
-pi install npm:@vitos-pizza/vitos-pizza@0.3.1
+pi install npm:@vitos-pizza/vitos-pizza@0.4.0
 
 # git (pinned tag)
-pi install git:github.com/xin2017338/vitos-pizza@v0.3.1
+pi install git:github.com/xin2017338/vitos-pizza@v0.4.0
 ```
 
 From source:
@@ -58,12 +80,16 @@ After install, start `pi`. Sessions are auto-titled from the first meaningful us
 ```
 vitos-pizza/                 # Pi distribution (install this)
 ├── assets/logo.svg
+├── assets/architecture.svg  # editable capability map source
+├── assets/architecture.png  # README preview (rendered from SVG)
 ├── package.json             # distro manifest + pi-package entry
 ├── AGENTS.md
 └── packages/                # built-in modules (not installed separately)
-    ├── ui-enhancements/   # @vitos-pizza/ui-enhancements — TUI display optimizations
+    ├── ui-enhancements/     # @vitos-pizza/ui-enhancements — TUI display optimizations
     ├── agent-mode/          # @vitos-pizza/agent-mode — agent / plan / execute mode switching
     ├── permission-system/   # @vitos-pizza/permission-system — allow/ask/deny gates
+    ├── settings-preset/     # @vitos-pizza/settings-preset — seed default Pi settings
+    ├── hypa/                # @vitos-pizza/hypa — Hypa defaults (additive, no MCP proxy)
     ├── question/            # @vitos-pizza/question — structured ask-user question tool
     ├── session-title/       # @vitos-pizza/session-title — auto session naming
     ├── subagents/           # @vitos-pizza/subagents — scout/planner/worker delegation
@@ -72,7 +98,7 @@ vitos-pizza/                 # Pi distribution (install this)
     └── keybindings/         # @vitos-pizza/keybindings — centralized shortcut bindings
 ```
 
-Built-in modules are wired via `scripts/sync-pi-manifest.mjs` (supports `pi.requires` load order).
+Built-in modules are wired via `scripts/sync-pi-manifest.mjs` (supports `pi.requires` load order). Third-party Pi packages listed in root `piBundled` (currently `@hypabolic/pi-hypa`) are merged into the same manifest.
 
 | Path | Role |
 |------|------|
@@ -221,6 +247,7 @@ vitos-pizza builds on the Pi ecosystem and several open-source projects. We are
 | [Claude Code TodoWrite / Task tools](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md) | `@vitos-pizza/todoist` | Complete = status done; delete only when no longer relevant (cancelled / mistaken) |
 | [@capyup/pi-basic-tools todo](https://www.npmjs.com/package/@capyup/pi-basic-tools) | `@vitos-pizza/todoist` | completed vs deleted prompt boundary for task-list tools |
 | [pi-package-template](https://github.com/S1M0N38/pi-package-template) | Repo layout | Pi package monorepo conventions |
+| [Hypa](https://github.com/Hypabolic/Hypa) (`@hypabolic/pi-hypa`) | `@vitos-pizza/hypa` + distro bundle | Additive bash rewrite / `hypa_*` tools; MCP proxy off (FSL-1.1-ALv2) |
 
 ### Runtime & tooling libraries
 

package/assets/architecture.svg

@@ -0,0 +1,97 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 620" role="img" aria-labelledby="title desc">
+  <title id="title">vitos-pizza architecture</title>
+  <desc id="desc">Pi coding agent with Vito's Pizzeria capability modules and bundled Hypa</desc>
+
+  <defs>
+    <linearGradient id="piBar" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#1e293b"/>
+      <stop offset="100%" stop-color="#334155"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#f4a442"/>
+      <stop offset="100%" stop-color="#d97706"/>
+    </linearGradient>
+    <filter id="shadow" x="-2%" y="-2%" width="104%" height="108%">
+      <feDropShadow dx="0" dy="1" stdDeviation="1.5" flood-color="#0f172a" flood-opacity="0.12"/>
+    </filter>
+  </defs>
+
+  <rect width="960" height="620" fill="#f8fafc" rx="12"/>
+
+  <text x="32" y="36" font-family="ui-sans-serif, system-ui, sans-serif" font-size="18" font-weight="700" fill="#0f172a">vitos-pizza</text>
+  <text x="140" y="36" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#64748b">Pi distribution / capability map</text>
+
+  <rect x="32" y="56" width="896" height="56" rx="10" fill="url(#piBar)" filter="url(#shadow)"/>
+  <text x="480" y="82" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="15" font-weight="600" fill="#f8fafc">Pi coding agent</text>
+  <text x="480" y="100" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="11" fill="#cbd5e1">runtime / tools / sessions / compaction</text>
+
+  <line x1="480" y1="112" x2="480" y2="136" stroke="#94a3b8" stroke-width="2"/>
+  <polygon points="480,142 474,132 486,132" fill="#94a3b8"/>
+
+  <rect x="32" y="148" width="896" height="150" rx="10" fill="#fff7ed" stroke="#fed7aa" stroke-width="1.5"/>
+  <text x="48" y="172" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" font-weight="700" fill="#c2410c">Workflow &amp; safety</text>
+
+  <g font-family="ui-sans-serif, system-ui, sans-serif">
+    <rect x="48" y="186" width="200" height="88" rx="8" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+    <text x="148" y="214" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Modes</text>
+    <text x="148" y="234" text-anchor="middle" font-size="11" fill="#64748b">agent / plan / execute</text>
+    <text x="148" y="252" text-anchor="middle" font-size="10" fill="#94a3b8">agent-mode</text>
+
+    <rect x="268" y="186" width="200" height="88" rx="8" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+    <text x="368" y="214" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Permissions</text>
+    <text x="368" y="234" text-anchor="middle" font-size="11" fill="#64748b">allow / ask / deny</text>
+    <text x="368" y="252" text-anchor="middle" font-size="10" fill="#94a3b8">permission-system</text>
+
+    <rect x="488" y="186" width="200" height="88" rx="8" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+    <text x="588" y="214" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Subagents</text>
+    <text x="588" y="234" text-anchor="middle" font-size="11" fill="#64748b">scout / planner / worker</text>
+    <text x="588" y="252" text-anchor="middle" font-size="10" fill="#94a3b8">subagents</text>
+
+    <rect x="708" y="186" width="200" height="88" rx="8" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+    <text x="808" y="214" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Question</text>
+    <text x="808" y="234" text-anchor="middle" font-size="11" fill="#64748b">structured ask-user</text>
+    <text x="808" y="252" text-anchor="middle" font-size="10" fill="#94a3b8">question</text>
+  </g>
+
+  <rect x="32" y="314" width="896" height="150" rx="10" fill="#eff6ff" stroke="#bfdbfe" stroke-width="1.5"/>
+  <text x="48" y="338" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" font-weight="700" fill="#1d4ed8">Context &amp; tools</text>
+
+  <g font-family="ui-sans-serif, system-ui, sans-serif">
+    <rect x="48" y="352" width="200" height="88" rx="8" fill="#ffffff" stroke="#fdba74" stroke-width="1.5" filter="url(#shadow)"/>
+    <rect x="48" y="352" width="6" height="88" rx="3" fill="url(#accent)"/>
+    <text x="148" y="380" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Hypa compress</text>
+    <text x="148" y="400" text-anchor="middle" font-size="11" fill="#64748b">bash rewrite / hypa_*</text>
+    <text x="148" y="418" text-anchor="middle" font-size="10" fill="#94a3b8">pi-hypa + hypa glue</text>
+
+    <rect x="268" y="352" width="200" height="88" rx="8" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+    <text x="368" y="380" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Web search</text>
+    <text x="368" y="400" text-anchor="middle" font-size="11" fill="#64748b">web_search / web_read</text>
+    <text x="368" y="418" text-anchor="middle" font-size="10" fill="#94a3b8">websearch</text>
+
+    <rect x="488" y="352" width="200" height="88" rx="8" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+    <text x="588" y="380" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Todo list</text>
+    <text x="588" y="400" text-anchor="middle" font-size="11" fill="#64748b">/todo + LLM tools</text>
+    <text x="588" y="418" text-anchor="middle" font-size="10" fill="#94a3b8">todoist</text>
+
+    <rect x="708" y="352" width="200" height="88" rx="8" fill="#ffffff" stroke="#e2e8f0" filter="url(#shadow)"/>
+    <text x="808" y="380" text-anchor="middle" font-size="13" font-weight="700" fill="#0f172a">Session title</text>
+    <text x="808" y="400" text-anchor="middle" font-size="11" fill="#64748b">auto-name after turn 1</text>
+    <text x="808" y="418" text-anchor="middle" font-size="10" fill="#94a3b8">session-title</text>
+  </g>
+
+  <rect x="32" y="480" width="896" height="72" rx="10" fill="#f1f5f9" stroke="#e2e8f0" stroke-width="1.5"/>
+  <text x="48" y="504" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" font-weight="700" fill="#475569">UX &amp; defaults</text>
+
+  <g font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" fill="#0f172a">
+    <rect x="48" y="516" width="280" height="24" rx="6" fill="#ffffff" stroke="#e2e8f0"/>
+    <text x="188" y="532" text-anchor="middle">UI enhancements / TUI chrome</text>
+
+    <rect x="340" y="516" width="280" height="24" rx="6" fill="#ffffff" stroke="#e2e8f0"/>
+    <text x="480" y="532" text-anchor="middle">Keybindings / Ctrl+. / Alt+M</text>
+
+    <rect x="632" y="516" width="280" height="24" rx="6" fill="#ffffff" stroke="#e2e8f0"/>
+    <text x="772" y="532" text-anchor="middle">Settings preset / first-run seed</text>
+  </g>
+
+  <text x="480" y="590" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="11" fill="#64748b">piBundled = @hypabolic/pi-hypa  |  local modules = @vitos-pizza/*</text>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/vitos-pizza",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"description": "Vito's Pizzeria — a Pi distribution (Garfield-approved)",
 	"publishConfig": {
 		"access": "public",
@@ -37,33 +37,43 @@
 		"typescript": "^5.8.0"
 	},
 	"dependencies": {
+		"@hypabolic/pi-hypa": "^0.1.10",
 		"typebox": "^1.1.38",
-		"@vitos-pizza/agent-mode": "0.3.1",
-		"@vitos-pizza/keybindings": "0.3.1",
-		"@vitos-pizza/permission-system": "0.3.1",
-		"@vitos-pizza/question": "0.3.1",
-		"@vitos-pizza/session-title": "0.3.1",
-		"@vitos-pizza/settings-preset": "0.3.1",
-		"@vitos-pizza/subagents": "0.3.1",
-		"@vitos-pizza/todoist": "0.3.1",
-		"@vitos-pizza/ui-enhancements": "0.3.1",
-		"@vitos-pizza/websearch": "0.3.1"
+		"@vitos-pizza/agent-mode": "0.4.1",
+		"@vitos-pizza/hypa": "0.4.1",
+		"@vitos-pizza/keybindings": "0.4.1",
+		"@vitos-pizza/permission-system": "0.4.1",
+		"@vitos-pizza/question": "0.4.1",
+		"@vitos-pizza/session-title": "0.4.1",
+		"@vitos-pizza/settings-preset": "0.4.1",
+		"@vitos-pizza/subagents": "0.4.1",
+		"@vitos-pizza/todoist": "0.4.1",
+		"@vitos-pizza/ui-enhancements": "0.4.1",
+		"@vitos-pizza/websearch": "0.4.1"
 	},
 	"bundledDependencies": [
+		"@hypabolic/pi-hypa",
 		"@vitos-pizza/agent-mode",
+		"@vitos-pizza/hypa",
 		"@vitos-pizza/keybindings",
 		"@vitos-pizza/permission-system",
 		"@vitos-pizza/question",
 		"@vitos-pizza/session-title",
+		"@vitos-pizza/settings-preset",
 		"@vitos-pizza/subagents",
+		"@vitos-pizza/todoist",
 		"@vitos-pizza/ui-enhancements",
 		"@vitos-pizza/websearch"
 	],
-	"piBundled": [],
+	"piBundled": [
+		"@hypabolic/pi-hypa"
+	],
 	"pi": {
 		"extensions": [
+			"node_modules/@hypabolic/pi-hypa/extensions",
 			"node_modules/@vitos-pizza/permission-system/extensions",
 			"node_modules/@vitos-pizza/settings-preset/extensions",
+			"node_modules/@vitos-pizza/hypa/extensions",
 			"node_modules/@vitos-pizza/question/extensions",
 			"node_modules/@vitos-pizza/ui-enhancements/extensions",
 			"node_modules/@vitos-pizza/subagents/extensions",

package/packages/agent-mode/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/agent-mode",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"description": "Centralized agent / plan / execute mode switching for Vito's Pizzeria",
 	"type": "module",
 	"license": "MIT",
@@ -13,8 +13,8 @@
 		"lint:fix": "biome check --write ."
 	},
 	"dependencies": {
-		"@vitos-pizza/keybindings": "0.3.1",
-		"@vitos-pizza/permission-system": "0.3.1"
+		"@vitos-pizza/keybindings": "0.4.1",
+		"@vitos-pizza/permission-system": "0.4.1"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*"

package/packages/agent-mode/src/plan-instructions.ts

@@ -3,6 +3,10 @@ export const PLAN_MODE_TOOLS = [
 	"grep",
 	"find",
 	"ls",
+	"hypa_read",
+	"hypa_grep",
+	"hypa_find",
+	"hypa_ls",
 	"question",
 	"subagent",
 	"wait",
@@ -23,26 +27,34 @@ This supersedes conflicting skill or prior guidance about implementing code or c
 - Prefer \`question\` for mutually exclusive choices (2–5 options); skip when context is enough. Available to main, scout, and planner.
 
 **Exploration**
-- Scout is optional — only for unfamiliar or multi-file recon. Parallel scouts via \`subagent({ tasks: [...] })\` for independent areas, then planner. Light lookups: use read/grep/find/ls yourself.
+- Scout is optional — only for unfamiliar or multi-file recon. Parallel scouts via \`subagent({ tasks: [...] })\` for independent areas, then planner.
+- Scout/planner use \`hypa_read\` / \`hypa_grep\` / \`hypa_find\` / \`hypa_ls\` only. Main session: prefer hypa_*; fall back to read/grep/find/ls if needed.
 - Web tools only for current external facts outside the repo.
 
 **Delegation**
 - Enough context → \`subagent({ agent: "planner", task })\`
 - Need recon → \`subagent({ chain: [scout, planner] })\`
 
-**Optional Next footer** (2–3 one-line reply verbs) when the next step is not obvious:
+**Optional open-questions footer** (2–4 one-line prompts) only when the plan may miss scope or adjacent capabilities the user has not clarified. Soft guidance — not next-steps, not mode-switching:
 
 \`\`\`
-**Next**
-- Confirm → \`/mode execute\` (or Ctrl+. / Alt+M)
-- Say what to change if scope is off
-\`\`\``;
+**Worth considering**
+- <gap or adjacent capability the user may not have decided yet>?
+- <in/out of scope this round>?
+\`\`\`
+
+Rules:
+- Ask about omissions, edge cases, related features, or "do you also need X?"
+- Do NOT list mode-switching or how-to-proceed verbs (e.g. \`/mode execute\`, Ctrl+.)
+- Do NOT restate the plan as todos
+- Prefer \`question\` for mutually exclusive choices; use this footer for soft, optional prompts
+- Skip the footer when scope is already clear`;
 
 export const PLAN_MODE_MESSAGE = `[PLAN MODE ACTIVE]
 
 Read-only planning. No write/edit/bash/worker.
 Clarify with \`question\` when needed. Scout only if recon is required; otherwise planner.
-Return the plan and wait; optionally a short **Next** footer.`;
+Prefer hypa_* read tools when available. Return the plan and wait; optionally a short **Worth considering** footer for gaps/adjacent capabilities.`;
 
 export const PLAN_MODE_ENDED_MESSAGE = `[PLAN MODE ENDED]
 

package/packages/hypa/extensions/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @vitos-pizza/hypa — seed Hypa Pi defaults (additive, MCP proxy off).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { seedHypaPiConfigIfMissing } from "../src/seed.ts";
+
+export default function (pi: ExtensionAPI) {
+	let seeded = false;
+
+	pi.on("session_start", async (_event, _ctx) => {
+		if (seeded) return;
+		seeded = true;
+		seedHypaPiConfigIfMissing();
+	});
+}

package/packages/hypa/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@vitos-pizza/hypa",
+	"version": "0.4.1",
+	"description": "Vito's Pizzeria Hypa defaults — additive mode, MCP proxy off, config seed",
+	"type": "module",
+	"license": "MIT",
+	"private": true,
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"smoke": "node scripts/smoke.mjs",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write ."
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"vitest": "^3.2.4"
+	}
+}

package/packages/hypa/scripts/smoke.mjs

@@ -0,0 +1,50 @@
+/**
+ * Smoke: resolve platform Hypa binary and run --version.
+ * Exit 0 = ok; 2 = binary missing (skip on unsupported install).
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "../../..");
+const require = createRequire(join(root, "package.json"));
+
+function resolveHypaBin() {
+	const platformKey = `${process.platform}-${process.arch}`;
+	const map = {
+		"win32-x64": "@hypabolic/hypa-win32-x64",
+		"win32-arm64": "@hypabolic/hypa-win32-arm64",
+		"linux-x64": "@hypabolic/hypa-linux-x64",
+		"linux-arm64": "@hypabolic/hypa-linux-arm64",
+		"darwin-x64": "@hypabolic/hypa-darwin-x64",
+		"darwin-arm64": "@hypabolic/hypa-darwin-arm64",
+	};
+	const pkgName = map[platformKey];
+	if (!pkgName) {
+		console.error(`Unsupported platform: ${platformKey}`);
+		process.exit(2);
+	}
+	try {
+		const pkgJson = require.resolve(`${pkgName}/package.json`);
+		const binName = process.platform === "win32" ? "hypa.exe" : "hypa";
+		const binPath = join(dirname(pkgJson), "bin", binName);
+		if (!existsSync(binPath)) {
+			console.error(`Binary missing: ${binPath}`);
+			process.exit(2);
+		}
+		return binPath;
+	} catch (err) {
+		console.error(`Could not resolve ${pkgName}:`, err);
+		process.exit(2);
+	}
+}
+
+const bin = resolveHypaBin();
+const result = spawnSync(bin, ["--version"], { encoding: "utf8" });
+if (result.status !== 0) {
+	console.error(result.stderr || result.stdout || "hypa --version failed");
+	process.exit(result.status ?? 1);
+}
+console.log(`hypa smoke ok: ${result.stdout.trim() || bin}`);

package/packages/hypa/src/config.ts

@@ -0,0 +1,37 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Default Hypa Pi extension config for Vito's Pizzeria (additive, no MCP). */
+export const DEFAULT_HYPA_PI_CONFIG = {
+	mode: "additive",
+	mcpProxyEnabled: false,
+} as const;
+
+export type HypaPiConfig = {
+	mode: string;
+	mcpProxyEnabled: boolean;
+	[key: string]: unknown;
+};
+
+/**
+ * Resolve config path the same way @hypabolic/pi-hypa documents:
+ * HYPA_PI_CONFIG, or ~/.hypa-pi/config.json. Empty / "none" means skip seeding.
+ */
+export function resolveHypaPiConfigPath(
+	env: NodeJS.ProcessEnv = process.env,
+	home: string = homedir(),
+): string | null {
+	const raw = env.HYPA_PI_CONFIG;
+	if (raw !== undefined) {
+		const trimmed = raw.trim();
+		if (trimmed === "" || trimmed.toLowerCase() === "none") {
+			return null;
+		}
+		return trimmed;
+	}
+	return join(home, ".hypa-pi", "config.json");
+}
+
+export function formatDefaultHypaPiConfig(): string {
+	return `${JSON.stringify(DEFAULT_HYPA_PI_CONFIG, null, "\t")}\n`;
+}

package/packages/hypa/src/seed.ts

@@ -0,0 +1,22 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import {
+	formatDefaultHypaPiConfig,
+	resolveHypaPiConfigPath,
+} from "./config.ts";
+
+/**
+ * Seed ~/.hypa-pi/config.json when missing. Never overwrites an existing file.
+ * @returns true if a new file was written
+ */
+export function seedHypaPiConfigIfMissing(
+	env: NodeJS.ProcessEnv = process.env,
+): boolean {
+	const path = resolveHypaPiConfigPath(env);
+	if (!path) return false;
+	if (existsSync(path)) return false;
+
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, formatDefaultHypaPiConfig(), "utf8");
+	return true;
+}

package/packages/hypa/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"allowImportingTsExtensions": true,
+		"types": ["node"]
+	},
+	"include": [
+		"extensions/**/*.ts",
+		"src/**/*.ts",
+		"tests/**/*.ts"
+	],
+	"exclude": ["node_modules"]
+}

package/packages/keybindings/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/keybindings",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"description": "Centralized keyboard shortcut registry for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",

package/packages/permission-system/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/permission-system",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"description": "Permission enforcement for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",
@@ -18,7 +18,7 @@
 		"lint:fix": "biome check --write ."
 	},
 	"dependencies": {
-		"@vitos-pizza/keybindings": "0.3.1",
+		"@vitos-pizza/keybindings": "0.4.1",
 		"tree-sitter-bash": "^0.25.1",
 		"web-tree-sitter": "^0.25.10",
 		"zod": "^3.25.76"

package/packages/permission-system/presets/default.json

@@ -5,6 +5,12 @@
 		"grep": "allow",
 		"find": "allow",
 		"ls": "allow",
+		"hypa_read": "allow",
+		"hypa_grep": "allow",
+		"hypa_find": "allow",
+		"hypa_ls": "allow",
+		"hypa_shell": "ask",
+		"hypa_mcp_proxy": "deny",
 		"web_search": "ask",
 		"web_read": "ask",
 		"path": {
@@ -28,6 +34,8 @@
 			"npm test *": "allow",
 			"npm run typecheck": "allow",
 			"npm run lint": "allow",
+			"hypa *": "ask",
+			"hypa -c *": "ask",
 			"rm -rf *": "deny",
 			"sudo *": "ask"
 		},