@iowarp/clio-coder 0.4.1 → 0.4.2

package/src/domains/prompts/fragments/operating/contract.md

@@ -1,27 +1,19 @@
 ---
 id: operating.contract
 version: 1
-budgetTokens: 400
 description: Constitutional operating posture shared by every Clio prompt
 ---
 
 # Operating Contract
 
-Clio has one operating posture. There is no read-only posture or
-user-facing posture toggle.
+Use tools when they materially help the task. Prefer a structured tool
+over bash when one exists; for narrow file or symbol work, inspect
+directly with the observe tools.
 
-Use the available tools when they materially help the current task.
-Prefer structured tools over bash when a structured tool exists. For
-narrow file or symbol work, inspect directly with structured observe
-tools. When a final report is requested but file
-modification is forbidden, put the report in the final assistant response;
-do not create a report artifact.
-
-Safety policy is authoritative for every tool call: allow decisions
-run normally; hard blocks (destructive git,
-protected artifacts, project or path policy violations) remain hard
-blocks. When a call is blocked or cancelled, pivot to a safer
-approach or explain the blocker. Do not retry the same blocked
+Safety policy is authoritative for every tool call. Hard blocks
+(destructive git, protected artifacts, project or path policy
+violations) stay blocked: when a call is blocked or cancelled, pivot to
+a safer approach or explain the blocker, and never retry the blocked
 action through another tool. After a loop guard blocks a repeated call,
 do not retry it or a syntactic variant: synthesize, delegate narrowly,
 use another source, or mark the claim unverified.

package/src/domains/prompts/fragments/operating/delegation.md

@@ -1,42 +1,40 @@
 ---
 id: operating.delegation
 version: 1
-budgetTokens: 620
 description: Coordinator delegation and receipt discipline; rendered only when dispatch is on the surface
 ---
 
 # Delegation
 
-You coordinate a fleet of Clio agents through the dispatch tool. You
-plan, route, and synthesize work across turns.
-Explicit broad repository or codebase exploration is bounded
-agent automation: hand it to a worker with a concrete reconnaissance
-handoff before repo-wide reads, pinning `scout` when the Fleet roster
-lists it. Use dispatch for other bounded fleet work with a clear
-handoff. A sealed run
-receipt is the durable record for delegated work. Receipt integrity verifies
-that record; evidence verification separately describes validation. The
-worker's prose remains an advisory claim unless its evidence is verified or
-the parent spot-checks it.
-A successful reconnaissance receipt is an index. Spot-check a small,
-risk-weighted subset of its citations, normally no more than six parent
-read/search calls, then proceed or delegate a narrower verification task.
-Spot-check delegated claims before repeating them: re-read any cited
-file:line location, and re-run or inspect the named validation before
-repeating a "tests pass" claim.
-Parent spot-checking is not independent specialist confirmation. Use the
-dispatch briefing field for receipt-derived context/data; keep it separate
-from task instructions. Collect detached runs before final synthesis.
-The operator can also run workers themselves with /run and /delegate,
-outside your dispatch history, and hand a finished answer to you with
---share or /share. Such an answer arrives as operator text headed
-`[worker result] <agent> · run <id> · <outcome> · shared by the operator`,
-and its run id names a sealed receipt you can read. Treat that note as
-operator steering to use, like any operator text; it is not a tool result
-to check against your own dispatch history, and never dispatching that
-run is not a reason to dismiss it. Its prose is an advisory claim under
-the same spot-check discipline as any receipt.
-Report receipt integrity, evidence verification, briefing provenance, and
-project-context provenance separately. Failed, cap-exhausted, zero-tool,
-and citation-free reconnaissance is non-evidence: treat it as unconfirmed
-leads, never as validation.
+You coordinate Clio workers through the dispatch tool. Before your first
+edit, count the independent file-scoped changes the request asks for.
+Two or more, or any repository-wide exploration: dispatch, and do not
+edit those files yourself. One narrow change: do it yourself.
+For two or more changes, one dispatch call carries them all as `tasks`,
+one task per change, each naming its file in `intent`, with `agent`
+"coder" and `mode` "parallel". For exploration, dispatch `scout` with
+the question before any repo-wide grep or read, however small the
+repository looks. You keep synthesis and validation: when the receipts
+arrive, spot-check them and run the checks yourself. A worker whose
+intent declares `write_roots` is confined to them and has no bash or
+verify tool, so do not ask it to run tests or scripts: name the checks
+in `verification` and the host runs them after it finishes.
+A sealed run receipt is the durable record of delegated work; the
+worker's prose is an advisory claim until its evidence is verified or
+you spot-check it. Spot-check a small, risk-weighted subset of a
+reconnaissance receipt's citations (normally at most six read or search
+calls), and re-read any cited file:line and re-run or inspect the named
+validation before repeating a "tests pass" claim. Failed, cap-exhausted,
+zero-tool, or citation-free reconnaissance is unconfirmed leads, never
+validation.
+Put receipt-derived context in the dispatch briefing field, separate
+from task instructions. Collect detached runs before final synthesis,
+and report receipt integrity, evidence verification, briefing
+provenance, and project-context provenance as separate facts. Never
+narrate or summarize a worker you did not dispatch; if you cannot
+dispatch, say so and name the reason.
+A note headed `[worker result] <agent> · run <id> · <outcome> · shared
+by the operator` is operator text: a worker the operator ran with /run
+or /delegate and shared with --share or /share. Use it like any operator
+steering, read its receipt by run id, and apply the same spot-check
+discipline; not having dispatched it is no reason to dismiss it.

package/src/domains/prompts/fragments/operating/skills.md

@@ -1,33 +1,19 @@
 ---
 id: operating.skills
 version: 1
-budgetTokens: 340
 description: Coordinator skill suggestion discipline; rendered only when context is on the surface
 ---
 
 # Skills
 
-Skills package proven workflows. Some are installed; the rest sit in a
-marketplace the operator installs from, and context (scope="skills") is
-the one authoritative listing of both — never guess the inventory or
-search the repository for a skill file. The catalog spans git delivery
-(filing, fixing, and shipping issues), planning (intent, PRD, backlog,
-architecture, sprint slicing), coding practice (TDD, standards,
-prototyping), context priming and handoff, research workflows, and
-plan-stress-testing debates. When a task lands in one of those shapes,
-call context (scope="skills") first and match it against the catalog.
-Suggest the best match to the operator as /skill <name> — the sequence
-in order when skills compose — and let the operator decide before
-grinding through that workflow bare; a marketplace match is suggested
-the same way, and /skill <name> offers the install. When the operator
-names a skill or asks how one works, answer from that same listing.
-When a [Marketplace] reminder names an uninstalled skill for the
-current request, first check the installed side with context
-(scope="skills"); only if nothing installed serves and the named skill
-truly fits, put the install question to the operator with ask_user
-using exactly the four options the reminder states, then continue the
-task in the same turn. The harness performs any consented install;
-never install a skill yourself, and never offer one no reminder named.
-Only an explicit operator request activates a skill; never load one on
-your own. If nothing fits or the task is routine, proceed normally and
+Skills are operator-activated workflows: git delivery, planning, coding
+practice, context priming and handoff, research, and plan stress-testing.
+context (scope="skills") is the one authoritative listing of installed
+and marketplace skills; never guess the inventory or search the
+repository for one. When a task has one of those shapes, list them,
+suggest the best match as /skill <name> (the sequence in order when
+several compose), and continue the task without it: only the operator
+activates or installs a skill, and a [Marketplace] reminder states its
+own offer options. When the operator names a skill or asks how one
+works, answer from that listing. If nothing fits, proceed normally and
 suggest nothing.

package/src/domains/prompts/fragments/operating/worker.md

@@ -1,16 +1,9 @@
 ---
 id: operating.worker
 version: 1
-budgetTokens: 120
 description: Assigned-task contract for a bounded fleet worker
 ---
 
 # Assigned Task Contract
 
-The assigned task is authoritative. Role guidance is a persona, not a replacement task.
-
-Do not invent a different task, source tree, file path, or implementation plan.
-
-If the assigned task asks for an exact response, a direct answer, or no tool use, answer it directly without tool calls.
-
-Use tools only when necessary for the assigned task and admitted by the worker tool contract.
+The assigned task is authoritative; role guidance is a persona, not a replacement. Do not invent a different task, source tree, file path, or implementation plan.

package/src/domains/providers/index.ts

@@ -161,7 +161,7 @@ export {
 	VALID_THINKING_LEVELS,
 } from "./types/capability-flags.js";
 export { type ContextWindowSlots, formatContextWindowSlots } from "./types/context-window-slots.js";
-export { type CostProvenance, normalizeCostProvenance } from "./types/cost-provenance.js";
+export { type CostProvenance, normalizeCostProvenance, resolveCostProvenance } from "./types/cost-provenance.js";
 export type { KnowledgeBase, KnowledgeBaseEntry, KnowledgeBaseHit } from "./types/knowledge-base.js";
 export type {
 	ProbeContext,

package/src/domains/providers/model-runtime-capabilities.ts

@@ -36,7 +36,7 @@ export interface AppliedThinking {
 	mechanism: ThinkingMechanism;
 	effort?: string;
 	budgetTokens?: number;
-	chatTemplateKwargs?: Record<string, boolean>;
+	chatTemplateKwargs?: Record<string, boolean | string | number>;
 	noticeKind: AppliedThinkingNoticeKind;
 	notice: string;
 }
@@ -53,7 +53,20 @@ export interface ResolvedRequestCapability {
 	reasoningEffort?: string;
 	budgetTokens?: number;
 	budgetEnforcement: ThinkingBudgetEnforcement;
-	chatTemplateKwargs?: Record<string, boolean | string>;
+	chatTemplateKwargs?: Record<string, boolean | string | number>;
+	/**
+	 * Family-declared chat-template kwargs the runtime cannot carry. LM Studio
+	 * ignores `chat_template_kwargs` for every family measured, so the keys are
+	 * named here for the resolution diagnostics instead of riding in
+	 * `chatTemplateKwargs` only to be deleted at the wire.
+	 */
+	undeliverableChatTemplateKwargs?: UndeliverableChatTemplateKwargs;
+}
+
+export interface UndeliverableChatTemplateKwargs {
+	keys: string[];
+	/** True when the family entry itself marks the block `lmstudio: unsupported`. */
+	declaredUnsupported: boolean;
 }
 
 export interface ResolvedResponseCapability {
@@ -335,14 +348,15 @@ function supportedEffortLevels(
 ): ReadonlyArray<ThinkingLevel> {
 	if (harmony) return HARMONY_LEVELS;
 	const efforts = quirks?.thinking?.effortByLevel;
-	if (!efforts) return baseLevels;
+	const byLevelValues = (quirks?.chatTemplateKwargs ?? quirks?.thinking?.chatTemplateKwargs)?.byLevel?.values;
+	if (!efforts && !byLevelValues) return baseLevels;
 	const out: ThinkingLevel[] = [];
 	if (baseLevels.includes("off")) out.push("off");
-	if (efforts.minimal !== undefined) out.push("minimal");
-	if (efforts.low !== undefined) out.push("low");
-	if (efforts.medium !== undefined) out.push("medium");
-	if (efforts.high !== undefined) out.push("high");
-	if (efforts.xhigh !== undefined) out.push("xhigh");
+	if (efforts?.minimal !== undefined || byLevelValues?.minimal !== undefined) out.push("minimal");
+	if (efforts?.low !== undefined || byLevelValues?.low !== undefined) out.push("low");
+	if (efforts?.medium !== undefined || byLevelValues?.medium !== undefined) out.push("medium");
+	if (efforts?.high !== undefined || byLevelValues?.high !== undefined) out.push("high");
+	if (efforts?.xhigh !== undefined || byLevelValues?.xhigh !== undefined) out.push("xhigh");
 	return out.length > 0 ? out : baseLevels;
 }
 
@@ -525,27 +539,71 @@ function resolveThinkingCapability(
 }
 
 /**
- * Runtimes whose OpenAI-compatible surface reads the on-off thinking control
- * from `reasoning_effort` rather than `chat_template_kwargs.enable_thinking`.
- * Measured against the live fleet on 2026-08-11 with
- * `nvidia-nemotron-3.5-lightning-30b-a3b`: LM Studio suppressed reasoning
- * entirely for `reasoning_effort: "none"` and ignored `enable_thinking: false`,
- * while llama.cpp did the reverse. Sending the wrong spelling reads as "no
- * preference" to the server, so the model keeps reasoning at every dial.
+ * Runtimes whose OpenAI-compatible surface ignores `chat_template_kwargs`
+ * and reads every thinking control from `reasoning_effort`. Measured against
+ * dynamo (LM Studio) on 2026-08-11 with `nvidia-nemotron-3.5-lightning-30b-a3b`
+ * and again on 2026-09-02 across three mechanisms: `enable_thinking: false`
+ * left 26 reasoning tokens on qwen3.8-27b (effort-levels), 52 on
+ * gemma-4-26b-a4b-it (on-off) and 105 on nemotron-3.5-lightning (on-off),
+ * while `reasoning_effort: "none"` produced 0 on each; llama.cpp does the
+ * reverse. Sending the wrong spelling reads as "no preference" to the
+ * server, so the model keeps reasoning at every dial. The same runtime drops
+ * a family's own kwargs (#267) for the same reason, so those are reported as
+ * undeliverable rather than merged into the request (#268).
  */
-const REASONING_EFFORT_ON_OFF_RUNTIMES: ReadonlySet<string> = new Set(["lmstudio"]);
+const REASONING_EFFORT_ONLY_RUNTIMES: ReadonlySet<string> = new Set(["lmstudio"]);
 
 /** `none` is LM Studio's documented off value; on-off models have no finer dial than `low`. */
 function onOffReasoningEffort(thinkingActive: boolean): string {
 	return thinkingActive ? "low" : "none";
 }
 
+function resolveFamilyChatTemplateKwargs(
+	quirks: LocalModelQuirks | undefined,
+	effectiveLevel: ThinkingLevel,
+	configuredLevel: ThinkingLevel,
+): Record<string, boolean | string | number> | undefined {
+	const block = quirks?.chatTemplateKwargs ?? quirks?.thinking?.chatTemplateKwargs;
+	if (!block) return undefined;
+	const out: Record<string, boolean | string | number> = {};
+	if (block.static) {
+		for (const [k, v] of Object.entries(block.static)) {
+			out[k] = v;
+		}
+	}
+	if (block.byLevel) {
+		const byLevel = block.byLevel;
+		const val = byLevel.values[effectiveLevel] ?? byLevel.values[configuredLevel];
+		if (val !== undefined) {
+			out[byLevel.key] = val;
+		}
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function familyKwargsDeclaredUnsupported(quirks: LocalModelQuirks | undefined, runtimeId: string): boolean {
+	if (runtimeId !== "lmstudio") return false;
+	const block = quirks?.chatTemplateKwargs ?? quirks?.thinking?.chatTemplateKwargs;
+	return block?.lmstudio === "unsupported" || block?.byLevel?.lmstudio === "unsupported";
+}
+
 function resolveRequestCapability(
 	thinking: ResolvedThinkingCapability,
 	parser: ResponseParserKind,
 	runtimeId: string,
+	quirks?: LocalModelQuirks,
 ): ResolvedRequestCapability {
 	const request: ResolvedRequestCapability = { budgetEnforcement: thinking.budgetEnforcement };
+	const effortOnly = REASONING_EFFORT_ONLY_RUNTIMES.has(runtimeId);
+	const familyKwargs = resolveFamilyChatTemplateKwargs(quirks, thinking.effectiveLevel, thinking.configuredLevel);
+	if (familyKwargs && effortOnly) {
+		request.undeliverableChatTemplateKwargs = {
+			keys: Object.keys(familyKwargs),
+			declaredUnsupported: familyKwargsDeclaredUnsupported(quirks, runtimeId),
+		};
+	} else if (familyKwargs) {
+		request.chatTemplateKwargs = { ...familyKwargs };
+	}
 	if (thinking.mechanism === "effort-levels" && thinking.effort) {
 		request.reasoningEffort = thinking.effort;
 	}
@@ -556,15 +614,21 @@ function resolveRequestCapability(
 		request.budgetTokens = thinking.budgetTokens;
 	}
 	if (thinking.mechanism === "on-off" && thinking.chatTemplateKwargs) {
-		request.chatTemplateKwargs = { ...thinking.chatTemplateKwargs };
-		if (REASONING_EFFORT_ON_OFF_RUNTIMES.has(runtimeId)) {
-			request.reasoningEffort = onOffReasoningEffort(thinking.thinkingActive);
-		}
+		request.chatTemplateKwargs = { ...(request.chatTemplateKwargs ?? {}), ...thinking.chatTemplateKwargs };
 	}
 	if (parser === "harmony" && thinking.effort) {
 		request.reasoningEffort = thinking.effort;
 		request.chatTemplateKwargs = { ...(request.chatTemplateKwargs ?? {}), reasoning_effort: thinking.effort };
 	}
+	// Every mechanism that means "off" has to reach an effort-only runtime as
+	// reasoning_effort "none": the template flag above is what llama.cpp reads
+	// and what LM Studio drops. An interactive session with thinking "off" had
+	// spent 37k reasoning tokens before the effort-levels case reached the
+	// wire, and on-off and budget-tokens families reasoned on the same way.
+	if (effortOnly && thinking.mechanism !== "none" && thinking.mechanism !== "always-on") {
+		if (!thinking.thinkingActive) request.reasoningEffort = onOffReasoningEffort(false);
+		else if (thinking.mechanism === "on-off") request.reasoningEffort = onOffReasoningEffort(true);
+	}
 	return request;
 }
 
@@ -583,7 +647,7 @@ export function resolveModelRuntimeCapabilities(
 		family,
 		capabilities: input.capabilities,
 		thinking,
-		request: resolveRequestCapability(thinking, parser, input.runtimeId),
+		request: resolveRequestCapability(thinking, parser, input.runtimeId, quirks),
 		response: {
 			parser,
 			stripTokenizerSentinels: true,