@mjasnikovs/pi-task 0.38.19 → 0.38.21

package/dist/shared/reasoning-capability.js

@@ -0,0 +1,82 @@
+/**
+ * pi's own level ladder, in order. The order is the whole algorithm: an
+ * unsupported level is resolved by walking UP first, then down.
+ */
+export const THINKING_LADDER = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+/**
+ * The levels this model will actually honour.
+ *
+ * Two rules that are easy to get backwards:
+ *  - `reasoning: false` collapses everything to `['off']`. That is failure mode
+ *    1: the knob is not rejected, it is erased.
+ *  - a MISSING map entry means "supported" for the standard levels but
+ *    "unsupported" for `xhigh` / `max`, which are opt-in and must be declared.
+ *    This is why config/reasoning.ts does not offer those two: a model with no
+ *    map at all would receive the raw string, and Qwen3.8's chat template
+ *    answers an unknown effort with HTTP 500 rather than a clamp.
+ */
+export function supportedThinkingLevels(model) {
+    if (!model.reasoning)
+        return ['off'];
+    return THINKING_LADDER.filter(level => {
+        const mapped = model.thinkingLevelMap?.[level];
+        if (mapped === null)
+            return false;
+        if (level === 'xhigh' || level === 'max')
+            return mapped !== undefined;
+        return true;
+    });
+}
+/**
+ * The level pi will use in place of the one asked for. Equal to the input when
+ * the model supports it — which is what makes the inequality a mismatch test.
+ */
+export function clampToModel(model, level) {
+    const available = supportedThinkingLevels(model);
+    if (available.includes(level))
+        return level;
+    const requested = THINKING_LADDER.indexOf(level);
+    if (requested === -1)
+        return available[0] ?? 'off';
+    for (let i = requested; i < THINKING_LADDER.length; i++) {
+        const candidate = THINKING_LADDER[i];
+        if (available.includes(candidate))
+            return candidate;
+    }
+    for (let i = requested - 1; i >= 0; i--) {
+        const candidate = THINKING_LADDER[i];
+        if (available.includes(candidate))
+            return candidate;
+    }
+    return available[0] ?? 'off';
+}
+/**
+ * Every group whose setting the model will silently change.
+ *
+ * `inherit` groups are skipped entirely, and that is what keeps a default
+ * install permanently quiet: with the shipped all-`inherit` table this returns
+ * an empty array for every model, including one with no reasoning at all.
+ *
+ * It reports mismatches in BOTH directions, which is wider than "warn when
+ * reasoning is on but unsupported". The failure actually captured on this
+ * machine is the mirror of that — `off` clamped UP to `medium`, so a user who
+ * turned thinking off still pays for it — and it is the same comparison. Warning
+ * about one direction while staying silent about the other would ship this
+ * feature with its own measured failure mode unreported.
+ */
+export function reasoningMismatches(model, settings) {
+    // No model resolved yet (session still starting, or none selected): say
+    // nothing. A warning naming no model is noise, not information.
+    if (!model)
+        return [];
+    const out = [];
+    for (const { group, setting } of settings) {
+        if (setting === 'inherit')
+            continue;
+        const wanted = setting;
+        const actual = clampToModel(model, wanted);
+        if (actual !== wanted)
+            out.push({ group, wanted, actual });
+    }
+    return out;
+}

package/dist/task/child-runner.d.ts

@@ -67,7 +67,14 @@ export interface PhaseRunResult {
     /** Set when the child's final turn failed with stopReason "error" (model/provider failure). */
     modelError?: string;
 }
-export declare function childArgs(tools: string, extensions?: readonly string[]): string[];
+export declare function childArgs(tools: string, extensions?: readonly string[], 
+/**
+ * An already-resolved `['--thinking', level]`, or `[]` for "emit no flag".
+ * Resolved by the CALLER, never here: the level is a property of the child's
+ * ROLE, and this function is handed tools and extensions, not a name.
+ * Omitted ⇒ byte-identical argv to the version before reasoning profiles.
+ */
+thinking?: readonly string[]): string[];
 export declare const USER_CANCELLED = "__user_cancelled__";
 /**
  * Run a child pi process with JSON event-stream output, loop detection, and
@@ -88,7 +95,17 @@ onToolResult?: (text: string, isError: boolean) => void,
  * one (issue #16), so the parent hands its own down — children carry no `-m`
  * and resolve the same default model. 0 / omitted = unknown, as before.
  */
-contextWindow?: number): Promise<PhaseRunResult>;
+contextWindow?: number, 
+/**
+ * The resolved `['--thinking', level]` fragment for this child's reasoning
+ * group, or `[]`/omitted to inherit the session default as before.
+ *
+ * A 13th trailing positional is not pretty. It is how `contextWindow` (the
+ * 12th) was added, and an options-bag refactor of this signature is a
+ * separate change from wiring one flag — doing both at once would put a
+ * behaviour change inside a mechanical one. DEBT: convert to an options bag.
+ */
+thinking?: readonly string[]): Promise<PhaseRunResult>;
 interface PhaseDeps {
     cwd: string;
     taskId: string;
@@ -195,30 +212,6 @@ interface PhaseDeps {
     searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
 }
 export type { PhaseDeps };
-/**
- * Run a child pi and return its assistant text. Throws if exit code != 0.
- *
- * If the child leaks a tool call as plain text (wrong dialect — never executed),
- * re-prompt with a correction hint up to MAX_LEAK_RETRIES times; if it keeps
- * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
- * Empty completions and connection-class model errors share that same budget —
- * see triageChildResult, which decides every one of those cases.
- *
- * THREE RUNAWAY GUARDS ride the same budget, because this is the runner every
- * /task-auto planning child goes through (clarify, decompose, coverage,
- * contract-extract) and until mx5-n 2026-08-14 it had none:
- *   • a LoopDetector, so an identical repeated tool call is killed and
- *     re-prompted instead of being allowed to fill the context window;
- *   • a StallDetector, the backstop for the varied-args thrash the loop
- *     detector's short window cannot see — the shape that actually cost us a
- *     16-minute decompose child that was never going to return. It bounds
- *     consecutive no-new-ground calls and total context churn, NOT elapsed time;
- *   • PHASE_CHILD_TIMEOUT_MS, a hard wall clock, OFF by default because the
- *     measured healthy range (610-927s for a reasoning-on decompose) overlaps
- *     any value that would catch the pathology. See its comment.
- * All three are checked BEFORE the triage ladder: we killed the child, so its
- * exit status describes our SIGTERM and says nothing about its verdict.
- */
 export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string, opts?: PhaseChildOptions): Promise<string>;
 export declare function formatLoopHint(hit: LoopHit): string;
 /**

package/dist/task/child-runner.js

@@ -15,6 +15,8 @@ import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../s
 import { readSection, setTaskSection } from './task-io.js';
 import { streamStallCause } from '../shared/stream-watchdog.js';
 import { getConfig } from '../config/config.js';
+import { groupThinkingArgs } from '../config/reasoning-args.js';
+import { reasoningGroupForChild } from './reasoning-groups.js';
 // ─── Loop detection constants ────────────────────────────────────────────────
 // Defined here (not in phases.ts) to avoid a circular dependency:
 //   phases.ts → child-runner.ts → phases.ts
@@ -132,7 +134,14 @@ export function connectionRetryBackoffMs(attempt) {
 }
 const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 // ─── Spawn helpers ───────────────────────────────────────────────────────────
-export function childArgs(tools, extensions = []) {
+export function childArgs(tools, extensions = [], 
+/**
+ * An already-resolved `['--thinking', level]`, or `[]` for "emit no flag".
+ * Resolved by the CALLER, never here: the level is a property of the child's
+ * ROLE, and this function is handed tools and extensions, not a name.
+ * Omitted ⇒ byte-identical argv to the version before reasoning profiles.
+ */
+thinking = []) {
     // `--mode json` puts the child into the structured event stream the
     // unified runner parses in `mode: 'json-events'`. Without it the child
     // emits plain text, every line fails JSON.parse, finalText stays empty,
@@ -153,7 +162,7 @@ export function childArgs(tools, extensions = []) {
     // one — the guards all hang off pi's `tool_call` hook.
     const toolFlags = tools === '' ? ['--no-tools'] : ['--tools', tools];
     const internal = tools === '' ? [] : extensions;
-    return [...childBaseArgs(internal), '--mode', 'json', ...toolFlags];
+    return [...childBaseArgs(internal), ...thinking, '--mode', 'json', ...toolFlags];
 }
 // Sentinel error thrown when the user dismisses a grill-me dialog.
 // Defined here (not in failure-classifier.ts) to avoid circular dependency.
@@ -178,8 +187,18 @@ onToolResult,
  * one (issue #16), so the parent hands its own down — children carry no `-m`
  * and resolve the same default model. 0 / omitted = unknown, as before.
  */
-contextWindow) {
-    const invocation = getPiInvocation(childArgs(tools, extensions), prompt);
+contextWindow, 
+/**
+ * The resolved `['--thinking', level]` fragment for this child's reasoning
+ * group, or `[]`/omitted to inherit the session default as before.
+ *
+ * A 13th trailing positional is not pretty. It is how `contextWindow` (the
+ * 12th) was added, and an options-bag refactor of this signature is a
+ * separate change from wiring one flag — doing both at once would put a
+ * behaviour change inside a mechanical one. DEBT: convert to an options bag.
+ */
+thinking) {
+    const invocation = getPiInvocation(childArgs(tools, extensions, thinking), prompt);
     let loopHit;
     const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
         mode: 'json-events',
@@ -310,9 +329,28 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  * All three are checked BEFORE the triage ladder: we killed the child, so its
  * exit status describes our SIGTERM and says nothing about its verdict.
  */
+/**
+ * The `--thinking` fragment for a named child, or `[]` when the name is unmapped.
+ *
+ * An unmapped name INHERITS rather than throwing: a child that reaches the model
+ * with today's argv is always safe, and aborting a user's task over a missing
+ * table row would be a worse failure than the one it reports. The guard that
+ * makes the table complete is `reasoning-groups.test.ts`, which fails the BUILD —
+ * where someone can actually fix it.
+ */
+function thinkingForChild(name) {
+    const group = reasoningGroupForChild(name);
+    return group ? groupThinkingArgs(group) : [];
+}
 export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
     if (deps.runChild)
         return await deps.runChild(name, tools, prompt);
+    // Resolved ONCE per call, not per attempt: a /task-config change landing
+    // between a loop-kill and its retry would otherwise make the two attempts
+    // different experiments, and the retry exists to repeat the first one with a
+    // hint. An unmapped name inherits, which is today's argv — the build-time
+    // guard for that is reasoning-groups.test.ts, not a throw in a user's run.
+    const thinking = thinkingForChild(name);
     const verb = opts.verb ?? 'retry';
     let hint = null;
     const loopHistory = [];
@@ -337,7 +375,7 @@ export async function runPhaseChild(deps, name, tools, prompt, opts = {}) {
                 // left the churn rule permanently disarmed (issue #16).
                 stall.noteContext(snapshot.contextWindow);
                 deps.onContextUsage?.(snapshot);
-            }, call => detector.record(call) ?? stall.record(call), deps.spawn, deps.childExtensions, (text, isError) => stall.noteResult(text, isError), deps.contextWindow);
+            }, call => detector.record(call) ?? stall.record(call), deps.spawn, deps.childExtensions, (text, isError) => stall.noteResult(text, isError), deps.contextWindow, thinking);
         }
         finally {
             clock.cleanup();
@@ -445,7 +483,11 @@ async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
 async function runDegradedFinalAttempt(deps, name, prompt, hit, loopHistory) {
     deps.logDebug?.(`${name}: loop budget exhausted — degrading to a no-tools final attempt`);
     const r = await runChild(deps.cwd, '', // --no-tools: the model cannot read/grep/list, only answer
-    prependHint(formatDegradeHint(hit), prompt), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn, undefined, undefined, deps.contextWindow);
+    prependHint(formatDegradeHint(hit), prompt), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn, undefined, undefined, deps.contextWindow, 
+    // Same group as the attempts that led here. The degrade changes the
+    // TOOLS, not the role — running it at a different thinking level would
+    // make the fallback a different experiment from the thing it rescues.
+    thinkingForChild(name));
     if (r.exitCode !== 0 || r.modelError || r.text.trim().length === 0) {
         throw new LoopExhaustedError(name, loopHistory);
     }

package/dist/task/decompose-fidelity.d.ts

@@ -1,12 +1,25 @@
 export interface SourcedTitle {
-    /** The title with any source clause stripped. */
+    /** The title with every source clause stripped. */
     base: string;
-    /** The cited spec line, when present and grounded in the source doc. */
-    source?: string;
+    /** The cited spec lines, in order, keeping only those GROUNDED in the doc. */
+    sources: string[];
 }
-/** Split a decompose title into its base and its GROUNDED source citation.
- *  An absent clause yields no source; a fabricated (ungrounded) one is stripped
- *  and dropped — exactly like keepGroundedContracts rejects a paraphrased quote. */
+/**
+ * Split a decompose title into its base and its GROUNDED source citations.
+ *
+ * PLURAL, because the model emits plural. The prompt asks for one trailing
+ * citation and a quarter of real titles carry more — 62 of 244 across the 20
+ * recorded runs. The old pattern was `\[source:\s*"(.+)"\]$`: greedy `.+`
+ * against an end anchor, so on `[source: "A"] [source: "B"]` it matched from the
+ * FIRST clause to the LAST quote and produced the superstring `A"] [source: "B`,
+ * which of course is not in the document. Two real citations became one
+ * fabricated one, and both were discarded. Peeling from the end with
+ * lastIndexOf is the fix; a lazy quantifier is NOT, because leftmost-first
+ * matching plus the `$` anchor expands it across the later clauses just the same.
+ *
+ * An absent clause yields no sources; a fabricated (ungrounded) one is dropped
+ * — exactly like keepGroundedContracts rejects a paraphrased quote.
+ */
 export declare function extractTitleSource(title: string, sourceDoc: string): SourcedTitle;
 /**
  * The `+`-joined trailing constraint fragments of `sourceLine` whose words are
@@ -24,8 +37,8 @@ export interface TitleRestoration {
     index: number;
     /** The verbatim fragments re-attached to the title. */
     fragments: string[];
-    /** The grounded source line they came from. */
-    source: string;
+    /** The grounded source lines they came from, in citation order. */
+    sources: string[];
 }
 export interface ReconciledPlan {
     titles: string[];

package/dist/task/decompose-fidelity.js

@@ -28,21 +28,88 @@
  * presence is exact word membership (with a singular/plural `s` allowance).
  */
 import { normalise } from './contracts.js';
-/** Trailing `[source: "…"]` clause a decompose line may carry (prompt asks for it last). */
-const SOURCE_RE = /\s*\[source:\s*"(.+)"\s*\]\s*$/i;
-/** Split a decompose title into its base and its GROUNDED source citation.
- *  An absent clause yields no source; a fabricated (ungrounded) one is stripped
- *  and dropped — exactly like keepGroundedContracts rejects a paraphrased quote. */
+/** One trailing `[source: "…"]` clause, anchored so it is the WHOLE remainder. */
+const SOURCE_RE = /^\[source:\s*"([\s\S]*)"\s*\]$/i;
+/**
+ * Markdown MARKUP dropped before grounding — emphasis runs, list and heading
+ * markers, table pipes and CODE BACKTICKS. Not content: no word, number or
+ * punctuation inside a sentence is touched, so this cannot make an invented
+ * quote match.
+ *
+ * WHY. A model copies a spec line as it READS, and what it reads is rendered:
+ * `2. **Auth** — sessions, login/logout/me, guards + tests.` comes back as
+ * `Auth — sessions, login/logout/me, guards + tests.` That is a verbatim copy of
+ * the line's TEXT, and the exact-substring test called it fabricated and threw
+ * it away — including, as here, the "+ tests" line that is this module's own
+ * worked example.
+ *
+ * BACKTICKS ARE THE SAME CLASS and were the larger half. A code span renders as
+ * bare text, so `3. **Invites** — create/validate/redeem, \`/join/:token\` page.`
+ * comes back as `Invites — create/validate/redeem, /join/:token page.` Measured
+ * on the mx5 fixture, screening every spec line in its RENDERED form:
+ * 107/216 grounded with backticks kept, 216/216 with them dropped.
+ *
+ * MEASURED 2026-08-27 over the 20 recorded decompose runs in
+ * ab-grouplab/ledger-planning.jsonl, and screened both ways first:
+ *   FLOOR   real spec lines with ONE content word altered: 0/216 pass.
+ *   CEILING real spec lines quoted without their markup: 209/257 = 81.3% passed
+ *           before, 257/257 after. 48 genuine lines were being rejected.
+ * Re-screened by scripts/decompose-fidelity-screen.ts, which is the standing
+ * check: CEILING raw 216/216, CEILING rendered 216/216, FLOOR 0/216.
+ */
+function demark(s) {
+    return s
+        .replace(/\*\*|__/g, '')
+        .replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, '')
+        .replace(/^#+\s*/gm, '')
+        .replace(/`/g, '')
+        .replace(/\|/g, ' ');
+}
+/**
+ * Undo the backslash-escaping a model applies to a quote it is putting INSIDE a
+ * double-quoted clause. `[source: "… \`import { sql } from \\"bun\\"\` gotcha …"]`
+ * is a faithful copy of a line the document stores with plain quotes; the
+ * backslashes are an artefact of the delimiter, not content. Measured live: 4 of
+ * the 19 ungrounded clauses in the n=30/arm planning run were this and nothing
+ * else. Only `\"` is undone — no other escape sequence is interpreted, so this
+ * cannot rewrite a quote into something the document happens to contain.
+ */
+function unescapeQuotes(s) {
+    return s.replace(/\\"/g, '"');
+}
+/**
+ * Split a decompose title into its base and its GROUNDED source citations.
+ *
+ * PLURAL, because the model emits plural. The prompt asks for one trailing
+ * citation and a quarter of real titles carry more — 62 of 244 across the 20
+ * recorded runs. The old pattern was `\[source:\s*"(.+)"\]$`: greedy `.+`
+ * against an end anchor, so on `[source: "A"] [source: "B"]` it matched from the
+ * FIRST clause to the LAST quote and produced the superstring `A"] [source: "B`,
+ * which of course is not in the document. Two real citations became one
+ * fabricated one, and both were discarded. Peeling from the end with
+ * lastIndexOf is the fix; a lazy quantifier is NOT, because leftmost-first
+ * matching plus the `$` anchor expands it across the later clauses just the same.
+ *
+ * An absent clause yields no sources; a fabricated (ungrounded) one is dropped
+ * — exactly like keepGroundedContracts rejects a paraphrased quote.
+ */
 export function extractTitleSource(title, sourceDoc) {
-    const m = SOURCE_RE.exec(title);
-    if (!m)
-        return { base: title.trim() };
-    const base = title.slice(0, m.index).trim();
-    const quote = m[1].trim();
-    if (quote.length === 0 || !normalise(sourceDoc).includes(normalise(quote))) {
-        return { base };
+    const ref = normalise(demark(sourceDoc));
+    let base = title.trim();
+    const sources = [];
+    for (;;) {
+        const at = base.toLowerCase().lastIndexOf('[source:');
+        if (at === -1)
+            break;
+        const m = SOURCE_RE.exec(base.slice(at).trim());
+        if (!m)
+            break;
+        const quote = m[1].trim();
+        base = base.slice(0, at).trim();
+        if (quote.length > 0 && ref.includes(normalise(demark(unescapeQuotes(quote)))))
+            sources.unshift(quote);
     }
-    return { base, source: quote };
+    return { base, sources };
 }
 /** Word tokens for presence checks: alphanumeric runs, lowercased. */
 function words(s) {
@@ -105,18 +172,32 @@ export function reconcileTitleSources(titles, sourceDoc) {
     const restored = [];
     let sourced = 0;
     for (let i = 0; i < titles.length; i++) {
-        const { base, source } = extractTitleSource(titles[i], sourceDoc);
-        if (source === undefined) {
+        const { base, sources } = extractTitleSource(titles[i], sourceDoc);
+        if (sources.length === 0) {
             out.push(base);
             continue;
         }
         sourced++;
-        const missing = findDroppedPlusFragments(source, base);
+        // EVERY grounded citation is checked, not just the first. A title that
+        // cites three spec lines can drop a constraint from any of them, and the
+        // fragments are deduped because two cited lines routinely share one
+        // ("+ tests" appears on four §12 milestones).
+        const seen = new Set();
+        const missing = [];
+        for (const src of sources) {
+            for (const f of findDroppedPlusFragments(src, base)) {
+                const k = f.toLowerCase();
+                if (seen.has(k))
+                    continue;
+                seen.add(k);
+                missing.push(f);
+            }
+        }
         if (missing.length === 0) {
             out.push(base);
             continue;
         }
-        restored.push({ index: i, fragments: missing, source });
+        restored.push({ index: i, fragments: missing, sources });
         out.push(`${base} — MUST also cover (restored from its spec line): ${missing.join(', ')}`);
     }
     return { titles: out, restored, sourced };

package/dist/task/gate-child.d.ts

@@ -75,6 +75,16 @@ export interface GateChildDeps {
     commandTimeoutMs: number;
     /** Hung-stream bound; the probe-based stall guard cannot supply it. */
     streamInactivityMs: number;
+    /**
+     * The resolved `['--thinking', level]` fragment for the `gate` reasoning
+     * group, or `[]` to inherit the session default.
+     *
+     * REQUIRED, like its two neighbours above: gate-child takes resolved config
+     * values and gate-deps supplies them. Optional-with-a-default would let a new
+     * gate wiring silently run at a level nobody chose, which is the failure the
+     * whole profile feature exists to end.
+     */
+    thinking: readonly string[];
     /**
      * The live widget state this child feeds and its loader reads. SHARED with
      * the caller — the verify gate's own loader reads the same status while this

package/dist/task/gate-child.js

@@ -94,6 +94,7 @@ export function makeGateChild(deps) {
                     timeoutMs: 0,
                     commandTimeoutMs: deps.commandTimeoutMs,
                     streamInactivityMs: deps.streamInactivityMs,
+                    thinking: deps.thinking,
                     // Exact-match loop guard only: pathThreshold Infinity disables
                     // the path-revisit heuristic, so revisiting one file (which IS
                     // the job) never trips — only a literally-identical call

package/dist/task/gate-deps.js

@@ -42,6 +42,7 @@ import { assessRunnerGlobs, runnerGlobVerifyFindings } from './runner-globs.js';
 import { captureGitState, reconcileGitState } from './git-state-guard.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { getConfig } from '../config/config.js';
+import { groupThinkingArgs } from '../config/reasoning-args.js';
 import { makeDebugAppender } from './debug-log.js';
 import { startAutoLoader } from './widget.js';
 import { ChildStatus } from './child-status.js';
@@ -584,6 +585,9 @@ export function buildGateDeps(params) {
         ...(opts.loader === undefined ? {} : { loader: opts.loader }),
         commandTimeoutMs: getConfig().requestTimeoutMs,
         streamInactivityMs: getConfig().streamInactivityMs,
+        // Read per gateChild() call, like its two neighbours, so a
+        // /task-config change lands on the next gate without a restart.
+        thinking: groupThinkingArgs('gate'),
         status,
         runWorker,
         makeDebugAppender,

package/dist/task/implementation-thinking.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Hold the host session at the `implementation` group's thinking level for the
+ * duration of one implementation turn, then put it back.
+ *
+ * WHY THIS IS NOT LIKE THE OTHER SIX GROUPS
+ * -----------------------------------------
+ * Every other group is a child process, so its level is one argv flag and it
+ * dies with the child. The implementation turn runs in the USER'S OWN session
+ * (orchestrator.ts `sendSpec` → sendUserMessage → superviseImplementation), so
+ * the only lever is `pi.setThinkingLevel`, which is session-global and visible.
+ *
+ * THREE THINGS pi DOES that this has to survive. All three read from
+ * pi-coding-agent's agent-session `setThinkingLevel`:
+ *
+ *  1. IT PERSISTS. On a real change it calls
+ *     `settingsManager.setDefaultThinkingLevel(...)`, writing
+ *     `~/.pi/agent/settings.json`. This is not a session-local toggle — without
+ *     the restore, running one task would silently rewrite the user's global
+ *     default. That makes `release()` load-bearing, not tidy-up.
+ *  2. IT CLAMPS, to what the model declares it supports. We may ask for `medium`
+ *     and be given `off`. So the restore writes back what was READ after
+ *     setting, never what was asked for — otherwise a clamp would ratchet the
+ *     stored default a little further every run.
+ *  3. IT IS OBSERVABLE, and the user can change it mid-turn (shift+tab cycles
+ *     the level). Restoring blindly would clobber a choice they just made. We
+ *     detect it by comparing the live level at release against what we applied:
+ *     if it has moved, somebody else moved it, and we leave it alone.
+ *
+ * We compare rather than subscribe because `pi.on` returns no unsubscribe
+ * handle, so a per-turn listener could only ever be added, never removed. The
+ * comparison answers the same question with no accumulating state.
+ */
+import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+import { type GroupSetting } from '../config/reasoning.js';
+/**
+ * The slice of the extension API this needs, named so tests can drive it without
+ * a live pi session. Every other dependency in `RunSingleTaskOptions` is
+ * injectable; this one has to be too, or the restore logic is only exercisable
+ * by running a real task.
+ */
+export interface ThinkingControl {
+    get(): ThinkingLevel;
+    set(level: ThinkingLevel): void;
+}
+/**
+ * Put the session at the implementation group's level and return the function
+ * that puts it back. Always call the returned function — `finally`, not the
+ * happy path.
+ *
+ * `inherit` makes NO call at all, not even a redundant set-to-current: a set
+ * that happens to be a no-op still goes through pi's change detection, and the
+ * shipped default must not touch the user's settings file.
+ */
+export declare function holdImplementationThinking(control: ThinkingControl, setting?: GroupSetting): () => void;

package/dist/task/implementation-thinking.js

@@ -0,0 +1,33 @@
+import { getConfig } from '../config/config.js';
+import { resolveReasoning } from '../config/reasoning.js';
+/**
+ * Put the session at the implementation group's level and return the function
+ * that puts it back. Always call the returned function — `finally`, not the
+ * happy path.
+ *
+ * `inherit` makes NO call at all, not even a redundant set-to-current: a set
+ * that happens to be a no-op still goes through pi's change detection, and the
+ * shipped default must not touch the user's settings file.
+ */
+export function holdImplementationThinking(control, setting = resolveReasoning('implementation', getConfig())) {
+    if (setting === 'inherit')
+        return () => { };
+    const before = control.get();
+    control.set(setting);
+    // Post-clamp, so a model that cannot do `medium` does not leave us believing
+    // it is at `medium` and treating the user's later change as our own.
+    const applied = control.get();
+    if (applied === before)
+        return () => { };
+    let released = false;
+    return () => {
+        // Idempotent: the caller's `finally` may run alongside an outer one on an
+        // abort path, and a second restore would fight a user change made in
+        // between.
+        if (released)
+            return;
+        released = true;
+        if (control.get() === applied)
+            control.set(before);
+    };
+}

package/dist/task/orchestrator.d.ts

@@ -20,6 +20,7 @@ import { type WidgetState } from './widget.js';
 import { type RunTaskFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
 import { type PhaseDeps } from './child-runner.js';
+import { type ThinkingControl } from './implementation-thinking.js';
 import { type RunEnd } from './run-end.js';
 import type { SpawnFn } from '../shared/child-process.js';
 import { type SuperviseOptions } from './implementation-turn.js';
@@ -166,6 +167,12 @@ export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId'
      * internal per-task runs, which must stay silent. Default false.
      */
     notifyFinish?: boolean;
+    /**
+     * How the implementation turn's thinking level is read and written. Defaults
+     * to the live pi session; injected by tests, which must be able to assert
+     * the restore without a real session to restore.
+     */
+    thinkingControl?: ThinkingControl;
 }
 export interface RunSingleTaskResult {
     taskId: string;