@mjasnikovs/pi-task 0.38.31 → 0.38.32

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

@@ -0,0 +1,118 @@
+/**
+ * Hold the host session on the `implementation` group's model AND thinking level
+ * for one implementation turn, then put both back.
+ *
+ * WHY THIS GROUP IS NOT LIKE THE OTHERS
+ * -------------------------------------
+ * Every other group runs in a child process, so its settings are two argv flags
+ * (`groupChildArgs` in config/group-args.ts) that die with the child. The
+ * implementation turn runs in the USER'S OWN session (orchestrator.ts `sendSpec`
+ * -> `sendUserMessage` -> `superviseImplementation`), so the only levers are
+ * `pi.setThinkingLevel` and `pi.setModel`, and both are session-global.
+ *
+ * WHAT pi DOES that this has to survive:
+ *
+ *  1. BOTH PERSIST. `setThinkingLevel` writes `defaultThinkingLevel` and
+ *     `setModel` writes `defaultProvider`/`defaultModel`, into pi's global
+ *     `~/.pi/agent/settings.json`. Without the restore, running one task would
+ *     silently rewrite the user's global defaults — and since children carry no
+ *     `-m` and resolve exactly those defaults, it would re-point every future
+ *     child in every project. That makes `release()` load-bearing, not tidy-up.
+ *  2. THEY CLAMP. A model with no reasoning support offers only `off`, so asking
+ *     for `medium` yields `off`. The restore writes back what was READ after
+ *     setting, never what was asked for, or a clamp would ratchet the stored
+ *     default further every run.
+ *  3. `setModel` RE-CLAMPS THINKING as part of switching. So the level must be
+ *     read before any model move, and written after the model is back.
+ *  4. THE USER CAN CHANGE EITHER MID-TURN — `shift+tab` cycles thinking. We
+ *     detect it by comparing the live value 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 the extension API's `on(...)` returns
+ * `void` — there is no unsubscribe handle — so a per-turn listener could only
+ * ever be added, never removed.
+ *
+ * WHAT THIS COSTS, so nobody has to rediscover it
+ * -----------------------------------------------
+ * A model switch re-bills the whole prompt. pi counts that deliberately —
+ * `core/cache-stats.js` says "Model switches are NOT exempt: they re-bill the
+ * full prompt and should be counted" — and prints `Cache miss after model
+ * switch: N tokens re-billed` once the miss clears 20k tokens or $0.10, which an
+ * implementation prompt does. It happens twice: once acquiring, once releasing.
+ * On a local server that is a full prompt reprocess, not a bill. This is why the
+ * cell ships `inherit`, and why the target-equals-current degrade below is the
+ * main guard rather than an optimisation.
+ */
+import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+import { type GroupSetting } from '../config/reasoning.js';
+import { type HoldStash } from './model-hold-stash.js';
+/**
+ * The slice of the extension API this needs, named so tests can drive the
+ * hold-and-restore with a fake object instead of a live pi session.
+ */
+export interface ThinkingControl {
+    get(): ThinkingLevel;
+    set(level: ThinkingLevel): void;
+}
+/**
+ * The model half, generic in the HANDLE so tests can use a literal.
+ *
+ * `current()` returns the spec AND the handle: the comparison is on a plain
+ * string, and the restore uses the handle captured at acquire rather than
+ * re-resolving against a registry that may have moved underneath us.
+ *
+ * `apply` may return `false` OR REJECT. pi's `setModel` returns false only when
+ * `hasConfiguredAuth` — a cached snapshot Set — is false; it then calls the
+ * session's own `setModel`, which awaits a live `checkAuth` and throws when the
+ * two disagree, as they do for an expired OAuth token. Callers here treat a
+ * throw and a `false` identically, because nothing useful differs between them.
+ */
+export interface ModelControl<H = unknown> {
+    current(): {
+        spec: string;
+        handle: H;
+    } | undefined;
+    resolve(spec: string): H | undefined;
+    apply(handle: H): Promise<boolean>;
+}
+export interface ImplementationControls<H = unknown> {
+    thinking: ThinkingControl;
+    model: ModelControl<H>;
+}
+/**
+ * The whole hold: model, then thinking. Returns the release, which is async and
+ * idempotent. Always call it from a `finally`, never the happy path.
+ *
+ * ONE function rather than two composable holds, because two independent holds
+ * acquired in the wrong order fail SILENTLY — `setModel` re-clamps thinking, so
+ * a thinking hold taken first is erased and a thinking restore taken last is
+ * clamped by the wrong model's ladder. A composition that can only be assembled
+ * one way belongs in one function.
+ */
+export declare function holdImplementation<H>(controls: ImplementationControls<H>, setting?: GroupSetting, spec?: string, stash?: HoldStash): Promise<() => Promise<void>>;
+/**
+ * Put back a model a crashed session left applied. Runs at `session_start`.
+ *
+ * THE GUARDS are the whole design, because this runs in a session that knows
+ * nothing about the one that crashed. Four cases, and only the last writes:
+ *
+ *  1. pi's saved default is still the note's `before` — the file is already
+ *     right. Either a live hold has written its note but not yet switched, or a
+ *     crash landed in that same gap. Decline, and KEEP the note: clearing here
+ *     is what would let an unrelated session start delete a live hold's only
+ *     crash record, in the millisecond before it applies.
+ *  2. the saved default is neither value — somebody moved on. Clear, decline.
+ *  3. the saved default matches, but THIS session is on a different model — it
+ *     was launched with an explicit `--model`, or resumed onto one. Restoring
+ *     would silently override a choice made on the command line. Decline, and
+ *     keep the note so a later ordinary start still repairs the file.
+ *  4. everything agrees. Restore, and clear.
+ *
+ * The note is also cleared on a failed restore: one that cannot happen must not
+ * re-fire on every subsequent startup.
+ *
+ * Thinking is deliberately NOT restored here. `setModel` re-clamps it to the
+ * model we are restoring TO, which is the level that model was running at
+ * before the crashed session touched anything.
+ */
+export declare function restoreHeldModel<H>(model: ModelControl<H>, savedDefaultSpec: () => string | undefined, stash?: HoldStash): Promise<'restored' | 'declined' | 'nothing'>;

package/dist/task/implementation-hold.js

@@ -0,0 +1,165 @@
+import { getConfig } from '../config/config.js';
+import { MODEL_INHERIT } from '../config/group-models.js';
+import { resolveReasoning } from '../config/reasoning.js';
+import { readHoldStash, writeHoldStash, clearHoldStash } from './model-hold-stash.js';
+/**
+ * `before` is the level read BEFORE any model move; `applied` is what is really
+ * in force after both moves.
+ *
+ * `inherit` writes nothing but still RECORDS, because the model switch may have
+ * moved the level on its own. `applied === before` means nothing moved, and then
+ * there is nothing to restore — a write there would be a settings.json write for
+ * no reason.
+ */
+function acquireThinking(control, setting, before) {
+    if (setting !== 'inherit')
+        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();
+    return applied === before ? undefined : { before, applied };
+}
+const userMovedThinking = (control, hold) => control.get() !== hold.applied;
+/**
+ * The whole hold: model, then thinking. Returns the release, which is async and
+ * idempotent. Always call it from a `finally`, never the happy path.
+ *
+ * ONE function rather than two composable holds, because two independent holds
+ * acquired in the wrong order fail SILENTLY — `setModel` re-clamps thinking, so
+ * a thinking hold taken first is erased and a thinking restore taken last is
+ * clamped by the wrong model's ladder. A composition that can only be assembled
+ * one way belongs in one function.
+ */
+export async function holdImplementation(controls, setting = resolveReasoning('implementation', getConfig()), spec = getConfig().groupModels.implementation, stash = { read: readHoldStash, write: writeHoldStash, clear: clearHoldStash }) {
+    const { thinking, model } = controls;
+    // BEFORE any model move: `setModel` re-clamps, so this is the only moment
+    // the pre-hold level is readable.
+    const beforeThinking = thinking.get();
+    const modelHold = await acquireModel(model, spec, stash);
+    // A model move that was ASKED FOR and failed no-ops the whole hold. Running
+    // the implementation turn on the wrong model at the right level is worse
+    // than running it exactly as it ran last week.
+    if (modelHold === 'failed')
+        return async () => { };
+    // A MODEL move alone moves the level, even with the thinking cell on
+    // `inherit`: pi's `setModel` re-clamps to the target's ladder and PERSISTS
+    // the result. So the thinking hold is taken whenever either half moved
+    // something, not only when a level was asked for — otherwise a session at
+    // `high` switched onto an off/medium model is left globally at `medium`
+    // with nothing to put it back, which is the one thing release() exists for.
+    const thinkingHold = setting === 'inherit' && modelHold === undefined ?
+        undefined
+        : acquireThinking(thinking, setting, beforeThinking);
+    let released = false;
+    return async () => {
+        if (released)
+            return;
+        released = true;
+        // Read the thinking comparison BEFORE restoring the model. A read taken
+        // after it is post-clamp, and the mid-turn-change detector then answers
+        // wrongly in both directions.
+        const moved = thinkingHold !== undefined && userMovedThinking(thinking, thinkingHold);
+        if (modelHold !== undefined) {
+            try {
+                await model.apply(modelHold.before);
+            }
+            catch {
+                // A failed model restore is still followed by the thinking
+                // restore. Restoring what we can beats restoring nothing.
+            }
+            stash.clear();
+        }
+        // LAST. Writing `before` while still on the target model has pi clamp it
+        // to the TARGET's ladder, and the model restore then re-clamps from that
+        // already-wrong value.
+        if (thinkingHold !== undefined && !moved)
+            thinking.set(thinkingHold.before);
+    };
+}
+/**
+ * `undefined` = no move was needed or possible, and today's behaviour stands.
+ * `'failed'` = a move was asked for and did not happen, which voids the hold.
+ */
+async function acquireModel(model, spec, stash) {
+    if (spec === MODEL_INHERIT)
+        return undefined;
+    const cur = model.current();
+    if (!cur)
+        return undefined;
+    // Not an optimisation. `setDefaultModelAndProvider` runs unconditionally
+    // inside pi's `setModel`, so a redundant call rewrites the user's global
+    // default, appends a model change to their session and re-bills the whole
+    // prompt as a cache miss — all to arrive where we already were.
+    if (cur.spec === spec)
+        return undefined;
+    const handle = model.resolve(spec);
+    // Model gone, or its provider unauthed. The session hint names it; the turn
+    // runs where it already was.
+    if (handle === undefined)
+        return undefined;
+    // Written BEFORE the apply, so a crash between the two costs an unnecessary
+    // restore attempt rather than a missed one.
+    stash.write({ before: cur.spec, applied: spec });
+    try {
+        if (await model.apply(handle))
+            return { before: cur.handle, beforeSpec: cur.spec, appliedSpec: spec };
+    }
+    catch {
+        // Identical to `false`: see ModelControl.apply.
+    }
+    stash.clear();
+    return 'failed';
+}
+/**
+ * Put back a model a crashed session left applied. Runs at `session_start`.
+ *
+ * THE GUARDS are the whole design, because this runs in a session that knows
+ * nothing about the one that crashed. Four cases, and only the last writes:
+ *
+ *  1. pi's saved default is still the note's `before` — the file is already
+ *     right. Either a live hold has written its note but not yet switched, or a
+ *     crash landed in that same gap. Decline, and KEEP the note: clearing here
+ *     is what would let an unrelated session start delete a live hold's only
+ *     crash record, in the millisecond before it applies.
+ *  2. the saved default is neither value — somebody moved on. Clear, decline.
+ *  3. the saved default matches, but THIS session is on a different model — it
+ *     was launched with an explicit `--model`, or resumed onto one. Restoring
+ *     would silently override a choice made on the command line. Decline, and
+ *     keep the note so a later ordinary start still repairs the file.
+ *  4. everything agrees. Restore, and clear.
+ *
+ * The note is also cleared on a failed restore: one that cannot happen must not
+ * re-fire on every subsequent startup.
+ *
+ * Thinking is deliberately NOT restored here. `setModel` re-clamps it to the
+ * model we are restoring TO, which is the level that model was running at
+ * before the crashed session touched anything.
+ */
+export async function restoreHeldModel(model, savedDefaultSpec, stash = { read: readHoldStash, write: writeHoldStash, clear: clearHoldStash }) {
+    const note = stash.read();
+    if (!note)
+        return 'nothing';
+    const saved = savedDefaultSpec();
+    if (saved === note.before)
+        return 'declined';
+    if (saved !== note.applied) {
+        stash.clear();
+        return 'declined';
+    }
+    if (model.current()?.spec !== note.applied)
+        return 'declined';
+    const handle = model.resolve(note.before);
+    if (handle === undefined) {
+        stash.clear();
+        return 'declined';
+    }
+    try {
+        return (await model.apply(handle)) ? 'restored' : 'declined';
+    }
+    catch {
+        return 'declined';
+    }
+    finally {
+        stash.clear();
+    }
+}

package/dist/task/model-hold-stash.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The crash half of the implementation hold.
+ *
+ * `release()` runs in a `finally`, and a `finally` does not run for SIGKILL, a
+ * segfault, or the power going out. An implementation turn is measured in hours.
+ * Without this, one of those leaves pi's GLOBAL `defaultModel` pointing at the
+ * implementation model — and because children carry no `-m` and resolve that
+ * same default, every child of every future run, in every project, quietly
+ * follows it until the user notices.
+ *
+ * So acquire leaves a note on disk and release removes it. A later session
+ * finds the note and puts the model back.
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/**
+ * Both halves of the switch, as `provider/id` strings.
+ *
+ * `applied` is what makes the restore safe to run in a second, unrelated
+ * session: it is the value we are allowed to overwrite, and nothing else.
+ */
+export interface StashRecord {
+    before: string;
+    applied: string;
+}
+/** The seam, so the hold's tests never touch a real home directory. */
+export interface HoldStash {
+    read(): StashRecord | undefined;
+    write(record: StashRecord): void;
+    clear(): void;
+}
+export declare function readHoldStash(): StashRecord | undefined;
+export declare function writeHoldStash(record: StashRecord): void;
+export declare function clearHoldStash(): void;
+/**
+ * Register the crash restore. Runs once per `session_start`, before any task.
+ *
+ * It reaches for `pi.setModel` rather than writing `settings.json` itself:
+ * pi-task has no sanctioned way to write that file, and inventing one would fork
+ * the format. Everything it can go wrong on — no registry, a model that has
+ * since vanished, a rejected auth check — ends the same way, with the note
+ * dropped, because a restore that cannot happen must not re-fire forever.
+ */
+export declare function registerModelHoldRestore(pi: ExtensionAPI): void;

package/dist/task/model-hold-stash.js

@@ -0,0 +1,70 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { splitSpec } from '../config/group-models.js';
+import { defaultModelRef } from '../shared/model-endpoint.js';
+import { stateFile } from '../shared/data-home.js';
+import { restoreHeldModel } from './implementation-hold.js';
+const stashPath = () => stateFile('model-hold.json');
+export function readHoldStash() {
+    try {
+        const j = JSON.parse(fs.readFileSync(stashPath(), 'utf8'));
+        if (typeof j.before !== 'string' || typeof j.applied !== 'string')
+            return undefined;
+        if (j.before === '' || j.applied === '')
+            return undefined;
+        return { before: j.before, applied: j.applied };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeHoldStash(record) {
+    try {
+        const p = stashPath();
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(record));
+    }
+    catch {
+        // A stash we cannot write costs us the crash restore, not the turn.
+    }
+}
+export function clearHoldStash() {
+    try {
+        fs.rmSync(stashPath(), { force: true });
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * Register the crash restore. Runs once per `session_start`, before any task.
+ *
+ * It reaches for `pi.setModel` rather than writing `settings.json` itself:
+ * pi-task has no sanctioned way to write that file, and inventing one would fork
+ * the format. Everything it can go wrong on — no registry, a model that has
+ * since vanished, a rejected auth check — ends the same way, with the note
+ * dropped, because a restore that cannot happen must not re-fire forever.
+ */
+export function registerModelHoldRestore(pi) {
+    pi.on('session_start', (_event, ctx) => {
+        const model = {
+            current: () => {
+                const m = ctx.model;
+                return m ? { spec: `${m.provider}/${m.id}`, handle: m } : undefined;
+            },
+            resolve: spec => {
+                const parts = splitSpec(spec);
+                return parts ? ctx.modelRegistry.find(parts.provider, parts.id) : undefined;
+            },
+            apply: handle => pi.setModel(handle)
+        };
+        // The saved default, read from the file the crash left wrong — not from
+        // `ctx.model`, which a `--model` flag or a resumed session can make say
+        // something else entirely.
+        const saved = () => {
+            const ref = defaultModelRef();
+            return ref && `${ref.provider}/${ref.id}`;
+        };
+        void restoreHeldModel(model, saved).catch(() => { });
+    });
+}

package/dist/task/orchestrator.d.ts

@@ -21,9 +21,18 @@ import { type WidgetState } from './widget.js';
 import { type RunTaskFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
 import { type PhaseSeams } from './child-runner.js';
-import { type ThinkingControl } from './implementation-thinking.js';
+import { type ImplementationControls } from './implementation-hold.js';
 import { type RunEnd } from './run-end.js';
 import { type SuperviseOptions } from './implementation-turn.js';
+/**
+ * pi's own `Model`, named WITHOUT importing `@earendil-works/pi-ai` — which is
+ * neither a dependency, a devDependency nor a peerDependency of this package
+ * (see shared/model-endpoint.ts's header). The context already carries the type,
+ * so deriving it costs nothing and adds no edge to the dependency graph.
+ */
+type PiModel = NonNullable<ExtensionCommandContext['model']>;
+/** Both halves of the implementation hold, over the live session. */
+export declare function piImplementationControls(ctx: ExtensionCommandContext): ImplementationControls<PiModel>;
 /**
  * Everything one TaskRunner needs, as one object. The runner is the shared core
  * under `runSingleTask` (and so under /task-auto's per-task loop), so this is the
@@ -163,11 +172,14 @@ export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId'
      */
     notifyFinish?: boolean;
     /**
-     * How the implementation turn's thinking level is read and written. Defaults
-     * to the live pi session; injectable so the hold-and-restore is assertable
-     * with no real session to restore.
+     * How the implementation turn's MODEL and thinking level are read and
+     * written. Defaults to the live pi session; injectable so the
+     * hold-and-restore is assertable with no real session to restore.
+     *
+     * One object rather than two, because the two must be acquired and released
+     * in one order and a caller handed two seams could supply half of one.
      */
-    thinkingControl?: ThinkingControl;
+    implementationControls?: ImplementationControls<never>;
 }
 export interface RunSingleTaskResult {
     taskId: string;
@@ -223,3 +235,4 @@ export declare function runGatedTask(ctx: ExtensionCommandContext, cwd: string,
     deps?: GateDeps;
 }): Promise<void>;
 export declare function registerTask(pi: ExtensionAPI): void;
+export {};

package/dist/task/orchestrator.js

@@ -38,7 +38,8 @@ import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phanto
 import { titleForDisplay } from './parsers.js';
 import { USER_CANCELLED } from './child-runner.js';
 import { cancelCheckpoint } from './cancel-points.js';
-import { holdImplementationThinking } from './implementation-thinking.js';
+import { splitSpec } from '../config/group-models.js';
+import { holdImplementation } from './implementation-hold.js';
 import { rearmCancelListener } from './cancel-input.js';
 import { takeHeldInput } from './mid-run-input.js';
 import { withRun, announceTerminal } from './run-bracket.js';
@@ -74,7 +75,38 @@ function piThinkingControl() {
     const api = piApi;
     if (!api)
         return { get: () => 'off', set: () => { } };
-    return { get: () => api.getThinkingLevel(), set: level => api.setThinkingLevel(level) };
+    return {
+        get: () => api.getThinkingLevel(),
+        set: (level) => api.setThinkingLevel(level)
+    };
+}
+/**
+ * The live session's model, as a {@link ModelControl} over pi's own `Model`.
+ *
+ * `current()` reads `ctx.model`, which is a live GETTER on the extension context
+ * (pi's `core/extensions/runner.js`), so a read after a set is the new value.
+ * `resolve` goes through `find(provider, id)` — EXACT, deliberately stricter
+ * than pi's own CLI, which also substring-matches. We store a canonical
+ * `provider/id`, so exact is the only match that should ever count, and being
+ * stricter here can only cost us a hold we then decline to take.
+ */
+function piModelControl(ctx) {
+    const api = piApi;
+    return {
+        current: () => {
+            const m = ctx.model;
+            return m ? { spec: `${m.provider}/${m.id}`, handle: m } : undefined;
+        },
+        resolve: spec => {
+            const parts = splitSpec(spec);
+            return parts ? ctx.modelRegistry.find(parts.provider, parts.id) : undefined;
+        },
+        apply: async (handle) => (api ? api.setModel(handle) : false)
+    };
+}
+/** Both halves of the implementation hold, over the live session. */
+export function piImplementationControls(ctx) {
+    return { thinking: piThinkingControl(), model: piModelControl(ctx) };
 }
 // ─── TaskRunner class ────────────────────────────────────────────────────────
 /** Encapsulates the full lifecycle of a single pi-task run. */
@@ -487,7 +519,7 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                     // The autofix re-runner (gateRunTask) re-enters runSingleTask
                     // and so re-enters this closure, which is why the hold lives
                     // here rather than at either call site.
-                    const release = holdImplementationThinking(opts.thinkingControl ?? piThinkingControl());
+                    const release = await holdImplementation(opts.implementationControls ?? piImplementationControls(newCtx));
                     try {
                         // Queue-or-run: naming a delivery mode means pi's
                         // "Agent is already processing" throw is unreachable here.
@@ -507,7 +539,7 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                         }
                     }
                     finally {
-                        release();
+                        await release();
                     }
                 },
                 seams: opts.seams,

package/dist/task/phases.js

@@ -38,7 +38,7 @@ import { readContracts, buildContractsBlock, buildContractsVerifyBlock } from '.
 import { readRequirements, buildRequirementsBlock, buildOwnedRequirementsBlock, readOwnedRequirements, writeOwnedRequirements, ownedForTitle, appendOwnedConstraints } from './requirements.js';
 import { detachUnsatisfiableRequirements, claimPendingRequirements, unclaimedPendingRequirements, formatReassignActions } from './owned-freeze-reassign.js';
 import { trackedSourceOracle } from './owned-freeze-conflict.js';
-import { thinkingForChild, runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED, CommandTimeoutError, isFatalChildCause } from './child-runner.js';
+import { groupArgsForChild, runPhaseChild, runWithEmphasisRetry, prependHint, USER_CANCELLED, CommandTimeoutError, isFatalChildCause } from './child-runner.js';
 import { runResearchWorker, researchWorkerCacheHeading } from './research-worker.js';
 import { SessionUI } from '../remote/bridge.js';
 import { isYoloMode, yoloPickAutoAnswer } from './yolo.js';
@@ -654,7 +654,7 @@ export async function phaseResearch(deps, refined) {
         // questions, so one shared `research` cell is the tempting shape —
         // but the four cells do not ship identical, so sharing one would
         // silently change three of them. See config/reasoning.ts.
-        thinkingFor: thinkingForChild,
+        groupArgsFor: groupArgsForChild,
         logDebug: deps.logDebug,
         onChildOutput: deps.onChildOutput,
         record: recordWorker,

package/dist/task/research-worker.d.ts

@@ -24,7 +24,7 @@ import type { DebugLine } from './debug-log.js';
 /**
  * One research worker's row. `section` is the heading its output is assembled
  * and cached under; `label` is its child NAME — what the loader and the debug
- * trail print, and the key into `REASONING_GROUP_BY_CHILD` (config/reasoning.ts).
+ * trail print, and the key into `GROUP_BY_CHILD` (config/groups.ts).
  */
 export interface ResearchWorkerSpec {
     section: string;
@@ -72,7 +72,7 @@ export interface ResearchWorkerRun {
     signal: AbortSignal;
     spawn?: SpawnFn;
     /** The `--thinking` fragment for a named child. */
-    thinkingFor: (label: string) => string[];
+    groupArgsFor: (label: string) => string[];
     logDebug?: (msg: string, kind?: DebugLine) => void;
     onChildOutput?: (line: string) => void;
     /** Record one finished worker's timing splits. */

package/dist/task/research-worker.js

@@ -241,7 +241,7 @@ export async function runResearchWorker(spec, run, prior = []) {
         // config/reasoning.ts is where each one's level lives, so this
         // line decides what THIS worker runs at for a default-mode
         // user.
-        thinking: run.thinkingFor(spec.label),
+        groupArgs: run.groupArgsFor(spec.label),
         ...(spec.tools ? { tools: spec.tools } : {}),
         ...(spec.extensions ? { extensions: spec.extensions } : {}),
         // The three lever spreads that would otherwise sit here are the

package/dist/workers/docs-core.js

@@ -11,7 +11,7 @@ import { runChild } from '../shared/child-process.js';
 import { docsLookup } from './docs-lookup.js';
 import { buildExtractionPrompt } from './abstention.js';
 import {} from '../shared/child-output.js';
-import { groupThinkingArgs } from '../config/reasoning-args.js';
+import { groupChildArgs } from '../config/group-args.js';
 const DEFAULT_LIMIT = PACKAGE_RETRIEVE_LIMIT;
 const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 const NO_CACHE_HEAD = 25_000;
@@ -550,7 +550,7 @@ export async function docsFocused(input) {
         spawn,
         // The `extraction` group's level. Resolved at the call site so neither
         // the lookup nor the extractor reads ambient config.
-        thinking: groupThinkingArgs('extraction')
+        groupArgs: groupChildArgs('extraction')
     });
     const extraction = r.extraction;
     const base = {

package/dist/workers/docs-lookup.d.ts

@@ -36,10 +36,11 @@ export interface DocsLookupInput {
     signal?: AbortSignal;
     spawn?: SpawnFn;
     /**
-     * The `extraction` group's `--thinking` fragment. Resolved by the CALLER so
-     * this module — like the extractor it wraps — never reads ambient config.
+     * The `extraction` group's argv fragment — its model and its thinking level.
+     * Resolved by the CALLER so this module, like the extractor it wraps, never
+     * reads ambient config.
      */
-    thinking: readonly string[];
+    groupArgs: readonly string[];
 }
 export type DocsLookup = {
     kind: 'answer';

package/dist/workers/docs-lookup.js

@@ -28,7 +28,7 @@ export async function docsLookup(input) {
         cwd: input.cwd,
         signal: input.signal,
         spawn: input.spawn,
-        thinking: input.thinking,
+        groupArgs: input.groupArgs,
         abortedMessage: input.corpus.abortedMessage
     });
     if (!extraction.ok)

package/dist/workers/fetch-core.js

@@ -2,7 +2,7 @@ import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { abstentionSentence } from './abstention.js';
 import {} from '../shared/child-output.js';
-import { groupThinkingArgs } from '../config/reasoning-args.js';
+import { groupChildArgs } from '../config/group-args.js';
 const CONTENT_BUDGET = 30_000;
 const HEAD_CHARS = 25_000;
 const TAIL_CHARS = 5_000;
@@ -79,7 +79,7 @@ export async function fetchFocused(input) {
         spawn: input.spawn,
         // The `extraction` group's level. Resolved at the call site so the
         // extractor itself never reads ambient config.
-        thinking: groupThinkingArgs('extraction'),
+        groupArgs: groupChildArgs('extraction'),
         abortedMessage: 'Fetch aborted.'
     });
     const base = {

package/dist/workers/focused-extractor.d.ts

@@ -3,12 +3,13 @@ import { type ExcerptVerification } from '../shared/child-output.js';
 /**
  * The argv every focused extraction child runs with: the shared child base — any whitelisted
  * extensions, then `--print --no-skills --no-extensions --no-prompt-templates
- * --no-context-files --no-session` — then the caller's thinking fragment, then `--no-tools`.
+ * --no-context-files --no-session` — then the caller's group fragment (its model and its
+ * thinking level), then `--no-tools`.
  *
  * `--no-tools` is the contract, not a default: the child is given all the content it may use
  * inside its prompt, so a tool call could only reach for something unsourced.
  */
-export declare const focusedChildArgs: (thinking?: readonly string[]) => string[];
+export declare const focusedChildArgs: (groupArgs?: readonly string[]) => string[];
 export interface FocusedRequest {
     /** The fully assembled prompt, including the content block. Delivered on stdin. */
     prompt: string;
@@ -42,7 +43,7 @@ export interface FocusedRequest {
      * `focusedChildArgs` read ambient config, and a function that reads config
      * internally cannot be tested without the developer's own machine state.
      */
-    thinking?: readonly string[];
+    groupArgs?: readonly string[];
 }
 /** What every outcome carries, success or failure — the raw child evidence. */
 interface FocusedChildEvidence {