feat: add readonly mode with bash safety and spawn child filtering

.gitignore

@@ -47,6 +47,12 @@ web_modules/
 # TypeScript cache
 *.tsbuildinfo
 
+# TypeScript compilation output
+*.js
+*.d.ts
+*.d.cts
+*.d.mts
+
 # Optional npm cache directory
 .npm
 
@@ -148,3 +154,10 @@ vite.config.ts.timestamp-*
 .chunkhound.json
 .chunkhound/
 .mcp.json
+
+# macOS
+.DS_Store
+
+# PR review artifacts
+AGENT_REVIEW.md
+HUMAN_REVIEW.md

.husky/pre-commit

@@ -0,0 +1 @@
+npm run typecheck

AGENTS.md

@@ -0,0 +1,5 @@
+# TUI Safety
+
+**Never use `console.debug/warn/error/log`** — writes to stdout/stderr corrupt pi's TUI ANSI rendering. Extension host runs in the same process.
+
+Use `ctx.ui.notify()` / `setStatus()` / `setWidget()` instead. For diagnostics, remove entirely.

handoff/command.ts

@@ -23,11 +23,19 @@ export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingStat
 			}
 
 			state.pendingRequestedHandoff = {
-				direction,
-				enforcementAttempts: 0,
 				toolCalled: false,
+				readonlyBypassActive: state.readonlyEnabled,
+				resumeReadonlyAfterHandoff: state.readonlyEnabled,
+				enforcementAttempts: 0,
 			};
 
+			if (ctx.hasUI && state.readonlyEnabled) {
+				ctx.ui.notify(
+					"Readonly is active. A temporary handoff-only exception is now enabled for this required handoff. The fresh context after handoff will resume in readonly mode.",
+					"info",
+				);
+			}
+
 			// Show live progress indicator in footer
 			if (ctx.hasUI && ctx.ui.theme) {
 				ctx.ui.setStatus(
@@ -36,8 +44,12 @@ export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingStat
 				);
 			}
 
+			const readonlyNotice = state.readonlyEnabled
+				? "\n\nReadonly remains active for normal mutations: write, edit, and non-temp bash writes stay blocked. A temporary exception allows the handoff tool for this request only. You must perform a real handoff now rather than continue normal work. The fresh context after compaction will resume in readonly mode with this handoff exception cleared, so draft the brief for a readonly continuation."
+				: "\n\nYou must perform a real handoff now rather than continue normal work.";
+
 			pi.sendUserMessage(
-				`Handoff direction: ${direction}\n\nPrepare a handoff in the current session. First, save any durable reusable knowledge that aligns with the direction above to the notebook: findings worth keeping, constraints discovered, decisions made, or other grounding future contexts will need. Then draft a concise but sufficiently detailed handoff brief capturing only the remaining situational context: current state, blockers, unresolved questions, failed paths worth avoiding, and next steps. The next context will read the notebook on demand, so do not duplicate notebook content in the brief. Use any structure that makes the next work unambiguous. Reference notebook pages by name when relevant.`,
+				`Handoff direction: ${direction}\n\nThe user explicitly requested /handoff. Prepare a handoff in the current session. First, save any durable reusable knowledge that aligns with the direction above to the notebook: findings worth keeping, constraints discovered, decisions made, or other grounding future contexts will need. Then draft a concise but sufficiently detailed handoff brief capturing only the remaining situational context: current state, blockers, unresolved questions, failed paths worth avoiding, and next steps. The next context will read the notebook on demand, so do not duplicate notebook content in the brief. Use any structure that makes the next work unambiguous. Reference notebook pages by name when relevant.${readonlyNotice}`,
 				ctx.isIdle() ? undefined : { deliverAs: "followUp" },
 			);
 		},

handoff/compact.ts

@@ -7,29 +7,22 @@
 
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { AgenticodingState } from "../state.js";
-import { clearActiveNotebookTopic } from "../notebook/topic.js";
-import { STATUS_KEY_HANDOFF } from "../tui.js";
 
 function getImpossibleKeptId(branchEntries: SessionEntry[]): string {
 	const leaf = branchEntries[branchEntries.length - 1];
 	return `${leaf?.id ?? "handoff"}-handoff-cut`;
 }
 
 export function registerHandoffCompaction(pi: ExtensionAPI, state: AgenticodingState): void {
-	pi.on("session_before_compact", async (event, ctx: ExtensionContext) => {
+	pi.on("session_before_compact", async (event, _ctx: ExtensionContext) => {
 		const pending = state.pendingHandoff;
 		if (!pending) {
 			return;
 		}
 
 		state.pendingHandoff = null;
-		state.pendingRequestedHandoff = null;
-		clearActiveNotebookTopic(state);
-
-		// Clear the handoff progress indicator now that compaction is consuming it
-		if (ctx.hasUI) {
-			ctx.ui.setStatus(STATUS_KEY_HANDOFF, undefined);
-		}
+		// Keep pendingRequestedHandoff — compaction must complete successfully first.
+		// onComplete in handoff/tool.ts clears it after success; onError preserves it for retry.
 
 		return {
 			compaction: {

handoff/tool.ts

@@ -11,6 +11,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { clearActiveNotebookTopic } from "../notebook/topic.js";
 import type { AgenticodingState } from "../state.js";
 import { STATUS_KEY_HANDOFF } from "../tui.js";
 
@@ -19,7 +20,7 @@ import { STATUS_KEY_HANDOFF } from "../tui.js";
  *
  * Shape: handoff primer + original task.
  */
-function buildEnrichedTask(task: string): string {
+export function buildEnrichedTask(task: string, options?: { resumeReadonlyAfterHandoff?: boolean }): string {
 	const parts: string[] = [
 		"## Handoff — Continue Previous Work",
 		"",
@@ -29,12 +30,20 @@ function buildEnrichedTask(task: string): string {
 		"- Use `notebook_index` to scan available pages when needed",
 		"- Use `spawn` to delegate isolated subtasks to child agents",
 		"- Build on notebook grounding and this brief rather than reconstructing old context",
-		"",
-		"## Task",
-		"",
-		task,
 	];
 
+	if (options?.resumeReadonlyAfterHandoff) {
+		parts.push(
+			"",
+			"## Execution Constraints",
+			"",
+			"- Fresh context resumes in readonly mode.",
+			"- The temporary handoff-only exception used to reach this context is no longer active.",
+			"- Write, edit, and non-temp bash filesystem mutations remain blocked unless the user changes readonly mode.",
+		);
+	}
+
+	parts.push("", "## Task", "", task);
 	return parts.join("\n");
 }
 
@@ -79,18 +88,25 @@ export function registerHandoffTool(
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const enrichedTask = buildEnrichedTask(params.task);
+			const requestedHandoff = state.pendingRequestedHandoff;
+			const enrichedTask = buildEnrichedTask(params.task, {
+				resumeReadonlyAfterHandoff: requestedHandoff?.resumeReadonlyAfterHandoff === true,
+			});
 			state.pendingHandoff = { task: enrichedTask, source: "tool" };
-			if (state.pendingRequestedHandoff) {
-				state.pendingRequestedHandoff.toolCalled = true;
+			if (requestedHandoff) {
+				requestedHandoff.toolCalled = true;
 			}
 			ctx.compact({
 				onComplete: () => {
+					clearActiveNotebookTopic(state);
+					state.pendingRequestedHandoff = null;
+					if (ctx.hasUI) {
+						ctx.ui.setStatus(STATUS_KEY_HANDOFF, undefined);
+					}
 					pi.sendUserMessage("Proceed.");
 				},
 				onError: () => {
 					state.pendingHandoff = null;
-					// Safe: pendingRequestedHandoff may already be cleaned up by watchdog
 					if (state.pendingRequestedHandoff) {
 						state.pendingRequestedHandoff.toolCalled = false;
 					}