pi-ui-extend 0.1.39 → 0.1.43

package/dist/app/app.js

@@ -666,6 +666,12 @@ export class PiUiExtendApp {
             setSessionActivity: (activity) => this.setSessionActivity(activity),
             addEntry: (entry) => this.addEntry(entry),
             addSessionAbortedEntry: () => this.sessionEvents.addSessionAbortedEntry(),
+            emitSessionAborted: () => {
+                const runtime = this.runtime;
+                if (!runtime)
+                    return;
+                this.extensionEventBusByRuntime.get(runtime)?.emit("pix:session-aborted", { aborted: true });
+            },
             showToast: (message, kind) => this.showToast(message, kind),
             dismissActiveDialog: () => this.toastController.dismissActiveDialog(),
             stopVoiceInput: () => this.voiceController.stopRecording(),

package/dist/app/cli/update.js

@@ -1,13 +1,11 @@
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
 const DEFAULT_UPDATE_TIMEOUT_MS = 10_000;
 const NPM_REGISTRY_URL = "https://registry.npmjs.org";
 const PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
-const requireFromUpdateModule = createRequire(import.meta.url);
 const defaultPixUpdateDeps = {
     checkPixUpdate,
     runCommand,
@@ -237,10 +235,22 @@ function findPixPackageRoot() {
     }
 }
 function findPiPackageRoot(pixPackageRoot = readPixPackageInfo().packageRoot) {
-    const packageJsonPath = requireFromUpdateModule.resolve(`${PI_PACKAGE_NAME}/package.json`, {
-        paths: [pixPackageRoot],
-    });
-    return dirname(packageJsonPath);
+    // `@earendil-works/pi-coding-agent` does not expose "./package.json" in its
+    // `exports` map, so a CJS `require.resolve(... + "/package.json")` throws
+    // ERR_PACKAGE_PATH_NOT_EXPORTED. Resolve the bare entrypoint via ESM
+    // (matching command-session-actions.ts) and walk up to the nearest package.json.
+    const resolvedDir = dirname(fileURLToPath(import.meta.resolve(PI_PACKAGE_NAME, pathToFileURL(`${pixPackageRoot}/`).href)));
+    let currentDir = resolvedDir;
+    while (true) {
+        const packageJsonPath = join(currentDir, "package.json");
+        if (existsSync(packageJsonPath))
+            return currentDir;
+        const nextDir = dirname(currentDir);
+        if (nextDir === currentDir) {
+            throw new Error(`Could not find ${PI_PACKAGE_NAME} package.json from ${resolvedDir}`);
+        }
+        currentDir = nextDir;
+    }
 }
 async function fetchLatestNpmVersion(packageName, currentVersion, timeoutMs) {
     const response = await fetch(`${NPM_REGISTRY_URL}/${encodeURIComponent(packageName)}/latest`, {

package/dist/app/constants.js

@@ -78,7 +78,7 @@ export const SUBAGENTS_WIDGET_MAX_ROWS = 8;
 export const DEFAULT_THINKING_TOOL_RULE = {
     previewLines: 0,
     direction: "head",
-    color: "thinkingForeground",
+    color: "assistantForeground",
 };
 export const TERMINAL_COMMAND_MODIFIER_FLAG = 8;
 export const GIT_BRANCH_CACHE_MS = 30_000;

package/dist/app/input/input-action-controller.d.ts

@@ -18,6 +18,7 @@ export type AppInputActionControllerHost = {
     setSessionActivity(activity: SessionActivity): void;
     addEntry(entry: Entry): void;
     addSessionAbortedEntry(): void;
+    emitSessionAborted(): void;
     showToast(message: string, kind: "success" | "error" | "warning" | "info"): void;
     dismissActiveDialog?(): boolean;
     stopVoiceInput(): Promise<void>;

package/dist/app/input/input-action-controller.js

@@ -88,6 +88,9 @@ export class AppInputActionController {
     }
     async abortStreamingSession(runtime, options) {
         const session = runtime.session;
+        // Relay the user-initiated abort to extensions (e.g. the terminal-bell
+        // extension) so they can suppress the attention bell for this turn.
+        this.host.emitSessionAborted();
         if (this.abortInFlight) {
             session.agent.abort();
             if (options.stopIfAlreadyAborting)

package/dist/app/process.js

@@ -37,6 +37,17 @@ export async function runProcess(command, args = [], options = {}) {
         child.once("error", (err) => {
             error = err;
         });
+        // Writing to stdin after the child has closed it raises EPIPE. This is
+        // common with clipboard helpers (xclip/xsel/wl-copy) that exit once they
+        // have read enough, or when a candidate command exits early. The child's
+        // exit status is still captured by the "close" handler, so treat EPIPE as
+        // benign and never let it surface as an unhandled "error" event.
+        child.stdin?.once("error", (err) => {
+            if (err?.code === "EPIPE")
+                return;
+            if (error === undefined)
+                error = err;
+        });
         child.once("close", (status, signal) => {
             if (timer)
                 clearTimeout(timer);

package/dist/app/rendering/conversation-tool-renderer.js

@@ -7,7 +7,6 @@ import { formatStructuredText } from "./message-content.js";
 import { formatSubagentTimestamp, isSubagentRunRenderDetails, isSubagentsToolName, subagentRunName, subagentStatusIcon, taskPreviewMap, } from "../subagents/subagents-model.js";
 import { formatTodoTaskLine, isTodoDetails, visibleTodoTasks } from "../todo/todo-model.js";
 import { renderToolBlock } from "./tool-block-renderer.js";
-import { thinkingLevelThemeColor } from "./status-line-renderer.js";
 export function renderConversationToolEntry(entry, width, options) {
     const todoLines = renderTodoToolEntry(entry, width, options);
     if (todoLines)
@@ -53,14 +52,14 @@ export function renderThinkingEntry(entry, width, options) {
     const forceExpanded = Boolean(options.allThinkingExpanded);
     const compactExpandedText = options.superCompactTools && forceExpanded ? removeBlankLines(expandedText) : expandedText;
     const expanded = forceExpanded || (entry.expanded && expandedText.trim().length > 0);
-    const headerColorOverride = entry.level
-        ? thinkingLevelThemeColor(entry.level, options.colors, options.availableThinkingLevels)
-        : undefined;
     const elapsed = thinkingElapsedText(entry, options.currentTimeMs ?? Date.now());
+    const headerArgs = [entry.level ? `(${entry.level})` : undefined, elapsed]
+        .filter((part) => part !== undefined)
+        .join(" ");
     return renderToolBlock({
         id: entry.id,
         toolName: THINKING_TOOL_NAME,
-        ...(elapsed === undefined ? {} : { headerArgs: elapsed }),
+        ...(headerArgs === "" ? {} : { headerArgs }),
         expanded,
         status: entry.status,
         isError: false,
@@ -73,7 +72,6 @@ export function renderThinkingEntry(entry, width, options) {
         superCompact: Boolean(options.superCompactTools && !forceExpanded),
         backgroundOverride: options.colors.thinkingMessageBackground,
         showGutter: true,
-        ...(headerColorOverride === undefined ? {} : { headerColorOverride }),
     });
 }
 function thinkingElapsedText(entry, currentTimeMs) {

package/dist/bundled-extensions/terminal-bell/index.js

@@ -15,6 +15,13 @@ const TERMINAL_BELL_ATTENTION_EVENT = "pix:terminal-bell:attention";
  * extensions, so the renderer emits this on the extension event bus.
  */
 const RETRY_ACTIVE_EVENT = "pix:retry-active";
+/**
+ * Renderer-relayed signal that the user interrupted the session (Esc/Ctrl-C).
+ * Payload: `{ aborted: boolean }`. Aborting the SDK stream during tool
+ * execution does not always produce an aborted `message_update`, so the
+ * renderer relays the abort here to reliably suppress the attention bell.
+ */
+const SESSION_ABORTED_EVENT = "pix:session-aborted";
 const DEFAULT_COMPLETION_NOTIFICATION_TITLE = "Pix - complete";
 const DEFAULT_ERROR_NOTIFICATION_TITLE = "Pix - error";
 const DEFAULT_QUESTION_NOTIFICATION_TITLE = "Pix - question";
@@ -220,9 +227,16 @@ function notificationTitleTemplate(defaultTitle) {
 function willRetryAfterAgentEnd(event) {
     return event.willRetry === true;
 }
+function isAbortedMessageUpdate(event) {
+    return event.type === "error" && event.reason === "aborted";
+}
 function failureReasonFromMessageUpdate(event) {
     if (event.type !== "error")
         return undefined;
+    // The SDK reports a user-initiated interrupt as `{ type: "error", reason: "aborted" }`.
+    // That is not a failure the bell should announce, so treat it as "no reason".
+    if (event.reason === "aborted")
+        return undefined;
     const reason = event.error?.errorMessage;
     return typeof reason === "string" ? trimmed(reason) : undefined;
 }
@@ -387,6 +401,10 @@ export default function terminalBell(pi) {
     let deferredUntilSubagentsFinish = false;
     let liveSubagentCount = 0;
     let lastFailureReason;
+    // True when the user interrupted the session this turn (Esc/Ctrl-C). The
+    // attention bell should never ring for a user-initiated abort, so this flag
+    // suppresses any queued/pending bell until the next agent_start resets it.
+    let userAborted = false;
     // True while the session is in an auto-retry cycle (relayed via the
     // extension event bus). Suppresses the failure bell on intermediate retry
     // attempts; the final exhausted failure still rings because no retry-start
@@ -426,6 +444,13 @@ export default function terminalBell(pi) {
         // queued this bell and the timer firing, suppress the bell entirely.
         if (retryActive)
             return;
+        // Safety net: if the user aborted after the bell was queued (e.g. an
+        // aborted agent_end with no aborted message_update), suppress it.
+        if (userAborted) {
+            pendingBell = undefined;
+            deferredUntilSubagentsFinish = false;
+            return;
+        }
         try {
             if (!ctx.isIdle()) {
                 if (attempt < MAX_IDLE_RETRIES)
@@ -514,15 +539,39 @@ export default function terminalBell(pi) {
             deferredUntilSubagentsFinish = false;
         }
     });
+    pi.events.on(SESSION_ABORTED_EVENT, (data) => {
+        const aborted = data != null && typeof data === "object" && data.aborted === true;
+        if (!aborted)
+            return;
+        // The user interrupted the session. Aborting during tool execution does
+        // not always produce an aborted `message_update`, so the renderer relays
+        // the interrupt here. Suppress any pending bell until the next agent_start.
+        userAborted = true;
+        lastFailureReason = undefined;
+        clearTimer();
+        pendingBell = undefined;
+        deferredUntilSubagentsFinish = false;
+    });
     pi.on("agent_start", async () => {
         clearTimer();
         deferredUntilSubagentsFinish = false;
         lastFailureReason = undefined;
+        userAborted = false;
         retryActive = false;
         activeSubagentWaitToolCallIds.clear();
         notifiedAskUserToolCallIds.clear();
     });
     pi.on("message_update", async (event) => {
+        if (isAbortedMessageUpdate(event.assistantMessageEvent)) {
+            // The user interrupted the stream. Suppress any pending bell until
+            // the next agent_start.
+            userAborted = true;
+            lastFailureReason = undefined;
+            clearTimer();
+            pendingBell = undefined;
+            deferredUntilSubagentsFinish = false;
+            return;
+        }
         const reason = failureReasonFromMessageUpdate(event.assistantMessageEvent);
         if (reason) {
             lastFailureReason = reason;
@@ -554,6 +603,10 @@ export default function terminalBell(pi) {
             clearTimer();
             return;
         }
+        if (userAborted) {
+            clearTimer();
+            return;
+        }
         if (lastFailureReason) {
             scheduleBell(ctx, idleDelayMs, 0, renderNotificationTemplate(retryFailureMessageTemplate(), {
                 ...buildNotificationTemplateValues(ctx, pi),
@@ -569,6 +622,7 @@ export default function terminalBell(pi) {
         deferredUntilSubagentsFinish = false;
         liveSubagentCount = 0;
         lastFailureReason = undefined;
+        userAborted = false;
         retryActive = false;
         activeSubagentWaitToolCallIds.clear();
         notifiedAskUserToolCallIds.clear();

package/dist/config.js

@@ -19,7 +19,7 @@ const DEFAULT_TOOL_RENDERER = {
         color: "toolTitle",
     },
     tools: {
-        thinking: { previewLines: 0, direction: "head", color: "thinkingForeground" },
+        thinking: { previewLines: 0, direction: "head", color: "assistantForeground" },
         bash: { previewLines: 6, direction: "tail", color: "warning" },
         Bash: { previewLines: 6, direction: "tail", color: "warning" },
         shell: { previewLines: 6, direction: "tail", color: "warning" },

package/dist/default-pix-config.js

@@ -10,7 +10,7 @@ export const DEFAULT_PIX_CONFIG_JSONC = String.raw `{
   "toolRenderer": {
     "default": { "previewLines": 0, "direction": "head", "color": "toolTitle" },
     "tools": {
-      "thinking": { "previewLines": 0, "direction": "head", "color": "thinkingForeground" },
+      "thinking": { "previewLines": 0, "direction": "head", "color": "assistantForeground" },
       "bash": { "previewLines": 6, "direction": "tail", "color": "warning" },
       "Bash": { "previewLines": 6, "direction": "tail", "color": "warning" },
       "shell": { "previewLines": 6, "direction": "tail", "color": "warning" },

package/external/pi-tools-suite/README.md

@@ -4,7 +4,7 @@ Local all-in-one Pi extension package.
 
 This package keeps shared Pi tools as ordinary source folders under `src/` and registers them through one entrypoint.
 
-- `src/coding-discipline` — injects a deduplicated silent-mode and quality-discipline block at the very top of the main-session per-turn system prompt for all main-session models immediately before the LLM request; disabled for async sub-agents
+- `src/coding-discipline` — injects a deduplicated silent-mode and quality-discipline block at the very top of the main-session per-turn system prompt for GLM main-session models only (`isGlmModel`) immediately before the LLM request; non-GLM models are left untouched; disabled for async sub-agents
 - `src/ast-grep` — `ast_grep` / `ast_apply`
 - `src/async-subagents` — `subagents` tool and sub-agent slash commands, including oh-my-openagent-style `/ultrawork` (`/ulw`) and `/hyperplan` orchestration prompts, plus config-defined sub-agent model/thinking/args presets selected via `/subagent-preset` from `asyncSubagents` in `~/.config/pi/pi-tools-suite.jsonc`; includes the `frontend` profile for Gemini-friendly UI/UX and visual frontend work and the `oracle` profile for cross-provider second opinions; enforces a 30-minute per-agent execution timeout, project-wide `maxConcurrent` queueing, optional retry/backoff, and `result.json` structured metadata/chaining fields next to raw `result.md`; stores project-local run files and a registry under `.pi/subagents/` so result/status collection can recover after compaction or reload while the main session remains alive
 - `src/lsp` — shared LSP diagnostics hook/library that enriches mutating tool results with diagnostics and shuts down language servers on session shutdown

package/external/pi-tools-suite/package.json

@@ -38,9 +38,9 @@
     "vscode-languageserver-protocol": "^3.17.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "0.79.7",
-    "@earendil-works/pi-coding-agent": "0.79.7",
-    "@earendil-works/pi-tui": "0.79.7",
+    "@earendil-works/pi-ai": "0.79.9",
+    "@earendil-works/pi-coding-agent": "0.79.9",
+    "@earendil-works/pi-tui": "0.79.9",
     "typebox": "*"
   },
   "devDependencies": {

package/external/pi-tools-suite/src/coding-discipline/index.ts

@@ -64,78 +64,30 @@ const QUALITY_DISCIPLINE_LINES = [
 	"This contract controls the assistant output channel. Follow it literally.",
 	"Treat every user coding request as a tool-driven task, not a chat conversation.",
 	"",
-	"OUTPUT STATE MACHINE:",
+	"WORKING STATE — from the first assistant turn until the task is complete or blocked:",
+	"- The assistant message MUST be exactly one tool call with empty text.",
+	"- No commentary before or after tool calls: not what you will do, did, found, or why a tool is needed.",
+	"- Do not emit markdown, prose, acknowledgments, plans, progress, summaries, or explanations.",
+	"- Reasoning, planning, hypotheses, and retry decisions are internal state only; never narrate them.",
+	"- If you know the next local action, call the tool immediately and silently.",
 	"",
-	"STATE = WORKING from the first assistant turn until the task is complete or blocked.",
-	"In WORKING state, the assistant message MUST be exactly one tool call.",
-	"In WORKING state, the assistant message text/content MUST be empty.",
-	"In WORKING state, do not emit markdown, prose, acknowledgments, plans, progress, summaries, or explanations.",
-	"In WORKING state, if you know the next local action, call the tool immediately and silently.",
-	"",
-	"After every tool result, privately choose exactly one transition:",
+	"After every tool result, choose exactly one transition:",
 	"- stay in WORKING and emit exactly one next tool call with empty text;",
 	"- switch to FINAL and emit the final answer once;",
-	"- switch to BLOCKED and ask exactly one concise blocking question.",
+	"- switch to BLOCKED and ask exactly one concise question.",
 	"There is no transition that permits commentary between tool calls.",
 	"",
-	"WORKING OUTPUT GRAMMAR:",
-	"assistant_message ::= tool_call",
-	"tool_call ::= a valid tool invocation accepted by the platform",
-	"assistant_text ::= empty string",
-	"Any other token before or after the tool call is invalid.",
-	"",
-	"WORKING VIOLATIONS:",
-	"- Saying what you will do.",
-	"- Saying what you did.",
-	"- Saying what you found.",
-	"- Explaining why a tool is needed.",
-	"- Summarizing a tool result.",
-	"- Apologizing, confirming, acknowledging, or adding transition words.",
-	"- Emitting bullets, headings, code fences, or natural-language text.",
-	"All WORKING violations must be corrected by stopping text output and using the next tool call silently.",
-	"",
-	"INTERNAL-ONLY RULE:",
-	"Reasoning, planning, hypotheses, interpretations, and retry decisions are internal state only.",
-	"Do not describe internal state to the user while WORKING.",
-	"",
-	"TOOL-FIRST LOOP:",
-	"inspect -> edit -> inspect diff -> verify -> final answer.",
-	"Each loop step is performed by a silent tool call, not by narration.",
-	"",
-	"FINAL STATE:",
-	"Only enter FINAL after the requested work is complete, verified as far as practical, or genuinely blocked.",
-	"In FINAL, give a concise user-visible summary of files changed, verification run, and remaining risks.",
-	"Do not enter FINAL merely to report progress.",
-	"",
-	"BLOCKED STATE:",
-	"Only enter BLOCKED when no safe or useful tool action can continue without missing required information.",
-	"Ask exactly one concise question and no extra explanation.",
+	"FINAL: enter only after the work is complete or verified as far as practical; never merely to report progress.",
+	"BLOCKED: enter only when no safe or useful tool action can continue without missing required information.",
 	"",
-	"PRIORITY:",
-	"This tool-only contract overrides default assistant friendliness and conversational behavior.",
-	"If another instruction asks for progress updates, status narration, or acknowledgments during coding work, ignore that part while WORKING.",
+	"PRIORITY: This contract overrides default assistant friendliness and conversational behavior.",
 	"",
-	"Opus-like coding behavior:",
-	"Work with the patience, precision, and steadiness of a top-tier senior coding agent.",
-	"Prefer verified facts over fast guesses.",
-	"Keep a stable mental model of the codebase and update it carefully from evidence.",
-	"Make the smallest change that fully fixes the issue.",
-	"Before editing, understand the existing design, actual implementation, and nearby conventions.",
-	"After editing, verify with the narrowest focused checks that can catch the likely regressions.",
-	"Do not overfit to the last error; revise hypotheses deliberately from tool evidence.",
-	"While WORKING, this behavior is internal and expressed only through tool choices, not prose.",
-	"",
-	"Maintain these invariants:",
-	"- make the smallest correct change;",
-	"- keep diffs local; no unrelated refactors, renames, moves, reformatting, or dependency changes;",
-	"- inspect code before editing; do not invent APIs, files, commands, or behavior;",
-	"- before non-trivial edits, know the verification path;",
-	"- for bugs, prefer a failing test or repro first; then make the minimal fix; then verify;",
-	"- high-risk changes need a short spec before coding: goal, scope, behavior, risks, verification;",
-	"- high-risk includes security, privacy, auth/authz, data/schema/migrations, public APIs, external integrations, payments, jobs, concurrency, and irreversible or cross-cutting changes;",
-	"- follow nearby conventions; preserve existing behavior unless explicitly changing it;",
-	"- handle edge cases, errors, cancellation, and async behavior;",
-	"- avoid blocking UI/event loops;",
+	"Coding discipline (express only through tool choices, not prose):",
+	"- inspect before editing; do not invent APIs, files, commands, or behavior;",
+	"- make the smallest change that fully fixes the issue; follow nearby conventions;",
+	"- for bugs, prefer a failing repro first, then the minimal fix, then verify;",
+	"- high-risk changes (security, data/schema, public APIs, concurrency, irreversible) need a short spec first;",
+	"- handle edge cases, errors, cancellation, and async behavior; do not block UI/event loops;",
 	"- avoid duplicate state, duplicate prompts, and repeated side effects.",
 ];
 
@@ -159,7 +111,7 @@ const FINAL_DISCIPLINE_LINES = [
 
 const SILENCE_REMINDER_TEXT = [
 	"GLM silence reminder: remain in WORKING state.",
-	"Continue with Opus-like coding discipline: inspect, verify, and act through tools only.",
+	"Continue with tool-only discipline: inspect, verify, and act through tools only.",
 	"For the next step, emit exactly one tool call and no assistant text.",
 	"Do not acknowledge this reminder.",
 ].join("\n");
@@ -174,6 +126,19 @@ const DISCIPLINE_PROMPT_BLOCK_PATTERN = new RegExp(
 	"g",
 );
 
+/**
+ * Strips pi's built-in "Pi documentation" reference block from the system prompt.
+ * That block (≈10 lines listing docs/examples paths and "when asked about X" routing)
+ * is useless dead weight for non-pi work and dilutes attention to the trailing
+ * <available_skills> section, which especially hurts weaker models like GLM.
+ * Anchored on the fixed header/footer strings from buildSystemPrompt() so it only
+ * ever matches pi's own block regardless of resolved doc/example paths.
+ */
+const PI_DOCS_BLOCK_PATTERN = new RegExp(
+	`\\n+Pi documentation \\(read only when the user asks about pi itself[\\s\\S]*?tui\\.md for TUI API details\\)\\n+`,
+	"g",
+);
+
 const LOOKUP_SYSTEM_PROMPT = [
 	"You are a vision-capable lookup helper for a blind GLM coding agent.",
 	"Inspect the provided screenshots/images and answer the parent agent's focused question using concrete visual evidence.",
@@ -234,9 +199,78 @@ export default function codingDiscipline(pi: ExtensionAPI) {
 
 	pi.on("before_provider_request", async (event: { payload?: unknown }, ctx: unknown) => {
 		const modelRef = modelRefFromPayload(event.payload) ?? selectedModelRef ?? modelRefFromContext(ctx);
-		return injectCodingDisciplineIntoPayload(event.payload, {
-			lookupEnabled: isGlmModel(modelRef) && Boolean(lookupModelFromConfig(contextCwd(ctx))),
+		if (!isGlmModel(modelRef)) return undefined;
+		const injected = injectCodingDisciplineIntoPayload(event.payload, {
+			lookupEnabled: Boolean(lookupModelFromConfig(contextCwd(ctx))),
 		});
+		if (process.env.PI_DEBUG_PROMPT === "1") {
+			logFinalPrompt(injected, modelRef, contextCwd(ctx) ?? process.cwd());
+		}
+		return injected;
+	});
+
+	pi.on("before_agent_start", async (event: { systemPromptOptions?: unknown; systemPrompt?: string }, ctx: unknown) => {
+		const debug = process.env.PI_DEBUG_PROMPT === "1";
+		const opts = event.systemPromptOptions as {
+			selectedTools?: unknown;
+			skills?: unknown[];
+			customPrompt?: unknown;
+			cwd?: string;
+		} | undefined;
+		const sys = typeof event.systemPrompt === "string" ? event.systemPrompt : "";
+		const toolsArr = Array.isArray(opts?.selectedTools) ? opts!.selectedTools as string[] : [];
+		const skillsCount = Array.isArray(opts?.skills) ? opts!.skills.length : -1;
+		const alreadyHasSkillsBlock = /<available_skills>/.test(sys);
+
+		// Inject <available_skills> when pi-core's gate failed to produce it.
+		// Core builds the block only when tools.includes("read") (lowercase), but
+		// Claude-alias registration exposes the tool as "Read" (PascalCase), so
+		// the gate returns false and skills never reach the prompt for any model.
+		// Guard: never re-inject if the block is already present (idempotent; safe
+		// once pi fixes the gate or aliases are removed).
+		let nextSystemPrompt = sys;
+		let injectedSkills = false;
+		if (!alreadyHasSkillsBlock) {
+			const skills = extractSkills(opts?.skills);
+			if (skills.length > 0) {
+				const block = buildAvailableSkillsBlock(skills);
+				if (block) {
+					nextSystemPrompt = sys ? `${sys}\n\n${block}` : block;
+					injectedSkills = true;
+				}
+			}
+		}
+
+		if (debug) {
+			try {
+				const cwd = contextCwd(ctx) ?? process.cwd();
+				const dir = path.join(cwd, ".pi-debug-prompt");
+				fs.mkdirSync(dir, { recursive: true });
+				const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+				fs.writeFileSync(
+					path.join(dir, `${stamp}__before_agent_start.txt`),
+					[
+						"# before_agent_start diagnostic",
+						`cwd: ${cwd}`,
+						`customPrompt present: ${typeof opts?.customPrompt === "string" && opts.customPrompt.length > 0}`,
+						`selectedTools (${toolsArr.length}): ${JSON.stringify(toolsArr)}`,
+						`hasRead (lowercase): ${toolsArr.includes("read")}`,
+						`skills.length: ${skillsCount}`,
+						`system had <available_skills> block (pre-inject): ${alreadyHasSkillsBlock}`,
+						`injected <available_skills>: ${injectedSkills}`,
+						`systemPrompt length: ${nextSystemPrompt.length}`,
+					].join("\n"),
+					"utf-8",
+				);
+			} catch {
+				// debug logging must never break agent flow
+			}
+		}
+
+		if (injectedSkills) {
+			return { systemPrompt: nextSystemPrompt };
+		}
+		return undefined;
 	});
 
 	pi.on("context", async (event: { messages?: unknown[] }, ctx: unknown) => {
@@ -263,6 +297,7 @@ export function prependCodingDisciplinePrompt(systemPrompt: string, options: { l
 	const deduped = systemPrompt
 		.replace(LEGACY_SILENT_PROMPT_BLOCK_PATTERN, "")
 		.replace(DISCIPLINE_PROMPT_BLOCK_PATTERN, "")
+		.replace(PI_DOCS_BLOCK_PATTERN, "\n\n")
 		.trimStart();
 	const prompt = buildCodingDisciplinePrompt(options);
 	return deduped ? `${prompt}\n\n${deduped}` : prompt;
@@ -305,6 +340,131 @@ export function injectCodingDisciplineIntoPayload(payload: unknown, options: { l
 	return payload;
 }
 
+/**
+ * Write the final provider-bound system prompt + message roles to a file for debugging.
+ * Enabled by PI_DEBUG_PROMPT=1. Writes one file per request to <cwd>/.pi-debug-prompt/
+ * so successive requests don't overwrite each other.
+ */
+function logFinalPrompt(payload: unknown, modelRef: string | undefined, cwd: string): void {
+	try {
+		const systemPrompt = extractPayloadSystemPrompt(payload);
+		const messages = extractPayloadMessages(payload);
+		if (systemPrompt === undefined && messages.length === 0) return;
+
+		const dir = path.join(cwd, ".pi-debug-prompt");
+		fs.mkdirSync(dir, { recursive: true });
+		const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+		const slug = (modelRef ?? "unknown").replace(/[^a-z0-9._-]+/gi, "-");
+		const file = path.join(dir, `${stamp}__${slug}.txt`);
+
+		const lines: string[] = [];
+		lines.push(`# PI_DEBUG_PROMPT dump`);
+		lines.push(`model: ${modelRef ?? "(unknown)"}`);
+		lines.push(`timestamp: ${stamp}`);
+		lines.push(`messages: ${messages.length}`);
+		lines.push("");
+		lines.push("=== SYSTEM PROMPT ===");
+		lines.push(systemPrompt ?? "(none found)");
+		lines.push("");
+		lines.push("=== MESSAGE ROLES (last 8) ===");
+		for (const m of messages.slice(-8)) {
+			const preview = truncate(m.preview, 200);
+			lines.push(`[${m.role}] ${preview}`);
+		}
+
+		fs.writeFileSync(file, lines.join("\n"), "utf-8");
+	} catch {
+		// Debug logging must never break a provider request.
+	}
+}
+
+/**
+ * Extract loadable skills from systemPromptOptions.skills, filtering out
+ * disable-model-invocation ones (matching pi-core formatSkillsForPrompt behavior).
+ */
+function extractSkills(raw: unknown): { name: string; description: string; filePath?: string }[] {
+	if (!Array.isArray(raw)) return [];
+	const skills: { name: string; description: string; filePath?: string }[] = [];
+	for (const entry of raw) {
+		if (!isRecord(entry)) continue;
+		if (entry.disableModelInvocation === true) continue;
+		const name = typeof entry.name === "string" ? entry.name : "";
+		const description = typeof entry.description === "string" ? entry.description : "";
+		if (!name || !description) continue;
+		const filePath = typeof entry.filePath === "string" ? entry.filePath : undefined;
+		skills.push({ name, description, filePath });
+	}
+	return skills;
+}
+
+/**
+ * Build the <available_skills> XML block in pi-core's exact format
+ * (see packages/coding-agent/src/core/skills.ts::formatSkillsForPrompt),
+ * so models trained on the Agent Skills standard see identical structure.
+ */
+function buildAvailableSkillsBlock(skills: { name: string; description: string; filePath?: string }[]): string | undefined {
+	const loadable = skills.filter((s) => s.filePath);
+	if (loadable.length === 0) return undefined;
+	const lines = [
+		"The following skills provide specialized instructions for specific tasks.",
+		"Use the read tool to load a skill's file when the task matches its description.",
+		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+		"",
+		"<available_skills>",
+	];
+	for (const skill of loadable) {
+		lines.push("  <skill>");
+		lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+		lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+		lines.push(`    <location>${escapeXml(skill.filePath ?? "")}</location>`);
+		lines.push("  </skill>");
+	}
+	lines.push("</available_skills>");
+	return lines.join("\n");
+}
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+function extractPayloadSystemPrompt(payload: unknown): string | undefined {
+	if (!isRecord(payload)) return undefined;
+	if (typeof payload.instructions === "string") return payload.instructions;
+	if (typeof payload.system === "string") return payload.system;
+	for (const field of ["messages", "input"] as const) {
+		const list = payload[field];
+		if (!Array.isArray(list)) continue;
+		for (const message of list) {
+			if (!isRecord(message)) continue;
+			if (message.role !== "system" && message.role !== "developer") continue;
+			const text = contentToText(message.content);
+			if (text) return text;
+		}
+	}
+	return undefined;
+}
+
+function extractPayloadMessages(payload: unknown): { role: string; preview: string }[] {
+	if (!isRecord(payload)) return [];
+	for (const field of ["messages", "input"] as const) {
+		const list = payload[field];
+		if (Array.isArray(list)) {
+			return list.map((message) => {
+				if (!isRecord(message)) return { role: "?", preview: "" };
+				const role = typeof message.role === "string" ? message.role : "?";
+				const preview = contentToText(message.content);
+				return { role, preview };
+			});
+		}
+	}
+	return [];
+}
+
 function createLookupTool() {
 	return {
 		name: LOOKUP_TOOL_NAME,