@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/interactive/theme/labels.ts

@@ -0,0 +1,88 @@
+/**
+ * Abbreviate a wire model id for chips and dashboards without amputating a
+ * version suffix. Whole dash-separated parts are kept while the joined result
+ * stays within 18 characters, so `claude-sonnet-5` and `claude-opus-4-8`
+ * survive intact and `qwen3-coder-30b-a3b-instruct` collapses to
+ * `qwen3-coder-30b`. A single part longer than 18 characters is hard-clipped.
+ */
+export function abbreviateModelId(modelId: string | null | undefined): string {
+	const base = (modelId ?? "").trim().split("/").filter(Boolean).pop() ?? "";
+	if (base.length === 0) return "model";
+	const parts = base.split("-").filter((part) => part.length > 0);
+	if (parts.length <= 1) return base.length > 18 ? base.slice(0, 18) : base;
+	const kept: string[] = [];
+	for (const part of parts) {
+		const next = [...kept, part].join("-");
+		if (kept.length > 0 && next.length > 18) break;
+		kept.push(part);
+	}
+	const joined = kept.join("-");
+	return joined.length > 18 ? joined.slice(0, 18) : joined;
+}
+
+export interface TargetLabelOptions {
+	/** Separator between the target id and the model. The narrow rail omits the spaces. */
+	separator?: string;
+	/** Off for surfaces with room for the whole wire id. */
+	abbreviate?: boolean;
+}
+
+/**
+ * The chat target as one label, with one spelling for the state where there
+ * isn't one.
+ *
+ * Five surfaces answered the same question five different ways: the banner read
+ * `not configured/not configured`, the editor rail `no model`, the footer
+ * `none · none`, the settings overlay `(unset)`, and the providers overlay
+ * `(no model)`. A user comparing them is checking whether Clio knows what it is
+ * talking to, and four spellings read as four states.
+ *
+ * A target with no model and a model with no target are distinct from having
+ * neither, so each says which half is missing rather than collapsing to the
+ * same phrase. The settings overlay keeps `(unset)`, which labels an empty
+ * editable field rather than reporting status.
+ */
+export function formatTargetLabel(
+	targetId: string | null | undefined,
+	modelId: string | null | undefined,
+	options: TargetLabelOptions = {},
+): string {
+	const target = (targetId ?? "").trim();
+	const model = (modelId ?? "").trim();
+	if (target.length === 0 && model.length === 0) return "not configured";
+	const shown = options.abbreviate === false ? model : abbreviateModelId(model);
+	if (target.length === 0) return `no target · ${shown}`;
+	if (model.length === 0) return `${target} · no model`;
+	return `${target}${options.separator ?? " · "}${shown}`;
+}
+
+/**
+ * Compact duration used everywhere the TUI shows elapsed time (footer chips,
+ * dispatch cards, task island rows): sub-second in ms, sub-minute in seconds
+ * with one decimal under 10s, then `XmYs`.
+ */
+export function formatCompactMs(value: number): string {
+	const ms = Math.max(0, Math.round(value));
+	if (ms < 1000) return `${ms}ms`;
+	const seconds = ms / 1000;
+	return seconds < 60
+		? `${seconds.toFixed(seconds >= 10 ? 0 : 1)}s`
+		: `${Math.floor(seconds / 60)}m${Math.round(seconds % 60)}s`;
+}
+
+/**
+ * Context-window fill percentage with one shared unknown grammar. A window
+ * that has not been measured yet renders `?%` everywhere (compact footer,
+ * expanded quadrant, segmented bar, /context-view overlay): a placeholder for
+ * a number that has not arrived, never a value.
+ */
+export function formatContextPercent(percent: number | null | undefined): string {
+	return typeof percent === "number" && Number.isFinite(percent) ? `${percent.toFixed(1)}%` : "?%";
+}
+
+export function collapseHomePath(path: string): string {
+	const home = process.env.HOME;
+	if (!home || home.length === 0) return path;
+	if (path === home) return "~";
+	return path.startsWith(`${home}/`) ? `~/${path.slice(home.length + 1)}` : path;
+}

package/src/interactive/theme/rules.ts

@@ -0,0 +1,138 @@
+import { truncateToWidth, visibleWidth } from "../../engine/tui.js";
+import { GLYPH } from "./glyphs.js";
+import type { ClioTheme, ClioToken } from "./tokens.js";
+
+/**
+ * Pad or clip a styled string to exactly `width` visible columns.
+ *
+ * `truncateToWidth(…, pad = true)` already returns a string of exactly `width`
+ * columns on both its paths: it appends the shortfall on the fits path and pads
+ * through its own finalizer on the cut path. Measuring the result again to
+ * compute a repeat count that is always zero cost ~24 µs per line whenever the
+ * string missed pi-tui's width cache, which is every footer line that carries a
+ * spinner frame or an elapsed time.
+ */
+export function padAnsi(text: string, width: number, ellipsis = ""): string {
+	return truncateToWidth(text, Math.max(0, width), ellipsis, true);
+}
+
+/**
+ * Join `units` onto `prefix` with the ` · ` separator, fitting the result to
+ * `maxWidth` without cutting a unit mid-glyph. A unit that would overflow is
+ * dropped whole, along with every later unit, and the line closes with one
+ * space plus a dim ellipsis. Two columns are reserved for that marker while
+ * placing every unit except the last. When even the first unit cannot fit,
+ * `prefix + first unit` is hard-truncated with an ellipsis so a one-unit line
+ * still marks its cut. Width accounting is ANSI-aware via visibleWidth.
+ */
+export function fitUnits(theme: ClioTheme, prefix: string, units: readonly string[], maxWidth: number): string {
+	const sep = " · ";
+	let line = prefix;
+	for (let index = 0; index < units.length; index += 1) {
+		const candidate = index === 0 ? `${line}${units[index]}` : `${line}${sep}${units[index]}`;
+		// Reserve two columns for the ` …` marker unless this is the last unit.
+		const reserve = index < units.length - 1 ? 2 : 0;
+		if (visibleWidth(candidate) + reserve > maxWidth) {
+			if (index === 0) return truncateToWidth(candidate, Math.max(0, maxWidth), "…", false);
+			return `${line} ${theme.fg("dim", "…")}`;
+		}
+		line = candidate;
+	}
+	return line;
+}
+
+export interface RuleOptions {
+	left?: string;
+	leftToken?: ClioToken;
+	right?: string;
+	fillToken?: ClioToken;
+	rightToken?: ClioToken;
+	rightRaw?: boolean;
+	rightTail?: string;
+}
+
+export function rule(theme: ClioTheme, width: number, options: RuleOptions = {}): string {
+	const safeWidth = Math.max(0, width);
+	if (safeWidth === 0) return "";
+	// A left label starts flush at column 0, with a single trailing space before
+	// the fill. There is no leading space, so labeled rules align with the frame.
+	const left = options.left ? `${theme.style(options.leftToken ?? "accent", options.left, { bold: true })} ` : "";
+	const rightBody = options.rightRaw ? options.right : theme.fg(options.rightToken ?? "muted", options.right ?? "");
+	const right = options.right ? ` ${rightBody} ${options.rightTail ?? ""}` : "";
+	const labelsWidth = visibleWidth(left) + visibleWidth(right);
+	if (labelsWidth >= safeWidth) return truncateToWidth(`${left}${right}`.trim(), safeWidth, "", true);
+	const fill = theme.style(options.fillToken ?? "frame", "─".repeat(safeWidth - labelsWidth), {
+		bold: options.fillToken === "frameStrong",
+	});
+	return `${left}${fill}${right}`;
+}
+
+export interface FrameOptions {
+	/**
+	 * Dim right-hand metadata placed just before the closing corner with one
+	 * space on each side. The dispatch cards pass a run's elapsed time here.
+	 */
+	rightMeta?: string;
+}
+
+/**
+ * The one framed-island recipe for every in-flow block: the welcome dashboard,
+ * the task island, the steering queue, and the dispatch cards.
+ *
+ * ```
+ * ┌─ Title ──────────────────── meta ─┐
+ * │ body line                         │
+ * └───────────────────────────────────┘
+ * ```
+ *
+ * Corners and fills carry the `frame` token. A plain `title` is drawn bold in
+ * the `title` token with exactly one space on each side. A title that already
+ * carries its own styling, such as the welcome header's composite of a brand
+ * glyph and a dim version, is placed verbatim so its escape sequences are never
+ * re-wrapped. The optional `rightMeta` renders dim before the closing corner.
+ */
+export function frame(
+	theme: ClioTheme,
+	title: string,
+	lines: readonly string[],
+	width: number,
+	opts: FrameOptions = {},
+): string[] {
+	const safeWidth = Math.max(4, width);
+	const contentWidth = Math.max(0, safeWidth - 4);
+	const frameFg = (text: string): string => theme.fg("frame", text);
+
+	const hasTitle = title.length > 0;
+	// A title that already carries escape sequences is a pre-styled composite
+	// (the welcome header's brand glyph and dim version); place it verbatim. A
+	// plain title is styled here as bold in the `title` token.
+	const styledTitle = !hasTitle ? "" : title.includes("\u001b") ? title : theme.style("title", title, { bold: true });
+	const titleWidth = visibleWidth(title);
+
+	const meta = opts.rightMeta ?? "";
+	const hasMeta = meta.length > 0;
+	const metaWidth = hasMeta ? visibleWidth(meta) : 0;
+
+	// `┌─`, plus ` Title ` when titled, on the left; `┐`, or ` meta ─┐` when a
+	// right meta is present, on the right. The fill is whatever keeps the total
+	// width exact.
+	const leftVisible = 2 + (hasTitle ? titleWidth + 2 : 0);
+	const rightVisible = hasMeta ? metaWidth + 4 : 1;
+	const fillWidth = Math.max(0, safeWidth - leftVisible - rightVisible);
+
+	const leftStr = hasTitle ? `${frameFg("┌─")} ${styledTitle} ` : frameFg("┌─");
+	const rightStr = hasMeta ? ` ${theme.fg("dim", meta)} ${frameFg("─┐")}` : frameFg("┐");
+	const top = `${leftStr}${frameFg("─".repeat(fillWidth))}${rightStr}`;
+
+	const body = lines.map((line) => `${frameFg("│")} ${padAnsi(line, contentWidth)} ${frameFg("│")}`);
+	const bottom = `${frameFg("└")}${frameFg("─".repeat(safeWidth - 2))}${frameFg("┘")}`;
+	return [top, ...body, bottom];
+}
+
+/**
+ * A full-width run of the inner-divider glyph in the `frame` token, drawn
+ * between rows inside an island. Callers pass the island's inner content width.
+ */
+export function innerDivider(theme: ClioTheme, width: number): string {
+	return theme.fg("frame", GLYPH.innerDivider.repeat(Math.max(0, width)));
+}

package/src/interactive/theme/segments.ts

@@ -0,0 +1,88 @@
+import { GLYPH } from "./glyphs.js";
+import type { ClioTheme, ClioToken } from "./tokens.js";
+
+/**
+ * Presentational primitives for the welcome/footer dashboards. These keep raw
+ * ANSI inside the theme module: every colored separator, chip, and section tag
+ * is produced here so interactive render code only ever composes already-styled
+ * strings. Helpers are pure and width-agnostic; callers fit/truncate with the
+ * engine helpers after composition.
+ */
+
+function present(parts: ReadonlyArray<string | null | undefined>): string[] {
+	return parts.filter((part): part is string => typeof part === "string" && part.length > 0);
+}
+
+/**
+ * The Clio logotype: the `>C_` wordmark composed from the tokens the system
+ * already assigns to its three characters. `>` and `_` are terminal
+ * scaffolding and render dim; `C` is Clio and renders bold accent. GLYPH.brand
+ * keeps the plain string for width math and ANSI-stripping tests, and the
+ * welcome header and dashboard header stay the only surfaces that paint it.
+ */
+export function brandMark(theme: ClioTheme): string {
+	const prompt = GLYPH.brand.slice(0, 1);
+	const initial = GLYPH.brand.slice(1, 2);
+	const cursor = GLYPH.brand.slice(2, 3);
+	return `${theme.fg("dim", prompt)}${theme.style("accent", initial, { bold: true })}${theme.fg("dim", cursor)}`;
+}
+
+/** Dim middot used to separate chips inside a single section. */
+export function dotSep(theme: ClioTheme): string {
+	return theme.fg("dim", " · ");
+}
+
+/** Frame-colored vertical bar used to separate sections on one row. */
+export function barSep(theme: ClioTheme): string {
+	return theme.fg("frame", " │ ");
+}
+
+/**
+ * A bold, color-tagged section label (PERCEIVE / target / …). Pad to align a
+ * column of tags; padding inherits the tag color but stays invisible.
+ */
+export function sectionTag(theme: ClioTheme, token: ClioToken, label: string, pad = 0): string {
+	const text = pad > 0 ? label.padEnd(pad) : label;
+	return theme.style(token, text, { bold: true });
+}
+
+/**
+ * A screen or overlay title (section 2.4 level 2): bold in the `title` token.
+ *
+ * The settings lane header, the settings breadcrumb, and the dispatch card
+ * title each open-coded `theme.style("title", text, { bold: true })`, so the
+ * one rule for what a title looks like lived in as many places as there were
+ * titles. `rules.ts:frame` applies the same treatment to an unstyled title it
+ * is handed, which is why an island does not call this.
+ */
+export function screenTitle(theme: ClioTheme, label: string): string {
+	return theme.style("title", label, { bold: true });
+}
+
+/**
+ * A list-group header (section 2.4 level 4): `── running (1)` in dim.
+ *
+ * The leading double dash is a structural rule literal, not a status glyph.
+ * Fleet Runs kept a private copy and the generic list overlay inlined the same
+ * string, so a change to the group vocabulary had to be made twice and was not.
+ */
+export function listGroupHeader(theme: ClioTheme, label: string): string {
+	return theme.fg("dim", `── ${label}`);
+}
+
+/** A single colored chip. */
+export function chip(theme: ClioTheme, token: ClioToken, text: string): string {
+	return theme.fg(token, text);
+}
+
+/** A key=value chip: a dim key glued to a colored value (e.g. `git main`). */
+/** Subtle keybinding affordance, e.g. `⌃U dashboard`. */
+/** Join chips within a section with a dim middot, dropping empties. */
+export function joinChips(theme: ClioTheme, parts: ReadonlyArray<string | null | undefined>): string {
+	return present(parts).join(dotSep(theme));
+}
+
+/** Join sections on one row with a frame bar, dropping empties. */
+export function joinSections(theme: ClioTheme, parts: ReadonlyArray<string | null | undefined>): string {
+	return present(parts).join(barSep(theme));
+}

package/src/interactive/theme/tokens.ts

@@ -0,0 +1,121 @@
+export type ClioToken =
+	| "accent"
+	| "accentDeep"
+	| "action"
+	| "success"
+	| "warning"
+	| "error"
+	| "info"
+	| "reason"
+	| "dim"
+	| "muted"
+	| "title"
+	| "frame"
+	| "frameStrong";
+
+interface TokenColor {
+	rgb: readonly [number, number, number];
+	xterm: number;
+}
+
+const TOKENS: Record<ClioToken, TokenColor> = {
+	accent: { rgb: [70, 229, 208], xterm: 80 },
+	accentDeep: { rgb: [31, 183, 166], xterm: 44 },
+	// Second brand color: neon orange. The token name teaches the rule: orange
+	// means Clio is acting. It fires only for Clio's signature actions
+	// (dispatching, queued and running fleet work, steering) and for the border
+	// of a prompt that has taken the keyboard and is waiting on a decision, never
+	// as decoration, and never a metric, at most one orange element per region of
+	// the screen. warning stays the soft amber for actual warnings.
+	action: { rgb: [255, 126, 41], xterm: 208 },
+	success: { rgb: [87, 227, 137], xterm: 114 },
+	warning: { rgb: [255, 180, 84], xterm: 221 },
+	error: { rgb: [255, 92, 102], xterm: 203 },
+	info: { rgb: [91, 168, 255], xterm: 75 },
+	reason: { rgb: [157, 140, 255], xterm: 141 },
+	dim: { rgb: [106, 122, 133], xterm: 59 },
+	muted: { rgb: [138, 153, 164], xterm: 102 },
+	title: { rgb: [70, 229, 208], xterm: 80 },
+	frame: { rgb: [47, 93, 90], xterm: 23 },
+	frameStrong: { rgb: [42, 171, 158], xterm: 37 },
+};
+
+export const SGR_RESET = "\u001b[0m";
+export const SGR_DIM = "\u001b[2m";
+
+export interface PaintMods {
+	fg?: ClioToken;
+	bg?: ClioToken;
+	bold?: boolean;
+	italic?: boolean;
+	underline?: boolean;
+	dim?: boolean;
+}
+
+export interface ClioTheme {
+	readonly truecolor: boolean;
+	paint(text: string, mods: PaintMods): string;
+	fg(token: ClioToken, text: string): string;
+	bg(token: ClioToken, text: string): string;
+	style(token: ClioToken, text: string, mods?: Omit<PaintMods, "fg">): string;
+	fgSequence(token: ClioToken): string;
+}
+
+/**
+ * The NO_COLOR convention: set and non-empty means emit no color, whatever the
+ * value is. Clio was ignoring it entirely. A session launched with NO_COLOR=1
+ * still wrote 961 non-reset SGR sequences in its first three seconds, most of
+ * them 24-bit foregrounds, which is exactly what the variable exists to stop.
+ *
+ * Only color is dropped. Bold, dim, italic, and underline carry structure
+ * rather than color and are what a monochrome terminal has left to read the
+ * interface with, so they stay.
+ */
+function colorDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	const raw = env.NO_COLOR;
+	return typeof raw === "string" && raw.length > 0;
+}
+
+function detectTruecolor(env: NodeJS.ProcessEnv = process.env): boolean {
+	const colorTerm = (env.COLORTERM ?? "").toLowerCase();
+	if (colorTerm.includes("truecolor") || colorTerm.includes("24bit")) return true;
+	const term = (env.TERM ?? "").toLowerCase();
+	return term.includes("truecolor") || term.includes("24bit");
+}
+
+function fgCode(color: TokenColor, truecolor: boolean): string {
+	return truecolor ? `38;2;${color.rgb[0]};${color.rgb[1]};${color.rgb[2]}` : `38;5;${color.xterm}`;
+}
+
+function bgCode(color: TokenColor, truecolor: boolean): string {
+	return truecolor ? `48;2;${color.rgb[0]};${color.rgb[1]};${color.rgb[2]}` : `48;5;${color.xterm}`;
+}
+
+export function fgSequence(token: ClioToken, truecolor: boolean = detectTruecolor()): string {
+	if (colorDisabled()) return "";
+	return `\u001b[${fgCode(TOKENS[token], truecolor)}m`;
+}
+
+export function createClioTheme(options: { truecolor?: boolean; color?: boolean } = {}): ClioTheme {
+	const truecolor = options.truecolor ?? detectTruecolor();
+	const color = options.color ?? !colorDisabled();
+	const paint = (text: string, mods: PaintMods): string => {
+		const codes: string[] = [];
+		if (mods.bold) codes.push("1");
+		if (mods.dim) codes.push("2");
+		if (mods.italic) codes.push("3");
+		if (mods.underline) codes.push("4");
+		if (color && mods.fg) codes.push(fgCode(TOKENS[mods.fg], truecolor));
+		if (color && mods.bg) codes.push(bgCode(TOKENS[mods.bg], truecolor));
+		if (codes.length === 0) return text;
+		return `\u001b[${codes.join(";")}m${text}${SGR_RESET}`;
+	};
+	return {
+		truecolor,
+		paint,
+		fg: (token, text) => paint(text, { fg: token }),
+		bg: (token, text) => paint(text, { bg: token }),
+		style: (token, text, mods = {}) => paint(text, { ...mods, fg: token }),
+		fgSequence: (token) => (color ? `\u001b[${fgCode(TOKENS[token], truecolor)}m` : ""),
+	};
+}

package/src/interactive/thinking-level-policy.ts

@@ -0,0 +1,6 @@
+export {
+	effectiveThinkingLevel,
+	restrictThinkingLevelsByMechanism,
+	thinkingLevelChoiceLabel,
+	thinkingLevelDisplayWord,
+} from "../domains/providers/model-runtime-capabilities.js";

package/src/interactive/tool-prose-loop.ts

@@ -0,0 +1,122 @@
+import { escapeRegExp } from "../tools/ignore-policy.js";
+
+/**
+ * Whether a runtime's models are prone to narrating tool calls as prose instead
+ * of emitting them.
+ *
+ * Keyed on the local-native tier rather than a list of server names. The
+ * behavior belongs to open-weight models served locally, not to the two servers
+ * that happened to be tested first: the same model narrating through llama.cpp
+ * narrates through Ollama, vLLM, and SGLang, and a name list left those runs
+ * with no cutoff at all. Hosted runtimes are unaffected either way.
+ */
+export function runtimeNarratesToolCalls(runtimeTier: string | undefined): boolean {
+	return runtimeTier === "local-native";
+}
+
+export interface ToolProseLoopInput {
+	text: string;
+	activeToolNames: ReadonlyArray<string>;
+	hasStructuredToolCall?: boolean;
+}
+
+export type ToolProseLoopAssessment =
+	| { kind: "ok" }
+	| {
+			kind: "loop";
+			reason: string;
+			matchCount: number;
+	  };
+
+const MIN_TOOL_PROSE_CHARS = 1200;
+const TOOL_PROSE_REPEAT_THRESHOLD = 4;
+
+/**
+ * Characters of new text between assessments.
+ *
+ * The assessment lower-cases and collapses the whole accumulated answer, then
+ * runs three regexes per active tool plus a generic one over it. Running that
+ * on every streamed delta makes the cost quadratic in answer length: measured
+ * on a 6942-character answer arriving as 1157 deltas, it spent 178ms of
+ * synchronous time in the streaming hot path, and the last hundred deltas cost
+ * roughly twice what the first hundred did. That time is taken from the same
+ * event loop the render timer waits on.
+ *
+ * A narration loop needs four repetitions of a whole sentence to trip the
+ * threshold, and the detector does not even look below 1200 characters, so
+ * sampling every half-kilobyte cannot miss one. It bounds the work to a handful
+ * of scans per answer instead of one per token.
+ */
+const TOOL_PROSE_ASSESS_STRIDE_CHARS = 512;
+
+/**
+ * True when enough new text has accumulated to be worth re-scanning.
+ * `lastAssessedChars` is 0 before the first assessment of a run.
+ */
+export function shouldAssessToolProse(textLength: number, lastAssessedChars: number): boolean {
+	if (textLength < MIN_TOOL_PROSE_CHARS) return false;
+	return textLength - lastAssessedChars >= TOOL_PROSE_ASSESS_STRIDE_CHARS;
+}
+
+function count(pattern: RegExp, text: string): number {
+	let matches = 0;
+	pattern.lastIndex = 0;
+	while (pattern.exec(text)) matches += 1;
+	return matches;
+}
+
+function toolPattern(toolName: string): string {
+	const escaped = escapeRegExp(toolName.trim().toLowerCase());
+	return escaped.replace(/[_-]+/g, "[ _-]+");
+}
+
+function normalizedToolNames(names: ReadonlyArray<string>): string[] {
+	const out: string[] = [];
+	const seen = new Set<string>();
+	for (const raw of names) {
+		const name = raw.trim().toLowerCase();
+		if (name.length === 0 || seen.has(name)) continue;
+		seen.add(name);
+		out.push(name);
+	}
+	return out;
+}
+
+export function assessToolProseLoop(input: ToolProseLoopInput): ToolProseLoopAssessment {
+	if (input.hasStructuredToolCall === true) return { kind: "ok" };
+	if (input.text.length < MIN_TOOL_PROSE_CHARS) return { kind: "ok" };
+	const tools = normalizedToolNames(input.activeToolNames);
+	if (tools.length === 0) return { kind: "ok" };
+
+	const text = input.text.toLowerCase().replace(/\s+/g, " ");
+	let maxToolMatches = 0;
+	let matchedTool = "";
+
+	for (const toolName of tools) {
+		const name = toolPattern(toolName);
+		const patterns = [
+			new RegExp(`\\b(?:execute|call|make|use)\\s+the\\s+${name}\\s+tool\\s+call\\b`, "g"),
+			new RegExp(`\\b(?:execute|call|use)\\s+the\\s+${name}\\s+tool\\b`, "g"),
+			new RegExp(`\\b${name}\\s+tool\\s+call\\b`, "g"),
+		];
+		const matches = patterns.reduce((sum, pattern) => sum + count(pattern, text), 0);
+		if (matches > maxToolMatches) {
+			maxToolMatches = matches;
+			matchedTool = toolName;
+		}
+	}
+
+	const genericMatches = count(
+		/\b(?:i(?:'|’)ll|i will|i(?:'|’)m going to|i am going to)\s+(?:now\s+)?(?:execute|call|make|use)\s+the\s+[a-z0-9_-]+\s+(?:tool\s+)?call\b/g,
+		text,
+	);
+	const matchCount = Math.max(maxToolMatches, genericMatches);
+	if (matchCount < TOOL_PROSE_REPEAT_THRESHOLD) return { kind: "ok" };
+
+	const target = matchedTool.length > 0 ? ` for '${matchedTool}'` : "";
+	return {
+		kind: "loop",
+		matchCount,
+		reason: `local model repeated tool-call narration${target} ${matchCount} times without emitting a structured tool call`,
+	};
+}

package/src/interactive/tool-prose-registration.ts

@@ -0,0 +1,48 @@
+/**
+ * Tool-prose loop assessor, packaged as a turn_end hook registration.
+ *
+ * The decision of record for local models that narrate tool calls instead of
+ * making them: when the final assistant text of a turn repeats tool-call
+ * narration without a structured tool call, this registration emits an
+ * `inject_reminder` with `hard-block` severity. The chat-loop's generic
+ * effect application interrupts the turn (unless its streaming cutoff already
+ * aborted it mid-delta) and flushes the reminder into the next model request
+ * as recovery guidance.
+ */
+
+import type { MiddlewareEffect, MiddlewareHookInput, MiddlewareHookRegistration } from "../domains/middleware/index.js";
+import { assessToolProseLoop, runtimeNarratesToolCalls } from "./tool-prose-loop.js";
+
+export const TOOL_PROSE_REGISTRATION_ID = "assessor.tool-prose-loop";
+
+export function createToolProseRegistration(): MiddlewareHookRegistration {
+	return {
+		id: TOOL_PROSE_REGISTRATION_ID,
+		description: "interrupt local model turns that narrate tool calls instead of emitting structured tool calls",
+		hooks: ["turn_end"],
+		evaluate(input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> {
+			if (input.hook !== "turn_end") return [];
+			const runtimeTier = typeof input.metadata?.runtimeTier === "string" ? input.metadata.runtimeTier : undefined;
+			if (!runtimeNarratesToolCalls(runtimeTier)) return [];
+			const text = input.text ?? "";
+			if (text.length === 0) return [];
+			const activeToolNames =
+				typeof input.metadata?.activeToolNames === "string"
+					? input.metadata.activeToolNames.split(",").filter((name) => name.length > 0)
+					: [];
+			const assessment = assessToolProseLoop({
+				text,
+				activeToolNames,
+				hasStructuredToolCall: input.metadata?.hasStructuredToolCall === true,
+			});
+			if (assessment.kind !== "loop") return [];
+			return [
+				{
+					kind: "inject_reminder",
+					message: `[Clio Coder] aborted local model turn: ${assessment.reason}.`,
+					severity: "hard-block",
+				},
+			];
+		},
+	};
+}