@code-yeongyu/senpi 2026.11.2-3 → 2026.11.3-1

package/dist/core/extensions/builtin/todotools/normalize.js

@@ -1,3 +1,4 @@
+import { DEFAULT_INIT_PHASE } from "./todo-types.js";
 const CONFLICTING_SHAPES = 'conflicting shapes. Use {"op":"init","list":[...]} to replace the list or {"op":"append","phase":"<active phase>","items":[...]} to add tasks.';
 function isRecord(value) {
     return typeof value === "object" && value !== null;
@@ -66,12 +67,257 @@ function unwrapTodoList(value) {
     }
     return Array.isArray(current) && current.length > 0 ? current : value;
 }
-/** The todo tool's `prepareArguments`: returns the arguments with `list` unwrapped to its canonical shape. */
-export function prepareTodoArguments(args) {
-    if (!isRecord(args) || Array.isArray(args) || !("list" in args))
+/**
+ * Reserved string key under which `prepareTodoArguments` carries its correction notices to
+ * `execute`. `validateToolArguments` clones prepared arguments with `structuredClone`, which
+ * drops symbol keys, so the channel must be a string key; `execute` strips it before
+ * `normalizeTodoParams` and prepends the notices. The key is never persisted or rendered,
+ * but prepared arguments flow to the agent loop's `beforeToolCall`/`afterToolCall` hooks, so
+ * extension `tool_call`/`tool_result` hooks may observe it on the arguments they receive.
+ */
+const TODO_PREPARED_CORRECTIONS_KEY = "__todoPreparedCorrections";
+function isPhaseRecord(value) {
+    return isRecord(value) && typeof value.phase === "string" && Array.isArray(value.items);
+}
+function isContentRecord(value) {
+    return isRecord(value) && typeof value.content === "string";
+}
+function quoted(values) {
+    return values.map((value) => JSON.stringify(value)).join(", ");
+}
+/**
+ * Rewrites near-canonical `list` entries (senpi#5332) to the canonical shape: an entry whose
+ * `items` are all nested `{phase, items}` records is replaced by them, `items` entries that
+ * are records carrying a string `content` become that string, entries with missing or empty
+ * `items` and stray string entries are dropped, and entries with tasks but no usable `phase`
+ * name get sequential default names. An `items` array that mixes strings with phase records
+ * is ambiguous and returns `null`, as does nothing else here: the caller then leaves the
+ * whole call untouched so validation rejects it as before. The input array and its entries
+ * are never mutated; when nothing changes, the same array reference is returned.
+ */
+function normalizeTodoListEntries(input, notices) {
+    let list = [...input];
+    let changed = false;
+    const promotedOuter = [];
+    for (let depth = 0; depth < 5; depth++) {
+        const next = [];
+        let promotedThisPass = false;
+        for (const entry of list) {
+            if (isPhaseRecord(entry) && entry.items.length > 0 && entry.items.every(isPhaseRecord)) {
+                next.push(...entry.items);
+                promotedOuter.push(entry.phase);
+                promotedThisPass = true;
+            }
+            else {
+                next.push(entry);
+            }
+        }
+        if (!promotedThisPass)
+            break;
+        list = next;
+    }
+    if (promotedOuter.length > 0) {
+        changed = true;
+        notices.push(`[auto-corrected] "list" ${promotedOuter.length === 1 ? "entry" : "entries"} ${quoted(promotedOuter)} contained only nested phases; promoted the nested phases to top level. Each "list" entry is exactly one phase: {"phase":"<name>","items":["<task>", ...]}`);
+    }
+    let unwrappedContent = 0;
+    for (let index = 0; index < list.length; index++) {
+        const entry = list[index];
+        if (!isPhaseRecord(entry))
+            continue;
+        const mapped = entry.items.map((item) => {
+            if (isContentRecord(item) && !isPhaseRecord(item)) {
+                unwrappedContent += 1;
+                return item.content;
+            }
+            return item;
+        });
+        // Strings and nested phase records in one items array cannot be told apart, so no
+        // correction may guess: leave the whole call to validation.
+        if (mapped.some((item) => typeof item === "string") && mapped.some(isPhaseRecord))
+            return null;
+        if (!mapped.every((item) => typeof item === "string"))
+            continue;
+        if (mapped.some((item, position) => item !== entry.items[position])) {
+            list[index] = { ...entry, items: mapped };
+            changed = true;
+        }
+    }
+    if (unwrappedContent > 0) {
+        notices.push(`[auto-corrected] unwrapped ${unwrappedContent} "items" ${unwrappedContent === 1 ? "entry" : "entries"} carrying a "content" field into their task strings. "items" holds only task strings.`);
+    }
+    const withoutEmptyPhases = list.filter((entry) => {
+        if (!isRecord(entry))
+            return true;
+        if (typeof entry.phase !== "string" && !("items" in entry))
+            return true;
+        return entry.items !== undefined && (!Array.isArray(entry.items) || entry.items.length > 0);
+    });
+    if (withoutEmptyPhases.length !== list.length) {
+        changed = true;
+        const dropped = list.length - withoutEmptyPhases.length;
+        notices.push(`[auto-corrected] dropped ${dropped} "list" ${dropped === 1 ? "entry" : "entries"} with no tasks. Every phase needs at least one task in "items".`);
+        list = withoutEmptyPhases;
+    }
+    const hasObjectEntries = list.some((entry) => isRecord(entry));
+    const strayStrings = list.filter((entry) => typeof entry === "string");
+    if (strayStrings.length > 0 && hasObjectEntries) {
+        changed = true;
+        notices.push(`[auto-corrected] dropped ${strayStrings.length} stray ${strayStrings.length === 1 ? "entry" : "entries"} from "list". "list" holds only phase objects: {"phase":"<name>","items":["<task>", ...]}`);
+        list = list.filter((entry) => typeof entry !== "string");
+    }
+    const usedNames = new Set();
+    for (const entry of list) {
+        if (isRecord(entry) && typeof entry.phase === "string" && entry.phase.trim() !== "")
+            usedNames.add(entry.phase);
+    }
+    const generatedNames = [];
+    for (let index = 0; index < list.length; index++) {
+        const entry = list[index];
+        if (!isRecord(entry) ||
+            !Array.isArray(entry.items) ||
+            entry.items.length === 0 ||
+            !entry.items.every((item) => typeof item === "string") ||
+            (typeof entry.phase === "string" && entry.phase.trim() !== "")) {
+            continue;
+        }
+        let counter = 1;
+        let name = DEFAULT_INIT_PHASE;
+        while (usedNames.has(name)) {
+            counter += 1;
+            name = `${DEFAULT_INIT_PHASE} ${counter}`;
+        }
+        usedNames.add(name);
+        generatedNames.push(name);
+        const { phase: _replaced, ...rest } = entry;
+        list[index] = { phase: name, ...rest };
+        changed = true;
+    }
+    if (generatedNames.length > 0) {
+        notices.push(`[auto-corrected] named ${generatedNames.length} "list" ${generatedNames.length === 1 ? "entry" : "entries"} without a phase name: ${quoted(generatedNames)}. Pass "phase" explicitly: {"phase":"<name>","items":["<task>", ...]}`);
+    }
+    return changed ? list : input;
+}
+/**
+ * The todo tool's `prepareArguments`: rewrites near-canonical shapes (senpi#5148 wrappers,
+ * senpi#5332 list/op corrections) to the canonical one before schema validation. Any call a
+ * rule does not correct is returned as the SAME reference, and a correction that would leave
+ * `list` empty is abandoned entirely so the malformed call still fails validation instead of
+ * clearing the todo list. A caller-sent `TODO_PREPARED_CORRECTIONS_KEY` is never trusted
+ * (senpi#5332): it is dropped on a copy before any rule runs, and when that removal is the
+ * only change the stripped copy is returned instead of the same reference.
+ */
+export function prepareTodoArguments(input) {
+    if (!isRecord(input) || Array.isArray(input))
+        return input;
+    const { [TODO_PREPARED_CORRECTIONS_KEY]: _callerSent, ...stripped } = input;
+    const args = TODO_PREPARED_CORRECTIONS_KEY in input ? stripped : input;
+    const notices = [];
+    let draft;
+    const revise = (mutate) => {
+        draft ??= { ...args };
+        mutate(draft);
+    };
+    const rawOp = args.op;
+    let op = rawOp;
+    if (typeof rawOp === "string" && !isOperation(rawOp)) {
+        // Only stray leading/trailing characters that are neither letters nor digits are
+        // stripped ("view}", " done."); digits survive, so "rm 2" and " 2rm" stay invalid
+        // ops, and the middle must already be exactly a known operation ("re-move").
+        const stripped = rawOp.replace(/^[^a-z0-9]+|[^a-z0-9]+$/gi, "");
+        // A corrected rm/done/drop/start without a non-blank "task"/"phase" would act on every
+        // task (senpi#5332 review): leave such a call for validation to reject unchanged.
+        const carriesTarget = nonBlank(args.task) !== undefined || nonBlank(args.phase) !== undefined;
+        const needsTarget = stripped === "rm" || stripped === "done" || stripped === "drop" || stripped === "start";
+        if (isOperation(stripped) && (!needsTarget || carriesTarget)) {
+            op = stripped;
+            revise((draftArgs) => {
+                draftArgs.op = stripped;
+            });
+            notices.push(`[auto-corrected] "op" ${JSON.stringify(rawOp)} is not a known operation; used "${stripped}" after stripping stray leading or trailing non-alphanumeric characters. Pass "op" exactly: init, start, done, rm, drop, append, view.`);
+        }
+    }
+    // A `list` always means init, so its rules also run when op is missing. The top-level
+    // `items` rules do not: an op-less `items` call is only inferred as init against an empty
+    // list and as append with a phase, so promoting or unwrapping it here would bypass those
+    // guards (senpi#5332 review). Only an explicit "init" — after the op correction above —
+    // may adopt the `items` rules.
+    if (op === undefined || op === "init") {
+        if ("list" in args) {
+            let listValue = args.list;
+            if (typeof listValue === "string") {
+                try {
+                    const parsed = JSON.parse(listValue);
+                    if (Array.isArray(parsed) || isRecord(parsed)) {
+                        listValue = parsed;
+                        notices.push('[auto-corrected] "list" was sent as a JSON string; parsed it. Pass "list" as an array of phases.');
+                    }
+                }
+                catch {
+                    // Unparseable: leave the string for validation to reject.
+                }
+            }
+            let candidate = unwrapTodoList(listValue);
+            if (Array.isArray(candidate)) {
+                const normalized = normalizeTodoListEntries(candidate, notices);
+                if (normalized === null)
+                    return args;
+                candidate = normalized;
+            }
+            // A correction must never widen a malformed call into a list clear.
+            if (Array.isArray(candidate) && candidate.length === 0)
+                return args;
+            if (candidate !== args.list) {
+                const adopted = candidate;
+                revise((draftArgs) => {
+                    draftArgs.list = adopted;
+                });
+            }
+        }
+    }
+    if (op === "init" && args.list === undefined && Array.isArray(args.items) && args.items.length > 0) {
+        const items = args.items;
+        if (items.every(isPhaseRecord)) {
+            const normalized = normalizeTodoListEntries([...items], notices);
+            if (normalized === null || normalized.length === 0)
+                return args;
+            const adopted = normalized;
+            revise((draftArgs) => {
+                draftArgs.list = adopted;
+                delete draftArgs.items;
+            });
+            notices.push('[auto-corrected] "items" held phase records; moved them to "list". Pass phases under "list": {"op":"init","list":[{"phase":"<name>","items":["<task>", ...]}]}');
+        }
+        else {
+            const mapped = items.map((item) => (isContentRecord(item) && !isPhaseRecord(item) ? item.content : item));
+            if (mapped.some((item) => typeof item === "string") && mapped.some(isPhaseRecord))
+                return args;
+            const unwrapped = items.filter((item) => isContentRecord(item) && !isPhaseRecord(item)).length;
+            if (unwrapped > 0 && mapped.every((item) => typeof item === "string")) {
+                revise((draftArgs) => {
+                    draftArgs.items = mapped;
+                });
+                notices.push(`[auto-corrected] unwrapped ${unwrapped} top-level "items" ${unwrapped === 1 ? "entry" : "entries"} carrying a "content" field into their task strings. "items" holds only task strings.`);
+            }
+        }
+    }
+    if (!draft)
         return args;
-    const unwrapped = unwrapTodoList(args.list);
-    return unwrapped === args.list ? args : { ...args, list: unwrapped };
+    return notices.length > 0 ? { ...draft, [TODO_PREPARED_CORRECTIONS_KEY]: [...notices] } : draft;
+}
+/**
+ * Splits the prepare-time correction notices off prepared arguments (see
+ * `TODO_PREPARED_CORRECTIONS_KEY`): the arguments without the reserved key, plus the notices
+ * to prepend to `normalizeTodoParams`'s own corrections.
+ */
+export function splitPreparedCorrections(args) {
+    const { [TODO_PREPARED_CORRECTIONS_KEY]: notices, ...rest } = args;
+    return {
+        args: rest,
+        corrections: Array.isArray(notices)
+            ? notices.filter((notice) => typeof notice === "string")
+            : [],
+    };
 }
 function nonBlank(value) {
     return typeof value === "string" && value.trim() !== "" ? value : undefined;

package/dist/core/extensions/builtin/todotools/prompt.d.ts

@@ -1,3 +1,3 @@
-export declare const TODO_TOOL_DESCRIPTION = "**Tasks referenced by verbatim content string, NEVER an auto-generated ID: no \"task-1\"/\"task-N\" exists. Pass the content text in the task field.**\n\nOn each completion the earliest still-open task (in phase order) auto-promotes to in_progress.\nCompleting tasks out of phase order can move this pointer **back** to an earlier phase. This is expected; completed tasks are never reverted.\n\n## Operations\n\n| op | Required fields | Effect |\n|---|---|---|\n| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing) |\n| init | items: string[] | Flattened single-phase init |\n| start | task | Mark in progress |\n| done | task or phase | Mark completed |\n| drop | task or phase | Mark abandoned |\n| rm | task or phase (optional) | Remove task or phase; omit both to clear |\n| append | phase?, items: string[] | Append tasks to phase; lazily creates phase |\n| view | - | Read-only: echo list |\n\nExample: {\"op\":\"init\",\"list\":[{\"phase\":\"Setup\",\"items\":[\"Survey code\",\"Write tests\"]}]}\n\n## Anatomy\n- **Task content**: 5\u201310 words; what, not how. Unique identifier.\n- **Phase name**: short noun phrase (e.g. Foundation, Auth, Verification). Unique identifier. NEVER prefix 1., A), Phase 1:.\n\n## Rules\n- Mark tasks done immediately after finishing, then re-check the list against the newest user message. Complete phases in order.\n- NEVER end a turn with a todo call as its only tool call - batch it with the real work: init with the first reads/edits, each done/start with the next action.\n- Blocked? append a task to the active phase, or drop.\n- Keep task/phase strings stable once introduced. done/start/drop take the task's EXACT text: copy it verbatim from the latest todo result; when it is lost, view echoes the list.\n\n## When to create a list\n- User explicitly requests one\n- User provides a set of tasks\n- New instructions arrive mid-task (reconcile before acting): keep what they don't conflict with, amend what they contradict, append what they add; replace only on explicit redirect\n\n<critical>\nUser hands you a multi-step plan (phased todo, numbered/bulleted checklist, or \"N bugs/items/tasks\"):\n- You MUST init the list with EVERY item as its own task before working.\n- Enumerate all; NEVER summarize into fewer tasks, sample \"the important ones\", drop items, or track the rest from memory.\n</critical>";
-export declare const TASK_MANAGEMENT_SECTION = "\n<Task_Management>\n## Todo Management\n\nA request with three or more distinct steps gets a phased todo before the first edit - investigation, implementation, verification, final report - in the todo tool; its description carries the operations, anatomy, and rules. Mark each item done the moment it finishes and reconcile the list against the newest user message before ending a turn.\n\n## Evidence\n- File edit: inspect the changed files and diagnostics.\n- Build command: require exit code 0.\n- Test run: require passing output, or state the pre-existing failure.\n</Task_Management>\n";
+export declare const TODO_TOOL_DESCRIPTION = "**Tasks referenced by verbatim content string, NEVER an auto-generated ID: no \"task-1\"/\"task-N\" exists. Pass the content text in the task field.**\n\nOn each completion the earliest still-open task (in phase order) auto-promotes to in_progress.\nCompleting tasks out of phase order can move this pointer **back** to an earlier phase. This is expected; completed tasks are never reverted.\n\n## Operations\n\n| op | Required fields | Effect |\n|---|---|---|\n| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing). Each list entry is exactly one phase; items holds only task strings |\n| init | items: string[] | Flattened single-phase init |\n| start | task | Mark in progress |\n| done | task or phase | Mark completed |\n| drop | task or phase | Mark abandoned |\n| rm | task or phase (optional) | Remove task or phase; omit both to clear |\n| append | phase?, items: string[] | Append tasks to phase; lazily creates phase |\n| view | - | Read-only: echo list |\n\nExample: {\"op\":\"init\",\"list\":[{\"phase\":\"Setup\",\"items\":[\"Survey code\",\"Write tests\"]}]}\n\n## Anatomy\n- **Task content**: 5\u201310 words; what, not how. Unique identifier.\n- **Phase name**: short noun phrase (e.g. Foundation, Auth, Verification). Unique identifier. NEVER prefix 1., A), Phase 1:.\n\n## Rules\n- Mark tasks done immediately after finishing, then re-check the list against the newest user message. Complete phases in order.\n- NEVER end a turn with a todo call as its only tool call - batch it with the real work: init with the first reads/edits, each done/start with the next action.\n- Blocked? append a task to the active phase, or drop.\n- Keep task/phase strings stable once introduced. done/start/drop take the task's EXACT text: copy it verbatim from the latest todo result; when it is lost, view echoes the list.\n\n## When to create a list\n- User explicitly requests one\n- User provides a set of tasks\n- New instructions arrive mid-task (reconcile before acting): keep what they don't conflict with, amend what they contradict, append what they add; replace only on explicit redirect\n\n<critical>\nUser hands you a multi-step plan (phased todo, numbered/bulleted checklist, or \"N bugs/items/tasks\"):\n- You MUST init the list with EVERY item as its own task before working.\n- Enumerate all; NEVER summarize into fewer tasks, sample \"the important ones\", drop items, or track the rest from memory.\n</critical>";
+export declare const TASK_MANAGEMENT_SECTION = "\n<Task_Management>\n## Todo Management\n\nRequest with 3+ distinct steps -> phased todo in the todo tool before first edit: investigation, implementation, verification, final report.\n\n## Evidence\n- File edit: inspect changed files + diagnostics.\n- Build: exit code 0.\n- Test run: passing output, or state the pre-existing failure.\n</Task_Management>\n";
 //# sourceMappingURL=prompt.d.ts.map

package/dist/core/extensions/builtin/todotools/prompt.js

@@ -11,7 +11,7 @@ Completing tasks out of phase order can move this pointer **back** to an earlier
 
 | op | Required fields | Effect |
 |---|---|---|
-| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing) |
+| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing). Each list entry is exactly one phase; items holds only task strings |
 | init | items: string[] | Flattened single-phase init |
 | start | task | Mark in progress |
 | done | task or phase | Mark completed |
@@ -46,12 +46,12 @@ export const TASK_MANAGEMENT_SECTION = `
 <Task_Management>
 ## Todo Management
 
-A request with three or more distinct steps gets a phased todo before the first edit - investigation, implementation, verification, final report - in the todo tool; its description carries the operations, anatomy, and rules. Mark each item done the moment it finishes and reconcile the list against the newest user message before ending a turn.
+Request with 3+ distinct steps -> phased todo in the todo tool before first edit: investigation, implementation, verification, final report.
 
 ## Evidence
-- File edit: inspect the changed files and diagnostics.
-- Build command: require exit code 0.
-- Test run: require passing output, or state the pre-existing failure.
+- File edit: inspect changed files + diagnostics.
+- Build: exit code 0.
+- Test run: passing output, or state the pre-existing failure.
 </Task_Management>
 `;
 //# sourceMappingURL=prompt.js.map

package/dist/core/extensions/builtin/todotools/tools/todo.js

@@ -6,7 +6,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { partialStrikethrough, strikeRevealCount } from "../../../../../modes/interactive/components/todo-strike.js";
 import { resolvePromptSurface } from "../../../../dynamic-prompt/build.js";
-import { normalizeTodoParams, prepareTodoArguments } from "../normalize.js";
+import { normalizeTodoParams, prepareTodoArguments, splitPreparedCorrections } from "../normalize.js";
 import { TODO_TOOL_DESCRIPTION } from "../prompt.js";
 import { applyParams, captureListAsk, clonePhases, findTaskByContent, formatHandoffCue, formatSummary, getCompletionTransitions, getTodoMarker, handoffMomentOf, nextActionableTask, sanitizeTodoText, TODO_STATE_ENTRY_TYPE, } from "../state.js";
 const TodoOperationSchema = Type.Union([
@@ -212,24 +212,25 @@ export function registerTodoTool(pi, accessors) {
         label: "Todo",
         description: TODO_TOOL_DESCRIPTION,
         promptSnippet: "Track phased tasks with one op-based todo tool; reference tasks by their exact content.",
-        promptGuidelines: [
-            "Use one todo operation at a time, batched with the real work; never end a turn with a todo call as its only tool call.",
-            "Reference tasks and phases by their exact content/name; use view when the text is uncertain.",
-            "Mark work done immediately and use drop for tasks that are no longer needed.",
-        ],
         parameters: TODO_PARAMS_SCHEMA,
         prepareArguments: (args) => prepareTodoArguments(args),
         executionMode: "sequential",
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const previousPhases = clonePhases(accessors.getCurrentPhases());
             const previousAsk = accessors.getCurrentAsk();
-            const normalized = normalizeTodoParams(params, previousPhases);
+            // prepareTodoArguments carries its notices on the prepared args under a reserved key
+            // (#5332). The key is stripped here before normalizing and is never persisted or
+            // rendered, but the prepared arguments — key included — flow to the agent loop's
+            // beforeToolCall/afterToolCall hooks, so extension tool_call/tool_result hooks may
+            // observe it on the arguments they receive.
+            const prepared = splitPreparedCorrections(params);
+            const normalized = normalizeTodoParams(prepared.args, previousPhases);
             if (normalized.error || !normalized.entry) {
                 const error = normalized.error ?? 'Missing "op". Example: {"op":"init","list":[{"phase":"Setup","items":["..."]}]}';
                 throw new Error(`${error}\n\n${formatSummary(previousPhases, [], true, previousAsk)}`);
             }
             const entry = normalized.entry;
-            const corrections = normalized.corrections;
+            const corrections = [...prepared.corrections, ...normalized.corrections];
             const readOnly = entry.op === "view";
             const errors = [];
             const applied = readOnly

package/dist/core/extensions/builtin/webfetch/webfetch/tool.js

@@ -19,11 +19,6 @@ export const webfetch = defineTool({
     description: "Fetches content from a URL and returns it as markdown, plain text, or HTML. " +
         "Network use is bounded by timeout and response size limits.",
     promptSnippet: "webfetch: retrieve URL content as markdown, text, or html",
-    promptGuidelines: [
-        "Use webfetch when a specific URL must be retrieved.",
-        "Prefer markdown format unless raw HTML or plain text is explicitly needed.",
-        "The tool is read-only and does not modify files.",
-    ],
     parameters: Params,
     async execute(_toolCallId, params, signal, onUpdate, _ctx) {
         const format = parseWebfetchFormat(params.format);

package/dist/core/extensions/builtin/websearch/index.js

@@ -8,7 +8,7 @@ import { loadWebsearchConfig } from "./websearch/config.js";
 import { attemptRouteLabel } from "./websearch/route-attempts.js";
 import { providerEntryLabel } from "./websearch/search.js";
 import { resolveNativeSearchModel } from "./websearch/search-model.js";
-import { createWebSearchTool } from "./websearch/tool.js";
+import { createWebSearchTool, WEB_SEARCH_CITE_GUIDELINE } from "./websearch/tool.js";
 const STATUS_KEY = "pi-websearch";
 const WIDGET_KEY = "pi-websearch";
 const NATIVE_BYPASS_MESSAGE = "Native provider web search is handled by the built-in provider extension.";
@@ -127,13 +127,18 @@ export default function (pi) {
         }
         if (!hasServerSearch(ctx.model))
             return undefined;
-        const systemPrompt = event.systemPrompt
+        const failed = hasServerSearchFailed(ctx.sessionManager, ctx.model);
+        const withoutSections = event.systemPrompt
             .replace(ANTHROPIC_WEB_SEARCH_SECTION, "")
             .replace(OPENAI_WEB_SEARCH_SECTION, "");
+        // Server search: the section below carries the cite rule, so the tool's guideline bullet goes.
+        const systemPrompt = failed
+            ? withoutSections
+            : withoutSections.replace(`- ${WEB_SEARCH_CITE_GUIDELINE}\n`, "");
         return {
-            systemPrompt: `${systemPrompt}\n## Web Search\n${hasServerSearchFailed(ctx.sessionManager, ctx.model)
+            systemPrompt: `${systemPrompt}\n## Web Search\n${failed
                 ? "Use the standalone web_search tool when current information is needed. Native search failed for this session model."
-                : "Use the provider's in-turn server web search when current information is needed."}`,
+                : "web_search = provider server-side search. Use when current info needed; cite returned URLs in final answer."}`,
         };
     }, { previewSafe: true });
     pi.on("before_provider_request", (event, ctx) => {

package/dist/core/extensions/builtin/websearch/websearch/tool.d.ts

@@ -12,6 +12,8 @@ type WebSearchTool = ReturnType<typeof defineTool<typeof Params, SearchRenderDet
 export interface WebSearchToolOptions {
     onSearchComplete?: (details: SearchDetails) => void;
 }
+/** The one Tool Guidelines bullet; the server-search `## Web Search` section states it instead (senpi#5335). */
+export declare const WEB_SEARCH_CITE_GUIDELINE = "web_search used -> cite returned URLs in final answer.";
 export declare function createWebSearchTool(getConfig: ConfigProvider, options?: WebSearchToolOptions): WebSearchTool;
 export declare const web_search: import("../../../types.ts").ToolDefinition<Type.TObject<{
     query: Type.TString;

package/dist/core/extensions/builtin/websearch/websearch/tool.js

@@ -40,6 +40,8 @@ function formatSearchProgressText(details) {
 function searchErrorDetails(query, error, reason) {
     return { phase: "error", query, error, ...(reason ? { reason } : {}) };
 }
+/** The one Tool Guidelines bullet; the server-search `## Web Search` section states it instead (senpi#5335). */
+export const WEB_SEARCH_CITE_GUIDELINE = "web_search used -> cite returned URLs in final answer.";
 export function createWebSearchTool(getConfig, options = {}) {
     let routingState;
     let routingKey = "";
@@ -49,7 +51,7 @@ export function createWebSearchTool(getConfig, options = {}) {
         label: "Web Search",
         description: "Search the web for current information and return source URLs for citation.",
         promptSnippet: "Search the web for current information, documentation, news, or external facts.",
-        promptGuidelines: ["After using web_search, cite relevant returned URLs in the final answer."],
+        promptGuidelines: [WEB_SEARCH_CITE_GUIDELINE],
         parameters: Params,
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
             if (params.allowed_domains?.length && params.blocked_domains?.length) {

package/dist/core/model-runtime.js

@@ -946,7 +946,7 @@ export class ModelRuntime {
         return this.enqueueCredentialOperation(providerId, signal, async () => {
             const store = this.credentials.backingStore;
             const before = await store.read(providerId, { signal });
-            const credential = await this.models.login(providerId, type, { ...interaction, signal }, options);
+            const credential = await this.models.login(providerId, type, { ...interaction, signal }, { ...options, appName: APP_NAME });
             if (this.poolStatePath !== undefined) {
                 const { retireLoginSlotHealth } = await import("./credential-pool/login-health.js");
                 await retireLoginSlotHealth(this.poolStatePath, providerId, before, await store.read(providerId, { signal }));

package/dist/core/provider-failure.d.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { type Api, type AssistantMessage, type Model, type ProviderDiagnostic, type ProviderDiagnosticCategory } from "@earendil-works/pi-ai";
+import { type TransportTrustFailure } from "../engine-trust/transport-failure.ts";
 import { type FallbackModelLookup } from "./retry-fallback/chains.ts";
 /**
  * `request_refused`: an `auth` failure on a credential that served a response moments before, so the
@@ -33,6 +34,11 @@ export interface ProviderFailure {
     readonly resetsAt?: number;
     readonly reason: string;
     readonly action: string;
+    /**
+     * Present when the request failed TLS chain verification while the engine runs on a fallback trust
+     * generation: the fallback reason and its repair action id (senpi#5244).
+     */
+    readonly trust?: TransportTrustFailure;
 }
 /** An `auth` failure on a credential that served a response moments before: the request was refused, not the key. */
 export declare function isRequestLevelRefusal(message: AssistantMessage): boolean;

package/dist/core/provider-failure.js

@@ -1,4 +1,5 @@
 import { PROVIDER_NOT_CONFIGURED_PREFIX, sanitizeProviderDiagnostic, stripTurnRetrySuppressionPrefix, } from "@earendil-works/pi-ai";
+import { transportTrustFailure } from "../engine-trust/transport-failure.js";
 import { parseFallbackSelector } from "./retry-fallback/chains.js";
 const ACTIONS = {
     auth: { reason: "the provider rejected the credentials", action: "re-authenticate the provider" },
@@ -82,11 +83,14 @@ export function providerFailureOf(messages, selected) {
     const last = messages.findLast((message) => message.role === "assistant");
     if (last === undefined || last.role !== "assistant" || last.stopReason !== "error")
         return undefined;
-    const failure = notConfiguredFailure(last) ??
-        describeProviderFailure(sanitizeProviderDiagnostic(last.providerDiagnostic), last.provider, {
+    const diagnostic = sanitizeProviderDiagnostic(last.providerDiagnostic);
+    const described = notConfiguredFailure(last) ??
+        describeProviderFailure(diagnostic, last.provider, {
             model: last.model,
             requestRefused: isRequestLevelRefusal(last),
         });
+    const trust = transportTrustFailure(diagnostic);
+    const failure = trust === undefined ? described : { ...described, trust };
     if (selected === undefined || (selected.provider === last.provider && selected.model === last.model)) {
         return failure;
     }

package/dist/core/retry-fallback/exhaustion.d.ts

@@ -0,0 +1,18 @@
+import type { FallbackReason } from "./controller-types.ts";
+/** One chain rung that failed during a turn's fallback walk: the model it ran on and its provider error. */
+export interface FallbackRungFailure {
+    model: string;
+    reason: FallbackReason;
+    error: string;
+}
+/** Appends a rung failure unless it repeats the last one (one failure can be offered to the walk twice). */
+export declare function recordRungFailure(failures: FallbackRungFailure[], failure: FallbackRungFailure): void;
+/**
+ * The exhaustion text every surface shows: the failure that started the walk first, then each later rung
+ * (senpi#4084). Without recorded rungs it falls back to the last error, as older events carried only that.
+ */
+export declare function describeFallbackExhaustion(event: {
+    lastError: string;
+    failures?: readonly FallbackRungFailure[];
+}): string;
+//# sourceMappingURL=exhaustion.d.ts.map

package/dist/core/retry-fallback/exhaustion.js

@@ -0,0 +1,20 @@
+/** Appends a rung failure unless it repeats the last one (one failure can be offered to the walk twice). */
+export function recordRungFailure(failures, failure) {
+    const last = failures.at(-1);
+    if (last && last.model === failure.model && last.error === failure.error)
+        return;
+    failures.push(failure);
+}
+/**
+ * The exhaustion text every surface shows: the failure that started the walk first, then each later rung
+ * (senpi#4084). Without recorded rungs it falls back to the last error, as older events carried only that.
+ */
+export function describeFallbackExhaustion(event) {
+    const failures = event.failures ?? [];
+    if (failures.length === 0)
+        return event.lastError;
+    return failures
+        .map((failure, index) => `${index === 0 ? "" : "then "}${failure.model}: ${failure.error}`)
+        .join("\n");
+}
+//# sourceMappingURL=exhaustion.js.map

package/dist/core/system-prompt.js

@@ -6,7 +6,7 @@ import { formatSkillsForPrompt } from "./skills.js";
 /** Contributions include eval-only tools even when the selected model-facing list does not. */
 export function getEvalOnlyGrepGuideline(selectedTools, toolSnippets) {
     return toolSnippets?.grep && !selectedTools.includes("grep")
-        ? "Search file contents with tool.grep({ pattern, path }) inside eval; prefer it over rg/grep in shell"
+        ? "Content search: tool.grep({ pattern, path }) in eval, not rg/grep in shell; page full -> skip, narrow with glob/path."
         : undefined;
 }
 const SYSTEM_PROMPT_SECTION_NAME = /^[a-z][a-z0-9_-]*$/;

package/dist/core/tools/bash.d.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { type Static, Type } from "typebox";
+import { type ShellTrust } from "../../engine-trust/shell-trust.ts";
 import { type ShellConfig } from "../../utils/shell.ts";
 import type { ToolDefinition } from "../extensions/types.ts";
 import { type TruncationResult } from "./truncate.ts";
@@ -9,7 +10,7 @@ declare const bashSchema: Type.TObject<{
 }>;
 export declare const bashToolSystemPromptContribution: {
     readonly snippet: "Execute bash commands (ls, rg, find, etc.)";
-    readonly guidelines: readonly ["You can inspect PI_* environment variables for current model and session details."];
+    readonly guidelines: readonly ["PI_* env vars = current model + session details."];
 };
 export type BashToolInput = Static<typeof bashSchema>;
 /**
@@ -27,6 +28,7 @@ export type BashToolOutput = Static<typeof bashOutputSchema>;
 export interface BashToolDetails {
     truncation?: TruncationResult;
     fullOutputPath?: string;
+    trust?: ShellTrust;
 }
 /**
  * Pluggable operations for the bash tool.

package/dist/core/tools/bash.js

@@ -4,6 +4,7 @@ import { access as fsAccess } from "node:fs/promises";
 import { constants as osConstants } from "node:os";
 import { spawn } from "child_process";
 import { Type } from "typebox";
+import { annotateShellTrust } from "../../engine-trust/shell-trust.js";
 import { waitForChildProcess } from "../../utils/child-process.js";
 import { getShellConfig, getShellEnv, killProcessTree, noteDetachedChildExited, pruneTrackedDetachedChildren, trackDetachedChildPid, } from "../../utils/shell.js";
 import { modelOnlyText } from "./model-only-text.js";
@@ -34,7 +35,7 @@ const bashSchema = Type.Object({
 });
 export const bashToolSystemPromptContribution = {
     snippet: "Execute bash commands (ls, rg, find, etc.)",
-    guidelines: ["You can inspect PI_* environment variables for current model and session details."],
+    guidelines: ["PI_* env vars = current model + session details."],
 };
 /**
  * Result for programmatic callers such as codemode scripts. A non-zero exit code is an error result for the model, but scripts still resolve to this value.
@@ -432,10 +433,19 @@ export function createShellToolDefinition(cwd, config, options) {
                     wall_time_seconds: wallTimeSeconds,
                 };
                 if (exitCode !== 0) {
+                    const text = appendStatus(outputText, `Command exited with code ${exitCode}`);
+                    // The engine trust annotation (omo#10762) rides only on error results, so the success
+                    // `outputSchema` (and the prompt bytes it costs) stays unchanged.
+                    const annotation = annotateShellTrust({ exitCode, output: fullOutput.content });
+                    if (annotation === undefined) {
+                        return { content: [{ type: "text", text }], details, structuredContent, isError: true };
+                    }
                     return {
-                        content: [{ type: "text", text: appendStatus(outputText, `Command exited with code ${exitCode}`) }],
-                        details,
-                        structuredContent,
+                        content: [
+                            { type: "text", text: annotation.text === undefined ? text : `${text}\n\n${annotation.text}` },
+                        ],
+                        details: { ...details, trust: annotation.trust },
+                        structuredContent: { ...structuredContent, trust: annotation.trust },
                         isError: true,
                     };
                 }

package/dist/core/tools/edit.d.ts

@@ -11,7 +11,7 @@ declare const editSchema: Type.TObject<{
 }>;
 export declare const editToolSystemPromptContribution: {
     readonly snippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call";
-    readonly guidelines: readonly ["Use edit for precise changes (edits[].oldText must match exactly)", "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls", "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.", "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions."];
+    readonly guidelines: readonly ["All changes to one file -> one edit call."];
 };
 export type EditToolInput = Static<typeof editSchema>;
 export interface EditToolDetails {

package/dist/core/tools/edit.js

@@ -22,12 +22,7 @@ const editSchema = Type.Object({
 }, {});
 export const editToolSystemPromptContribution = {
     snippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call",
-    guidelines: [
-        "Use edit for precise changes (edits[].oldText must match exactly)",
-        "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls",
-        "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.",
-        "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
-    ],
+    guidelines: ["All changes to one file -> one edit call."],
 };
 function isSingleEditInput(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {