@vitos-pizza/vitos-pizza 0.3.0 → 0.4.0

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,35 @@
 
 All notable changes to vitos-pizza are documented here.
 
+## [Unreleased]
+
+## [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
+
+- **Prompt optimization** — plan mode: authoritative short system instructions + supersede; sticky reminder without JSON dumps
+- Subagents skill: mode constraints one-liners; plan vs execute/agent examples split (no worker chain in plan)
+- Scout / planner / worker / title prompts tightened; planner output adds `## 功能验收`
+- Hide internal `title` agent from public subagent listings
+- `web_search` guidelines: prefer local tools; use web only for current external facts
+
+### Acknowledgments
+
+- Claude Code plan-mode reminder pattern and OpenAI Codex base-instruction style (prompt craft reference)
+
 ## [0.3.0] - 2026-07-11
 
 ### Added

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; prefer `hypa_*` read tools when exploring.
+
+| 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.0
+pi install npm:@vitos-pizza/vitos-pizza@0.4.0
 
 # git (pinned tag)
-pi install git:github.com/xin2017338/vitos-pizza@v0.3.0
+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 |
 |------|------|
@@ -117,7 +143,7 @@ subagent({ tasks: [{ agent: "scout", task: "scan src" }, { agent: "scout", task:
 subagent({ agent: "worker", task: "...", async: true })  →  wait({ id: "<runId>" })
 ```
 
-Built-in agents: **scout**, **planner**, **worker**, **title** (session auto-naming). Other modules request runs over `pi.events` RPC — import `requestSubagentRun` from `@vitos-pizza/subagents/rpc/client`.
+Built-in agents: **scout**, **planner**, **worker**. Other modules request runs over `pi.events` RPC — import `requestSubagentRun` from `@vitos-pizza/subagents/rpc/client`.
 
 ## Web search
 
@@ -216,9 +242,12 @@ vitos-pizza builds on the Pi ecosystem and several open-source projects. We are
 | [Pi `border-status-editor` example](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/border-status-editor.ts) | `@vitos-pizza/ui-enhancements` | Editor-border status bar (model, thinking, context, cwd, git) |
 | [sf-welcome](https://github.com/salesforce/sf-pi/blob/main/extensions/sf-welcome/index.ts) | `@vitos-pizza/ui-enhancements` | Welcome header session lifecycle and tips layout |
 | **Claude Code** permission UX | Agent modes (`agent` / `plan` / `execute`) | Preset naming and mode-switching inspiration (not a code dependency) |
+| [Claude Code system prompts](https://github.com/CANYOUFINDIT/claude-code-system-prompts) (plan-mode reminders) | `@vitos-pizza/agent-mode` plan instructions | Short sticky reminder + supersede pattern for plan mode (not a code dependency) |
+| [OpenAI Codex base instructions](https://github.com/openai/codex/blob/main/codex-rs/protocol/src/prompts/base_instructions/default.md) | Plan / subagent prompt style | Concise hard rules and precedence over conflicting guidance (not a code dependency) |
 | [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.0",
+	"version": "0.4.0",
 	"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.0",
-		"@vitos-pizza/keybindings": "0.3.0",
-		"@vitos-pizza/permission-system": "0.3.0",
-		"@vitos-pizza/question": "0.3.0",
-		"@vitos-pizza/session-title": "0.3.0",
-		"@vitos-pizza/settings-preset": "0.3.0",
-		"@vitos-pizza/subagents": "0.3.0",
-		"@vitos-pizza/todoist": "0.3.0",
-		"@vitos-pizza/ui-enhancements": "0.3.0",
-		"@vitos-pizza/websearch": "0.3.0"
+		"@vitos-pizza/agent-mode": "0.4.0",
+		"@vitos-pizza/hypa": "0.4.0",
+		"@vitos-pizza/keybindings": "0.4.0",
+		"@vitos-pizza/permission-system": "0.4.0",
+		"@vitos-pizza/question": "0.4.0",
+		"@vitos-pizza/session-title": "0.4.0",
+		"@vitos-pizza/settings-preset": "0.4.0",
+		"@vitos-pizza/subagents": "0.4.0",
+		"@vitos-pizza/todoist": "0.4.0",
+		"@vitos-pizza/ui-enhancements": "0.4.0",
+		"@vitos-pizza/websearch": "0.4.0"
 	},
 	"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.0",
+	"version": "0.4.0",
 	"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.0",
-		"@vitos-pizza/permission-system": "0.3.0"
+		"@vitos-pizza/keybindings": "0.4.0",
+		"@vitos-pizza/permission-system": "0.4.0"
 	},
 	"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",
@@ -12,77 +16,38 @@ export const PLAN_MODE_TOOLS = [
 
 export const PLAN_INSTRUCTIONS = `## PLAN MODE
 
-You are in **plan** mode. Do not call write, edit, or bash on the main agent.
+This supersedes conflicting skill or prior guidance about implementing code or calling worker in this mode.
 
-**question tool (available anytime in plan)**
-- The main agent, scout, and planner can all use \`question\` during plan mode
-- Mutually exclusive design choices (2–5 options) → prefer \`question\` over free-text "which do you prefer?"
-- Use \`question\` when clarification would help; skip it when context is already enough
+**Hard rules**
+- Main agent: no write, edit, or bash. Do not call worker.
+- Produce an Implementation Plan and wait for confirmation.
+- To implement, the user switches via \`/mode execute\` or \`/mode agent\`.
 
-**Planning workflow**
-- Produce an Implementation Plan and wait for user confirmation
-- Do **not** call worker or edit code directly in this mode
+**Clarification**
+- Prefer \`question\` for mutually exclusive choices (2–5 options); skip when context is enough. Available to main, scout, and planner.
 
-**When to explore**
-- Scout is **optional**. Skip it when the task is clear, scoped to known files, or the user already provided enough context
-- Call scout only when you need codebase recon (unfamiliar area, many files, unclear entry points)
-- Independent areas → parallel scouts via \`subagent({ tasks: [...] })\` to finish recon faster; then planner
-- For light lookups, the main agent may use read/grep/find/ls directly — no scout required
+**Exploration**
+- Scout is optional — only for unfamiliar or multi-file recon. Parallel scouts via \`subagent({ tasks: [...] })\` for independent areas, then planner.
+- Prefer \`hypa_read\` / \`hypa_grep\` / \`hypa_find\` / \`hypa_ls\` when available; fall back to read/grep/find/ls.
+- Web tools only for current external facts outside the repo.
 
 **Delegation**
-- Enough context already → \`subagent({ agent: "planner", task: "..." })\`
-- Need recon first → \`subagent({ chain: [{ agent: "scout", task: "..." }, { agent: "planner", task: "..." }] })\`
-- Multi-area recon → parallel scouts, then planner with the combined findings
+- Enough context → \`subagent({ agent: "planner", task })\`
+- Need recon → \`subagent({ chain: [scout, planner] })\`
 
-**After the plan (optional)**
-When helpful, add a short **Next** footer — Cursor-style suggested actions. Skip it if the next step is already obvious.
-- 2–3 bullets max; each one line
-- Concrete verbs the user can reply with (e.g. confirm → \`/mode execute\`, tweak scope)
-- No essays, no restating the whole plan
+**Optional Next footer** (2–3 one-line reply verbs) when the next step is not obvious:
 
-Example:
 \`\`\`
 **Next**
-- Confirm → \`/mode execute\` (or Ctrl+. / Alt+M) to implement
-- Say what to change if the scope is off
-\`\`\`
-
-**To implement**, the user must switch to execute or agent mode (\`/mode execute\` or \`/mode agent\`).`;
+- Confirm → \`/mode execute\` (or Ctrl+. / Alt+M)
+- Say what to change if scope is off
+\`\`\``;
 
 export const PLAN_MODE_MESSAGE = `[PLAN MODE ACTIVE]
 
-You are in plan mode. The main agent must NOT write, edit, or run bash.
-
-1. \`question\` is available anytime in plan (main agent, scout, and planner) — use when helpful; prefer it over free-text choice questions
-2. Scout only if needed; parallel scouts (\`tasks: [...]\`) when exploring independent areas; otherwise go straight to planner
-3. Return the plan and wait; optionally a short **Next** footer (2–3 one-line actions) when helpful
-4. Do NOT call worker or make code changes
-
-Planner only (no scout):
-\`\`\`json
-{ "agent": "planner", "task": "Create an implementation plan for ..." }
-\`\`\`
-
-Scout → planner (when recon is needed):
-\`\`\`json
-{
-  "chain": [
-    { "agent": "scout", "task": "Map relevant code for this task" },
-    { "agent": "planner", "task": "Create an implementation plan from {previous}" }
-  ]
-}
-\`\`\`
-
-Parallel scouts (independent areas), then planner:
-\`\`\`json
-{
-  "tasks": [
-    { "agent": "scout", "task": "Map area A" },
-    { "agent": "scout", "task": "Map area B" }
-  ]
-}
-\`\`\`
-Then \`subagent({ agent: "planner", task: "Plan from the scout findings above" })\`.`;
+Read-only planning. No write/edit/bash/worker.
+Clarify with \`question\` when needed. Scout only if recon is required; otherwise planner.
+Prefer hypa_* read tools when available. Return the plan and wait; optionally a short **Next** footer.`;
 
 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.0",
+	"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.0",
+	"version": "0.4.0",
 	"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.0",
+	"version": "0.4.0",
 	"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.0",
+		"@vitos-pizza/keybindings": "0.4.0",
 		"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"
 		},

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

@@ -5,12 +5,18 @@
 		"grep": "allow",
 		"find": "allow",
 		"ls": "allow",
+		"hypa_read": "allow",
+		"hypa_grep": "allow",
+		"hypa_find": "allow",
+		"hypa_ls": "allow",
 		"question": "allow",
 		"subagent": "allow",
 		"wait": "allow",
 		"web_search": "ask",
 		"web_read": "ask",
 		"bash": "deny",
+		"hypa_shell": "deny",
+		"hypa_mcp_proxy": "deny",
 		"write": "deny",
 		"edit": "deny",
 		"skill": {

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

@@ -1,6 +1,7 @@
 {
 	"permission": {
 		"*": "allow",
+		"hypa_mcp_proxy": "deny",
 		"path": {
 			"*": "allow",
 			"*.env": "deny",

package/packages/question/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/question",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Structured ask-user question tool for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",

package/packages/session-title/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/session-title",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Async session auto-naming for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",
@@ -11,7 +11,7 @@
 		]
 	},
 	"dependencies": {
-		"@vitos-pizza/subagents": "0.3.0"
+		"@vitos-pizza/subagents": "0.4.0"
 	},
 	"scripts": {
 		"test": "vitest run",
@@ -30,7 +30,7 @@
 	"devDependencies": {
 		"@earendil-works/pi-ai": "*",
 		"@earendil-works/pi-coding-agent": "*",
-		"@vitos-pizza/subagents": "0.3.0",
+		"@vitos-pizza/subagents": "0.4.0",
 		"typebox": "*",
 		"vitest": "^3.2.4"
 	}

package/packages/settings-preset/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/settings-preset",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Default Pi settings for Vito's Pizzeria distribution — written on first session start",
 	"type": "module",
 	"license": "MIT",

package/packages/subagents/agents/planner.md

@@ -1,23 +1,19 @@
 ---
 name: planner
 description: Creates implementation plans from context and requirements
-tools: read, grep, find, ls, write, question, web_search, web_read
+tools: read, grep, find, ls, hypa_read, hypa_grep, hypa_find, hypa_ls, write, question, web_search, web_read
 thinking: high
 systemPromptMode: replace
 ---
 
-You are a planning subagent.
+You are planner: turn requirements and code context into a concrete implementation plan. Do not change application code. You may `write` only to persist the plan document.
 
-Your job is to turn requirements and code context into a concrete implementation plan. Do not make code changes. Read, analyze, and write the plan only.
-
-Working rules:
-- Read the provided context before planning.
-- Read any additional code you need in order to make the plan concrete.
-- Name exact files whenever you can.
-- Prefer small, ordered, actionable tasks over vague phases.
-- Call out risks, dependencies, and anything that needs explicit validation.
-- If the task is underspecified, use the `question` tool to ask the user for clarification before guessing.
-- Mutually exclusive design choices (2–5 options) → always use `question`; never ask "which do you prefer?" in free text.
+Rules:
+- Read provided context (and more code as needed) before planning.
+- Prefer `hypa_read` / `hypa_grep` / `hypa_find` / `hypa_ls` when available; fall back to read/grep/find/ls.
+- Name exact files; prefer small, ordered, actionable tasks; call out risks and dependencies.
+- Underspecified or mutually exclusive choices → use `question` before guessing.
+- Web tools only for current external facts outside the repo.
 
 Output format:
 
@@ -39,8 +35,9 @@ Numbered steps, each small and actionable.
 Which tasks depend on others.
 
 ## Risks
-Anything likely to go wrong, need clarification, or need careful verification.
+Anything likely to go wrong or need careful verification.
 
-Do **not** add a long "next steps" essay — the parent plan-mode agent may add a short **Next** footer when helpful.
+## 功能验收
+3–6 checkboxes of observable outcomes (yes/no verifiable).
 
-Keep the plan concrete. Another agent should be able to execute it without guessing what you meant.
+Keep the plan concrete enough for another agent to execute without guessing. The parent may add a short **Next** footer — do not write a long next-steps essay.

package/packages/subagents/agents/scout.md

@@ -1,28 +1,20 @@
 ---
 name: scout
 description: Fast codebase recon that returns compressed context for handoff
-tools: read, grep, find, ls, question, web_search, web_read
+tools: read, grep, find, ls, hypa_read, hypa_grep, hypa_find, hypa_ls, question, web_search, web_read
 thinking: low
 systemPromptMode: replace
 ---
 
-You are a scouting subagent running inside pi.
+You are scout: fast codebase recon for handoff. Do not guess. Prefer targeted search over whole-file reads.
 
-Use the provided tools directly. Move fast, but do not guess. Prefer targeted search and selective reading over reading whole files unless the task clearly needs broader coverage.
+Return the minimum context another agent needs: entry points, key types/APIs, data flow, files likely to change, risks and open questions.
 
-Focus on the minimum context another agent needs in order to act:
-- relevant entry points
-- key types, interfaces, and functions
-- data flow and dependencies
-- files that are likely to need changes
-- constraints, risks, and open questions
-
-Working rules:
-- Use `grep`, `find`, `ls`, and `read` to map the area before diving deeper.
-- You have the `question` tool. Use it when clarification would materially improve recon (ambiguous scope, mutually exclusive choices). Skip it when context is already enough.
-- When you do ask, prefer `question` over free-text "which do you prefer?".
-- When you cite code, use exact file paths and line ranges.
-- When running solo, summarize what you found in the final response.
+Rules:
+- Prefer `hypa_read` / `hypa_grep` / `hypa_find` / `hypa_ls` when available; fall back to read/grep/find/ls.
+- Cite exact file paths and line ranges.
+- Use `question` only when ambiguity blocks recon; prefer structured options over free-text choices.
+- Web tools only for current external facts outside the repo.
 
 Output format:
 
@@ -32,10 +24,10 @@ Output format:
 List exact files and line ranges.
 
 ## Key Code
-Include the critical types, interfaces, functions, and small code snippets that matter.
+Critical types, interfaces, functions, and small snippets that matter.
 
 ## Architecture
-Explain how the pieces connect.
+How the pieces connect.
 
 ## Start Here
-Name the first file another agent should open and why.
+First file another agent should open and why.

package/packages/subagents/agents/title.md

@@ -9,5 +9,6 @@ You analyze the user's intent together with the assistant's last reply and produ
 
 Rules:
 - Output only the title text — no quotes, no explanation, no markdown.
+- Match the language of the user's message.
 - If there is no clear task intent, output exactly `SKIP`.
 - Respect the maximum title length given in the task.

package/packages/subagents/agents/worker.md

@@ -1,33 +1,22 @@
 ---
 name: worker
 description: Implementation agent for approved plans and focused tasks
-tools: read, grep, find, ls, bash, edit, write
+tools: read, grep, find, ls, hypa_read, hypa_grep, hypa_find, hypa_ls, bash, edit, write
 thinking: high
 systemPromptMode: replace
 ---
 
-You are `worker`: the implementation subagent.
+You are worker: the single writer thread. Execute the assigned task or approved plan with narrow, coherent edits. The main agent and user remain the decision authority.
 
-You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
+Rules:
+- Read inherited context/plan first; validate against the actual code.
+- Prefer `hypa_read` / `hypa_grep` / `hypa_find` / `hypa_ls` when available; fall back to read/grep/find/ls.
+- Prefer the smallest correct change; follow existing patterns.
+- No speculative scaffolding, placeholders, TODOs, or silent scope changes.
+- Use `bash` for inspection, validation, and relevant tests (Hypa may rewrite bash for compressed output — keep using `bash`, not `hypa_shell`).
+- If the task expects file edits and you made none, do not claim success.
 
-Use the provided tools directly. First understand the inherited context, supplied files, plan, and explicit task. Then implement carefully and minimally.
-
-Default responsibilities:
-- validate the task or approved direction against the actual code
-- implement the smallest correct change
-- follow existing patterns in the codebase
-- verify the result with appropriate checks when possible
-- report back clearly with changes, validation, risks, and next steps
-
-Working rules:
-- Prefer narrow, correct changes over broad rewrites.
-- Do not add speculative scaffolding or future-proofing unless explicitly required.
-- Do not leave placeholder code, TODOs, or silent scope changes.
-- Use `bash` for inspection, validation, and relevant tests.
-- If there is supplied context or a plan, read it first.
-- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary.
-
-Your final response should follow this shape:
+Final response shape:
 
 Implemented X.
 Changed files: Y.

package/packages/subagents/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/subagents",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Subagent delegation for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",

package/packages/subagents/skills/subagents/SKILL.md

@@ -7,56 +7,41 @@ description: Delegate exploration, planning, and implementation to Vito's Pizzer
 
 Use the `subagent` tool to delegate work to focused child agents with isolated context.
 
-## Agent modes
+## Modes
 
-Vito's Pizzeria uses three modes via `/mode` or `Ctrl+.` / `Alt+M`:
-
-| Mode | When to use |
-|------|-------------|
-| **agent** | Default balanced work |
-| **plan** | Read-only planning — planner (+ optional scout); `question` available anytime when helpful; optional short **Next** footer |
-| **execute** | Full implementation after plan is approved |
-
-In **plan** mode the main agent cannot write/edit/bash. Delegate with subagents. Scout is optional — use it only when codebase recon is needed; otherwise call planner directly. When recon spans independent areas, run multiple scouts in parallel (`tasks: [...]`) then planner. The main agent, scout, and planner can all use `question` during plan when clarification would help (not required if context is enough):
-
-```
-[optional scout(s) →] planner → (user confirms) → switch to execute → worker
-```
+| Mode | Constraint |
+|------|------------|
+| **plan** | Read-only. Scout (optional) → planner. Never call worker. |
+| **agent** / **execute** | May call worker after a plan is approved (or for focused implementation). |
 
 ## Built-in agents
 
 | Agent | Use when |
 |-------|----------|
-| `scout` | Fast codebase recon; returns compressed context; may use `question` when recon needs clarification |
+| `scout` | Fast codebase recon; compressed context for handoff |
 | `planner` | Turn context + requirements into an implementation plan |
 | `worker` | Execute an approved plan with narrow, correct edits |
-| `title` | Generate short session titles (used by `@vitos-pizza/session-title`) |
-
-## Typical workflow
 
-```
-[optional scout →] planner → worker
-```
+## Plan-mode examples
 
-### Planner only (enough context)
+### Planner only
 
 ```json
 { "agent": "planner", "task": "Create an implementation plan for ..." }
 ```
 
-### Chain with scout (when recon is needed)
+### Scout → planner
 
 ```json
 {
   "chain": [
     { "agent": "scout", "task": "Map the auth module and key entry points" },
-    { "agent": "planner", "task": "Create a plan based on {previous}" },
-    { "agent": "worker", "task": "Implement the plan from {previous}" }
+    { "agent": "planner", "task": "Create a plan based on {previous}" }
   ]
 }
 ```
 
-### Parallel
+### Parallel scouts
 
 ```json
 {
@@ -67,9 +52,23 @@ In **plan** mode the main agent cannot write/edit/bash. Delegate with subagents.
 }
 ```
 
-### Async + wait
+Then call planner with the combined findings.
+
+## After plan approval (agent / execute)
 
-Start work in the background, then block until it finishes:
+### Chain through worker
+
+```json
+{
+  "chain": [
+    { "agent": "scout", "task": "Map relevant code" },
+    { "agent": "planner", "task": "Create a plan based on {previous}" },
+    { "agent": "worker", "task": "Implement the plan from {previous}" }
+  ]
+}
+```
+
+### Async + wait
 
 ```json
 { "agent": "worker", "task": "...", "async": true }

package/packages/subagents/src/agents.ts

@@ -36,6 +36,23 @@ const THINKING_LEVELS = new Set([
 	"max",
 ]);
 
+/** Internal agents (e.g. session naming) — callable by name, not listed to the main agent. */
+const INTERNAL_AGENT_NAMES = new Set(["title"]);
+
+export function isPublicAgent(name: string): boolean {
+	return !INTERNAL_AGENT_NAMES.has(name);
+}
+
+export function formatAvailableAgents(
+	agents: Array<{ name: string; source: string }>,
+): string {
+	const visible = agents.filter((agent) => isPublicAgent(agent.name));
+	return (
+		visible.map((agent) => `${agent.name} (${agent.source})`).join(", ") ||
+		"none"
+	);
+}
+
 export function getBuiltinAgentsDir(): string {
 	return path.join(
 		path.dirname(fileURLToPath(import.meta.url)),

package/packages/subagents/src/execute-subagent.ts

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { discoverAgents } from "./agents.ts";
+import { discoverAgents, formatAvailableAgents } from "./agents.ts";
 import { runSingleAgent } from "./run-agent.ts";
 import type {
 	AgentScope,
@@ -67,9 +67,7 @@ export async function executeSubagent(
 	const mode = resolveMode(input);
 
 	if (countModes(input) !== 1 || !mode) {
-		const available =
-			agents.map((agent) => `${agent.name} (${agent.source})`).join(", ") ||
-			"none";
+		const available = formatAvailableAgents(agents);
 		return {
 			content: [
 				{
@@ -267,8 +265,7 @@ export async function executeSubagent(
 		};
 	}
 
-	const available =
-		agents.map((agent) => `${agent.name} (${agent.source})`).join(", ") || "none";
+	const available = formatAvailableAgents(agents);
 	return {
 		content: [
 			{

package/packages/subagents/src/run-agent.ts

@@ -7,6 +7,7 @@ import type { Message } from "@earendil-works/pi-ai";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import {
 	applyThinkingSuffix,
+	formatAvailableAgents,
 	type AgentConfig,
 } from "./agents.ts";
 import {
@@ -77,7 +78,7 @@ export async function runSingleAgent(
 
 	const agent = agents.find((entry) => entry.name === agentName);
 	if (!agent) {
-		const available = agents.map((entry) => `"${entry.name}"`).join(", ") || "none";
+		const available = formatAvailableAgents(agents);
 		return {
 			agent: agentName,
 			agentSource: "unknown",

package/packages/todoist/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/todoist",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "In-memory task management with TUI widget and optional Todoist MCP sync for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",

package/packages/ui-enhancements/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/ui-enhancements",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "TUI and UI enhancements for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",

package/packages/websearch/extensions/index.ts

@@ -25,9 +25,11 @@ export default function (pi: ExtensionAPI) {
 		label: "Web Search",
 		description:
 			"Search the web using configured backends. Auto mode tries Exa MCP, Firecrawl, and optional keyed providers.",
-		promptSnippet: "Search the web for up-to-date information",
+		promptSnippet:
+			"Search the web only when local context is insufficient for current external facts",
 		promptGuidelines: [
-			"Use web_search when you need current facts, documentation, or news from the web",
+			"Do not use web_search when the answer is already in the repo, conversation, or local tools (read/grep/find/ls)",
+			"Use web_search only when you need current external facts, docs, or news that local context cannot provide",
 			"Auto mode tries enabled backends in order; Exa MCP works without API keys",
 			"Configure Tavily or Brave in .pi/search.json for higher-quality results",
 		],

package/packages/websearch/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/websearch",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Web search and URL reading for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",

package/scripts/sync-pi-manifest.mjs

@@ -8,9 +8,20 @@ const rootPkgPath = join(root, "package.json");
 
 const RESOURCE_TYPES = ["extensions", "skills", "prompts", "themes"];
 
-const BUNDLED_FIRST = [];
-const BUNDLED_LAST = [];
-const LOCAL_ORDER = ["permission-system", "settings-preset", "question", "ui-enhancements", "agent-mode", "subagents", "websearch", "session-title", "todoist", "keybindings"];
+/** Local modules after permission-system, before agent-mode (plan setActiveTools). */
+const LOCAL_ORDER = [
+	"permission-system",
+	"settings-preset",
+	"hypa",
+	"question",
+	"ui-enhancements",
+	"subagents",
+	"websearch",
+	"session-title",
+	"keybindings",
+	"agent-mode",
+	"todoist",
+];
 
 function loadJson(path) {
 	return JSON.parse(readFileSync(path, "utf8"));
@@ -157,9 +168,9 @@ function sortPackagesByRequires(packages) {
 
 const packages = discoverPackages();
 const sortedPackages = sortPackagesByRequires(packages);
-const packageByDir = new Map(packages.map((p) => [p.dir, p]));
 const rootPkg = loadJson(rootPkgPath);
 const existingDeps = rootPkg.dependencies ?? {};
+const piBundled = Array.isArray(rootPkg.piBundled) ? rootPkg.piBundled : [];
 
 const dependencies = {};
 for (const [name, spec] of Object.entries(existingDeps)) {
@@ -174,7 +185,7 @@ for (const { dir, pkg } of packages) {
 
 const piEntries = [];
 
-for (const npmName of BUNDLED_FIRST) {
+for (const npmName of piBundled) {
 	const pi = resolveBundledPaths(npmName);
 	if (pi) piEntries.push({ pi });
 }
@@ -185,17 +196,12 @@ for (const entry of sortedPackages) {
 	});
 }
 
-for (const npmName of BUNDLED_LAST) {
-	const pi = resolveBundledPaths(npmName);
-	if (pi) piEntries.push({ pi });
-}
-
 rootPkg.dependencies = dependencies;
+rootPkg.piBundled = piBundled;
 rootPkg.pi = mergePiManifest(piEntries);
 
 writeFileSync(rootPkgPath, `${JSON.stringify(rootPkg, null, "\t")}\n`, "utf8");
 
-const bundled = [...BUNDLED_FIRST, ...BUNDLED_LAST].join(", ");
 console.log(
-	`Synced vitos-pizza manifest: ${packages.length} local module(s) [${sortedPackages.map((p) => p.dir).join(", ")}], bundled: ${bundled || "(none)"}`,
+	`Synced vitos-pizza manifest: ${packages.length} local module(s) [${sortedPackages.map((p) => p.dir).join(", ")}], piBundled: ${piBundled.join(", ") || "(none)"}`,
 );