@hank-warren/pi-loop 0.5.0 → 0.7.0

package/src/manager.ts

@@ -7,7 +7,6 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { formatDuration, parseInterval } from "./interval.js";
 import type { LoopController } from "./loop.js";
-import { readGoalSnapshot } from "./state.js";
 import {
 	DEFAULT_LOOP_SETTINGS,
 	type LoopSettings,
@@ -79,39 +78,35 @@ async function startFromMenu(
 		ctx.ui.notify(`Invalid interval: ${intervalText}. Use <number><unit>, e.g. 5m.`, "error");
 		return;
 	}
-	// With an active goal the loop binds to it and the text is an optional
-	// per-wake focus. Without one the loop owns its objective, so the text is
-	// required — asking for it here is what replaces the old dead-end refusal.
-	const goal = readGoalSnapshot(ctx.sessionManager.getBranch());
-	const goalBound = goal?.status === "active";
+	// The loop owns its objective, so the text is required — asking for it here
+	// is what replaces the old dead-end refusal.
 	const promptText = await ctx.ui.input(
-		goalBound
-			? "Loop focus (optional, added to every goal poke)"
-			: "Objective, including how the loop knows it is done",
-		goalBound ? undefined : "e.g. get CI green on main, verified by a passing run",
+		"Objective, including how the loop knows it is done",
+		"e.g. get CI green on main, verified by a passing run",
 	);
 	if (promptText === undefined) return;
 	const prompt = promptText.trim();
-	if (!goalBound && !prompt) {
-		ctx.ui.notify(
-			"A loop with no active goal needs its own objective, so no loop was started.",
-			"warning",
-		);
+	if (!prompt) {
+		ctx.ui.notify("A loop needs an objective, so no loop was started.", "warning");
 		return;
 	}
-	controller.startLoop(ctx, {
+	const result = controller.startLoop(ctx, {
 		kind: "start",
 		requestedMs: interval.requestedMs,
 		intervalMs: interval.effectiveMs,
 		clamped: interval.clamped,
 		...(prompt ? { prompt } : {}),
 	});
+	if (!result.ok) ctx.ui.notify(result.message, "error");
 }
 
 async function editPrompt(controller: LoopController, ctx: ExtensionCommandContext): Promise<void> {
 	const loop = controller.state;
 	if (!loop || loop.status === "stopped") return;
-	const next = await ctx.ui.input("Loop focus (optional, added to every goal poke)", loop.prompt ?? "");
+	const next = await ctx.ui.input(
+		"Loop focus (optional, restated on every loop message)",
+		loop.prompt ?? "",
+	);
 	if (next === undefined) return;
 	const prompt = next.trim();
 	if (prompt) controller.state = { ...loop, prompt };
@@ -159,8 +154,7 @@ export async function showLoopSettings(
 	for (;;) {
 		const s = controller.settings;
 		const items = [
-			`Max wakes: ${s.maxIterations === null ? "Unlimited" : s.maxIterations}`,
-			`Max automatic turns: ${s.automaticTurns === null ? "Unlimited" : s.automaticTurns}`,
+			`Max loop turns: ${s.maxTurns === null ? "Unlimited" : s.maxTurns}`,
 			`No-progress breaker: ${s.noProgressTurns === null ? "Off" : `after ${s.noProgressTurns} repeats`}`,
 			`Max loop duration: ${s.maxLoopDuration}`,
 			`Proactive compaction: ${s.compaction.enabled ? `On at ${Math.round(s.compaction.threshold * 100)}%` : "Off"}`,
@@ -172,14 +166,10 @@ export async function showLoopSettings(
 		if (index === 0) {
 			// Unlimited is a first-class choice, not a magic word typed into a free
 			// text box: it is only reachable by discovery otherwise.
-			const cap = await editCap(ctx, "Max wakes", "no wake cap", s.maxIterations);
+			const cap = await editCap(ctx, "Max loop turns", "no turn cap", s.maxTurns);
 			if (cap === undefined) continue;
-			next.maxIterations = cap === "unlimited" ? null : cap;
+			next.maxTurns = cap === "unlimited" ? null : cap;
 		} else if (index === 1) {
-			const cap = await editCap(ctx, "Max automatic turns", "no turn cap", s.automaticTurns);
-			if (cap === undefined) continue;
-			next.automaticTurns = cap === "unlimited" ? null : cap;
-		} else if (index === 2) {
 			const cap = await editCap(
 				ctx,
 				"No-progress breaker",
@@ -188,7 +178,7 @@ export async function showLoopSettings(
 			);
 			if (cap === undefined) continue;
 			next.noProgressTurns = cap === "unlimited" ? null : cap;
-		} else if (index === 3) {
+		} else if (index === 2) {
 			const value = await ctx.ui.input("Max loop duration (e.g. 7d)", s.maxLoopDuration);
 			if (value === undefined) continue;
 			if (parseDuration(value.trim()) === undefined) {
@@ -196,7 +186,7 @@ export async function showLoopSettings(
 				continue;
 			}
 			next.maxLoopDuration = value.trim();
-		} else if (index === 4) {
+		} else if (index === 3) {
 			if (s.compaction.enabled) next.compaction.enabled = false;
 			else {
 				const value = await ctx.ui.input(
@@ -221,7 +211,7 @@ export async function showLoopSettings(
 }
 
 /**
- * One cap editor for both counters. Unlimited is a first-class choice, not a
+ * One cap editor for every cap. Unlimited is a first-class choice, not a
  * magic word typed into a free text box: it is only reachable by discovery
  * otherwise. The typed word still works, so the /loop --max vocabulary and
  * muscle memory keep working.

package/src/messages.ts

@@ -10,48 +10,35 @@ import { LOOP_OK_TOKEN } from "./ack.js";
 import { formatDuration } from "./interval.js";
 import { CRITERIA_FILE, type LedgerPaths, PROGRESS_FILE } from "./ledger.js";
 import { appendContinuationMarker, appendPokeMarker } from "./markers.js";
-import type { GoalSnapshot, LoopState } from "./state.js";
+import type { LoopState } from "./state.js";
 
 /** Why the loop is talking: the first turn, an ordinary turn, or after a compaction. */
 export type ContinuationKind = "kickoff" | "continue" | "reanchor";
 
-function formatIteration(loop: LoopState): string {
-	const cap = loop.maxIterations === null ? "unlimited" : `${loop.maxIterations}`;
-	return `${loop.iteration + 1}/${cap}`;
-}
-
 /**
- * The goal-bound poke: wake the session and point at the goal without
- * restating it. Loops require an active pi-goal goal, so every poke turn
- * already carries the objective, goal_id, and goal-mode rules through
- * pi-goal's system prompt append; restating them here would store duplicate
- * tokens in the conversation on every wake (see README: cross-extension
- * assumption). Only the dynamic per-wake state (iteration, reason) belongs in
- * this tail message.
+ * The wake ordinal, and only the ordinal. It used to read `4/25`, the wake
+ * counter against the delivered-wake cap; that cap is gone, collapsed into
+ * the single loop-turn cap, and pairing a wake number with a turn cap would
+ * have been a number that reads as a budget and is not one. The cap is shown
+ * to the *user*, in the widget and `/loop status`, which is who it is for.
  */
-export function buildGoalPoke(loop: LoopState, reason: "goal-stalled" | "goal-waiting"): string {
-	const lines = [
-		`Scheduled loop wakeup ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}).`,
-		reason === "goal-waiting"
-			? "This is the external wake for your waiting goal. Re-check whatever the goal was waiting on and continue."
-			: "The session went idle but the active goal is not complete. Continue working toward it — the objective and goal-mode rules are in the system prompt.",
-	];
-	if (loop.prompt) lines.push("", `Loop focus: ${loop.prompt}`);
-	return appendPokeMarker(lines.join("\n"), loop.id, loop.iteration + 1);
+function formatWakeOrdinal(loop: LoopState): string {
+	return `${loop.iteration + 1}`;
 }
 
 /**
- * The standalone poke. Slim for the same reason the goal-bound one is: this
- * loop's own objective injection puts the objective and loop-mode rules in
- * the system prompt of every turn, so restating them here would store a
- * duplicate copy on every wake.
+ * The poke. Deliberately slim: the loop's own objective injection puts the
+ * objective and loop-mode rules in the system prompt of every turn, so
+ * restating them here would store a duplicate copy on every wake. Only the
+ * dynamic per-wake state (the wake ordinal, the reason) belongs in this tail
+ * message.
  */
 export function buildObjectivePoke(
 	loop: LoopState,
 	reason: "objective-stalled" | "wait-elapsed" = "objective-stalled",
 ): string {
 	const lines = [
-		`Scheduled loop wakeup ${formatIteration(loop)} (every ${formatDuration(loop.intervalMs)}).`,
+		`Scheduled loop wakeup ${formatWakeOrdinal(loop)} (every ${formatDuration(loop.intervalMs)}).`,
 		reason === "wait-elapsed"
 			? "The wait you asked for has elapsed. Re-check the external state it depended on and continue — the objective and loop-mode rules are in the system prompt."
 			: "The session went idle but the loop objective's completion criteria are not met. Continue working it — the objective and loop-mode rules are in the system prompt.",
@@ -81,8 +68,8 @@ function addCancelledWaitHint(lines: string[], loop: LoopState): void {
 }
 
 /**
- * The settle-driven continuation: the message that actually paces a
- * standalone loop now. Pointer-sized for the same reason the pokes are — it
+ * The settle-driven continuation: the message that actually paces a loop.
+ * Pointer-sized for the same reason the pokes are — it
  * only ever fires while the loop is active, so the byte-stable system append
  * carrying the objective and loop-mode rules is guaranteed present on that
  * turn.
@@ -207,20 +194,16 @@ export function extractNextActions(summary: string, maxLength = 240): string | u
  */
 export function buildCompactionInstructions(
 	loop: LoopState,
-	/** The goal only when it is still active; a finished goal is not the objective. */
-	goal: GoalSnapshot | undefined,
 	override: string | null,
 	/** The loop's ledger, when it has one. */
 	ledger?: LedgerPaths,
 ): string {
 	if (override) return override;
-	const objective = goal
-		? `The session is working toward this goal: ${goal.text}`
-		: loop.objective
-			? `The session is working toward this loop objective: ${loop.objective}`
-			: loop.prompt
-				? `The session is running a recurring loop focused on: ${loop.prompt}`
-				: "The session is running a recurring loop.";
+	const objective = loop.objective
+		? `The session is working toward this loop objective: ${loop.objective}`
+		: loop.prompt
+			? `The session is running a recurring loop focused on: ${loop.prompt}`
+			: "The session is running a recurring loop.";
 	return [
 		`${objective}`,
 		"This summary must let that work continue seamlessly. Preserve verbatim:",

package/src/objective.ts

@@ -1,12 +1,10 @@
 /**
- * The standalone loop's objective injection.
+ * The loop's objective injection.
  *
- * A goal-bound loop gets the objective in front of the model for free:
- * pi-goal appends it to the system prompt on every active goal turn, which is
- * why pokes do not restate it. A standalone loop has no such provider, so it
- * has to carry its own — and it does so under the same cache-stability
- * discipline, because the alternative (restating the objective in every poke)
- * is exactly the per-wake duplication that discipline exists to remove.
+ * The loop carries its own objective to the model on every active turn, which
+ * is what lets the pokes and continuations stay pointer-sized. The
+ * alternative — restating the objective in every poke — is exactly the
+ * per-wake duplication the cache-stability discipline below exists to remove.
  *
  * Cache-stability contract: this append lands inside the provider's cached
  * system block (Anthropic caches tools -> system -> messages as one prefix),

package/src/render.ts

@@ -5,8 +5,8 @@
  * text plus a provenance marker comment. This transformer collapses each into
  * a one-line themed chip in the transcript. Display-only by Pi contract: the
  * stored message and model context are untouched, and pokes keep being
- * delivered through sendUserMessage so pi-goal's before_agent_start hook
- * (which appends the goal system prompt) still fires for every poke turn.
+ * delivered through sendUserMessage so the loop's own before_agent_start hook
+ * (which appends the objective) still fires for every poke turn.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -29,11 +29,7 @@ export function compactPokeMessage(markdown: string) {
 	if (!extractPokeMarker(markdown)) return undefined;
 	const head = POKE_HEAD_PATTERN.exec(markdown);
 	if (!head) return undefined;
-	const reason = markdown.includes("external wake")
-		? "waiting"
-		: markdown.includes("completion criteria are not met")
-			? "objective"
-			: "stalled";
+	const reason = markdown.includes("wait you asked for has elapsed") ? "wait elapsed" : "stalled";
 	const focus = POKE_FOCUS_PATTERN.exec(markdown)?.[1];
 	return `*⏰ loop wake ${head[1]} · ${reason}${focus ? ` · ${focus}` : ""}*`;
 }

package/src/settings.ts

@@ -1,6 +1,6 @@
 /**
  * Global pi-loop settings: `~/.pi/agent/pi-loop.json`. Follows the sibling
- * convention (pi-goal, pi-plan-mode): an absent file means defaults and is
+ * convention (pi-plan-mode): an absent file means defaults and is
  * never created implicitly, saves are atomic and preserve unknown fields, and
  * an invalid file warns and falls back to defaults without being overwritten.
  */
@@ -21,15 +21,22 @@ export interface LoopCompactionSettings {
 	instructions: string | null;
 }
 
+/**
+ * The cap fields this one replaced: a delivered-wake cap (`maxIterations`,
+ * `--max`) and a loop-caused-turn cap (`automaticTurns`). A settle-paced loop
+ * can run its whole life without delivering a single fallback wake, so the
+ * wake cap bounded nothing the turn cap did not already bound.
+ */
+const LEGACY_CAP_KEYS = ["maxIterations", "automaticTurns"] as const;
+
 export interface LoopSettings {
-	/** Delivered-wake cap; null means unlimited (explicit opt-in). */
-	maxIterations: number | null;
 	/**
-	 * Cap on turns the loop itself causes (settle continuations plus fallback
-	 * pokes); null means unlimited. A settle-paced loop can run many turns per
-	 * wake, so this is the bound that actually holds it.
+	 * Cap on the turns the loop itself causes (settle continuations plus
+	 * fallback pokes); null means unlimited (explicit opt-in). The only cap
+	 * there is: one wake can yield many turns, so counting turns is what
+	 * actually bounds a loop.
 	 */
-	automaticTurns: number | null;
+	maxTurns: number | null;
 	/**
 	 * Consecutive tool-free loop turns with identical output that pause the
 	 * loop; null disables the breaker.
@@ -37,14 +44,28 @@ export interface LoopSettings {
 	noProgressTurns: number | null;
 	/** Wall-clock expiry for a loop, e.g. "7d" (research: bound forgotten loops). */
 	maxLoopDuration: string;
+	/**
+	 * Detect an inline `/loop` token or a `loop:` prefixed line mid-prompt and
+	 * point the model at the `loop_start` tool. Pi only dispatches `/loop` from
+	 * position 0, so without this a mid-prompt invocation is silently prose.
+	 */
+	inlineInvocation: boolean;
+	/**
+	 * Fallback heartbeat used by an inline invocation that names no interval.
+	 * In a settle-paced loop the interval is only a fallback — the settle
+	 * boundary is the pacemaker — so this value is far less consequential than
+	 * it looks; it is still clamped to MIN_INTERVAL_MS.
+	 */
+	defaultInterval: string;
 	compaction: LoopCompactionSettings;
 }
 
 export const DEFAULT_LOOP_SETTINGS: LoopSettings = {
-	maxIterations: 25,
-	automaticTurns: 25,
+	maxTurns: 25,
 	noProgressTurns: 3,
 	maxLoopDuration: "7d",
+	inlineInvocation: true,
+	defaultInterval: "10m",
 	compaction: {
 		enabled: true,
 		threshold: 0.7,
@@ -61,11 +82,8 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 	const record = ownRecord(value);
 	if (!record) return undefined;
 
-	const maxIterations = normalizeCap(record.maxIterations, DEFAULT_LOOP_SETTINGS.maxIterations);
-	if (maxIterations === false) return undefined;
-
-	const automaticTurns = normalizeCap(record.automaticTurns, DEFAULT_LOOP_SETTINGS.automaticTurns);
-	if (automaticTurns === false) return undefined;
+	const maxTurns = normalizeTurnCap(record);
+	if (maxTurns === false) return undefined;
 
 	const noProgressTurns = normalizeCap(
 		record.noProgressTurns,
@@ -80,12 +98,24 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 		return undefined;
 	}
 
+	const inlineInvocation = Object.hasOwn(record, "inlineInvocation")
+		? record.inlineInvocation
+		: DEFAULT_LOOP_SETTINGS.inlineInvocation;
+	if (typeof inlineInvocation !== "boolean") return undefined;
+
+	const defaultInterval = Object.hasOwn(record, "defaultInterval")
+		? record.defaultInterval
+		: DEFAULT_LOOP_SETTINGS.defaultInterval;
+	if (typeof defaultInterval !== "string" || parseDuration(defaultInterval) === undefined) {
+		return undefined;
+	}
+
 	const compactionValue = Object.hasOwn(record, "compaction") ? record.compaction : undefined;
 	if (compactionValue !== undefined && !ownRecord(compactionValue)) return undefined;
 	const compactionRecord = ownRecord(compactionValue) ?? {};
-	// `postCompactContinuation` was removed in favour of pi-goal owning the
-	// post-compaction re-prompt; a file still carrying it is preserved as an
-	// unknown field and ignored, never rejected.
+	// `postCompactContinuation` was removed in favour of the loop's own
+	// re-anchor; a file still carrying it is preserved as an unknown field and
+	// ignored, never rejected.
 	const enabled = readBoolean(compactionRecord, "enabled", DEFAULT_LOOP_SETTINGS.compaction.enabled);
 	const threshold = Object.hasOwn(compactionRecord, "threshold")
 		? compactionRecord.threshold
@@ -107,10 +137,11 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 	}
 
 	return {
-		maxIterations,
-		automaticTurns,
+		maxTurns,
 		noProgressTurns,
 		maxLoopDuration,
+		inlineInvocation,
+		defaultInterval,
 		compaction: { enabled, threshold, instructions },
 	};
 }
@@ -122,6 +153,32 @@ function normalizeCap(value: unknown, fallback: number | null): number | null |
 	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : false;
 }
 
+/**
+ * The turn cap, accepting the two caps it replaced.
+ *
+ * A settings file written by an older version names no `maxTurns`, and asking
+ * users to rewrite their settings to keep a cap they already chose is not a
+ * trade worth making. So a file carrying only the legacy keys keeps the
+ * tighter of the two: that is the bound their loops were already running
+ * under. An invalid value in either key still fails the whole file closed,
+ * exactly as it did when the key was current.
+ */
+function normalizeTurnCap(record: Record<string, unknown>): number | null | false {
+	if (Object.hasOwn(record, "maxTurns")) {
+		return normalizeCap(record.maxTurns, DEFAULT_LOOP_SETTINGS.maxTurns);
+	}
+	let adopted: number | null | undefined;
+	for (const key of LEGACY_CAP_KEYS) {
+		if (!Object.hasOwn(record, key)) continue;
+		const cap = normalizeCap(record[key], DEFAULT_LOOP_SETTINGS.maxTurns);
+		if (cap === false) return false;
+		// null is unlimited, so it only wins when every legacy cap is unlimited.
+		if (adopted === undefined || adopted === null) adopted = cap;
+		else if (cap !== null) adopted = Math.min(adopted, cap);
+	}
+	return adopted === undefined ? DEFAULT_LOOP_SETTINGS.maxTurns : adopted;
+}
+
 function readBoolean(record: Record<string, unknown>, key: string, fallback: boolean): unknown {
 	return Object.hasOwn(record, key) ? record[key] : fallback;
 }
@@ -192,13 +249,18 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 	}
 
 	const compaction = ownRecord(raw.compaction) ?? {};
+	// Unknown fields are preserved, but the two caps `maxTurns` replaced are not
+	// unknown: leaving them next to a cap that supersedes them would show the
+	// user two numbers where only one applies.
+	for (const key of LEGACY_CAP_KEYS) delete raw[key];
 	const document = `${JSON.stringify(
 		{
 			...raw,
-			maxIterations: normalized.maxIterations,
-			automaticTurns: normalized.automaticTurns,
+			maxTurns: normalized.maxTurns,
 			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
+			inlineInvocation: normalized.inlineInvocation,
+			defaultInterval: normalized.defaultInterval,
 			compaction: { ...compaction, ...normalized.compaction },
 		},
 		null,

package/src/start-tool.ts

@@ -0,0 +1,199 @@
+/**
+ * `loop_start`: the model-invoked way into a loop.
+ *
+ * Pi only dispatches `/loop` when it starts the message, so a mid-prompt
+ * `quick check /loop 10m get CI green` arrives as ordinary prose. The
+ * inline-invocation hooks append a one-turn reminder to the system prompt for
+ * exactly that message, and this tool is what the reminder points at. It
+ * reuses `LoopController.startLoop`, the same path the `/loop` command takes,
+ * so replacement rules, the loop_complete availability guard, the ledger, the
+ * kickoff anchor, and persistence all behave identically.
+ *
+ * The hard armed-gate is the deliberate divergence from pi-goal's equivalent
+ * tool, which relied on prompt guidelines alone. A loop is *self-continuing*:
+ * a spurious start does not produce one unwanted answer, it produces turns
+ * until a cap. So the tool refuses outright unless the inline hint armed for
+ * the turn that is calling it.
+ *
+ * The one thing this path may decide that the `/loop` command cannot is the
+ * loop's completion criteria. They are otherwise a deterministic split of the
+ * objective's grammar, which turns a context sentence into a gate criterion;
+ * a model that read the objective can do better. It is accepted only *here*,
+ * at start, before any work exists to grade and with the user seeing the
+ * criteria echoed back — the point where the incentive to write an easy gate
+ * is weakest. After start they are immutable, exactly as a derived set is.
+ *
+ * Registered unconditionally, like the other loop tools: the tool set is part
+ * of the cached request prefix, so it never changes with loop state.
+ */
+
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { LOOP_COMPLETE_TOOL } from "./complete-tool.js";
+import { formatDuration, parseDuration, parseInterval } from "./interval.js";
+import { MAX_CRITERIA, MAX_DESCRIPTION_LENGTH } from "./ledger.js";
+import type { InlineInvocationState } from "./inline-invocation.js";
+import type { LoopController } from "./loop.js";
+
+export const LOOP_START_TOOL = "loop_start";
+
+/** Long enough for a real objective, short enough to reject a pasted file. */
+const MAX_OBJECTIVE_LENGTH = 4_000;
+
+export function registerLoopStartTool(
+	pi: ExtensionAPI,
+	controller: LoopController,
+	invocation: InlineInvocationState,
+) {
+	pi.registerTool(
+		defineTool({
+			name: LOOP_START_TOOL,
+			label: "Loop Start",
+			description:
+				"Start a /loop for an objective the user explicitly invoked with an inline /loop or loop: token in their message. Only for explicit invocations: never start a loop from general conversation, your own initiative, or an instruction that merely sounds loop-like. The objective is the text following the token.",
+			promptSnippet:
+				"Start a /loop when the user's message contains an explicit inline /loop or loop: invocation",
+			promptGuidelines: [
+				"Call loop_start only when the user's message contains an explicit `/loop <objective>` or `loop: <objective>` token. Never start a loop without that token, no matter how loop-like the request sounds; the tool refuses when the turn carries no inline invocation.",
+				"If the user is discussing, quoting, or documenting the /loop command rather than invoking it — asking how it works, pasting a transcript, or editing text that mentions it — do not call loop_start.",
+				"Pass the objective text that follows the token, without the token itself. A leading interval (`10m`, `2h`) and flags like `--max 5` or `--expires 3d` become the interval, max, and expires parameters, not part of the objective.",
+				"Call loop_start before doing any of the objective's work, then continue working toward it in the same turn.",
+				"Leave the criteria parameter out by default: the extension splits the objective into completion criteria on its own (bullets, else sentences, else the whole objective). Propose criteria only when that split would misfire — when the objective mixes requirements with context sentences (`fix CI. it has been red since Tuesday.`), or packs several requirements into one sentence.",
+				"Every criterion you propose must be a faithful restatement of something the user asked for: never fewer, weaker, or easier than the objective as typed, and never a requirement they did not state. They are echoed back to the user at start and frozen afterwards — you may only ever flip a criterion's passes field.",
+				"When in doubt, omit criteria and let the deterministic split stand.",
+				"Never call loop_complete in the same turn as loop_start: the starting turn has not done the work, and completion needs cited evidence per criterion.",
+				"Before your first loop_start this session, read the pi-loop skill: the objective is split into the completion criteria this loop will be gated on, so its wording is the leverage point.",
+			],
+			parameters: Type.Object({
+				objective: Type.String({
+					minLength: 1,
+					maxLength: MAX_OBJECTIVE_LENGTH,
+					description:
+						"The loop objective, including how the loop knows it is done: the user's text following the /loop or loop: token, verbatim, without the token, the interval, or flags.",
+				}),
+				interval: Type.Optional(
+					Type.String({
+						description:
+							"Fallback wake interval from the invocation, e.g. '10m' or '2h'. Omit when the user named none.",
+					}),
+				),
+				max: Type.Optional(
+					Type.Integer({
+						minimum: 1,
+						description:
+							"Cap on the turns the loop causes (continuations and pokes), from a --max flag in the invocation.",
+					}),
+				),
+				expires: Type.Optional(
+					Type.String({
+						description: "Loop lifetime from an --expires flag in the invocation, e.g. '3d'.",
+					}),
+				),
+				criteria: Type.Optional(
+					Type.Array(
+						Type.String({ minLength: 1, maxLength: MAX_DESCRIPTION_LENGTH }),
+						{
+							minItems: 1,
+							maxItems: MAX_CRITERIA,
+							description:
+								"Optional completion criteria for this loop, each one checkable requirement restated faithfully from the user's objective. Replaces the deterministic split of the objective, so omit it unless that split would misfire.",
+						},
+					),
+				),
+			}),
+			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+				// The gate. Everything below is ordinary validation; this is the
+				// one check that makes a self-continuing tool safe to expose.
+				if (!invocation.invokedThisTurn) {
+					return refusal(
+						`${LOOP_START_TOOL} is only available on a turn whose user message contains an explicit inline /loop or loop: invocation. This turn has none, so no loop was started. If the user wants one, they can type /loop <interval> <objective>.`,
+						{},
+					);
+				}
+				const objective = params.objective.trim();
+				if (!objective) {
+					return refusal("Loop not started: the objective is empty.", {});
+				}
+				const criteria = params.criteria?.map((description) => description.trim());
+				const badCriteria = criteria && describeBadCriteria(criteria);
+				if (badCriteria) {
+					return refusal(
+						`Loop not started: ${badCriteria}. Pass one short checkable requirement per entry, or omit criteria to split the objective deterministically.`,
+						{ objective },
+					);
+				}
+				const existing = controller.state;
+				if (existing && existing.status !== "stopped") {
+					return refusal(
+						`Loop not started: a loop already exists in this session (${existing.status}). The user can replace it with /loop, or stop it with /loop stop.`,
+						{ existingLoopId: existing.id },
+					);
+				}
+				const intervalToken = params.interval?.trim() || controller.settings.defaultInterval;
+				const interval = parseInterval(intervalToken);
+				if (!interval) {
+					return refusal(
+						`Loop not started: invalid interval ${intervalToken}. Use <number><unit> with unit s, m, h, or d, e.g. 10m.`,
+						{ objective },
+					);
+				}
+				let expiresInMs: number | undefined;
+				if (params.expires !== undefined) {
+					expiresInMs = parseDuration(params.expires.trim());
+					if (expiresInMs === undefined) {
+						return refusal(
+							`Loop not started: invalid expiry ${params.expires}. Use <number><unit> with unit s, m, h, or d, e.g. 3d.`,
+							{ objective },
+						);
+					}
+				}
+				const result = controller.startLoop(ctx, {
+					kind: "start",
+					requestedMs: interval.requestedMs,
+					intervalMs: interval.effectiveMs,
+					clamped: interval.clamped,
+					...(params.max === undefined ? {} : { maxTurns: params.max }),
+					...(expiresInMs === undefined ? {} : { expiresInMs }),
+					...(criteria === undefined ? {} : { criteria }),
+					prompt: objective,
+				});
+				if (!result.ok) return refusal(`Loop not started: ${result.message}`, { objective });
+				const loop = result.loop;
+				return {
+					content: toolContent(
+						`Loop started (loop_id ${loop.id}): ${objective}. Fallback wake every ${formatDuration(loop.intervalMs)}. Keep working the objective this turn; the loop continues at every idle boundary until you call ${LOOP_COMPLETE_TOOL} with this loop_id and cited evidence for every criterion, a cap is reached, or the user stops it. Do not call ${LOOP_COMPLETE_TOOL} in this turn.`,
+					),
+					details: { loopId: loop.id, objective, intervalMs: loop.intervalMs },
+				};
+			},
+		}),
+	);
+}
+
+/**
+ * Why a proposed criteria list cannot be used, or undefined when it can.
+ *
+ * A list that says nothing is worse than no list: it would replace the
+ * deterministic split with a gate the model wrote and can pass by saying
+ * anything. So a malformed list refuses the start rather than falling back
+ * silently, which would leave the model believing its criteria were accepted.
+ */
+function describeBadCriteria(criteria: readonly string[]): string | undefined {
+	if (criteria.length === 0) return "the criteria list is empty";
+	if (criteria.length > MAX_CRITERIA) {
+		return `a loop takes at most ${MAX_CRITERIA} criteria and ${criteria.length} were given`;
+	}
+	if (criteria.some((description) => !description)) return "one of the criteria is blank";
+	if (criteria.some((description) => description.length > MAX_DESCRIPTION_LENGTH)) {
+		return `a criterion may be at most ${MAX_DESCRIPTION_LENGTH} characters`;
+	}
+	return undefined;
+}
+
+function refusal(text: string, details: Record<string, unknown>) {
+	return { content: toolContent(text), details, isError: true };
+}
+
+function toolContent(text: string) {
+	return [{ type: "text" as const, text }];
+}