@mjasnikovs/pi-task 0.38.18 → 0.38.20

package/dist/config/register.js

@@ -5,6 +5,7 @@ import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../w
 import { COMMAND_TIMEOUT_OPTIONS, DEBUG_LOG_OPTIONS, getConfig, sanitizeDebugLogs, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 import { listGuardableTools } from './tool-list.js';
+import { REASONING_GROUPS, REASONING_MODES, sanitizeReasoningMode, REASONING_GROUP_HELP, REASONING_SETTINGS, resolveReasoning } from './reasoning.js';
 // Version in the title so a bug report or screenshot says which build it came
 // from without anyone having to go look it up.
 const CONFIG_TITLE = `pi-task ${readPkgVersion()} settings`;
@@ -67,14 +68,37 @@ class BorderedBox {
         this.child.handleInput(data);
     }
 }
+/** Section order, and the label each header renders. */
+export const SECTIONS = [
+    { key: 'session', title: 'session' },
+    { key: 'checks', title: 'after each task' },
+    { key: 'research', title: 'research' },
+    { key: 'reasoning', title: 'reasoning' },
+    { key: 'timeouts', title: 'timeouts' },
+    { key: 'unattended', title: 'unattended' },
+    { key: 'logging', title: 'logging' },
+    { key: 'extensions', title: 'child extensions' }
+];
+/** Marks a header row, so onChange can ignore one and tests can find them. */
+export const SECTION_ID_PREFIX = 'section:';
+/** An inert titled row. No `values` ⇒ SettingsList's Enter handler no-ops on it. */
+function sectionHeader(title) {
+    return {
+        id: SECTION_ID_PREFIX + title,
+        label: `── ${title} ──`,
+        description: '',
+        currentValue: ''
+    };
+}
 /**
  * The shared pair for a boolean setting: shown as on/off, stored as a boolean.
  * Every non-enum row uses this, so a boolean cannot be given a bespoke parser by
  * accident.
  */
-function booleanItem(id, label, description) {
+function booleanItem(section, id, label, description) {
     return {
         id,
+        section,
         label,
         description,
         format: cfg => (cfg[id] ? 'on' : 'off'),
@@ -92,27 +116,28 @@ function booleanItem(id, label, description) {
  * either of the two ladders this replaced.
  */
 export const ITEMS = [
-    booleanItem('remote', 'remote control', 'Serve the task UI on your local network so you can follow and steer a run from '
+    booleanItem('session', 'remote', 'remote control', 'Serve the task UI on your local network so you can follow and steer a run from '
         + 'your phone. Prints a QR code to scan when it starts'),
-    booleanItem('autoCommit', 'auto-commit', 'Make a git commit before and after every sub-task, so each step is a checkpoint '
+    booleanItem('checks', 'autoCommit', 'auto-commit', 'Make a git commit before and after every sub-task, so each step is a checkpoint '
         + 'you can read back or roll back to'),
-    booleanItem('verifyWork', 'verify work', 'When a task says it is done, actually run the checks its spec asks for and report '
+    booleanItem('checks', 'verifyWork', 'verify work', 'When a task says it is done, actually run the checks its spec asks for and report '
         + "PASS or FAIL instead of taking the model's word for it. This is also what lets "
         + '"enforce guidelines" fix things safely. /task waits for the work to finish'),
-    booleanItem('enforceGuidelines', 'enforce guidelines', 'Check what each task committed against your AGENTS.md / CLAUDE.md rules. With '
+    booleanItem('checks', 'enforceGuidelines', 'enforce guidelines', 'Check what each task committed against your AGENTS.md / CLAUDE.md rules. With '
         + '"verify work" on it also fixes what it finds, undoing any fix that breaks the '
         + 'checks; on its own it only reports. /task waits for the work to finish'),
-    booleanItem('orientation', 'project tour', 'Show the research workers the shape of the project first — package manifest, '
+    booleanItem('research', 'orientation', 'project tour', 'Show the research workers the shape of the project first — package manifest, '
         + 'types, schema — so they spend their steps on the question instead of on finding '
         + 'their way around'),
-    booleanItem('parallelResearchWorkers', 'parallel research', 'Run the 4 research workers at once instead of one after another. Only faster if '
+    booleanItem('research', 'parallelResearchWorkers', 'parallel research', 'Run the 4 research workers at once instead of one after another. Only faster if '
         + 'your model backend can answer several requests at the same time — on a single '
         + 'local GPU it is measurably slower, so leave it off there'),
-    booleanItem('researchCache', 'research cache', 'Remember docs and web pages for the length of one run, so later tasks reuse what '
+    booleanItem('research', 'researchCache', 'research cache', 'Remember docs and web pages for the length of one run, so later tasks reuse what '
         + 'the first one already fetched instead of downloading it again. Only external '
         + 'sources, only successful fetches, and it is dropped when the run ends'),
     {
         id: 'searchProvider',
+        section: 'research',
         label: 'search engine',
         description: 'Which engine backs web search. Exa and DuckDuckGo work with no setup; Brave needs '
             + 'a BRAVE_SEARCH_API_KEY in your environment',
@@ -127,6 +152,7 @@ export const ITEMS = [
     },
     {
         id: 'requestTimeoutMs',
+        section: 'timeouts',
         label: 'command timeout',
         description: 'Give up on any single command that runs this long, and tell the model to set its '
             + 'own timeout next time. Stops a run from waiting forever on a dev server or a '
@@ -144,6 +170,7 @@ export const ITEMS = [
     },
     {
         id: 'streamInactivityMs',
+        section: 'timeouts',
         label: 'stuck reply retry',
         description: 'Give up on a model reply that has sent nothing for this long and ask again. A '
             + 'dropped connection looks exactly like a model thinking hard and reports no '
@@ -160,12 +187,30 @@ export const ITEMS = [
                 cfg.streamInactivityMs = opt.ms;
         }
     },
-    booleanItem('yoloMode', 'yolo mode', 'Stop asking you anything: every question takes the option pi recommends, a failed '
+    booleanItem('unattended', 'yoloMode', 'yolo mode', 'Stop asking you anything: every question takes the option pi recommends, a failed '
         + 'check is accepted and written down as debt, and a failed final check is retried '
         + 'until the budget runs out. Each auto-answer is marked (YOLO) in the task file. '
         + 'For throwaway projects you are not watching'),
+    {
+        id: 'reasoningMode',
+        section: 'reasoning',
+        label: 'reasoning',
+        description: 'How much the helper sessions think before answering. "default" uses the '
+            + 'per-step table pi-task has measured, "on" and "off" force one answer '
+            + 'everywhere, and "custom" is whatever you set in the "think:" rows below. '
+            + 'Those rows always show what each step actually runs at, and changing one '
+            + 'switches this to custom. A step left on "inherit" uses whatever thinking '
+            + 'level pi itself is set to, which is what every step did before this setting '
+            + 'existed',
+        values: [...REASONING_MODES],
+        format: cfg => String(cfg.reasoningMode),
+        apply: (cfg, chosen) => {
+            cfg.reasoningMode = sanitizeReasoningMode(chosen);
+        }
+    },
     {
         id: 'debugLogs',
+        section: 'logging',
         label: 'debug logs',
         description: 'How much of a run gets written to .pi-tasks/*-debug.log. "events" keeps the '
             + 'decisions and the guard actions — what a checking step changed, why something '
@@ -233,6 +278,70 @@ export function applyToolToggle(exempt, toolName, watched) {
     const rest = exempt.filter(n => n !== toolName);
     return watched ? rest : [...rest, toolName];
 }
+/**
+ * One /task-config row per reasoning group, so a group's thinking level can be
+ * set without hand-editing config.json.
+ *
+ * SHOWN IN EVERY MODE, not only `custom`. Two reasons, and the second is the
+ * real one:
+ *  - `SettingsList` fixes the overlay's body height from the descriptions it was
+ *    constructed with (see createSettingsPanel), so rows that appear and vanish
+ *    would leave the box sized for the wrong list.
+ *  - The value displayed is what the group ACTUALLY runs at — resolveReasoning,
+ *    not the stored custom table. That makes the measured `default` table
+ *    readable from the menu instead of hidden in a source file, which is the
+ *    whole point of having measured it.
+ */
+const REASON_ID_PREFIX = 'reason:';
+export function reasoningItems(cfg) {
+    return REASONING_GROUPS.map(group => ({
+        id: REASON_ID_PREFIX + group,
+        label: `think: ${group}`,
+        description: REASONING_GROUP_HELP[group],
+        // The EFFECTIVE level, not cfg.reasoningLevels[group]: in default/on/off
+        // the stored table is not what runs, and a row that shows a value the
+        // run does not use is worse than no row.
+        currentValue: resolveReasoning(group, cfg),
+        values: [...REASONING_SETTINGS]
+    }));
+}
+/**
+ * Apply one group row's new value.
+ *
+ * Setting any group necessarily means "custom" — there is nowhere else to store
+ * a per-group choice. The seeding step is what stops that from being a trap: on
+ * the way out of `default`/`on`/`off` every OTHER group is first pinned to the
+ * level it was already running at, so changing one row changes one row. Without
+ * it, nudging `research` while in `off` would silently return the other six to
+ * whatever the stored table happened to hold.
+ */
+/**
+ * Write every `think:` row's displayed value back from the config.
+ *
+ * Called after ANY change, not just a reasoning one, because the mode row and
+ * the seven group rows are one control split across eight lines: cycling
+ * `reasoning` to `off` changes what all seven of them run at, and cycling one
+ * group row flips the mode, which changes the other six. A row showing a level
+ * the run will not use is worse than no row.
+ */
+export function refreshReasoningRows(cfg, list) {
+    for (const group of REASONING_GROUPS) {
+        list.updateValue(REASON_ID_PREFIX + group, resolveReasoning(group, cfg));
+    }
+    list.updateValue('reasoningMode', cfg.reasoningMode);
+}
+export function applyReasoningLevel(cfg, group, chosen) {
+    if (!REASONING_SETTINGS.includes(chosen))
+        return;
+    if (cfg.reasoningMode !== 'custom') {
+        const seeded = {};
+        for (const g of REASONING_GROUPS)
+            seeded[g] = resolveReasoning(g, cfg);
+        cfg.reasoningLevels = seeded;
+        cfg.reasoningMode = 'custom';
+    }
+    cfg.reasoningLevels = { ...cfg.reasoningLevels, [group]: chosen };
+}
 /** Overlay width; the list gets `- 4` of it, the description `- 4` again. */
 const OVERLAY_WIDTH = 68;
 /** Settings rows shown at once before the list scrolls. */
@@ -272,29 +381,59 @@ function makeTheme(theme) {
  * exact component the overlay shows can be rendered to a string in a test or a
  * preview script, rather than only being inspectable by opening the TUI.
  */
-export function createSettingsPanel(items, theme, onChange, onCancel) {
-    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme), onChange, onCancel);
+export function createSettingsPanel(items, theme, 
+/**
+ * Called with the row's id, its new value, and the LIST ITSELF.
+ *
+ * The list is handed back because some rows change what OTHER rows display:
+ * flipping `reasoning` to off means all seven `think:` rows now run at off,
+ * and a row's `currentValue` is a snapshot taken when the panel was built.
+ * Without a way to write the others back, the menu shows `reasoning off`
+ * beside seven rows still claiming `inherit` — which is what it did.
+ */
+onChange, onCancel) {
+    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme), (id, newValue) => onChange(id, newValue, list), onCancel);
     return new BorderedBox(list, CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)), settingsBodyHeight(items.map(i => i.description), MAX_VISIBLE, OVERLAY_WIDTH - 8));
 }
 /** The full settings row list for the current config, in menu order. */
 export function panelItems(cfg, installed, tools = []) {
-    return [
-        ...ITEMS.map(({ id, label, description, values, format }) => ({
-            id: id,
-            label,
-            description,
-            currentValue: format(cfg),
-            values: values ?? ['on', 'off']
-        })),
-        ...toolItems(tools, cfg.commandTimeoutExemptTools),
-        ...extensionItems(installed, cfg.extensionWhitelist)
-    ];
+    // The discovered rows belong to a section too — the per-tool watchdog
+    // exemptions under `timeouts` (they are exemptions FROM that timeout), and
+    // the per-extension toggles under their own heading.
+    const extra = {
+        reasoning: reasoningItems(cfg),
+        timeouts: toolItems(tools, cfg.commandTimeoutExemptTools),
+        extensions: extensionItems(installed, cfg.extensionWhitelist)
+    };
+    const out = [];
+    for (const { key, title } of SECTIONS) {
+        const rows = [
+            ...ITEMS.filter(i => i.section === key).map(({ id, label, description, values, format }) => ({
+                id: id,
+                label,
+                description,
+                currentValue: format(cfg),
+                values: values ?? ['on', 'off']
+            })),
+            ...(extra[key] ?? [])
+        ];
+        // An empty section prints no header. `extensions` has no fixed rows at
+        // all, so with nothing installed the heading would otherwise sit alone.
+        if (rows.length === 0)
+            continue;
+        out.push(sectionHeader(title), ...rows);
+    }
+    return out;
 }
 async function handleTaskConfig(_args, ctx, getTools = () => []) {
     const cfg = {
         ...getConfig(),
         extensionWhitelist: [...getConfig().extensionWhitelist],
-        commandTimeoutExemptTools: [...getConfig().commandTimeoutExemptTools]
+        commandTimeoutExemptTools: [...getConfig().commandTimeoutExemptTools],
+        // Copied for the same reason as the two arrays above: the panel mutates
+        // its own draft, and sharing the live object would apply half-made
+        // choices to running children before the user finished choosing.
+        reasoningLevels: { ...getConfig().reasoningLevels }
     };
     // Enumerated live at open so an installed extension appears and an
     // uninstalled one vanishes without pi-task doing any bookkeeping. A failed
@@ -307,22 +446,26 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
     if (ctx.mode !== 'tui') {
         // Reads the SAME `format` the panel does, so the two renderings cannot
         // disagree about what a setting currently says.
-        const lines = ITEMS.map(({ label, format }) => `${label.padEnd(22)} ${format(cfg)}`);
-        for (const t of tools) {
-            const state = cfg.commandTimeoutExemptTools.includes(t.name) ? 'off' : 'on';
-            lines.push(`${('watch: ' + t.name).padEnd(22)} ${state}`);
-        }
-        for (const e of installed) {
-            const state = cfg.extensionWhitelist.includes(e.path) ? 'on' : 'off';
-            lines.push(`${('ext: ' + e.label).padEnd(22)} ${state}`);
-        }
+        // Built from panelItems, not a second hand-written walk of the same
+        // tables: the two renderings used to be able to disagree about what a
+        // setting said, and a headless run is the one place nobody would notice.
+        const lines = panelItems(cfg, installed, tools).map(i => i.values === undefined ?
+            `[${i.label.replace(/─/g, '').trim()}]`
+            : `${i.label.padEnd(22)} ${i.currentValue}`);
         ctx.ui.notify(lines.join('  |  '), 'info');
         return;
     }
-    await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(panelItems(cfg, installed, tools), theme, (id, newValue) => {
+    await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(panelItems(cfg, installed, tools), theme, (id, newValue, list) => {
+        // Header rows carry no `values`, so SettingsList never
+        // cycles them and this can only be a real setting.
+        if (id.startsWith(SECTION_ID_PREFIX))
+            return;
         if (id.startsWith(EXT_ID_PREFIX)) {
             cfg.extensionWhitelist = applyExtensionToggle(cfg.extensionWhitelist, id.slice(EXT_ID_PREFIX.length), newValue === 'on');
         }
+        else if (id.startsWith(REASON_ID_PREFIX)) {
+            applyReasoningLevel(cfg, id.slice(REASON_ID_PREFIX.length), newValue);
+        }
         else if (id.startsWith(TOOL_ID_PREFIX)) {
             cfg.commandTimeoutExemptTools = applyToolToggle(cfg.commandTimeoutExemptTools, id.slice(TOOL_ID_PREFIX.length), newValue === 'on');
         }
@@ -334,6 +477,12 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
             // until someone noticed.
             ITEMS.find(item => item.id === id)?.apply(cfg, newValue);
         }
+        // The reasoning rows describe each other, so they are
+        // re-read from the config after every change — including
+        // changes to unrelated rows, which costs nothing and means
+        // there is no list of "changes that need a refresh" to keep
+        // correct.
+        refreshReasoningRows(cfg, list);
         saveConfig(cfg).catch(() => { });
     }, () => done(undefined)), { overlay: true, overlayOptions: { width: OVERLAY_WIDTH } });
 }

package/dist/shared/child-process.d.ts

@@ -115,6 +115,25 @@ export interface RunChildJsonEventsOptions {
     mode: 'json-events';
     onLine?: (line: string) => void;
     onContextUsage?: (snapshot: ContextSnapshot) => void;
+    /**
+     * The child's context window in tokens, supplied BY THE CALLER — pi's event
+     * stream does not carry one (GitHub issue #16).
+     *
+     * Verified against the published tarballs of @earendil-works/pi-coding-agent
+     * and @earendil-works/pi-agent-core at 0.80.2 and 0.84.2, and against pi's
+     * own docs/json.md: the wire union is session / agent_* / turn_* / message_*
+     * / tool_execution_* / queue_update / compaction_* / auto_retry_*, the
+     * session header is {type,version,id,timestamp,cwd,parentSession}, and no
+     * member of either carries a window or even a model id. `contextUsage`
+     * exists ONLY as the in-process `ctx.getContextUsage()` extension API, which
+     * a `--mode json` child never speaks back to its parent.
+     *
+     * The parent therefore has to say. Children are spawned without `-m`
+     * (CHILD_BASE_ARGS), so they resolve the same default model the parent runs
+     * and the parent session's window is the honest answer. 0 / omitted keeps
+     * the old behaviour: report the token count with no window.
+     */
+    contextWindow?: number;
     onToolCall?: (call: ToolCall) => LoopHit | null;
     /**
      * Fires when a tool call finishes, carrying its RESULT (mx5 run 10 item 6: the

package/dist/shared/child-process.js

@@ -88,15 +88,12 @@ export class JsonEventSink {
     handleEvent(evt) {
         const opts = this.opts;
         const t = typeof evt.type === 'string' ? evt.type : '';
-        if (t === 'context_usage' && opts.onContextUsage) {
-            const tokens = Number(evt.tokens ?? 0);
-            const contextWindow = Number(evt.contextWindow ?? 0);
-            const percent = Number(evt.percent ?? 0);
-            if (tokens > 0 || contextWindow > 0) {
-                opts.onContextUsage({ tokens, contextWindow, percent });
-            }
-            return;
-        }
+        // `message_end` is the ONLY context readout pi gives a `--mode json`
+        // child's parent. There used to be a `context_usage` branch above this
+        // one that was preferred over it; no released pi has ever emitted such
+        // an event (see `contextWindow` on RunChildJsonEventsOptions), so it was
+        // unreachable, and its presence is what made the zero window below look
+        // like a harmless fallback rather than the only path. Issue #16.
         if (t === 'message_end' && opts.onContextUsage) {
             const msg = evt.message;
             if (msg?.role === 'assistant') {
@@ -107,7 +104,9 @@ export class JsonEventSink {
                         + Number(usage.cacheWrite ?? 0)
                         + Number(usage.output ?? 0);
                     if (tokens > 0) {
-                        opts.onContextUsage({ tokens, contextWindow: 0, percent: 0 });
+                        const cw = Math.max(0, Number(opts.contextWindow ?? 0));
+                        const percent = cw > 0 ? Math.min(100, (tokens / cw) * 100) : 0;
+                        opts.onContextUsage({ tokens, contextWindow: cw, percent });
                     }
                 }
             }

package/dist/shared/model-endpoint.d.ts

@@ -6,3 +6,37 @@ export declare function discoverModelEndpoints(agentDir?: string): string[];
  * timeout. An empty list is true: nothing to probe means never kill.
  */
 export declare function probeModelEndpoints(urls: string[], timeoutMs?: number): Promise<boolean>;
+/**
+ * What a llama.cpp server's own chat template can actually do about reasoning,
+ * as reported by `GET /props`.
+ *
+ * This is the only source of truth that does NOT come from models.json. It
+ * answers the one question the host-side clamp cannot: *is models.json lying
+ * about the server?* — the case that matters being pi's built-in llama.cpp
+ * provider, which hardcodes `reasoning: false`, so anyone who reached their
+ * server through `/login llama.cpp` rather than a hand-written provider entry
+ * has a dead knob and nothing to tell them so.
+ */
+export interface ChatTemplateCaps {
+    /** The template reads `reasoning_effort` — i.e. levels, not just on/off. */
+    supportsReasoningEffort: boolean;
+    /** The template reads `preserve_thinking` / `preserve_reasoning`. */
+    supportsPreserveReasoning: boolean;
+    /** The template mentions `enable_thinking` at all — i.e. thinking can be switched. */
+    mentionsEnableThinking: boolean;
+}
+/**
+ * Probe one base URL for its chat-template capabilities, or `null` for "no
+ * answer worth having" — not a llama.cpp server, unreachable, or a body in a
+ * shape this does not recognise.
+ *
+ * `null` is a first-class result, not an error: every non-llama.cpp backend
+ * returns it, and the caller must degrade to the models.json view rather than
+ * warn about a server it could not read. Never throws.
+ *
+ * The LEADING SLASH in `/props` is load-bearing. A configured baseUrl normally
+ * ends in `/v1` (llama-server's OpenAI-compatible prefix) while `/props` lives at
+ * the server root, so a relative `'props'` would resolve to `/v1/props` and 404 —
+ * which this would report as `null`, i.e. as a silent loss of the better signal.
+ */
+export declare function probeChatTemplateCaps(baseUrl: string, timeoutMs?: number): Promise<ChatTemplateCaps | null>;

package/dist/shared/model-endpoint.js

@@ -54,3 +54,39 @@ export async function probeModelEndpoints(urls, timeoutMs = 5_000) {
     }));
     return results.some(Boolean);
 }
+/**
+ * Probe one base URL for its chat-template capabilities, or `null` for "no
+ * answer worth having" — not a llama.cpp server, unreachable, or a body in a
+ * shape this does not recognise.
+ *
+ * `null` is a first-class result, not an error: every non-llama.cpp backend
+ * returns it, and the caller must degrade to the models.json view rather than
+ * warn about a server it could not read. Never throws.
+ *
+ * The LEADING SLASH in `/props` is load-bearing. A configured baseUrl normally
+ * ends in `/v1` (llama-server's OpenAI-compatible prefix) while `/props` lives at
+ * the server root, so a relative `'props'` would resolve to `/v1/props` and 404 —
+ * which this would report as `null`, i.e. as a silent loss of the better signal.
+ */
+export async function probeChatTemplateCaps(baseUrl, timeoutMs = 2_000) {
+    try {
+        const res = await fetch(new URL('/props', baseUrl), {
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        const caps = body.chat_template_caps;
+        if (typeof caps !== 'object' || caps === null)
+            return null;
+        const template = typeof body.chat_template === 'string' ? body.chat_template : '';
+        return {
+            supportsReasoningEffort: caps.supports_reasoning_effort === true,
+            supportsPreserveReasoning: caps.supports_preserve_reasoning === true,
+            mentionsEnableThinking: template.includes('enable_thinking')
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/shared/reasoning-capability.d.ts

@@ -0,0 +1,86 @@
+/**
+ * What pi will ACTUALLY send, given a model and a requested thinking level.
+ *
+ * WHY A LOCAL COPY OF PI'S CLAMP
+ * ------------------------------
+ * pi never reports that it ignored or downgraded a level. Measured live against
+ * this machine's llama-server, with a proxy capturing the request body:
+ *
+ *   1. a model with `reasoning: false` + `--thinking medium`
+ *        → the body carries NO reasoning field at all. No error, no warning.
+ *   2. `thinkingLevelMap: {off: null, ...}` + `--thinking off`
+ *        → silently clamped UP to `medium`. Thinking stays on.
+ *   3. `--thinking low` where `low: null`
+ *        → silently clamped to `medium`.
+ *
+ * All three are the same arithmetic, and it is pure: `getSupportedThinkingLevels`
+ * / `clampThinkingLevel` in @earendil-works/pi-ai's models module. Reproducing it
+ * lets one predicate — `clampToModel(m, wanted) !== wanted` — catch all three
+ * host-side, before a single request is sent.
+ *
+ * Reimplemented rather than imported because `@earendil-works/pi-ai` is neither a
+ * dependency nor a peerDependency of pi-task: it is present only because
+ * pi-coding-agent hoists it, so importing it would take a hard dependency on a
+ * transitive package to get twenty lines of arithmetic. SOURCE OF TRUTH is that
+ * module; `reasoning-capability.test.ts` is where a change upstream shows up.
+ */
+import type { ReasoningGroup, GroupSetting } from '../config/reasoning.js';
+/**
+ * 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 declare const THINKING_LADDER: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type LadderLevel = (typeof THINKING_LADDER)[number];
+/**
+ * The two fields of pi's `Model` that decide reasoning behaviour. Named
+ * separately so the pure functions below can be tested with object literals
+ * instead of a whole model registry.
+ */
+export interface ReasoningModelFacts {
+    reasoning: boolean;
+    thinkingLevelMap?: Partial<Record<string, string | null>>;
+}
+/**
+ * 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 declare function supportedThinkingLevels(model: ReasoningModelFacts): LadderLevel[];
+/**
+ * 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 declare function clampToModel(model: ReasoningModelFacts, level: LadderLevel): LadderLevel;
+/** One group whose configured setting the connected model will not honour. */
+export interface ReasoningMismatch {
+    group: ReasoningGroup;
+    /** What /task-config says. Never `inherit` — an inherited group asks for nothing. */
+    wanted: LadderLevel;
+    /** What pi will send instead. */
+    actual: LadderLevel;
+}
+/**
+ * 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 declare function reasoningMismatches(model: ReasoningModelFacts | undefined, settings: ReadonlyArray<{
+    group: ReasoningGroup;
+    setting: GroupSetting;
+}>): ReasoningMismatch[];

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;
+}