@gavin-hu/my-pi-agent 0.11.4 → 0.12.0

package/extensions/plan/web-client.ts

@@ -17,12 +17,15 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   "use strict";
 
   var dataNode = document.getElementById("review-data");
-  var fallback = { blocks: [], annotations: [], outline: [], steps: { done: 0, total: 0 }, code: {}, token: "" };
+  // The caps come from the island, which takes them from the server's own
+  // validation; the fallback only guards a page whose island failed to parse.
+  var fallback = { blocks: [], annotations: [], outline: [], steps: { done: 0, total: 0 }, code: {}, limits: { comments: 200, comment: 2000, quote: 500 }, token: "" };
   var data = fallback;
   if (dataNode && dataNode.textContent) {
     try { data = JSON.parse(dataNode.textContent); } catch (error) { data = fallback; }
   }
   var token = typeof data.token === "string" ? data.token : "";
+  var limits = data.limits || fallback.limits;
   var annotations = Array.isArray(data.annotations) ? data.annotations.slice() : [];
   var saved = false;
   var approved = false;
@@ -34,6 +37,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   var pendingQuote = null;
   var activeIndex = -1;
   var outlineItems = {};
+  var stream = null;
 
   var planEl = document.getElementById("plan");
   var statusEl = document.getElementById("status");
@@ -94,12 +98,20 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     stateEl.className = "bf-chip bf-chip--accent review-state" + (tone ? " bf-chip--" + tone : "");
   }
 
-  function safeHref(url) {
+  // A link is rendered only for an http(s) or mailto target. Resolving against
+  // the review origin is what catches a target that only looks relative: the
+  // URL parser strips a tab or newline, so "/\t/evil.com" is cross-origin once
+  // it is parsed, and a disguised target must stay text.
+  function safeHref(url, base) {
     var trimmed = String(url).trim();
-    if (/^[\\/]{2}/.test(trimmed)) return null;
-    if (/^(https?:|mailto:)/i.test(trimmed)) return trimmed;
-    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return null;
-    return trimmed;
+    if (!trimmed || /^\/\//.test(trimmed)) return null;
+    var resolved;
+    try { resolved = new URL(trimmed, base); } catch (error) { return null; }
+    if (resolved.protocol === "mailto:") return trimmed;
+    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") return null;
+    if (resolved.username || resolved.password) return null;
+    if (resolved.origin === new URL(base).origin) return resolved.href;
+    return /^https?:\/\//i.test(trimmed) ? resolved.href : null;
   }
 
   // Inline token order matters: code, emphasis, and links are matched before a
@@ -120,7 +132,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
         var em = el("em"); em.textContent = match[1]; container.appendChild(em); return;
       }
       if ((match = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(part))) {
-        var href = safeHref(match[2]);
+        var href = safeHref(match[2], location.href);
         if (!href) { container.appendChild(document.createTextNode(part)); return; }
         var link = el("a"); link.textContent = match[1]; link.href = href; link.target = "_blank"; link.rel = "noreferrer noopener";
         container.appendChild(link); return;
@@ -133,7 +145,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
         }
         var dot = url.indexOf(".");
         var target = /^www\./i.test(url) ? "http://" + url : url;
-        var safe = dot > 0 && /\.[^./]/.test(url.slice(dot)) ? safeHref(target) : null;
+        var safe = dot > 0 && /\.[^./]/.test(url.slice(dot)) ? safeHref(target, location.href) : null;
         if (safe) {
           var auto = el("a");
           auto.textContent = url;
@@ -311,7 +323,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     if (!selection || selection.isCollapsed) return "";
     var range = selection.rangeCount ? selection.getRangeAt(0) : null;
     if (!range || !wrap.contains(range.commonAncestorContainer)) return "";
-    return selection.toString().replace(/\s+/g, " ").trim().slice(0, 500);
+    return selection.toString().replace(/\s+/g, " ").trim().slice(0, limits.quote);
   }
 
   function commentsBoxAfter(wrap) {
@@ -325,7 +337,9 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   // Enter submits a comment; Shift+Enter is left for the browser.
   function submitOnEnter(area, submit) {
     area.addEventListener("keydown", function (event) {
-      if (event.key !== "Enter" || event.shiftKey) return;
+      // An IME uses Enter to commit a composition; submitting then would send a
+      // half-typed comment.
+      if (event.key !== "Enter" || event.shiftKey || event.isComposing) return;
       event.preventDefault();
       submit();
     });
@@ -343,6 +357,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     var area = el("textarea", "bf-textarea");
     area.placeholder = "Leave feedback on this part of the plan (Enter to add)";
     area.setAttribute("aria-label", "Comment");
+    area.maxLength = limits.comment;
     composer.appendChild(area);
     var row = el("div", "bf-composer__row");
     var cancel = el("button"); cancel.type = "button"; cancel.className = "bf-btn"; cancel.textContent = "Cancel";
@@ -351,7 +366,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     var submit = function () {
       var comment = area.value.replace(/\s+/g, " ").trim();
       if (!comment) { area.focus(); return; }
-      if (annotations.length >= 200) { setStatus("Comment limit reached (200).", "error"); return; }
+      if (annotations.length >= limits.comments) { setStatus("Comment limit reached (" + limits.comments + ").", "error"); return; }
       annotations.push(quote ? { anchor: block.start, quote: quote, comment: comment } : { anchor: block.start, comment: comment });
       dirty = true;
       renderPlan();
@@ -369,6 +384,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     var area = el("textarea", "bf-textarea");
     area.value = annotation.comment;
     area.setAttribute("aria-label", "Edit comment");
+    area.maxLength = limits.comment;
     card.appendChild(area);
     var row = el("div", "bf-comment__row");
     var cancel = el("button"); cancel.type = "button"; cancel.className = "bf-btn"; cancel.textContent = "Cancel";
@@ -585,6 +601,10 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
       planEl.appendChild(box);
     }
     planEl.scrollTop = scrollTop;
+    // The DOM was rebuilt, so the active block's class is gone; restore it in
+    // place rather than scrolling, so j/k resume where the reviewer was.
+    var active = activeIndex >= 0 ? blockElements()[activeIndex] : null;
+    if (active) active.classList.add("bf-block--active");
     renderFacts();
     observeSections();
     updateState();
@@ -633,6 +653,12 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     controls.appendChild(reload);
   }
 
+  // The stream exists only to notice a closed tab. Once the review is settled it
+  // has no job, and leaving it open retries a dead port until the tab closes.
+  function settleStream() {
+    if (stream && stream.close) { stream.close(); stream = null; }
+  }
+
   // Save and approve share the same POST shape; only the route, the settled
   // flag, and the wording differ. Both persist the current annotations.
   function submit(url, okText, failText, mark) {
@@ -644,6 +670,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
       if (response.ok) {
         mark();
         dirty = false;
+        settleStream();
         setStatus(okText, "saved");
         lockActions();
         updateState();
@@ -656,7 +683,12 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
         offerReload();
         return;
       }
-      throw new Error("server returned " + response.status);
+      // Surface the server's own reason (a malformed comment, a stale body)
+      // rather than a bare status code.
+      return response.json().then(
+        function (payload) { throw new Error(payload && payload.error ? payload.error : "server returned " + response.status); },
+        function () { throw new Error("server returned " + response.status); }
+      );
     }).catch(function (error) {
       setStatus(failText + error.message, "error");
     });
@@ -677,6 +709,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   function cancel() {
     if (saved || approved || closed) return;
     closed = true;
+    settleStream();
     lockActions();
     setStatus("Closing\u2026");
     updateState();
@@ -742,18 +775,18 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     if (event.key === "s") { event.preventDefault(); save(); return; }
   });
 
-  window.addEventListener("beforeunload", function () {
-    if (saved || approved || closed) return;
-    var url = "/api/cancel?token=" + encodeURIComponent(token);
-    if (navigator.sendBeacon) navigator.sendBeacon(url);
-  });
+  // A closed tab is detected by the stream below: the server sees the last
+  // client go away and cancels after a grace period, and a reload reconnects
+  // inside it. A beacon here would cancel the review on every reload, including
+  // the reload a 409 offers.
 
   window.addEventListener("scroll", updateProgress);
   window.addEventListener("resize", updateProgress);
+  window.addEventListener("pagehide", settleStream);
   if (planEl) planEl.addEventListener("scroll", updateProgress);
 
   try {
-    var stream = new EventSource("/events?token=" + encodeURIComponent(token));
+    stream = new EventSource("/events?token=" + encodeURIComponent(token));
     stream.addEventListener("open", function () { connected = true; everConnected = true; updateState(); });
     stream.addEventListener("error", function () {
       // The server ends the stream once the review is settled; keep showing the

package/extensions/plan/web-page.ts

@@ -57,6 +57,11 @@ export interface ReviewPageData {
 	steps: { done: number; total: number };
 	/** Highlighted HTML per line, keyed by the code block's 0-based start line. */
 	code: Record<string, string[]>;
+	/**
+	 * The caps the server enforces, so the page does not retype them: comment
+	 * count, comment length, and quote length, from `feedback.ts`.
+	 */
+	limits: { comments: number; comment: number; quote: number };
 	/** Whether the review may approve the plan (only the `exit_plan_mode` flow). */
 	canApprove: boolean;
 	/** Per-session secret the client echoes on every request. */

package/extensions/plan/web-router.ts

@@ -50,8 +50,13 @@ const HOST_PATTERN = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i;
 
 const HTML_SECURITY: Record<string, string> = {
 	"Content-Type": "text/html; charset=utf-8",
+	// `frame-ancestors` keeps a local page from framing the review and clickjacking
+	// the one control with a side effect (Approve & run); the rest is the same
+	// no-script, no-network envelope the page already relied on.
 	"Content-Security-Policy":
-		"default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'self'; connect-src 'self'",
+		"default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'self'; " +
+		"connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'none'",
+	"X-Frame-Options": "DENY",
 	"X-Content-Type-Options": "nosniff",
 	"Referrer-Policy": "no-referrer",
 	"Cache-Control": "no-store",
@@ -62,7 +67,7 @@ const SCRIPT_HEADERS: Record<string, string> = {
 	"Content-Type": "text/javascript; charset=utf-8",
 };
 
-const JSON_HEADERS: Record<string, string> = {
+export const JSON_HEADERS: Record<string, string> = {
 	"Content-Type": "application/json; charset=utf-8",
 	"X-Content-Type-Options": "nosniff",
 	"Referrer-Policy": "no-referrer",
@@ -112,7 +117,10 @@ function checkEnvelope(
 ): ServeResponse | undefined {
 	const upper = method.toUpperCase();
 	if (upper !== "GET" && upper !== "HEAD" && upper !== "POST") {
-		return { ...errorResponse(405, "Only GET and POST are served."), headers: { ...JSON_HEADERS, Allow: "GET, POST" } };
+		return {
+			...errorResponse(405, "Only GET, HEAD, and POST are served."),
+			headers: { ...JSON_HEADERS, Allow: "GET, HEAD, POST" },
+		};
 	}
 	// Fail closed: a missing or non-string Host is rejected too, not just a
 	// foreign one, so the DNS-rebinding guard cannot be skipped.

package/extensions/plan/web.ts

@@ -15,11 +15,24 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { basename } from "node:path";
 import { openInBrowser } from "../../lib/browser.ts";
 import { fenceLanguage, highlightLines } from "../../lib/highlight.ts";
-import { codeBody, fenceInfo, planBlocks, planHeadings } from "./blocks.ts";
-import { parseFeedback, stripFeedback, type PlanAnnotation } from "./feedback.ts";
+import { codeBody, fenceInfo, planBlocks } from "./blocks.ts";
+import {
+	MAX_ANNOTATIONS,
+	MAX_COMMENT_LENGTH,
+	MAX_QUOTE_LENGTH,
+	parseFeedback,
+	stripFeedback,
+	type PlanAnnotation,
+} from "./feedback.ts";
 import { planTitle, type PlanStore, type StoredPlan } from "./plans.ts";
-import { changedSections, extractPlanSteps } from "./steps.ts";
-import { handleReviewRequest, type ReviewContext, type ServeResponse, type SaveResult } from "./web-router.ts";
+import { changedSections, extractPlanSections, extractPlanSteps } from "./steps.ts";
+import {
+	handleReviewRequest,
+	JSON_HEADERS,
+	type ReviewContext,
+	type ServeResponse,
+	type SaveResult,
+} from "./web-router.ts";
 import type { ReviewPageData } from "./web-page.ts";
 
 /** How a browser review ended. */
@@ -64,6 +77,10 @@ export interface PlanWebReviewDeps {
 	token?: () => string;
 	/** Override the bind port; the default `0` lets the OS pick. */
 	port?: number;
+	/** Override the closed-tab grace; the default leaves a reload time to reconnect. */
+	dropGraceMs?: number;
+	/** Override the accepted body size; a test keeps it small. */
+	maxBodyBytes?: number;
 }
 
 /** Largest feedback body accepted, in bytes. */
@@ -71,21 +88,37 @@ const MAX_BODY_BYTES = 1024 * 1024;
 /** Grace period before an empty client set counts as a closed tab. */
 const DROP_GRACE_MS = 1500;
 
-function readBody(request: IncomingMessage): Promise<string | undefined> {
+/** A request body, or the fact that it was too large to read. */
+type BodyResult = { ok: true; body: string } | { ok: false };
+
+/**
+ * Read a request body, stopping at {@link MAX_BODY_BYTES}. An oversize body is
+ * reported rather than destroyed here, so the handler can still answer 413 over
+ * the open socket instead of the client seeing a dropped connection.
+ */
+function readBody(request: IncomingMessage, limit: number): Promise<BodyResult> {
 	return new Promise((resolve) => {
 		const chunks: Buffer[] = [];
 		let size = 0;
+		let done = false;
+		const settle = (result: BodyResult): void => {
+			if (done) return;
+			done = true;
+			resolve(result);
+		};
 		request.on("data", (chunk: Buffer) => {
+			if (done) return;
 			size += chunk.length;
-			if (size > MAX_BODY_BYTES) {
-				resolve(undefined);
-				request.destroy();
+			if (size > limit) {
+				chunks.length = 0;
+				request.pause();
+				settle({ ok: false });
 				return;
 			}
 			chunks.push(chunk);
 		});
-		request.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
-		request.on("error", () => resolve(undefined));
+		request.on("end", () => settle({ ok: true, body: Buffer.concat(chunks).toString("utf-8") }));
+		request.on("error", () => settle({ ok: false }));
 	});
 }
 
@@ -115,6 +148,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 	): Promise<PlanReviewSession | undefined> => {
 		const { signal } = options;
 		const canApprove = options.canApprove === true;
+		const maxBody = deps.maxBodyBytes ?? MAX_BODY_BYTES;
 		const token = (deps.token ?? (() => randomBytes(16).toString("hex")))();
 		let settled = false;
 		let resolveDone!: (result: PlanReviewResult) => void;
@@ -133,23 +167,46 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		// The stripped plan the page last rendered; a save must anchor against a file
 		// that still matches it, or the comments land beside the wrong text.
 		let baseline = stripFeedback(plan.content);
-		// Section titles that differ from what the previous review showed. Feedback
-		// is stripped on both sides, so a comment never reads as an edit.
-		const changed =
-			options.previous === undefined ? new Set<string>() : changedSections(stripFeedback(options.previous), baseline);
 		let savedPlan: StoredPlan | undefined;
 		// Set by `onSaved`/`onCancel`; resolved once the HTTP response has flushed,
 		// so the caller cannot close the socket before the browser sees the reply.
 		let pendingResult: PlanReviewResult | undefined;
 
-		const page = async (): Promise<ReviewPageData> => {
+		/**
+		 * Re-read the plan into `baseline` and return it. Named apart from the page
+		 * build because it writes the state a later save validates against, so a `GET`
+		 * does not hide that write inside what looks like a read.
+		 */
+		const refreshBaseline = async (): Promise<StoredPlan> => {
 			const current = (await store.read(cwd, plan.path)) ?? plan;
 			baseline = stripFeedback(current.content);
-			const blocks = planBlocks(baseline);
-			const headings = planHeadings(blocks);
+			return current;
+		};
+
+		const page = async (): Promise<ReviewPageData> => {
+			const stored = await refreshBaseline();
+			const current = baseline;
+			const blocks = planBlocks(current);
+			const sections = extractPlanSections(current);
+			// Per-occurrence change flags, aligned with the sections list: the same shape
+			// the terminal review renders, so duplicate headings cannot both light up.
+			const changed = options.previous === undefined ? [] : changedSections(stripFeedback(options.previous), current);
+			const outline = sections.flatMap((section, index) =>
+				section.title === ""
+					? []
+					: [
+							{
+								id: `s-${section.line}`,
+								line: section.line,
+								level: section.level,
+								text: section.title,
+								...(changed[index] ? { changed: true } : {}),
+							},
+						],
+			);
 			// The same step list approval seeds and set_plan_steps indexes, so the page's
 			// progress cannot disagree with the todo list.
-			const stepList = extractPlanSteps(baseline);
+			const stepList = extractPlanSteps(current);
 			// Highlight code blocks once, at the boundary: the client copies only the
 			// tok-* spans out of the server-escaped HTML.
 			const code: Record<string, string[]> = {};
@@ -161,21 +218,16 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 			return {
 				// The document's own H1 reads better than the file-name slug, and the
 				// slug is still the fallback for a plan that starts with something else.
-				title: headings.find((heading) => heading.level === 1)?.text || planTitle(basename(current.path)),
+				title: sections.find((section) => section.level === 1)?.title || planTitle(basename(plan.path)),
 				blocks,
-				annotations: parseFeedback(current.content),
-				outline: headings.map((heading) => ({
-					id: `s-${heading.line}`,
-					line: heading.line,
-					level: heading.level,
-					text: heading.text,
-					...(changed.has(heading.text) ? { changed: true } : {}),
-				})),
+				annotations: parseFeedback(stored.content),
+				outline,
 				steps: {
 					done: stepList.filter((step) => step.status === "completed").length,
 					total: stepList.length,
 				},
 				code,
+				limits: { comments: MAX_ANNOTATIONS, comment: MAX_COMMENT_LENGTH, quote: MAX_QUOTE_LENGTH },
 				token,
 				canApprove,
 			};
@@ -215,31 +267,34 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		// button and the abort signal are the deterministic paths.
 		const clients = new Set<ServerResponse>();
 		let hadClient = false;
+		const dropGrace = deps.dropGraceMs ?? DROP_GRACE_MS;
 		const scheduleDrop = (): void => {
 			if (clients.size > 0 || !hadClient || settled || dropTimer) return;
 			dropTimer = setTimeout(() => {
 				dropTimer = undefined;
 				if (clients.size === 0) finish({ status: "cancelled" });
-			}, DROP_GRACE_MS);
+			}, dropGrace);
 			(dropTimer as { unref?: () => void }).unref?.();
 		};
 
 		const server = createServer((request, response) => {
 			void (async () => {
 				const method = request.method ?? "GET";
-				const body = method.toUpperCase() === "POST" ? await readBody(request) : "";
-				if (body === undefined) {
-					response.writeHead(413, { "Content-Type": "application/json" });
+				const read =
+					method.toUpperCase() === "POST" ? await readBody(request, maxBody) : { ok: true as const, body: "" };
+				if (!read.ok) {
+					response.writeHead(413, { ...JSON_HEADERS, Connection: "close" });
 					response.end(JSON.stringify({ error: "The request body is too large." }));
 					return;
 				}
+				const body = read.body;
 				let result: ServeResponse;
 				try {
 					result = await handleReviewRequest(context, method, request.url ?? "/", request.headers, body);
 				} catch {
 					result = {
 						status: 500,
-						headers: { "Content-Type": "application/json" },
+						headers: { ...JSON_HEADERS },
 						body: JSON.stringify({ error: "Internal error" }),
 					};
 				}
@@ -264,16 +319,25 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 					return;
 				}
 				// A save or cancel only resolves the session after its response is on the
-				// wire; otherwise `close()` would force-close the socket mid-reply.
-				response.end(result.body ?? "", () => {
-					if (!pendingResult) return;
+				// wire; otherwise `close()` would force-close the socket mid-reply. The
+				// `close` path covers a client that walks away before the flush callback
+				// runs, so a settle cannot be lost with the socket.
+				const settlePending = (): void => {
 					const terminal = pendingResult;
+					if (!terminal) return;
 					pendingResult = undefined;
 					finish(terminal);
-				});
+				};
+				response.end(result.body ?? "", settlePending);
+				response.on("close", settlePending);
 			})();
 		});
 
+		// An accept-level error (EMFILE and friends) is emitted on the server, and an
+		// `error` event with no listener would take the host down mid-review. The
+		// review still ends through its own paths: cancel, abort, drop, or shutdown.
+		server.on("error", () => {});
+
 		const preferred = deps.port ?? ports.get(plan.path) ?? 0;
 		let port: number | undefined;
 		try {

package/extensions/question/README.md

@@ -131,7 +131,7 @@ None in v1 — the tool is either available (a UI exists) or not.
 |---|---|
 | Tool | `ask_user_question`; `exposure: "model-only"`, `defaultActive: false`, activated in `session_start` when `ctx.hasUI` is true. |
 | Execution | `executionMode: "sequential"`. |
-| Annotations | `readOnlyHint: true`, `openWorldHint: false`, `destructiveHint: false`. |
+| Annotations | `readOnlyHint: true`, `openWorldHint: false` (a read-only tool declares no `destructiveHint`). |
 | Output schema | None. Structured data is returned as tool-result `details` (not `structuredContent`). |
 | State storage | Tool-result `details` (`questions`, `answers`, `cancelled`, `unavailable`). No `pi.appendEntry`. |
 | Lifecycle | `session_start` only: add the tool to the active set when a UI exists. No `session_shutdown`. |

package/extensions/question/tools.ts

@@ -45,7 +45,7 @@ export function registerTools(pi: ExtensionAPI): void {
 		parameters: AskUserQuestionParams,
 		exposure: "model-only",
 		defaultActive: false,
-		annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: false },
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/extensions/subagent/index.ts

@@ -74,8 +74,6 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 		promptSnippet: "Delegate a task to a specialized subagent with an isolated context window.",
 		promptGuidelines: GUIDELINES,
 		parameters: SubagentParams,
-		exposure: "direct",
-		defaultActive: true,
 		// Deliberately no `executionMode`: sibling subagent calls are independent
 		// (each spawns its own child process), so they stay parallel by default.
 		annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },

package/extensions/todo/README.md

@@ -41,9 +41,13 @@ How the `todo` call and its result look in the transcript — the call line as a
   mutating tool call (`write`/`edit`/`bash`/`powershell`, or a tool declaring
   `readOnlyHint: false`) without a todo update, it injects one hidden reminder
   and forces a single continuation. A failed or blocked call changed nothing, so
-  it never triggers one. It only fires while the list has unfinished items, at
-  most once per user turn, and is dropped on the next user turn, so a reader can
-  never trigger it.
+  it never triggers one. It fires while the list has unfinished items, and —
+  when no list exists at all — only after three such calls in one turn, at least
+  one of them a file write (`write`/`edit`, or a tool declaring
+  `readOnlyHint: false`), so repeated `bash` inspection is not mistaken for
+  unplanned work. A list the model wrote or cleared during the turn is left
+  alone. At most one reminder per user turn, and it is dropped on the next user
+  turn, so a reader can never trigger it.
 - Declares an `outputSchema` and returns matching `structuredContent`
   (`{ todos, action, error? }`), so codemode/scripts can read the list as data.
 
@@ -157,7 +161,7 @@ depends on config.
 
 | Integration point | Value |
 |---|---|
-| Tool | `todo`; `exposure: "direct"` (default), `executionMode: "sequential"` |
+| Tool | `todo`; direct exposure (the default), `executionMode: "sequential"` |
 | Annotations | `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false` |
 | Output | `outputSchema` `TodoResult` — `{ todos, action, error? }` — also returned as `structuredContent` |
 | Command | `/todos` |
@@ -196,12 +200,16 @@ depends on config.
   [`lib/rails.ts`](../../lib/rails.ts) and [`goal`](../goal/).
 - **The reminder is a bounded nudge, not a nag.** A prompt guideline cannot
   guarantee a timely update, so the extension backs it with one forced
-  continuation. `tool_execution_end` marks a lag only for a successful call by
-  an explicit mutator list plus `readOnlyHint: false` — a failed or blocked call
-  is ignored, and a false positive costs a whole extra model request, so an
-  unrecognized reader is treated as harmless. `nudged` caps it at one per user
-  turn, `setTodos` clears the work flag, and `context` drops the hidden message
-  on the next user turn so it never accumulates.
+  continuation. `tool_execution_end` counts a successful call by an explicit
+  mutator list plus `readOnlyHint: false` — a failed or blocked call is ignored,
+  and a false positive costs a whole extra model request, so an unrecognized
+  reader is treated as harmless. An open item makes one call enough; a run with
+  no list at all must reach `EMPTY_LIST_MUTATIONS` (three) first and include a
+  file write, because a shell call cannot be told apart from `rg` and counts as
+  work but not as a write; a list the model wrote or cleared this turn is its own
+  answer and never reopens that path. `nudged` caps it at one per user turn,
+  `setTodos` clears the counters, and `context` drops the hidden message on the
+  next user turn so it never accumulates.
 - **Content is sanitized at the boundary.** `normalizeTodos` replaces control
   characters and collapses whitespace before the length and duplicate checks,
   keeping `format.ts` free of terminal concerns and every surface to one row
@@ -228,7 +236,7 @@ depends on config.
 | `types.ts` | `Todo`, `TodoStatus`, `TodoDetails`. |
 | `schema.ts` | TypeBox parameters and pure validation/normalization. |
 | `state.ts` | Branch reconstruction and status queries (pure). |
-| `nudge.ts` | Lag detection: mutating-tool classification, due check, reminder text (pure). |
+| `nudge.ts` | Lag detection: mutating and file-write classification, due check, reminder text (pure). |
 | `format.ts` | Model-facing and transcript text (pure). |
 | `tui.ts` | Widget and scrollable `/todos` components, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `config.ts` | Widget config load/validation (the `todo` section of `bytefly.json`). |

package/extensions/todo/index.ts

@@ -16,7 +16,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { registerCommands } from "./commands.ts";
 import { loadTodoConfig } from "./config.ts";
-import { formatNudge, isMutatingTool } from "./nudge.ts";
+import { formatNudge, isFileWrite, isMutatingTool } from "./nudge.ts";
 import { createTodoRuntime } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
 
@@ -55,11 +55,13 @@ export default function todo(pi: ExtensionAPI) {
 
 	// Only work that can change the working tree sets the lag flag; read-only
 	// tools and the todo call itself are ignored. A failed or blocked call changed
-	// nothing, so it must not force a reminder.
+	// nothing, so it must not force a reminder. A shell call counts as work but
+	// not as a write: its name cannot tell `rg` from `git commit`.
 	pi.on("tool_execution_end", (event) => {
 		if (event.isError) return;
 		const annotations = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
-		if (isMutatingTool(event.toolName, annotations)) runtime.noteWork();
+		if (!isMutatingTool(event.toolName, annotations)) return;
+		runtime.noteWork(isFileWrite(event.toolName, annotations));
 	});
 
 	// When the run is about to settle with unfinished work done since the last