one-code-extension 0.3.0 → 0.4.0

package/extensions/auto-mode/paths.ts

@@ -15,9 +15,9 @@
  *    and every caller treats that as "not provably contained".
  */
 
-import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import { lstatSync, readlinkSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { expandTilde } from "../lib/paths.ts";
+import { comparablePath, expandTilde, gitBashPathToNative, isPathAtOrUnder, tryRealpath } from "../lib/paths.ts";
 
 /**
  * Tools whose calls write to a path. Lives here — the lowest shared layer both
@@ -41,23 +41,8 @@ export function pathArgument(input: Record<string, unknown> | undefined): string
 	return typeof path === "string" ? path : undefined;
 }
 
-/** Case-folded on darwin/win32, where the filesystem is case-insensitive. */
-function normalize(target: string): string {
-	const normalized = resolve(target).replace(/\\/g, "/").replace(/\/+$/, "");
-	return process.platform === "linux" ? normalized : normalized.toLowerCase();
-}
-
-function tryRealpath(target: string): string | undefined {
-	try {
-		return realpathSync.native(target);
-	} catch {
-		try {
-			return realpathSync(target);
-		} catch {
-			return undefined;
-		}
-	}
-}
+/** The shared comparison form (lib/paths.ts): `/` separators, case-folded on darwin/win32. */
+const normalize = comparablePath;
 
 /**
  * Resolve a path for containment checks, following a symlink leaf that does not
@@ -99,11 +84,9 @@ export function resolveForContainment(target: string): string | undefined {
 	}
 }
 
-/** True only when `target` is provably at or under `base`. */
+/** True only when `target` is provably at or under `base` (lib/paths.ts `isPathAtOrUnder`, argument order kept for the callers here). */
 export function isWithin(base: string, target: string): boolean {
-	const normalizedBase = normalize(base);
-	const normalizedTarget = normalize(target);
-	return normalizedTarget === normalizedBase || normalizedTarget.startsWith(`${normalizedBase}/`);
+	return isPathAtOrUnder(target, base);
 }
 
 /**
@@ -119,3 +102,18 @@ export function toAbsolute(cwd: string, token: string, home: string): string {
 	if (isAbsolute(token)) return resolve(token);
 	return resolve(cwd, token);
 }
+
+/**
+ * {@link toAbsolute} for a token taken from a bash command line. On Windows the
+ * bash tool runs Git Bash, whose absolute paths are MSYS spellings — `/c/proj/f`
+ * is `C:\proj\f`, `/tmp/f` sits under the user's temp dir — so the token is
+ * converted first (lib/paths.ts gitBashPathToNative). `path.resolve` alone reads
+ * `/c/proj/f` as `<cwd drive>:\c\proj\f`, which no gate recognises as the
+ * project: the error fell towards escalate/prompt, never towards allow, but every
+ * in-project write spelled that way went to the classifier. File-tool paths keep
+ * `toAbsolute`: pi's read/edit/write resolve them natively, and a gate must
+ * judge the path the tool acts on, not the one Git Bash would reach.
+ */
+export function toAbsoluteBash(cwd: string, token: string, home: string): string {
+	return toAbsolute(cwd, gitBashPathToNative(token), home);
+}

package/extensions/auto-mode/safety-floor.ts

@@ -25,14 +25,11 @@
 import { analyzeShellCommand } from "./shell-analysis.ts";
 import { autoModeSettingsPaths } from "./config.ts";
 import { oneCodeProjectSettingsPath } from "../lib/one-code-settings.ts";
-import { claudeJsonPath } from "../lib/paths.ts";
+import { claudeJsonPath, comparablePath } from "../lib/paths.ts";
 import { isWritingTool, resolveForContainment, toAbsolute } from "./paths.ts";
 
-/** Case-fold the same way resolveForContainment's output is folded. */
-function fold(path: string): string {
-	const forward = path.replace(/\\/g, "/");
-	return process.platform === "linux" ? forward : forward.toLowerCase();
-}
+/** The same comparison form resolveForContainment's output is in (lib/paths.ts). */
+const fold = comparablePath;
 
 /**
  * Any `.claude/settings.json` or `.claude/settings.local.json`, wherever it
@@ -127,5 +124,46 @@ export function safetyControlWrite({ toolName, input, cwd, home, oneCodeProjectS
 		}
 	}
 
+	if (toolName === "powershell") {
+		// No PowerShell write model yet, so the floor is textual and wider than
+		// bash's: ANY mention of a gate-control file in the command line stops it,
+		// whether the cmdlet reads or writes. A `Get-Content` of settings.json
+		// costs one prompt; a `Set-Content` that slipped through would cost the
+		// gate (the floor may only ever say "stop" — header).
+		const command = typeof input.command === "string" ? input.command : "";
+		if (!command) return undefined;
+		for (const token of powershellPathTokens(command, home)) {
+			const absolute = toAbsolute(cwd, token, home);
+			if (isSafetyControlTarget(resolveForContainment(absolute) ?? absolute, home, perRepoSettings)) return REASON(token);
+		}
+	}
+
 	return undefined;
 }
+
+/**
+ * Path-looking tokens of a PowerShell line, quotes stripped, `$env:USERPROFILE`,
+ * `$env:HOME`, `$HOME` and `~` expanded to the home dir, backslashes
+ * forward-slashed. Anything with a separator or a `.json`-style file name
+ * counts; the floor tolerates false positives.
+ */
+export function powershellPathTokens(command: string, home: string): string[] {
+	const out: string[] = [];
+	for (const raw of command.split(/[\s;|()]+/)) {
+		let token = raw.replace(/^["']+|["',]+$/g, "");
+		if (!token) continue;
+		token = token
+			.replace(/^\$env:(USERPROFILE|HOME)/i, home)
+			.replace(/^\$HOME\b/i, home)
+			.replace(/^~(?=[\\/]|$)/, home)
+			.replace(/\\/g, "/");
+		// Parameter names (`-Path`) are not paths; `-Path:value` carries one.
+		if (token.startsWith("-")) {
+			const colon = token.indexOf(":");
+			if (colon === -1) continue;
+			token = token.slice(colon + 1);
+		}
+		if (/[\\/]/.test(token) || /\.json$/i.test(token)) out.push(token);
+	}
+	return out;
+}

package/extensions/auto-mode/shell-analysis.ts

@@ -32,7 +32,7 @@
 
 import { isProtectedPath } from "../permissions/protected-paths.ts";
 import { isExecutionPrimitivePath, isSensitivePath } from "./sensitive.ts";
-import { isWithin, resolveForContainment, toAbsolute } from "./paths.ts";
+import { isWithin, resolveForContainment, toAbsoluteBash } from "./paths.ts";
 
 export type ShellVerdict = "safe" | "escalate";
 
@@ -43,7 +43,13 @@ export interface ShellEvidence {
 	/** The commands that actually run, wrappers peeled (`env rm` → `rm`). */
 	commands: string[];
 	/** Resolved paths this command may write, with containment already decided. */
-	writes: { token: string; resolved?: string; outsideCwd: boolean }[];
+	/**
+	 * Every write target: the token as written, its absolute form as the shell
+	 * reaches it (`toAbsoluteBash`: Git Bash spellings converted, `~` and cwd
+	 * applied, not yet realpath'd — the form a "write it here instead" message
+	 * keeps the model's spelling from), the realpath'd form, and the verdict.
+	 */
+	writes: { token: string; absolute: string; resolved?: string; outsideCwd: boolean }[];
 	/** Credential/secret paths named anywhere in the command (original tokens, never expanded). */
 	sensitivePaths: string[];
 	/** In-project paths whose contents execute later (`.git/hooks/*`, `.vscode/*.json`). */
@@ -722,12 +728,21 @@ export interface AnalyzeInput {
 	 * A redirect landing inside one escalates like a write to `.git/hooks`.
 	 */
 	protectedDirs?: string[];
+	/**
+	 * REALPATH-resolved directories a read-only command may read from besides
+	 * the working directory without escalating: the harness's own session dirs
+	 * (memory, scratchpad, persisted results, this project's transcripts —
+	 * permissions/matcher.ts `DecideInput.sessionDirPath`), resolved once per
+	 * session by the caller (compared against realpaths here, unresolved). Reads
+	 * only; the write and delete checks never consult this list.
+	 */
+	readableRoots?: string[];
 }
 
 /**
  * Classify a shell command. Never denies — see the module contract above.
  */
-export function analyzeShellCommand({ command, cwd, home, protectedDirs = [] }: AnalyzeInput): ShellEvidence {
+export function analyzeShellCommand({ command, cwd, home, protectedDirs = [], readableRoots = [] }: AnalyzeInput): ShellEvidence {
 	const evidence: ShellEvidence = {
 		verdict: "safe",
 		notes: [],
@@ -790,10 +805,10 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [] }:
 	 */
 	const checkWriteTarget = (token: string) => {
 		if (token === "/dev/null") return;
-		const absolute = toAbsolute(effectiveCwd, token, home);
+		const absolute = toAbsoluteBash(effectiveCwd, token, home);
 		const resolved = resolveForContainment(absolute);
 		const outsideCwd = resolved === undefined || !isWithin(containmentRoot, resolved);
-		evidence.writes.push({ token, resolved, outsideCwd });
+		evidence.writes.push({ token, absolute, resolved, outsideCwd });
 		if (resolved === undefined) {
 			escalate(`writes to ${token}, which could not be resolved to a real path`);
 		} else if (outsideCwd) {
@@ -863,7 +878,7 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [] }:
 		// `~/.kube/config` through two tokens that each look harmless (N12).
 		for (const { value } of args) {
 			if (!value || value.startsWith("-")) continue;
-			const absolute = toAbsolute(effectiveCwd, value, home);
+			const absolute = toAbsoluteBash(effectiveCwd, value, home);
 			if (isSensitivePath(value) || isSensitivePath(absolute)) {
 				// The *original* token, never the resolved/expanded form (N18).
 				if (!evidence.sensitivePaths.includes(value)) evidence.sensitivePaths.push(value);
@@ -878,7 +893,7 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [] }:
 		if (name === "cd") {
 			const target = args.find((token) => !token.value.startsWith("-"))?.value;
 			if (target) {
-				effectiveCwd = toAbsolute(effectiveCwd, target, home);
+				effectiveCwd = toAbsoluteBash(effectiveCwd, target, home);
 				escalate(`changes directory to ${target}, so later paths in this command resolve elsewhere`);
 			}
 			continue;
@@ -902,7 +917,7 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [] }:
 				continue;
 			}
 			const reason = gitEscalationReason(args, (dir) => {
-				const resolved = resolveForContainment(toAbsolute(effectiveCwd, dir, home));
+				const resolved = resolveForContainment(toAbsoluteBash(effectiveCwd, dir, home));
 				return resolved === undefined || !isWithin(containmentRoot, resolved);
 			});
 			if (reason) escalate(reason);
@@ -946,8 +961,8 @@ export function analyzeShellCommand({ command, cwd, home, protectedDirs = [] }:
 			}
 			for (const value of positionals) {
 				if (!looksLikePath(value)) continue;
-				const resolved = resolveForContainment(toAbsolute(effectiveCwd, value, home));
-				if (resolved !== undefined && isWithin(containmentRoot, resolved)) continue;
+				const resolved = resolveForContainment(toAbsoluteBash(effectiveCwd, value, home));
+				if (resolved !== undefined && (isWithin(containmentRoot, resolved) || readableRoots.some((root) => isWithin(root, resolved)))) continue;
 				if (!evidence.outsideReads.includes(value)) evidence.outsideReads.push(value);
 				escalate(`reads ${value}, which is outside the working directory`, { outsideRead: true });
 			}

package/extensions/auto-mode/transcript.ts

@@ -16,6 +16,8 @@
 // the hooks matcher (its `ccToolName` is the correct-direction, mcp-passthrough
 // map; permissions/matcher.ts's is lower-cased and cannot recover casing).
 import { ccToolName } from "../hooks/matcher.ts";
+// The shell tools render as `{"<Tool>":"<command>"}` (lib/shell-tools.ts is the one list).
+import { SHELL_TOOLS } from "../lib/shell-tools.ts";
 
 export { ccToolName };
 
@@ -30,7 +32,13 @@ export { ccToolName };
 export type TranscriptEntry =
 	| { kind: "user"; text: string }
 	| { kind: "tool"; tool: string; input: Record<string, unknown> }
-	| { kind: "denied"; tool: string; subject: string; rule: string };
+	| { kind: "denied"; tool: string; subject: string; rule: string }
+	/**
+	 * Harness ground truth, Claude Code's `{"meta":{"gitStatus":{"clean":…}}}`
+	 * line after a `git status` call (captured 2.1.276, findings §22): the
+	 * classifier reads the tree's real state, not the model's account of it.
+	 */
+	| { kind: "meta"; gitStatus: { clean: boolean } };
 
 /** Truncate one field so a single huge argument cannot dominate the transcript. */
 export function clip(value: string, max: number): string {
@@ -47,12 +55,14 @@ function clipInput(input: Record<string, unknown>, max: number): Record<string,
 }
 
 /**
- * Render one entry as its compact JSON line. Bash renders as `{"Bash":"<command>"}`
- * (the command string, as Claude Code does); every other tool renders as
- * `{"<Tool>":{…input…}}` with string fields clipped.
+ * Render one entry as its compact JSON line. The shell tools render as
+ * `{"Bash":"<command>"}` / `{"PowerShell":"<command>"}` (the command string,
+ * as Claude Code does); every other tool renders as `{"<Tool>":{…input…}}`
+ * with string fields clipped.
  */
 function renderEntry(entry: TranscriptEntry, maxField: number): string {
 	if (entry.kind === "user") return JSON.stringify({ user: clip(entry.text, maxField) });
+	if (entry.kind === "meta") return JSON.stringify({ meta: { gitStatus: { clean: entry.gitStatus.clean } } });
 	if (entry.kind === "denied") {
 		return JSON.stringify({
 			denied_by_permission_rule: { tool: ccToolName(entry.tool), attempted: clip(entry.subject, maxField), rule: entry.rule },
@@ -60,7 +70,7 @@ function renderEntry(entry: TranscriptEntry, maxField: number): string {
 	}
 	const name = ccToolName(entry.tool);
 	const command = entry.input.command;
-	if (entry.tool === "bash" && typeof command === "string") {
+	if (SHELL_TOOLS.has(entry.tool) && typeof command === "string") {
 		return JSON.stringify({ [name]: clip(command, maxField) });
 	}
 	return JSON.stringify({ [name]: clipInput(entry.input, maxField) });

package/extensions/background/index.ts

@@ -6,18 +6,19 @@
  * long-running work over TASK_REGISTER_CHANNEL at runtime, so task_output and
  * task_stop address every background task in the session regardless of which
  * extension started it. Events and completions are delivered as steered
- * system notifications (lib/notifications.ts), never as user input.
+ * task notifications (lib/notifications.ts), never as user input; a fired
+ * wakeup or loop tick re-invokes the session with its prompt verbatim.
  */
 
-import { spawn } from "node:child_process";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { whenAborted } from "../lib/abort.ts";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { persistIfLarge, sessionResultsDir } from "../lib/persisted-output.ts";
-import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree } from "../lib/process-tree.ts";
+import { detachedSpawnOptions, KILL_GRACE_MS, stopProcessTree, waitForChildExit } from "../lib/process-tree.ts";
 import { sessionAlive } from "../lib/session-lifecycle.ts";
-import { ccToolRenderers, customMessageText, liveUiCtx, notificationComponent } from "../lib/tui-render.ts";
+import { bashSpawn, spawnShellCommand } from "../lib/shell-spawn.ts";
+import { ccToolRenderers, customMessageText, liveUiCtx, notificationComponent, scheduledTaskComponent } from "../lib/tui-render.ts";
 import {
 	type BackgroundTask,
 	BackgroundRegistry,
@@ -35,16 +36,28 @@ import {
 	MIN_DELAY_SECONDS,
 	parseLoopArgs,
 } from "./wakeup.ts";
-import { createTaskNotifier, oneShotNote, sessionOutlivesTurn, systemNotification } from "../lib/notifications.ts";
+import {
+	createTaskNotifier,
+	monitorEndedSummary,
+	monitorEventSummary,
+	oneShotNote,
+	sessionOutlivesTurn,
+	TASK_OUTPUT_DELIVERED_CHANNEL,
+	type TaskOutputDelivered,
+	taskNotification,
+	taskStatusOf,
+} from "../lib/notifications.ts";
 import {
 	batchSize,
 	emptyBatch,
-	formatMonitorBatch,
+	formatMonitorEvents,
 	MONITOR_BATCH_BUSY_MS,
+	MONITOR_BATCH_MAX_CHARS,
 	MONITOR_BATCH_IDLE_MS,
 	type MonitorBatch,
 	pushEvent,
 } from "./monitor-batch.ts";
+import { registerLocalCommand } from "../lib/local-command.ts";
 
 const OUTPUT_CAP = 30_000;
 const STORED_OUTPUT_CAP = 200_000;
@@ -103,16 +116,26 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		live.ui.setWidget("cc-background", running > 0 ? [` background tasks: ${running} running`] : undefined);
 	};
 
-	// Harness-injected notifications carry anti-confabulation framing for the
-	// model; the transcript shows a compact headline instead (ctrl+o expands).
-	// One registration covers every emitter of the type (bash uses it too).
-	for (const customType of ["task-notification", "wakeup", "loop"]) {
+	// The wire frames are model-facing; the transcript shows a compact headline
+	// instead (ctrl+o expands). One registration covers every emitter of
+	// `task-notification` (bash uses it too). A fired wakeup or loop tick is the
+	// prompt verbatim, shown behind Claude Code's "Running scheduled task" line.
+	pi.registerMessageRenderer("task-notification", (message, { expanded }, theme) =>
+		notificationComponent(theme, customMessageText(message.content), expanded),
+	);
+	for (const customType of ["wakeup", "loop"]) {
 		pi.registerMessageRenderer(customType, (message, { expanded }, theme) =>
-			notificationComponent(theme, customMessageText(message.content), expanded),
+			scheduledTaskComponent(theme, customMessageText(message.content), (message as { timestamp?: number }).timestamp ?? Date.now(), expanded),
 		);
 	}
+	// The dynamic /loop's opening turn is the user's command, not a fired task.
+	pi.registerMessageRenderer("loop-start", (message, { expanded }, theme) =>
+		notificationComponent(theme, customMessageText(message.content), expanded),
+	);
 
-	const notify = createTaskNotifier(pi);
+	// A monitor's end the model already read through task_output is withdrawn
+	// like a shell's (lib/notifications.ts).
+	const notify = createTaskNotifier(pi, { withdrawOnDelivery: true });
 
 	pi.registerTool({
 		name: "monitor",
@@ -137,7 +160,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				),
 			),
 		}),
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			lastCtx = ctx;
 			if (Boolean(params.command) === Boolean(params.ws)) {
 				return {
@@ -170,10 +193,12 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				if (batchSize(pending) === 0) return;
 				const batch = pending;
 				pending = emptyBatch();
-				notify("task-notification", systemNotification(formatMonitorBatch(id, params.description, batch)), {
-					taskId: id,
-					events: batchSize(batch),
-				});
+				// CC's mid-run monitor batch: no status, the lines in `<event>`.
+				notify(
+					"task-notification",
+					taskNotification({ kind: "monitor", taskId: id, summary: monitorEventSummary(params.description), result: formatMonitorEvents(id, batch) }),
+					{ taskId: id, events: batchSize(batch) },
+				);
 			};
 
 			const onEvent = (line: string) => {
@@ -200,9 +225,19 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				if (!alive() || oneShot) return;
 				flush();
 				updateWidget();
+				// CC's monitor end: the recent tail rides `<event>` under the ended summary.
+				const ccStatus = taskStatusOf(finalStatus);
+				const recent = tail(stored, MONITOR_BATCH_MAX_CHARS).trim();
 				notify(
 					"task-notification",
-					systemNotification(`Monitor ${id} (${params.description}) ${finalStatus}${note ? ` — ${note}` : ""} after ${eventCount} event(s).`),
+					taskNotification({
+						kind: "monitor",
+						taskId: id,
+						toolUseId: toolCallId,
+						status: ccStatus,
+						summary: monitorEndedSummary(params.description, ccStatus, eventCount > 0, note),
+						result: recent || undefined,
+					}),
 					{ taskId: id, status: finalStatus },
 				);
 			};
@@ -214,13 +249,22 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				// leader — with zsh a `cmd; echo` or a pipeline otherwise lives on as an
 				// orphan holding the stdout pipe, so the task never finishes and, in a
 				// one-shot run, the process cannot exit (LIFECYCLE-REVIEW M2, measured).
-				const child = spawn(process.env.SHELL || "/bin/sh", ["-c", params.command], {
+				// The session's bash (Git Bash on Windows) — lib/shell-spawn.ts.
+				const bash = bashSpawn();
+				if (!bash.spawn) {
+					return {
+						content: [{ type: "text", text: `Cannot start the monitor: ${bash.error ?? "no bash shell was found"}` }],
+						details: {},
+						isError: true,
+					};
+				}
+				const child = spawnShellCommand(bash.spawn, params.command, {
 					cwd: ctx.cwd,
 					...detachedSpawnOptions(),
 					stdio: ["ignore", "pipe", "pipe"],
 				});
 				let buffer = "";
-				child.stdout.on("data", (chunk: Buffer) => {
+				child.stdout?.on("data", (chunk: Buffer) => {
 					buffer += chunk.toString();
 					let idx: number;
 					while ((idx = buffer.indexOf("\n")) !== -1) {
@@ -229,15 +273,17 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 						if (line) onEvent(line);
 					}
 				});
-				child.stderr.on("data", (chunk: Buffer) => {
+				child.stderr?.on("data", (chunk: Buffer) => {
 					stored = tail(`${stored}${chunk.toString()}`, STORED_OUTPUT_CAP);
 				});
-				child.on("error", (error) => end("failed", error.message));
-				child.on("close", (code) =>
-					end(
-						stopRequested ? "stopped" : code === 0 ? "completed" : "failed",
-						code !== null && code !== 0 ? `exit code ${code}` : undefined,
-					),
+				// Exit plus a short stdio grace, not `close` (lib/process-tree.ts).
+				waitForChildExit(child).then(
+					({ code }) =>
+						end(
+							stopRequested ? "stopped" : code === 0 ? "completed" : "failed",
+							code !== null && code !== 0 ? `exit code ${code}` : undefined,
+						),
+					(error: Error) => end("failed", error.message),
 				);
 				stop = () => {
 					stopRequested = true;
@@ -328,7 +374,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Monitor ${id} started (${params.description}). Events arrive as system notifications; stop with task_stop, inspect with task_output.`,
+						text: `Monitor ${id} started (${params.description}). Events arrive as task notifications; stop with task_stop, inspect with task_output.`,
 					},
 				],
 				details: { taskId: id },
@@ -341,7 +387,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		label: "Task Output",
 		...ccToolRenderers("Task Output"),
 		description:
-			"Retrieve output from a running or finished background task (monitor, background subagent, or background bash) by task id. block=true (default) waits up to `timeout` ms for completion; block=false returns the current status immediately. You never need this just to learn that a task finished — completion arrives as a system notification with the status and the last 2 KB of output; call this for the rest of the output, when your next step needs the result now, or for a mid-run peek.",
+			"Retrieve output from a running or finished background task (monitor, background subagent, or background bash) by task id. block=true (default) waits up to `timeout` ms for completion; block=false returns the current status immediately. You never need this just to learn that a task finished — completion arrives as a task notification naming the output file; call this for the output itself, when your next step needs the result now, or for a mid-run peek.",
 		parameters: Type.Object({
 			task_id: Type.String({ description: "The task id to get output from" }),
 			block: Type.Optional(Type.Boolean({ description: "Wait for completion (default true)" })),
@@ -377,6 +423,9 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 			updateWidget();
 			const header = formatTaskLine(task);
 			const body = tail(task.output(), OUTPUT_CAP) || "(no output yet)";
+			// The model now holds a finished task's output: a completion notification
+			// still waiting to go out for it is redundant (lib/notifications.ts).
+			if (task.status !== "running") pi.events.emit(TASK_OUTPUT_DELIVERED_CHANNEL, { taskId: task.id } satisfies TaskOutputDelivered);
 			return {
 				content: [{ type: "text", text: `${header}\n\n${body}` }],
 				details: { taskId: task.id, status: task.status, logPath: task.logPath },
@@ -430,7 +479,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 			title: (a) => (a?.stop ? "stop" : a?.delaySeconds !== undefined ? `${a.delaySeconds}s` : undefined),
 		}),
 		description:
-			"Schedule when to resume work on a self-paced recurring task — the dynamic mode of the /loop command. After `delaySeconds` (clamped to [60, 3600]) the given prompt is delivered as a system notification and a new turn starts. One wakeup is pending at a time — scheduling again replaces it; {stop: true} ends the loop and cancels any pending wakeup.\n\nPass the same task back via `prompt` each turn so the next firing repeats it. Set `noop: true` when nothing changed this tick (you checked and there's nothing to report); `noop: false` when something happened worth keeping. Pick `delaySeconds` from what you're actually waiting for: poll external state (a CI run, a deploy) at the rate it changes; for a quiet idle heartbeat prefer a long delay (1200s+). Do NOT schedule a short wakeup just to poll background work you started here — its completion already notifies you.",
+			"Schedule when to resume work on a self-paced recurring task — the dynamic mode of the /loop command. After `delaySeconds` (clamped to [60, 3600]) the harness re-invokes you with the given prompt, verbatim, as the next turn's input. One wakeup is pending at a time — scheduling again replaces it; {stop: true} ends the loop and cancels any pending wakeup.\n\nPass the same task back via `prompt` each turn so the next firing repeats it. Set `noop: true` when nothing changed this tick (you checked and there's nothing to report); `noop: false` when something happened worth keeping. Pick `delaySeconds` from what you're actually waiting for: poll external state (a CI run, a deploy) at the rate it changes; for a quiet idle heartbeat prefer a long delay (1200s+). Do NOT schedule a short wakeup just to poll background work you started here — its completion already notifies you.",
 		parameters: Type.Object({
 			delaySeconds: Type.Optional(Type.Number({ description: "Seconds from now to wake up, clamped to [60, 3600]. Required unless stop is true" })),
 			prompt: Type.Optional(Type.String({ description: "The task to continue when the wakeup fires. Required unless stop is true" })),
@@ -488,9 +537,9 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		pi.events.emit(DEFER_CHANNEL, { name, keywords });
 	}
 
-	pi.registerCommand("background", {
+	registerLocalCommand(pi, "background", {
 		description: "List background tasks (monitors, background subagents)",
-		handler: async (_args, ctx) => {
+		handler: async (args, ctx) => {
 			const tasks = registry.list();
 			ctx.ui.notify(tasks.length ? tasks.map(formatTaskLine).join("\n") : "No background tasks.", "info");
 		},
@@ -509,7 +558,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 		}
 	};
 
-	pi.registerCommand("loop", {
+	registerLocalCommand(pi, "loop", {
 		description: "Repeat a task on a loop: `/loop 5m <task>` (fixed interval) or `/loop <task>` (self-paced). `/loop stop` ends it.",
 		handler: async (args, ctx) => {
 			lastCtx = ctx;
@@ -580,7 +629,7 @@ export default function backgroundExtension(pi: ExtensionAPI) {
 				activatedWakeupTool = true;
 			}
 			ctx.ui.notify(`Self-paced loop started: ${parsed.task}. Stop with /loop stop.`, "info");
-			notify("loop", buildDynamicLoopPrompt(parsed.task), {});
+			notify("loop-start", buildDynamicLoopPrompt(parsed.task), {});
 		},
 	});
 

package/extensions/background/monitor-batch.ts

@@ -37,9 +37,12 @@ export function batchSize(batch: MonitorBatch): number {
 	return batch.shown.length + batch.overflow;
 }
 
-/** The notification body for one flushed batch. */
-export function formatMonitorBatch(id: string, description: string, batch: MonitorBatch): string {
-	const total = batchSize(batch);
+/**
+ * The `<event>` body for one flushed batch: the lines, then how many more
+ * arrived (the full stream stays behind `task_output`). The monitor's
+ * description rides the notification's `<summary>`, not this text.
+ */
+export function formatMonitorEvents(id: string, batch: MonitorBatch): string {
 	const lines: string[] = [];
 	let chars = 0;
 	let hidden = batch.overflow;
@@ -52,7 +55,6 @@ export function formatMonitorBatch(id: string, description: string, batch: Monit
 		lines.push(shown);
 		chars += shown.length + 1;
 	}
-	const head = `Monitor ${id} (${description}) emitted ${total} event(s):`;
 	const more = hidden > 0 ? `\n… +${hidden} more line(s) not shown — task_output ${id} has the full stream` : "";
-	return `${head}\n${lines.join("\n")}${more}`;
+	return `${lines.join("\n")}${more}`;
 }

package/extensions/background/wakeup.ts

@@ -1,9 +1,13 @@
 /**
  * schedule_wakeup helpers (pure) — Claude Code's self-paced /loop timer.
+ *
+ * A fired wakeup or loop tick is a RE-INVOCATION, not a notification: Claude
+ * Code enqueues the scheduled prompt verbatim as the next turn's input, behind
+ * a dim "Running scheduled task" line in the TUI (findings §21), so the model
+ * reads its own task back exactly as it wrote it. These builders therefore
+ * return the prompt as-is; the TUI shows the line (`scheduledTaskComponent`).
  */
 
-import { systemNotification } from "../lib/notifications.ts";
-
 export const MIN_DELAY_SECONDS = 60;
 export const MAX_DELAY_SECONDS = 3600;
 
@@ -42,37 +46,27 @@ export function parseLoopArgs(raw: string): ParsedLoop {
 	return { task: raw.trim() };
 }
 
-/** A loop follow-up: an instruction line, a blank, then the task — system-framed. */
-function framedLoop(lead: string, task: string): string {
-	return systemNotification([lead, "", task].join("\n"));
-}
-
-/** The follow-up a fixed-interval `/loop` tick delivers. */
+/** The turn input a fixed-interval `/loop` tick delivers: the task, verbatim (CC's cron fire). */
 export function buildLoopMessage(task: string): string {
-	return framedLoop(
-		"Loop tick — run the task below now. This repeats automatically on the interval and keeps firing until the user runs `/loop stop`.",
-		task,
-	);
+	return task;
 }
 
-/** The opening message for a dynamic (self-paced) `/loop` — instructs the model to drive schedule_wakeup. */
+/**
+ * The opening turn of a dynamic (self-paced) `/loop`: the user's command, so it
+ * reads as their instruction — drive schedule_wakeup, pass the task back each
+ * time. Unframed: it is the user's `/loop`, not a harness event.
+ */
 export function buildDynamicLoopPrompt(task: string): string {
-	return framedLoop(
+	return [
 		"Self-paced loop started. Work the task below now. When this iteration is done, call schedule_wakeup to schedule the next one — choose delaySeconds by what you're waiting for, and pass the same task back as `prompt`. End the loop with schedule_wakeup {stop: true} when the task is complete or the user says to stop.",
+		"",
 		task,
-	);
+	].join("\n");
 }
 
-/** The follow-up message a fired wakeup delivers. Framed so it never reads as user input. */
+/** The turn input a fired wakeup delivers: the scheduled prompt, verbatim (CC re-invokes with it). */
 export function buildWakeupMessage(request: WakeupRequest): string {
-	return systemNotification(
-		[
-			`Scheduled wake-up fired (reason given when scheduled: ${request.reason}).`,
-			"Continue the task below; when done, either schedule the next wake-up with schedule_wakeup or end the loop with schedule_wakeup {stop: true}.",
-			"",
-			request.prompt,
-		].join("\n"),
-	);
+	return request.prompt;
 }
 
 export function describeSchedule(request: WakeupRequest): string {