@vitos-pizza/vitos-pizza 0.3.1 → 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,21 @@
 
 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

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.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.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.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.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.1",
+	"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.1",
-		"@vitos-pizza/permission-system": "0.3.1"
+		"@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",
@@ -23,7 +27,8 @@ 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.
+- 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**
@@ -42,7 +47,7 @@ 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 **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.1",
+	"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.1",
+	"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.1",
+		"@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.1",
+	"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.1",
+	"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.1"
+		"@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.1",
+		"@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.1",
+	"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,7 +1,7 @@
 ---
 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
 ---
@@ -10,6 +10,7 @@ You are planner: turn requirements and code context into a concrete implementati
 
 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.

package/packages/subagents/agents/scout.md

@@ -1,7 +1,7 @@
 ---
 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
 ---
@@ -11,6 +11,7 @@ You are scout: fast codebase recon for handoff. Do not guess. Prefer targeted se
 Return the minimum context another agent needs: entry points, key types/APIs, data flow, files likely to change, risks and open questions.
 
 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.

package/packages/subagents/agents/worker.md

@@ -1,7 +1,7 @@
 ---
 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
 ---
@@ -10,9 +10,10 @@ You are worker: the single writer thread. Execute the assigned task or approved
 
 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.
+- 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.
 
 Final response shape:

package/packages/subagents/package.json

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

package/packages/todoist/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/todoist",
-	"version": "0.3.1",
+	"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.1",
+	"version": "0.4.0",
 	"description": "TUI and UI enhancements for Vito's Pizzeria Pi distribution",
 	"type": "module",
 	"license": "MIT",

package/packages/websearch/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitos-pizza/websearch",
-	"version": "0.3.1",
+	"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)"}`,
 );