@garaje/base 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 teammates.work
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @garaje/base
+
+The garaje framework's agent-side substrate, distributed as a pi package
+(extensions, prompts, roles, rules, the Garaje persona, and the park/upgrade
+skills), plus the `presets.json` and `agents/*.md` generated from those roles
+by `bin/build-roles`. This is the built substrate: the host repo consumes it
+declaratively via the local-path `packages` pin in `.pi/settings.json`, and
+`.agent/` at the repo root layers thin, repo-local overrides on top.
+
+See `docs/superpowers/specs/2026-06-30-agent-first-garaje-framework-design.md`.

package/agents/doc-writer.md

@@ -0,0 +1,28 @@
+---
+name: doc-writer
+description: Update docs to match current behavior, light touch on code
+tools: read, bash, edit, write, grep, find, ls
+model: anthropic/claude-sonnet-4-5
+---
+
+<!-- DO NOT EDIT — generated by bin/build-roles from packages/base/prompts/roles/ -->
+
+You are the **doc-writer** role.
+
+Your job is to keep the repo's prose in sync with its code. You may edit
+files under `docs/`, `README.md`, `AGENTS.md`, `.agent/**/*.md`, and inline
+docstrings — but not service source code, configs, or other behavior-bearing
+files. If a doc change implies a code change, surface it and stop.
+
+Process:
+- Read the code you're documenting IN FULL.
+- Match the existing voice: terse, second person, present tense, no marketing.
+- Cross-link with relative paths.
+- Update `docs/garaje-spec.md` / `docs/recipe-schema.md` when you ship work
+  that changes the framework design or resolves an open seam.
+- Keep `AGENTS.md` short and stable; push narrower or evolving guidance into
+  `.agent/rules/`.
+
+Wrap up with:
+- List of files touched.
+- Any drift you noticed but did not fix (so the next role can pick it up).

package/agents/implementer.md

@@ -0,0 +1,31 @@
+---
+name: implementer
+description: Make focused, surgical edits and prove they took effect
+tools: read, bash, edit, write, grep, find, ls
+model: anthropic/claude-sonnet-4-5
+---
+
+<!-- DO NOT EDIT — generated by bin/build-roles from packages/base/prompts/roles/ -->
+
+You are the **implementer** role.
+
+Your job is to execute a plan (explicit or implicit) with focused, surgical
+edits. Keep scope tight: do exactly what was asked, no more.
+
+Rules:
+- Read files before editing. Prefer `edit` over `write` for existing files.
+- Mirror existing patterns in the repo; do not introduce new conventions
+  unless asked.
+- Honor `.agent/rules/` (especially `10-safety.md`) and `protected-paths`.
+- After changes to a service, give the reloader a beat, then prove the edit
+  took effect by hitting the service from inside this container (see
+  `AGENTS.md` → "Proving an edit took effect"). Do not declare done without
+  proof.
+- If you hit unexpected complexity, STOP and surface it — do not hack around
+  it.
+
+Wrap up with:
+- A short summary of what changed (files + one-line reason each).
+- The proof you ran and its output.
+- Suggested follow-ups (tests, docs, review). Offer to switch to
+  `/preset reviewer` for a self-review pass.

package/agents/planner.md

@@ -0,0 +1,33 @@
+---
+name: planner
+description: Read-only exploration and step-by-step plan, no edits
+tools: read, bash, grep, find, ls
+model: anthropic/claude-sonnet-4-5
+---
+
+<!-- DO NOT EDIT — generated by bin/build-roles from packages/base/prompts/roles/ -->
+
+You are the **planner** role.
+
+Your job is to deeply understand the problem and produce a tight, numbered
+implementation plan. You CANNOT edit or write files. `bash` is for read-only
+exploration only (`git`, `rg`, `ls`, `curl` a parked bay's health endpoint, etc.) —
+never run mutating commands.
+
+Process:
+- Read files IN FULL (no offset/limit) to get complete context.
+- Map the surrounding architecture: which services, which `.agent/rules/`
+  apply, which existing patterns to mirror.
+- Identify risks, edge cases, dependencies, and missing information.
+- Ask clarifying questions when requirements are ambiguous.
+
+Output a plan with:
+1. Goal restated in one sentence.
+2. Numbered steps. For each: what to change, why, files touched, risks.
+3. Tests / proofs that should pass after the change (curl, unit tests, etc.).
+4. An explicit "handoff" line naming the next role
+   (usually `implementer`) and what it needs to know.
+
+When done, ask whether to (a) write the plan to `scratch/PLAN-*.md`,
+(b) hand off to the implementer via `/preset implementer`, or
+(c) iterate on the plan.

package/agents/reviewer.md

@@ -0,0 +1,36 @@
+---
+name: reviewer
+description: Critical review of staged or recent changes, read-only
+tools: read, bash, grep, find, ls
+model: anthropic/claude-sonnet-4-5
+---
+
+<!-- DO NOT EDIT — generated by bin/build-roles from packages/base/prompts/roles/ -->
+
+You are the **reviewer** role.
+
+Your job is to critically review recent changes. You are read-only: no
+`edit`, no `write`, no mutating `bash`. Treat the author as a peer who
+wants real feedback, not validation.
+
+Process:
+1. Identify the change set. Prefer `git diff --staged`; fall back to
+   `git diff HEAD~1` or the most recent commit. State which scope you are
+   reviewing.
+2. For each modified file, read it IN FULL so review comments are grounded
+   in the post-change state, not just the diff hunks.
+3. Cross-check against `AGENTS.md` and every `.agent/rules/*.md` that
+   applies.
+
+Report structure:
+- **Summary** — one paragraph on what the change does and whether it
+  achieves its stated goal.
+- **Blocking issues** — bugs, security holes, rule violations. Cite file +
+  line.
+- **Non-blocking** — style, naming, missing tests, doc drift.
+- **Proof gaps** — what the author should run (e.g. `curl` a parked bay's endpoint)
+  before claiming done.
+- **Verdict** — `ship`, `ship after fixes`, or `rework`.
+
+Do not propose edits as patches; describe the fix and let the implementer
+apply it.

package/extensions/README.md

@@ -0,0 +1,96 @@
+# Extension bundle
+
+The curated set of extensions that auto-load for this repo. Each `.ts` file (or
+directory with `index.ts`) here is loaded by pi as `@garaje/base` package
+extensions: the local-path `packages` pin in `.pi/settings.json` names this
+directory (`extensions/**`, with an optional filter), and pi merges it in at
+session start — no symlink involved.
+
+See [`docs/garaje-spec.md`](../../docs/garaje-spec.md) for the
+**bundle** vs **preset** vs **role** terminology and the framework design.
+
+> **Status — testing scaffolding vs garaje substrate.** The **vendored** and
+> **example-forked** rows below (notably `subagent/` and `plan-mode/`) are
+> **development-time testing scaffolding**: placeholder copies of pi's bundled
+> *example* extensions, carried while the framework is built out. They are
+> **not** committed framework features — the plan is to replace them with
+> maintained off-the-shelf pi packages (e.g. `npm:pi-subagents`,
+> `pi-web-access`) pinned declaratively in `.pi/settings.json` `packages`. Only
+> the garaje-specific extensions — `agent-rules` + `protected-paths` (forked)
+> and `role-commands` + `standalone-commands` + `usage-status` (local) — are
+> intended as permanent `@garaje/base` substrate. Do not build new features on
+> top of the vendored copies. See the Phase-3 spec's "Known follow-ups".
+
+## Lineup
+
+| File                  | Origin    | Purpose                                                                                  |
+| --------------------- | --------- | ---------------------------------------------------------------------------------------- |
+| `agent-rules.ts`      | forked    | Scans base package rules (`packages/base/rules/*.md`) plus local `.agent/rules/*.md` overrides, lists them in the system prompt so the agent can read them. |
+| `protected-paths.ts`  | forked    | Blocks `write`/`edit` to secrets, VCS internals, deps, and the framework substrate (`docker-compose.yml`, `compose.framework.yaml`, Dockerfile, entrypoint, `packages/base/`, `.pi/settings.json`). |
+| `confirm-destructive` | vendored  | Confirms before destructive session actions (`/new`, `/resume`, fork).                   |
+| `dirty-repo-guard`    | vendored  | Refuses session switches while the git working tree is dirty.                            |
+| `git-checkpoint`      | vendored  | Stashes a checkpoint each turn; offers to restore on fork.                               |
+| `plan-mode/`          | forked    | Read-only "plan first" mode toggle and badge. Command renamed `/plan` → `/plan-mode` so role-commands can own `/plan`. |
+| `subagent/`           | vendored  | Spawn isolated child pi processes as named subagents. Base roles ship in the `@garaje/base` package's `agents/` (regenerated by `bin/build-roles`); `.pi/agents/` is the local project override dir. |
+| `preset.ts`           | vendored  | `/preset <name>` to swap model + thinking + tool allowlist + prompt fragment in one shot. Base presets ship in the `@garaje/base` package's `presets.json` (regenerated by `bin/build-roles`); `.pi/presets.json` is the local project override file. |
+| `role-commands.ts`    | local     | `/plan`, `/spec`, `/review` — thin wrappers that switch preset and kick off a templated turn. |
+| `standalone-commands.ts` | local  | `/checkpoint`, `/handoff`, `/proof` — repo-flavored commands that don't wrap a preset. |
+| `session-name.ts`     | vendored  | `/session-name` command for naming sessions in the picker.                               |
+| `custom-compaction`   | vendored  | Replaces default compaction with a full-context summary (uses Gemini Flash).             |
+| `status-line.ts`      | vendored  | Footer "Turn N…/✓ Turn N complete" indicator.                                           |
+| `model-status.ts`     | vendored  | Footer badge with current model id; notifies on changes.                                 |
+| `usage-status.ts`     | local     | Footer block: live tokens + $ for the current session. Resets on every `session_start`. |
+| `notify.ts`           | vendored  | Terminal-native notification (OSC 777/99/toast) when the agent goes idle.                |
+
+## Vendored vs forked
+
+- **vendored** files are byte-for-byte copies of the upstream examples shipped
+  with `@earendil-works/pi-coding-agent`. Don't edit them in place — if you
+  need a behaviour change, fork (rename + edit + note the divergence in the
+  file header) so future refreshes don't clobber local changes.
+- **forked** files have a header block stating what was changed relative to
+  upstream.
+
+## Refreshing from upstream
+
+The pi npm package ships the originals at
+`/usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions/`.
+When bumping pi:
+
+```bash
+SRC=/usr/local/lib/node_modules/@earendil-works/pi-coding-agent/examples/extensions
+DST=packages/base/extensions
+for f in confirm-destructive.ts custom-compaction.ts dirty-repo-guard.ts \
+         git-checkpoint.ts model-status.ts notify.ts preset.ts \
+         session-name.ts status-line.ts; do
+  diff -u "$DST/$f" "$SRC/$f" || cp "$SRC/$f" "$DST/$f"
+done
+diff -ru "$SRC/plan-mode" "$DST/plan-mode"
+diff -ru "$SRC/subagent"  "$DST/subagent" --exclude=agents --exclude=prompts --exclude=README.md
+```
+
+Re-review the forks (`agent-rules.ts`, `protected-paths.ts`) against the
+upstream originals (`claude-rules.ts`, `protected-paths.ts`) to pick up bug
+fixes.
+
+## Adding to the bundle
+
+1. Drop a `.ts` file (or directory with `index.ts`) into this folder.
+2. Add a row above and note whether it's vendored or homegrown.
+3. Restart pi (or `/reload`).
+
+## Where these fit
+
+These extensions are the agent-side substrate the garaje ships with: rules
+surfacing (`agent-rules`), guardrails (`protected-paths`, `dirty-repo-guard`,
+`confirm-destructive`, `git-checkpoint`), flow (`plan-mode`, `preset`,
+`role-commands`, `standalone-commands`, `subagent`), and footer telemetry
+(`status-line`, `model-status`, `usage-status`, `notify`). Slash commands
+(`/plan`, `/spec`, `/review`, `/checkpoint`, `/handoff`, `/proof`) come from
+the `role-commands` / `standalone-commands` rows; subagent roles live in
+`packages/base/prompts/roles/`, regenerated into `packages/base/presets.json`
+and `packages/base/agents/` by `bin/build-roles`.
+
+See [`docs/garaje-spec.md`](../../docs/garaje-spec.md) for the framework
+design and [`docs/extensions.md`](../../docs/extensions.md) for the
+maintainer-side loading/refresh details.

package/extensions/agent-rules.ts

@@ -0,0 +1,29 @@
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { packageRoot } from "../lib/base-paths.ts";
+import { resolveRuleFiles } from "../lib/rules.ts";
+
+const LOCAL_RULES_SUBDIR = path.join(".agent", "rules");
+
+export default function agentRulesExtension(pi: ExtensionAPI) {
+	let rules: { label: string }[] = [];
+
+	pi.on("session_start", async (_event, ctx) => {
+		const baseDir = path.join(packageRoot(), "rules");
+		const localDir = path.join(ctx.cwd, LOCAL_RULES_SUBDIR);
+		rules = resolveRuleFiles(baseDir, localDir).map((r) => ({
+			label: path.relative(ctx.cwd, r.absPath),
+		}));
+		if (rules.length > 0) ctx.ui.notify(`Found ${rules.length} rule(s) (base + local)`, "info");
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (rules.length === 0) return;
+		const list = rules.map((r) => `- ${r.label}`).join("\n");
+		return {
+			systemPrompt:
+				event.systemPrompt +
+				`\n\n## Project Rules\n\nThe following rules are available (base package + local overrides):\n\n${list}\n\nWhen working on tasks that touch one of these areas, read the relevant rule file(s) before acting.\n`,
+		};
+	});
+}

package/extensions/command-guard.ts

@@ -0,0 +1,94 @@
+/**
+ * Command-Intent Guard Extension (Phase 4 — north-star §5.1, defense layer 3)
+ *
+ * Blocks bash commands that could touch the agent's own container or bypass
+ * the socket proxy: raw-socket access, DOCKER_HOST overrides, framework-layer
+ * compose invocations, --force-recreate, --remove-orphans, docker/compose
+ * lifecycle verbs aimed at the pi service, and bare compose lifecycle
+ * invocations that name no service (which act on the whole file set — the
+ * pi service included). Layers 1 (whitelisting socket proxy) and 2 (compose
+ * split + protected paths) are the structural defenses; this one catches
+ * intent early, with an explanation instead of a downstream failure.
+ *
+ * Bay lifecycle is untouched: `garaje bay <verb> <name>` (and even raw
+ * docker/compose against bay services) passes through.
+ *
+ * Accepted limitations (layer 3 of 3; backstopped by the socket proxy and
+ * the bays-only compose scope): absolute-path invocations (/usr/bin/docker),
+ * --file long-flag and nested -f paths, quoted DOCKER_HOST pointing at a
+ * non-standard socket, raw HTTP to docker-proxy:2375, and container names
+ * using "pi" without a separator (-pi2).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** A token that means "the docker CLI is being invoked" (start of command or
+ *  after a shell separator). Note: \b also matches inside hyphenated
+ *  filenames (docker-compose.yml), so downstream checks must require
+ *  lifecycle context before blocking. */
+const DOCKER_INVOCATION = /(^|[\s;&|(])docker\b/;
+
+/** Lifecycle verbs that (re)create, stop, or remove containers. */
+const LIFECYCLE = "(up|down|stop|start|restart|rm|kill|pause|unpause|update)";
+
+/** Check for compose lifecycle verbs aimed at the pi service. */
+const COMPOSE_LIFECYCLE_PI = new RegExp(`\\bcompose\\b.*\\b${LIFECYCLE}\\b.*\\spi(\\s|$)`);
+
+/** Check for docker lifecycle verbs (matches the invocation, not the target yet). */
+const DOCKER_LIFECYCLE = new RegExp(`\\bdocker\\s+${LIFECYCLE}\\b`);
+
+export function blockedCommandReason(command: string): string | undefined {
+	if (command.includes("/var/run/docker.sock")) {
+		return "raw docker socket access — the agent talks to docker only via the proxy (DOCKER_HOST)";
+	}
+	if (/DOCKER_HOST=unix:/.test(command)) {
+		return "overriding DOCKER_HOST to a unix socket would bypass the socket proxy";
+	}
+	if (!DOCKER_INVOCATION.test(command)) return undefined;
+	if (command.includes("--force-recreate")) {
+		return "--force-recreate can recreate the pi service — the container this agent lives in";
+	}
+	if (command.includes("--remove-orphans")) {
+		return "--remove-orphans would remove the framework services (pi, docker-proxy) that sit outside the bays scope";
+	}
+	if (/-f\s+(\.\/)?(docker-compose\.ya?ml|compose\.framework\.ya?ml)/.test(command)) {
+		return "compose against the framework layer is host-only; use `garaje bay <verb> <name>` for parked services";
+	}
+	if (COMPOSE_LIFECYCLE_PI.test(command)) {
+		return "that would touch the pi service — the agent cannot manage its own container (cold changes hand off to the host)";
+	}
+	if (DOCKER_LIFECYCLE.test(command)) {
+		// The pi container's name puts "pi" as the terminal service component:
+		// <project>-pi or <project>-pi-<index> (also _ separators). A bay name
+		// that merely CONTAINS "pi" (raspberry-pi-web-1) must not match.
+		const targetsPi = command.split(/\s+/).some((tok) => /[-_]pi([-_]\d+)?$/.test(tok));
+		if (targetsPi) {
+			return "that targets the pi container by name — the agent cannot manage its own container";
+		}
+	}
+	// A bare compose lifecycle invocation (no service token after the verb, up
+	// to the next shell separator) acts on the WHOLE file set — which includes
+	// the pi service — so it must be blocked even though it doesn't name "pi".
+	const composeVerb = new RegExp(`\\bcompose\\b[^;|&]*?\\b${LIFECYCLE}\\b([^;|&]*)`).exec(command);
+	if (composeVerb) {
+		const tail = composeVerb[2].trim().split(/\s+/).filter((t) => t && !t.startsWith("-"));
+		if (tail.length === 0) {
+			return "a compose lifecycle command that names no service acts on the whole file set — which includes the pi service; name bay services explicitly or use `garaje bay <verb> <name>`";
+		}
+	}
+	return undefined;
+}
+
+export default function commandGuardExtension(pi: ExtensionAPI) {
+	pi.on("tool_call", async (event, ctx) => {
+		if (event.toolName !== "bash") return undefined;
+		const command = String((event.input as { command?: unknown }).command ?? "");
+		const reason = blockedCommandReason(command);
+		if (!reason) return undefined;
+		if (ctx.hasUI) ctx.ui.notify(`Blocked docker command: ${reason}`, "warning");
+		return {
+			block: true,
+			reason: `Blocked by packages/base/extensions/command-guard.ts: ${reason}.`,
+		};
+	});
+}

package/extensions/confirm-destructive.ts

@@ -0,0 +1,59 @@
+/**
+ * Confirm Destructive Actions Extension
+ *
+ * Prompts for confirmation before destructive session actions (clear, switch, branch).
+ * Demonstrates how to cancel session events using the before_* events.
+ */
+
+import type { ExtensionAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent, ctx) => {
+		if (!ctx.hasUI) return;
+
+		if (event.reason === "new") {
+			const confirmed = await ctx.ui.confirm(
+				"Clear session?",
+				"This will delete all messages in the current session.",
+			);
+
+			if (!confirmed) {
+				ctx.ui.notify("Clear cancelled", "info");
+				return { cancel: true };
+			}
+			return;
+		}
+
+		// reason === "resume" - check if there are unsaved changes (messages since last assistant response)
+		const entries = ctx.sessionManager.getEntries();
+		const hasUnsavedWork = entries.some(
+			(e): e is SessionMessageEntry => e.type === "message" && e.message.role === "user",
+		);
+
+		if (hasUnsavedWork) {
+			const confirmed = await ctx.ui.confirm(
+				"Switch session?",
+				"You have messages in the current session. Switch anyway?",
+			);
+
+			if (!confirmed) {
+				ctx.ui.notify("Switch cancelled", "info");
+				return { cancel: true };
+			}
+		}
+	});
+
+	pi.on("session_before_fork", async (event, ctx) => {
+		if (!ctx.hasUI) return;
+
+		const choice = await ctx.ui.select(`Fork from entry ${event.entryId.slice(0, 8)}?`, [
+			"Yes, create fork",
+			"No, stay in current session",
+		]);
+
+		if (choice !== "Yes, create fork") {
+			ctx.ui.notify("Fork cancelled", "info");
+			return { cancel: true };
+		}
+	});
+}

package/extensions/custom-compaction.ts

@@ -0,0 +1,127 @@
+/**
+ * Custom Compaction Extension
+ *
+ * Replaces the default compaction behavior with a full summary of the entire context.
+ * Instead of keeping the last 20k tokens of conversation turns, this extension:
+ * 1. Summarizes ALL messages (messagesToSummarize + turnPrefixMessages)
+ * 2. Discards all old turns completely, keeping only the summary
+ *
+ * This example also demonstrates using a different model (Gemini Flash) for summarization,
+ * which can be cheaper/faster than the main conversation model.
+ *
+ * Usage:
+ *   pi --extension examples/extensions/custom-compaction.ts
+ */
+
+import { complete } from "@earendil-works/pi-ai/compat";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_before_compact", async (event, ctx) => {
+		ctx.ui.notify("Custom compaction extension triggered", "info");
+
+		const { preparation, branchEntries: _, signal } = event;
+		const { messagesToSummarize, turnPrefixMessages, tokensBefore, firstKeptEntryId, previousSummary } = preparation;
+
+		// Use Gemini Flash for summarization (cheaper/faster than most conversation models)
+		const model = ctx.modelRegistry.find("google", "gemini-2.5-flash");
+		if (!model) {
+			ctx.ui.notify(`Could not find Gemini Flash model, using default compaction`, "warning");
+			return;
+		}
+
+		// Resolve request auth for the summarization model
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) {
+			ctx.ui.notify(`Compaction auth failed: ${auth.error}`, "warning");
+			return;
+		}
+		if (!auth.apiKey) {
+			ctx.ui.notify(`No API key for ${model.provider}, using default compaction`, "warning");
+			return;
+		}
+
+		// Combine all messages for full summary
+		const allMessages = [...messagesToSummarize, ...turnPrefixMessages];
+
+		ctx.ui.notify(
+			`Custom compaction: summarizing ${allMessages.length} messages (${tokensBefore.toLocaleString()} tokens) with ${model.id}...`,
+			"info",
+		);
+
+		// Convert messages to readable text format
+		const conversationText = serializeConversation(convertToLlm(allMessages));
+
+		// Include previous summary context if available
+		const previousContext = previousSummary ? `\n\nPrevious session summary for context:\n${previousSummary}` : "";
+
+		// Build messages that ask for a comprehensive summary
+		const summaryMessages = [
+			{
+				role: "user" as const,
+				content: [
+					{
+						type: "text" as const,
+						text: `You are a conversation summarizer. Create a comprehensive summary of this conversation that captures:${previousContext}
+
+1. The main goals and objectives discussed
+2. Key decisions made and their rationale
+3. Important code changes, file modifications, or technical details
+4. Current state of any ongoing work
+5. Any blockers, issues, or open questions
+6. Next steps that were planned or suggested
+
+Be thorough but concise. The summary will replace the ENTIRE conversation history, so include all information needed to continue the work effectively.
+
+Format the summary as structured markdown with clear sections.
+
+<conversation>
+${conversationText}
+</conversation>`,
+					},
+				],
+				timestamp: Date.now(),
+			},
+		];
+
+		try {
+			// Pass signal to honor abort requests (e.g., user cancels compaction)
+			const response = await complete(
+				model,
+				{ messages: summaryMessages },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					maxTokens: 8192,
+					signal,
+				},
+			);
+
+			const summary = response.content
+				.filter((c): c is { type: "text"; text: string } => c.type === "text")
+				.map((c) => c.text)
+				.join("\n");
+
+			if (!summary.trim()) {
+				if (!signal.aborted) ctx.ui.notify("Compaction summary was empty, using default compaction", "warning");
+				return;
+			}
+
+			// Return compaction content - SessionManager adds id/parentId
+			// Use firstKeptEntryId from preparation to keep recent messages
+			return {
+				compaction: {
+					summary,
+					firstKeptEntryId,
+					tokensBefore,
+				},
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Compaction failed: ${message}`, "error");
+			// Fall back to default compaction on error
+			return;
+		}
+	});
+}

package/extensions/dirty-repo-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * Dirty Repo Guard Extension
+ *
+ * Prevents session changes when there are uncommitted git changes.
+ * Useful to ensure work is committed before switching context.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+async function checkDirtyRepo(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	action: string,
+): Promise<{ cancel: boolean } | undefined> {
+	// Check for uncommitted changes
+	const { stdout, code } = await pi.exec("git", ["status", "--porcelain"]);
+
+	if (code !== 0) {
+		// Not a git repo, allow the action
+		return;
+	}
+
+	const hasChanges = stdout.trim().length > 0;
+	if (!hasChanges) {
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		// In non-interactive mode, block by default
+		return { cancel: true };
+	}
+
+	// Count changed files
+	const changedFiles = stdout.trim().split("\n").filter(Boolean).length;
+
+	const choice = await ctx.ui.select(`You have ${changedFiles} uncommitted file(s). ${action} anyway?`, [
+		"Yes, proceed anyway",
+		"No, let me commit first",
+	]);
+
+	if (choice !== "Yes, proceed anyway") {
+		ctx.ui.notify("Commit your changes first", "warning");
+		return { cancel: true };
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_before_switch", async (event, ctx) => {
+		const action = event.reason === "new" ? "new session" : "switch session";
+		return checkDirtyRepo(pi, ctx, action);
+	});
+
+	pi.on("session_before_fork", async (_event, ctx) => {
+		return checkDirtyRepo(pi, ctx, "fork");
+	});
+}