@mjasnikovs/pi-task 0.38.31 → 0.39.0

package/dist/task/context-usage.js

@@ -4,6 +4,8 @@
  * the planning and gate children; the single-task widget (TaskRunner) calls it
  * directly, because its state is the whole-run `WidgetState`, not one child's.
  */
+import { getConfig } from '../config/config.js';
+import { MODEL_INHERIT, splitSpec } from '../config/group-models.js';
 /**
  * The parent session's context window, or 0 when the model doesn't expose it.
  *
@@ -19,6 +21,45 @@
 export function getParentContextWindow(ctx) {
     return ctx.model?.contextWindow ?? 0;
 }
+/**
+ * The window for the model ONE GROUP's children will actually run on.
+ *
+ * This number drives the widget and, more importantly, `StallDetector`'s
+ * context-churn rule, and the two error directions are not symmetric. A parent
+ * window LARGER than the child's makes churn fire late — degraded, and the
+ * no-new-ground rule still covers it. A parent window SMALLER makes churn fire
+ * early and KILL A HEALTHY CHILD. A big-context research model under a small
+ * host model is a real false positive, which is why this exists at all.
+ *
+ * For the same reason there is no `min(parent, group)`: that would import the
+ * dangerous direction on purpose.
+ *
+ * `inherit`, an unresolvable spec, or a model with no declared window all return
+ * exactly `getParentContextWindow(ctx)` — byte-identical to the behaviour before
+ * per-group models existed.
+ *
+ * Callers WITHOUT a ctx read `groupWindow` from config/group-args.ts instead,
+ * which the session pass fills from this. One producer, so the two views cannot
+ * describe different models.
+ */
+export function contextWindowForGroup(ctx, group, cfg = getConfig()) {
+    return contextWindowForSpec(ctx, cfg.groupModels[group]);
+}
+/**
+ * The same answer for a spec the caller already has.
+ *
+ * The session pass needs this: it walks an INJECTED spec table, and reaching for
+ * `getConfig()` here would let the window it stores describe a different model
+ * from the one it just checked.
+ */
+export function contextWindowForSpec(ctx, spec) {
+    if (spec === MODEL_INHERIT)
+        return getParentContextWindow(ctx);
+    const parts = splitSpec(spec);
+    const found = parts && ctx.modelRegistry?.find(parts.provider, parts.id);
+    const window = found?.contextWindow ?? 0;
+    return window > 0 ? window : getParentContextWindow(ctx);
+}
 /**
  * Fold a raw context snapshot into a display snapshot: prefer the child's own
  * contextWindow, else the last known one, else the parent session's; then derive

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

@@ -75,15 +75,26 @@ export interface GateChildDeps {
     /** 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.
+     * The resolved argv fragment for the `gate` group — its model and its
+     * thinking level — or `[]` to inherit both.
      *
      * 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
+     * gate wiring silently run on a model nobody chose, which is the failure the
      * whole profile feature exists to end.
      */
-    thinking: readonly string[];
+    groupArgs: readonly string[];
+    /**
+     * The context window of the model THESE children run on, for the churn rule.
+     *
+     * Not `status.parentContextWindow`, which is a per-RUN value and a run spans
+     * several groups. The direction matters: a window smaller than the child's
+     * real one makes churn fire early and kill a healthy child, so this follows
+     * the `gate` group's model and falls back to the host's.
+     *
+     * REQUIRED, like its neighbours: gate-child takes resolved config values.
+     */
+    contextWindow: number;
     /**
      * 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

@@ -98,7 +98,7 @@ export function makeGateChild(deps) {
                         commandTimeoutMs: deps.commandTimeoutMs,
                         streamInactivityMs: deps.streamInactivityMs
                     },
-                    thinking: deps.thinking,
+                    groupArgs: deps.groupArgs,
                     // A discarded attempt is otherwise invisible: the returned
                     // exitCode/text describe the FINAL attempt, so a child that
                     // burned two attempts reads exactly like one that ran clean.
@@ -125,7 +125,7 @@ export function makeGateChild(deps) {
                     // stream — what `--mode json` emits — carries token counts but
                     // no context window; `contextWindow` appears nowhere in
                     // agent-session.d.ts.
-                    contextWindow: deps.status.parentContextWindow
+                    contextWindow: deps.contextWindow
                 });
             }
             finally {

package/dist/task/gate-deps.js

@@ -48,7 +48,8 @@ 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 { groupChildArgs } from '../config/group-args.js';
+import { contextWindowForGroup } from './context-usage.js';
 import { makeDebugAppender } from './debug-log.js';
 import { startAutoLoader } from './widget.js';
 import { ChildStatus } from './child-status.js';
@@ -602,7 +603,11 @@ export function buildGateDeps(params) {
         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'),
+        groupArgs: groupChildArgs('gate'),
+        // `gateCtx` rather than the run's own window: a run spans several
+        // groups, and a window smaller than the child's real one makes the
+        // churn rule fire early and kill a healthy child.
+        contextWindow: contextWindowForGroup(gateCtx, 'gate'),
         status,
         runWorker,
         makeDebugAppender,

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,