@hank-warren/pi-loop 0.9.0 → 1.1.0

package/src/propose-tool.ts

@@ -2,11 +2,11 @@
  * `loop_propose`: put a drafted loop up for the user's approval.
  *
  * It starts nothing. That separation is the point — the model drafts, the user
- * approves, and the approval is what arms the start. `loop_start`'s gate
- * exists because a loop is self-continuing and must never begin on model
- * initiative; an explicit approval on a card showing the objective, the
- * criteria, the cadence and the caps is stronger evidence of intent than a
- * typed token, not weaker, so it arms the same gate rather than bypassing it.
+ * approves, and the approval is what starts the loop. A loop is
+ * self-continuing and must never begin on model initiative, so this is the
+ * only way a model can put one in front of a user: a card showing the
+ * objective, the criteria, the ground rules, the cadence and the caps, with
+ * the start reserved to the human reading it.
  *
  * Registered unconditionally, like the other loop tools: the tool set is part
  * of the cached request prefix, so it never changes with loop state.
@@ -16,23 +16,27 @@ import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { formatDuration, MAX_INTERVAL_MS, parseDuration } from "./interval.js";
 import type { LoopController } from "./loop.js";
-import { showLoopProposalCard } from "./presentation.js";
+import { MAX_GROUND_RULE_LENGTH, MAX_GROUND_RULES } from "./planning.js";
 
 export const LOOP_PROPOSE_TOOL = "loop_propose";
 
-export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopController) {
+export function registerLoopProposeTool(
+	pi: ExtensionAPI,
+	controller: LoopController,
+	onProposed?: () => void,
+) {
 	pi.registerTool(
 		defineTool({
 			name: LOOP_PROPOSE_TOOL,
 			label: "Loop Propose",
 			description:
-				"Put a drafted loop objective up for the user's approval during loop planning. Renders an approval card showing the exact completion criteria the objective will produce. Starts nothing: the user approves, edits, or cancels.",
+				"Put a drafted loop objective up for the user's approval during loop planning. Renders an approval card showing the exact completion criteria the objective will produce, plus any ground rules. Starts nothing: the user approves, edits, or cancels.",
 			promptSnippet: "Propose a drafted loop objective for approval",
 			promptGuidelines: [
 				"Call loop_propose only while loop planning is open, and only once the objective reads as an acceptance test: one requirement per bullet, each naming the check that proves it.",
 				"Pass the objective you and the user agreed on, not a tidier version of it. The criteria are derived from this text and frozen when the loop starts.",
-				"Do not call loop_start for a planned loop; approving the card is what starts it.",
-				"loop_propose starts nothing, so the rule that a loop needs an inline /loop token in the user's message does not apply to it. While planning is open, a conversational request for a loop is the signal to draft one and propose it — never to refuse and ask the user to type /loop instead.",
+				"Pass ground_rules for the hard constraints the loop must never violate while unattended. They bound how the work may be done and never gate completion, so they belong there rather than in the objective.",
+				"loop_propose starts nothing, so no rule against starting loops on your own applies to it. While planning is open, a conversational request for a loop is the signal to draft one and propose it — never to refuse and ask the user to run a command instead.",
 			],
 			parameters: Type.Object({
 				objective: Type.String({
@@ -58,6 +62,13 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 						description: "Loop lifetime as <number><unit>, e.g. 3d. Omit for the default.",
 					}),
 				),
+				ground_rules: Type.Optional(
+					Type.Array(Type.String({ minLength: 1, maxLength: MAX_GROUND_RULE_LENGTH }), {
+						maxItems: MAX_GROUND_RULES,
+						description:
+							"Hard constraints the loop must never violate, one per entry (e.g. 'never touch production', 'never force-push', 'never edit a test to make it pass'). Constraints, not criteria: they never gate completion.",
+					}),
+				),
 			}),
 			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 				if (!controller.planning.active) {
@@ -67,14 +78,22 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 				}
 				if (controller.state && controller.state.status !== "stopped") {
 					return failure(
-						"A loop is already running in this session. Stop it with /loop stop before planning another.",
+						"A loop is already running in this session. Stop it from the /loop menu before planning another.",
 					);
 				}
 				const objective = params.objective.trim();
 				if (!objective) return failure("A proposal needs an objective.");
 
-				const overrides: { intervalMs?: number; maxTurns?: number | null; expiresInMs?: number } =
-					{};
+				const overrides: {
+					intervalMs?: number;
+					maxTurns?: number | null;
+					expiresInMs?: number;
+					groundRules?: string[];
+				} = {};
+				// Bounded and trimmed in buildProposal, so an over-long or empty entry
+				// is normalized rather than refused: a rejected proposal costs the whole
+				// draft, and the card is where the user reviews them anyway.
+				if (params.ground_rules !== undefined) overrides.groundRules = params.ground_rules;
 				if (params.interval !== undefined) {
 					const parsed = parseDuration(params.interval);
 					if (parsed === undefined) {
@@ -101,6 +120,7 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 				}
 
 				const proposal = controller.propose(objective, overrides);
+				onProposed?.();
 				// The card goes to the transcript as a framed block, not back through
 				// this tool result. Returning it here too would render the same
 				// artifact twice, once framed and once as a wall of markdown, and
@@ -111,13 +131,14 @@ export function registerLoopProposeTool(pi: ExtensionAPI, controller: LoopContro
 					content: [
 						{
 							type: "text" as const,
-							text: `Approval card rendered: ${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}, waking every ${formatDuration(proposal.intervalMs)}, cap ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns}, expires in ${formatDuration(proposal.expiresInMs)}. The user starts it from /loop; nothing is running yet.`,
+							text: `Approval card rendered: ${proposal.criteria.length} ${proposal.criteria.length === 1 ? "criterion" : "criteria"}${proposal.groundRules ? `, ${proposal.groundRules.length} ground rule${proposal.groundRules.length === 1 ? "" : "s"}` : ""}, waking every ${formatDuration(proposal.intervalMs)}, cap ${proposal.maxTurns === null ? "unlimited" : proposal.maxTurns}, expires in ${formatDuration(proposal.expiresInMs)}. The user starts it from /loop; nothing is running yet.`,
 						},
 					],
 					details: {
 						criteria: proposal.criteria.length,
 						intervalMs: proposal.intervalMs,
 						maxTurns: proposal.maxTurns,
+						groundRules: proposal.groundRules?.length ?? 0,
 					},
 				};
 			},

package/src/settings.ts

@@ -29,12 +29,28 @@ export interface LoopCompactionSettings {
  */
 const LEGACY_CAP_KEYS = ["maxIterations", "automaticTurns"] as const;
 
+/**
+ * Settings that no longer exist. They are tolerated on read (an unknown field
+ * is ignored, never a reason to reject the file) and dropped on the next save,
+ * so a settings file written by an older version keeps working and quietly
+ * stops advertising a switch that controls nothing.
+ *
+ * `inlineInvocation` toggled mid-prompt `/loop` detection, which was removed
+ * along with the `loop_start` tool it pointed at.
+ */
+const REMOVED_KEYS = ["inlineInvocation"] as const;
+
 export interface LoopSettings {
 	/**
 	 * 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.
+	 * fallback pokes); null means unlimited, and unlimited is the default. The
+	 * only cap there is: one wake can yield many turns, so counting turns is
+	 * what actually bounds a loop.
+	 *
+	 * A turn budget is a proxy for cost, not for progress, and a loop that hits
+	 * one stops in the middle of the work with nothing decided. The real bounds
+	 * are the expiry and the no-progress breaker, which stop a loop for reasons
+	 * a user can act on. Set a number here to opt back into a budget.
 	 */
 	maxTurns: number | null;
 	/**
@@ -45,26 +61,19 @@ export interface LoopSettings {
 	/** 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.
+	 * Fallback heartbeat used by a proposal 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 = {
-	maxTurns: 25,
+	maxTurns: null,
 	noProgressTurns: 3,
 	maxLoopDuration: "7d",
-	inlineInvocation: true,
 	defaultInterval: "10m",
 	compaction: {
 		enabled: true,
@@ -98,11 +107,6 @@ 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;
@@ -140,7 +144,6 @@ export function normalizeLoopSettings(value: unknown): LoopSettings | undefined
 		maxTurns,
 		noProgressTurns,
 		maxLoopDuration,
-		inlineInvocation,
 		defaultInterval,
 		compaction: { enabled, threshold, instructions },
 	};
@@ -253,13 +256,15 @@ export function saveLoopSettings(settings: LoopSettings, settingsPath = loopSett
 	// 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];
+	// Removed settings are dropped rather than preserved: keeping a switch that
+	// controls nothing is worse than losing it.
+	for (const key of REMOVED_KEYS) delete raw[key];
 	const document = `${JSON.stringify(
 		{
 			...raw,
 			maxTurns: normalized.maxTurns,
 			noProgressTurns: normalized.noProgressTurns,
 			maxLoopDuration: normalized.maxLoopDuration,
-			inlineInvocation: normalized.inlineInvocation,
 			defaultInterval: normalized.defaultInterval,
 			compaction: { ...compaction, ...normalized.compaction },
 		},

package/src/state.ts

@@ -29,6 +29,12 @@ export interface LoopState {
 	 * before 0.6.0 may predate it — every loop started now has one.
 	 */
 	objective?: string;
+	/**
+	 * Hard constraints, approved with the objective and injected alongside it on
+	 * every active turn. Optional: a loop started before ground rules existed,
+	 * or approved without any, simply has none.
+	 */
+	groundRules?: string[];
 	intervalMs: number;
 	/**
 	 * Cap on the turns this loop causes (continuations plus pokes); null means
@@ -57,6 +63,8 @@ export interface LoopState {
 	lastFingerprint?: string;
 	/** Why a paused loop paused, for the widget and status after a restore. */
 	pauseCause?: string;
+	/** Durable reason recorded when the loop enters its terminal stopped state. */
+	terminalReason?: string;
 	/**
 	 * Set once the expiry's final wake has been delivered. The loop is still
 	 * active for exactly that one turn, so the objective append is present
@@ -100,6 +108,8 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		objective = record.objective.trim();
 		if (!objective || objective.length > MAX_PROMPT_LENGTH) return undefined;
 	}
+	const groundRules = normalizeGroundRuleList(record.groundRules);
+	if (groundRules === false) return undefined;
 	const intervalMs = record.intervalMs;
 	if (!isPositiveSafeInteger(intervalMs)) return undefined;
 	const maxTurns = readTurnCap(record);
@@ -136,6 +146,8 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 	if (cancelledWaitReason === false) return undefined;
 	const pauseCause = optionalText(record.pauseCause);
 	if (pauseCause === false) return undefined;
+	const terminalReason = optionalText(record.terminalReason);
+	if (terminalReason === false) return undefined;
 	const toolFreeRepeatCount = record.toolFreeRepeatCount;
 	if (
 		toolFreeRepeatCount !== undefined &&
@@ -154,6 +166,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		status: status as LoopStatus,
 		...(prompt === undefined ? {} : { prompt }),
 		...(objective === undefined ? {} : { objective }),
+		...(groundRules === undefined ? {} : { groundRules }),
 		intervalMs,
 		maxTurns,
 		compactAt: compactAt as number | null,
@@ -167,6 +180,7 @@ export function normalizeLoopState(value: unknown): LoopState | undefined {
 		...(toolFreeRepeatCount === undefined ? {} : { toolFreeRepeatCount }),
 		...(lastFingerprint === undefined ? {} : { lastFingerprint }),
 		...(pauseCause === undefined ? {} : { pauseCause }),
+		...(terminalReason === undefined ? {} : { terminalReason }),
 		...(record.expiring === true ? { expiring: true as const } : {}),
 		...(record.handoff === true ? { handoff: true as const } : {}),
 	};
@@ -235,6 +249,25 @@ function ownRecord(value: unknown): Record<string, unknown> | undefined {
 		: undefined;
 }
 
+/**
+ * A present-but-optional ground-rule list: the list, undefined when absent,
+ * false when invalid. Empty survives as undefined so an approved loop with no
+ * rules and a restored one are the same state.
+ */
+function normalizeGroundRuleList(value: unknown): string[] | undefined | false {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) return false;
+	const rules: string[] = [];
+	for (const entry of value) {
+		if (typeof entry !== "string") return false;
+		const trimmed = entry.trim();
+		if (!trimmed) continue;
+		if (trimmed.length > MAX_PROMPT_LENGTH) return false;
+		rules.push(trimmed);
+	}
+	return rules.length > 0 ? rules : undefined;
+}
+
 /** A present-but-optional string: the value, undefined when absent, false when invalid. */
 function optionalText(value: unknown): string | undefined | false {
 	if (value === undefined) return undefined;

package/src/wait-tool.ts

@@ -59,7 +59,7 @@ export function registerLoopWaitTool(pi: ExtensionAPI, controller: LoopControlle
 				if (!loop || loop.objective === undefined) {
 					return {
 						content: toolContent(
-							"No /loop with an objective is active, so there is nothing to wait on. Start one with /loop <interval> <objective>.",
+							"No /loop with an objective is active, so there is nothing to wait on. Run /loop to plan and approve one.",
 						),
 						details: {},
 						isError: true,

package/src/widget.ts

@@ -21,6 +21,11 @@
  * order is the whole reason to glance at the line: paused and blocked and
  * expiring come before the ordinary running line.
  *
+ * The glyph vocabulary is shared with pi-plan-mode by convention, not by
+ * import — `◆` planning or ready, `▶` implementing, `⟳` running, `⏸` paused,
+ * `⏳` waiting, `⚠` attention. Six characters are not worth a package; a user
+ * reading a footer is worth the consistency.
+ *
  * Presentation only: every entry point tolerates a host without setWidget
  * (test fixtures, print mode) and swallows render-side failures, because a
  * widget must never interrupt loop state transitions.
@@ -122,9 +127,8 @@ export function widgetTone(view: LoopWidgetView): Tone {
 
 export function loopWidgetLine(view: LoopWidgetView): string {
 	if (view.kind === "planning") {
-		return view.proposedCriteria === undefined
-			? "◆ loop planning · drafting an objective"
-			: `◆ loop planning · ${view.proposedCriteria} criteria proposed · approve to start`;
+		if (view.proposedCriteria === undefined) return "◆ loop · drafting objective";
+		return `◆ loop · ${view.proposedCriteria} ${view.proposedCriteria === 1 ? "criterion" : "criteria"} proposed · approve to start`;
 	}
 	const loop = view.loop;
 

package/src/inline-command.ts

@@ -1,159 +0,0 @@
-/**
- * Inline slash-command detection.
- *
- * Pi dispatches extension commands only when a message *starts* with the
- * command token; a command mentioned mid-prompt arrives as plain text. This
- * helper finds inline occurrences of a `/cmd` token (and `cmd:` prefix lines)
- * so the caller can react — here, by appending a reminder that tells the model
- * to invoke the corresponding tool. It never rewrites or re-sends the user's
- * message.
- *
- * Ported from @hank-warren/pi-goal, which proved the mechanism before pi-loop
- * absorbed it; the helper was always generic over the command name.
- */
-
-export interface InlineCommandSplit {
-	/** Text before the command token, trailing whitespace removed. */
-	prose: string;
-	/** Everything after the command token to end of message, trimmed. */
-	commandArgs: string;
-}
-
-/**
- * Find the first inline `/<commandName>` occurrence in `text`.
- *
- * Detection rules:
- * - The token must be preceded by start-of-line or whitespace and followed by
- *   whitespace plus a non-empty remainder. A bare trailing `/cmd` mention or a
- *   path-like `foo/cmd` never matches.
- * - A token at position 0 is ignored: that is Pi's native dispatch position.
- * - Occurrences inside backtick code (inline spans and fenced blocks) or
- *   inside a single/double-quoted span are ignored. Code regions are
- *   approximated by the CommonMark backtick-run rule: a run of N backticks
- *   opens a region closed by the next run of exactly N backticks.
- *
- * Returns undefined when no qualifying occurrence exists.
- */
-export function extractInlineCommand(
-	text: string,
-	commandName: string,
-): InlineCommandSplit | undefined {
-	const token = `/${commandName}`;
-	const ignored = ignoredRegions(text);
-	let searchFrom = 0;
-	while (searchFrom < text.length) {
-		const index = text.indexOf(token, searchFrom);
-		if (index === -1) return undefined;
-		searchFrom = index + 1;
-		if (index === 0) continue;
-		const before = text[index - 1];
-		if (before !== undefined && !/\s/.test(before)) continue;
-		const afterToken = text[index + token.length];
-		if (afterToken === undefined || !/\s/.test(afterToken)) continue;
-		if (insideRegion(ignored, index)) continue;
-		const commandArgs = text.slice(index + token.length).trim();
-		if (!commandArgs) continue;
-		return {
-			prose: text.slice(0, index).trimEnd(),
-			commandArgs,
-		};
-	}
-	return undefined;
-}
-
-/**
- * True when the message inline-invokes the command: a mid-message `/cmd`
- * token with a remainder, or a `cmd:` prefix at the start of any line — both
- * outside backtick code and quoted spans.
- */
-export function detectsInlineInvocation(text: string, commandName: string): boolean {
-	if (extractInlineCommand(text, commandName) !== undefined) return true;
-	const ignored = ignoredRegions(text);
-	const prefixPattern = new RegExp(`^[ \\t]*${escapeRegExpText(commandName)}:[ \\t]+\\S`, "gim");
-	for (
-		let match = prefixPattern.exec(text);
-		match;
-		match = prefixPattern.exec(text)
-	) {
-		if (!insideRegion(ignored, match.index)) return true;
-	}
-	return false;
-}
-
-type Region = readonly [start: number, end: number];
-
-/**
- * Backtick code regions plus single/double-quoted spans. Quoting a command is
- * how people discuss one (`use "/loop 10m ship it" to start`), so a quoted
- * token is a mention, not an invocation.
- */
-function ignoredRegions(text: string): Region[] {
-	return [...codeRegions(text), ...quoteRegions(text)];
-}
-
-function codeRegions(text: string): Region[] {
-	const regions: Region[] = [];
-	const runs: Array<{ index: number; length: number }> = [];
-	const runPattern = /`+/g;
-	for (let match = runPattern.exec(text); match; match = runPattern.exec(text)) {
-		runs.push({ index: match.index, length: match[0].length });
-	}
-	for (let open = 0; open < runs.length; open += 1) {
-		const opener = runs[open];
-		if (opener === undefined) continue;
-		for (let close = open + 1; close < runs.length; close += 1) {
-			const closer = runs[close];
-			if (closer === undefined || closer.length !== opener.length) continue;
-			regions.push([opener.index, closer.index + closer.length]);
-			open = close;
-			break;
-		}
-	}
-	return regions;
-}
-
-/**
- * Single- and double-quoted spans, matched conservatively so an apostrophe
- * inside a word (`don't`) never opens one: an opening quote follows nothing,
- * whitespace, or an opening bracket and precedes a non-space; its closing
- * quote is on the same line, follows a non-space, and precedes end-of-line,
- * whitespace, or closing punctuation.
- */
-function quoteRegions(text: string): Region[] {
-	const regions: Region[] = [];
-	for (let index = 0; index < text.length; index += 1) {
-		const quote = text[index];
-		if (quote !== '"' && quote !== "'") continue;
-		const before = text[index - 1];
-		const after = text[index + 1];
-		if (before !== undefined && !/[\s([{<]/.test(before)) continue;
-		if (after === undefined || /\s/.test(after)) continue;
-		const close = closingQuoteIndex(text, index, quote);
-		if (close === undefined) continue;
-		regions.push([index, close + 1]);
-		index = close;
-	}
-	return regions;
-}
-
-function closingQuoteIndex(text: string, openIndex: number, quote: string): number | undefined {
-	for (let index = openIndex + 1; index < text.length; index += 1) {
-		const char = text[index];
-		if (char === "\n") return undefined;
-		if (char !== quote) continue;
-		const before = text[index - 1];
-		const after = text[index + 1];
-		if (before === undefined || /\s/.test(before)) continue;
-		if (after !== undefined && !/[\s.,;:!?)\]}>]/.test(after)) continue;
-		return index;
-	}
-	return undefined;
-}
-
-function insideRegion(regions: readonly Region[], index: number): boolean {
-	return regions.some(([start, end]) => index >= start && index < end);
-}
-
-function escapeRegExpText(value: string) {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}

package/src/inline-invocation.ts

@@ -1,109 +0,0 @@
-/**
- * Inline `/loop` invocation, tool-mediated.
- *
- * Pi only dispatches `/loop` when it starts the message. When the user writes
- * `quick check /loop 10m get CI green` or a `loop:` prefixed line mid-prompt,
- * this module appends a one-turn reminder to the system prompt so the model
- * reliably calls the `loop_start` tool with the objective. The user's message
- * itself is never touched — no cutting, splitting, re-sending, or visible
- * annotation — so there are no delivery races, no message loss, and no
- * transcript noise: guidance is injected at agent-start time, not by
- * rewriting input.
- *
- * Two hooks cooperate because neither alone is safe:
- * - `input` carries a `source` and so can tell user-typed text from
- *   extension-sent prompts, but any transform it returns rewrites the stored,
- *   visible user message. It only records the armed text here.
- * - `before_agent_start` can extend the system prompt, but fires for
- *   extension-sent prompts too, and pi-loop's own kickoff and continuation
- *   prompts contain phrases like "the active /loop objective" that the
- *   detector would match. It injects only when the starting prompt *is* the
- *   armed user message, and disarms on every start, matched or not.
- *
- * Two deliberate limits keep the armed window one turn wide:
- * - Streaming-typed input (`streamingBehavior` set, i.e. steered or queued)
- *   never arms. Pi returns from `prompt()` before `before_agent_start` for
- *   those, so an armed flag would survive to a later, unrelated turn — the
- *   window through which pi-loop's own continuation prompts could be matched.
- * - The hint is a per-turn `systemPrompt` append, not a stored message, so
- *   "call loop_start now" cannot linger in the conversation and fire on a
- *   later turn.
- *
- * The armed flag is also the `loop_start` tool's gate: unlike pi-goal, which
- * relied on prompt guidelines alone, a loop is self-continuing, so this
- * extension *enforces* that the tool only runs on a turn the user explicitly
- * invoked. See `InlineInvocationState.invokedThisTurn`.
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { detectsInlineInvocation } from "./inline-command.js";
-import type { LoopController } from "./loop.js";
-
-export const INLINE_LOOP_COMMAND = "loop";
-
-export const INLINE_LOOP_HINT =
-	"<system-reminder>The user's message this turn inline-invoked a loop (/loop or loop:). Call the loop_start tool now with the objective text that follows the token in that message, then begin working toward it. Do not answer the objective as prose without starting the loop. If the message is discussing, quoting, or documenting the /loop command rather than invoking it, do not call loop_start. This reminder applies only to the user's message this turn.</system-reminder>";
-
-/**
- * The armed state, shared between the hooks and the `loop_start` tool.
- *
- * `invokedThisTurn` is the hard gate: set when `before_agent_start` matched
- * the armed user message, cleared at `agent_end` and at every session
- * boundary. `loop_start` refuses whenever it is false, so no amount of prompt
- * drift, transcript replay, or model initiative can start a self-continuing
- * loop the user did not ask for.
- */
-export class InlineInvocationState {
-	invokedThisTurn = false;
-}
-
-export function registerInlineInvocation(
-	pi: ExtensionAPI,
-	controller: LoopController,
-	state: InlineInvocationState,
-) {
-	let armedText: string | undefined;
-
-	pi.on("input", (event) => {
-		// Extension-sourced messages (loop kickoffs, continuations, pokes, other
-		// extensions' injections) never arm the hint.
-		if (event.source === "extension") return;
-		// Steered or queued input returns from prompt() without ever reaching
-		// before_agent_start, so arming it would leave stale text armed.
-		if (event.streamingBehavior !== undefined) return;
-		if (!controller.settings.inlineInvocation) return;
-		if (!detectsInlineInvocation(event.text, INLINE_LOOP_COMMAND)) return;
-		armedText = event.text;
-	});
-
-	pi.on("before_agent_start", (event) => {
-		const armed = armedText;
-		armedText = undefined;
-		// Every start closes the previous turn's window, so a turn that ends
-		// without an agent_end still cannot leave the tool unlocked.
-		state.invokedThisTurn = false;
-		if (armed === undefined) return;
-		if (!controller.settings.inlineInvocation) return;
-		if (!promptCarriesArmedMessage(event.prompt, armed)) return;
-		state.invokedThisTurn = true;
-		return { systemPrompt: `${event.systemPrompt}\n\n${INLINE_LOOP_HINT}` };
-	});
-
-	const disarm = () => {
-		armedText = undefined;
-		state.invokedThisTurn = false;
-	};
-	pi.on("agent_end", disarm);
-	pi.on("session_start", disarm);
-	pi.on("session_shutdown", disarm);
-}
-
-/**
- * True when the starting prompt is the armed user message. Pi may wrap the
- * text with expanded prefixes or suffixes, so the armed text has to be the
- * whole prompt or one of its ends — mirroring how upstream recognises its own
- * owned prompts at a terminal boundary.
- */
-function promptCarriesArmedMessage(prompt: string, armed: string) {
-	return prompt === armed || prompt.startsWith(armed) || prompt.endsWith(armed);
-}