@tea-agent/loop-agent 0.26.2 → 0.26.4

package/dist/executors/pi-executor.js

@@ -1,10 +1,10 @@
-import { spawn, spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import path from 'node:path';
-import { PI_REUSE_RUNTIME_ENV, isPiReuseRuntimeEffective, resolvePiReuseRuntimeMode as resolveConfiguredPiReuseRuntimeMode, } from './pi-runtime-reuse.js';
-import { cleanupPiPromptTransport, createPiPromptTransport, } from './pi-prompt-transport.js';
-import { processTreeSpawnOptions, terminateProcessTree } from './process-tree.js';
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { PI_REUSE_RUNTIME_ENV, isPiReuseRuntimeEffective, resolvePiReuseRuntimeMode as resolveConfiguredPiReuseRuntimeMode, } from "./pi-runtime-reuse.js";
+import { cleanupPiPromptTransport, createPiPromptTransport, } from "./pi-prompt-transport.js";
+import { processTreeSpawnOptions, terminateProcessTree, } from "./process-tree.js";
 export function extractSubagentStats(stdout) {
     let totalCalls = 0;
     let failedCalls = 0;
@@ -16,20 +16,22 @@ export function extractSubagentStats(stdout) {
             continue;
         try {
             const event = JSON.parse(trimmed);
-            if (event.type === 'tool_execution_start' && event.toolName === 'subagent') {
+            if (event.type === "tool_execution_start" &&
+                event.toolName === "subagent") {
                 totalCalls += 1;
                 if (isRecord(event.input)) {
                     if (event.input.agent)
                         agents.add(String(event.input.agent));
                     if (event.input.tasks)
-                        modes.add('parallel');
+                        modes.add("parallel");
                     if (event.input.chain)
-                        modes.add('chain');
+                        modes.add("chain");
                     if (event.input.agent && !event.input.tasks && !event.input.chain)
-                        modes.add('single');
+                        modes.add("single");
                 }
             }
-            if (event.type === 'tool_execution_end' && event.toolName === 'subagent') {
+            if (event.type === "tool_execution_end" &&
+                event.toolName === "subagent") {
                 if (event.isError === true)
                     failedCalls += 1;
             }
@@ -39,15 +41,15 @@ export function extractSubagentStats(stdout) {
         }
     }
     if (totalCalls === 0)
-        return 'calls=0';
+        return "calls=0";
     const parts = [`calls=${totalCalls}`];
     if (failedCalls > 0)
         parts.push(`${failedCalls} failed`);
     if (modes.size > 0)
-        parts.push(Array.from(modes).sort().join('+'));
+        parts.push(Array.from(modes).sort().join("+"));
     if (agents.size > 0)
-        parts.push(`agents=[${Array.from(agents).sort().join(',')}]`);
-    return parts.join(' | ');
+        parts.push(`agents=[${Array.from(agents).sort().join(",")}]`);
+    return parts.join(" | ");
 }
 /** Absolute max wall clock for a single Pi attempt (4h). Not renewed by empty heartbeats. */
 export const DEFAULT_TIMEOUT_MS = 14_400_000;
@@ -56,14 +58,14 @@ export const MAX_ALLOWED_TIMEOUT_MS = 14_400_000;
 export const DEFAULT_STALL_TIMEOUT_MS = 900_000;
 /** Grace after SIGTERM before SIGKILL on absolute max. */
 export const DEFAULT_ABORT_GRACE_MS = 30_000;
-const PI_BACKEND_ENV = 'CODE_AGENT_PI_BACKEND';
+const PI_BACKEND_ENV = "CODE_AGENT_PI_BACKEND";
 const OUTPUT_PREVIEW_HEAD_CHARS = 64_000;
 const OUTPUT_PREVIEW_TAIL_CHARS = 64_000;
 const MAX_STREAM_JSONL_LINE_CHARS = 16_000_000;
 const MAX_ASSISTANT_TEXT_CHARS = 16_000_000;
 const PI_CLI_PACKAGE_NAMES = [
-    '@earendil-works/pi-coding-agent',
-    '@mariozechner/pi-coding-agent',
+    "@earendil-works/pi-coding-agent",
+    "@mariozechner/pi-coding-agent",
 ];
 export { PI_REUSE_RUNTIME_ENV };
 /** Resolve configured Pi SDK runtime reuse mode. Default off; unknown values fall back to off. */
@@ -82,7 +84,7 @@ export async function withPiReuseRuntimeScope(fn) {
     if (!isPiReuseRuntimeEnabled()) {
         return fn();
     }
-    const { beginPiSdkReuseScope, endPiSdkReuseScope } = await import('./pi-sdk-executor.js');
+    const { beginPiSdkReuseScope, endPiSdkReuseScope } = await import("./pi-sdk-executor.js");
     beginPiSdkReuseScope();
     try {
         return await fn();
@@ -94,14 +96,14 @@ export async function withPiReuseRuntimeScope(fn) {
 /** Resolve configured Pi backend mode. Default sdk-first; cli-only preserves pure CLI path. */
 export function resolvePiBackend() {
     const raw = process.env[PI_BACKEND_ENV]?.trim().toLowerCase();
-    if (raw === 'cli-only')
-        return 'cli-only';
-    if (raw === 'sdk-first' || !raw)
-        return 'sdk-first';
-    return 'sdk-first';
+    if (raw === "cli-only")
+        return "cli-only";
+    if (raw === "sdk-first" || !raw)
+        return "sdk-first";
+    return "sdk-first";
 }
 function piCliPathFromPackageRoot(nodeModulesRoot, packageName) {
-    return path.join(nodeModulesRoot, ...packageName.split('/'), 'dist', 'cli.js');
+    return path.join(nodeModulesRoot, ...packageName.split("/"), "dist", "cli.js");
 }
 function findExistingPiCliUnderNodeModules(nodeModulesRoot) {
     for (const packageName of PI_CLI_PACKAGE_NAMES) {
@@ -113,7 +115,7 @@ function findExistingPiCliUnderNodeModules(nodeModulesRoot) {
 }
 function resolveGlobalNpmPiCliPath() {
     try {
-        const npmRoot = spawnSync('npm', ['root', '-g'], { encoding: 'utf-8' });
+        const npmRoot = spawnSync("npm", ["root", "-g"], { encoding: "utf-8" });
         if (npmRoot.status === 0 && npmRoot.stdout.trim()) {
             return findExistingPiCliUnderNodeModules(npmRoot.stdout.trim());
         }
@@ -127,23 +129,25 @@ function resolvePiCliNearShim(shimPath) {
     if (!existsSync(shimPath))
         return undefined;
     const shimDir = path.dirname(shimPath);
-    const nearGlobalShim = findExistingPiCliUnderNodeModules(path.join(shimDir, 'node_modules'));
+    const nearGlobalShim = findExistingPiCliUnderNodeModules(path.join(shimDir, "node_modules"));
     if (nearGlobalShim)
         return nearGlobalShim;
     if (shimDir.endsWith(`${path.sep}.bin`)) {
-        const nearLocalBin = findExistingPiCliUnderNodeModules(path.join(shimDir, '..'));
+        const nearLocalBin = findExistingPiCliUnderNodeModules(path.join(shimDir, ".."));
         if (nearLocalBin)
             return nearLocalBin;
     }
     return undefined;
 }
 function resolvePiCliFromPathLookup() {
-    const lookupCommands = process.platform === 'win32'
-        ? [{ command: 'where.exe', args: ['pi'] }]
-        : [{ command: 'which', args: ['pi'] }];
+    const lookupCommands = process.platform === "win32"
+        ? [{ command: "where.exe", args: ["pi"] }]
+        : [{ command: "which", args: ["pi"] }];
     for (const lookup of lookupCommands) {
         try {
-            const result = spawnSync(lookup.command, lookup.args, { encoding: 'utf-8' });
+            const result = spawnSync(lookup.command, lookup.args, {
+                encoding: "utf-8",
+            });
             if (result.status !== 0 || !result.stdout.trim())
                 continue;
             for (const rawPath of result.stdout.split(/\r?\n/)) {
@@ -153,10 +157,10 @@ function resolvePiCliFromPathLookup() {
                 const nearShim = resolvePiCliNearShim(lookupPath);
                 if (nearShim)
                     return nearShim;
-                if (process.platform !== 'win32') {
+                if (process.platform !== "win32") {
                     try {
-                        const realPathResult = spawnSync('readlink', ['-f', lookupPath], {
-                            encoding: 'utf-8',
+                        const realPathResult = spawnSync("readlink", ["-f", lookupPath], {
+                            encoding: "utf-8",
                         });
                         if (realPathResult.status === 0 && realPathResult.stdout.trim()) {
                             const resolved = realPathResult.stdout.trim();
@@ -191,20 +195,20 @@ function resolvePiCliPath() {
     const home = homedir();
     // Try nvm paths with both "v"-prefixed and non-prefixed version directories
     const nodeVersion = process.versions.node; // e.g. "22.19.0"
-    const nvmBase = path.join(home, '.nvm', 'versions', 'node');
+    const nvmBase = path.join(home, ".nvm", "versions", "node");
     const nvmCandidates = [
-        path.join(nvmBase, `v${nodeVersion}`, 'lib', 'node_modules'),
-        path.join(nvmBase, nodeVersion, 'lib', 'node_modules'),
+        path.join(nvmBase, `v${nodeVersion}`, "lib", "node_modules"),
+        path.join(nvmBase, nodeVersion, "lib", "node_modules"),
     ].flatMap((nodeModulesRoot) => PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(nodeModulesRoot, packageName)));
     const otherCandidates = [
         // Prefer the project-local Pi dependency. `npm run` adds node_modules/.bin
         // to PATH, but direct invocations from the DAG runner may not, so resolve
         // the package from the current workspace explicitly.
-        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(path.resolve(process.cwd(), 'node_modules'), packageName)),
+        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(path.resolve(process.cwd(), "node_modules"), packageName)),
         // Global npm installation (non-nvm)
-        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot('/usr/local/lib/node_modules', packageName)),
+        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot("/usr/local/lib/node_modules", packageName)),
         // Bun installation
-        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(path.join(home, '.bun', 'install', 'global', 'node_modules'), packageName)),
+        ...PI_CLI_PACKAGE_NAMES.map((packageName) => piCliPathFromPackageRoot(path.join(home, ".bun", "install", "global", "node_modules"), packageName)),
     ];
     const allCandidates = [...nvmCandidates, ...otherCandidates];
     for (const candidate of allCandidates) {
@@ -218,7 +222,7 @@ function resolvePiCliPath() {
     const pathLookupPi = resolvePiCliFromPathLookup();
     if (pathLookupPi)
         return pathLookupPi;
-    throw new Error('Could not resolve pi CLI path. Ensure pi is installed.');
+    throw new Error("Could not resolve pi CLI path. Ensure pi is installed.");
 }
 let cachedPiCliPath;
 /** Lazily resolve and cache the pi CLI script path (avoids import-time sync I/O). */
@@ -235,17 +239,19 @@ export function resetPiCliPathCacheForTests() {
 export function checkPiAvailability() {
     // Use process.execPath to run pi CLI directly, avoiding shebang-based
     // resolution that can drop built-in providers when spawned from tsx.
-    const result = spawnSync(process.execPath, [getPiCliPath(), '--help'], { encoding: 'utf-8' });
+    const result = spawnSync(process.execPath, [getPiCliPath(), "--help"], {
+        encoding: "utf-8",
+    });
     if (result.error) {
         return { ok: false, detail: result.error.message };
     }
     if (result.status !== 0) {
         return { ok: false, detail: result.stderr || `exit ${result.status}` };
     }
-    return { ok: true, detail: 'pi available' };
+    return { ok: true, detail: "pi available" };
 }
 export function extractAssistantTextFromPiJson(stdout) {
-    let assistantText = '';
+    let assistantText = "";
     let parsedEvents = 0;
     for (const line of stdout.split(/\r?\n/)) {
         const trimmed = line.trim();
@@ -292,9 +298,22 @@ function extractUsageFromEvent(event) {
     for (const candidate of candidates) {
         if (!isRecord(candidate))
             continue;
-        const input = readNumericUsageField(candidate, ['input_tokens', 'inputTokens', 'prompt_tokens', 'promptTokens']);
-        const output = readNumericUsageField(candidate, ['output_tokens', 'outputTokens', 'completion_tokens', 'completionTokens']);
-        const total = readNumericUsageField(candidate, ['total_tokens', 'totalTokens']);
+        const input = readNumericUsageField(candidate, [
+            "input_tokens",
+            "inputTokens",
+            "prompt_tokens",
+            "promptTokens",
+        ]);
+        const output = readNumericUsageField(candidate, [
+            "output_tokens",
+            "outputTokens",
+            "completion_tokens",
+            "completionTokens",
+        ]);
+        const total = readNumericUsageField(candidate, [
+            "total_tokens",
+            "totalTokens",
+        ]);
         if (input !== null && output !== null)
             return input + output;
         if (total !== null)
@@ -305,20 +324,20 @@ function extractUsageFromEvent(event) {
 function readNumericUsageField(record, keys) {
     for (const key of keys) {
         const value = record[key];
-        if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
             return Math.trunc(value);
         }
     }
     return null;
 }
 function extractAssistantTextFromEvent(event) {
-    if (event.type === 'turn_end' && isRecord(event.message)) {
+    if (event.type === "turn_end" && isRecord(event.message)) {
         return extractAssistantTextFromMessage(event.message);
     }
-    if (event.type === 'message_end' && isRecord(event.message)) {
+    if (event.type === "message_end" && isRecord(event.message)) {
         return extractAssistantTextFromMessage(event.message);
     }
-    if (event.type === 'agent_end' && Array.isArray(event.messages)) {
+    if (event.type === "agent_end" && Array.isArray(event.messages)) {
         for (let i = event.messages.length - 1; i >= 0; i -= 1) {
             const message = event.messages[i];
             if (isRecord(message)) {
@@ -328,27 +347,27 @@ function extractAssistantTextFromEvent(event) {
             }
         }
     }
-    return '';
+    return "";
 }
 function extractAssistantTextFromMessage(message) {
-    if (message.role !== 'assistant' || !Array.isArray(message.content))
-        return '';
+    if (message.role !== "assistant" || !Array.isArray(message.content))
+        return "";
     const textParts = message.content
         .filter(isRecord)
-        .filter((item) => item.type === 'text' && typeof item.text === 'string')
+        .filter((item) => item.type === "text" && typeof item.text === "string")
         .map((item) => item.text);
-    return textParts.join('\n').trim();
+    return textParts.join("\n").trim();
 }
 function isRecord(value) {
-    return typeof value === 'object' && value !== null;
+    return typeof value === "object" && value !== null;
 }
 export class BoundedTextPreview {
     label;
     headMax;
     tailMax;
     parts = [];
-    head = '';
-    tail = '';
+    head = "";
+    tail = "";
     bufferedChars = 0;
     totalChars = 0;
     truncated = false;
@@ -367,7 +386,7 @@ export class BoundedTextPreview {
                 this.bufferedChars += chunk.length;
                 return;
             }
-            const combined = this.parts.join('') + chunk;
+            const combined = this.parts.join("") + chunk;
             this.head = combined.slice(0, this.headMax);
             this.tail = combined.slice(-this.tailMax);
             this.parts = [];
@@ -379,19 +398,19 @@ export class BoundedTextPreview {
     }
     text() {
         if (!this.truncated)
-            return this.parts.join('');
+            return this.parts.join("");
         const omitted = Math.max(0, this.totalChars - this.head.length - this.tail.length);
         return [
             this.head,
             `[${this.label} truncated: omitted ${omitted} chars; kept first ${this.head.length} and last ${this.tail.length}]`,
             this.tail,
-        ].join('\n');
+        ].join("\n");
     }
 }
 export class PiJsonlStreamCollector {
-    lineBuffer = '';
+    lineBuffer = "";
     discardUntilNewline = false;
-    assistantText = '';
+    assistantText = "";
     parsedEvents = 0;
     tokensUsed = 0;
     outputTooLarge = false;
@@ -404,7 +423,7 @@ export class PiJsonlStreamCollector {
             return;
         const lines = chunk.split(/\r?\n/);
         for (let index = 0; index < lines.length; index += 1) {
-            const part = lines[index] ?? '';
+            const part = lines[index] ?? "";
             const isLast = index === lines.length - 1;
             if (this.discardUntilNewline) {
                 if (!isLast)
@@ -413,7 +432,7 @@ export class PiJsonlStreamCollector {
             }
             if (this.lineBuffer.length + part.length > MAX_STREAM_JSONL_LINE_CHARS) {
                 this.outputTooLarge = true;
-                this.lineBuffer = '';
+                this.lineBuffer = "";
                 if (isLast)
                     this.discardUntilNewline = true;
                 continue;
@@ -421,7 +440,7 @@ export class PiJsonlStreamCollector {
             this.lineBuffer += part;
             if (!isLast) {
                 this.consumeLine(this.lineBuffer);
-                this.lineBuffer = '';
+                this.lineBuffer = "";
             }
         }
     }
@@ -429,7 +448,7 @@ export class PiJsonlStreamCollector {
         if (!this.discardUntilNewline && this.lineBuffer.trim()) {
             this.consumeLine(this.lineBuffer);
         }
-        this.lineBuffer = '';
+        this.lineBuffer = "";
         return {
             assistantText: this.assistantText.trim(),
             outputTooLarge: this.outputTooLarge,
@@ -465,47 +484,51 @@ export class PiJsonlStreamCollector {
         const usage = extractUsageFromEvent(event);
         if (usage !== null)
             this.tokensUsed += usage;
-        if (event.type === 'tool_execution_start' && event.toolName === 'subagent') {
+        if (event.type === "tool_execution_start" &&
+            event.toolName === "subagent") {
             this.subagentTotalCalls += 1;
             if (isRecord(event.input)) {
                 if (event.input.agent)
                     this.subagentAgents.add(String(event.input.agent));
                 if (event.input.tasks)
-                    this.subagentModes.add('parallel');
+                    this.subagentModes.add("parallel");
                 if (event.input.chain)
-                    this.subagentModes.add('chain');
+                    this.subagentModes.add("chain");
                 if (event.input.agent && !event.input.tasks && !event.input.chain) {
-                    this.subagentModes.add('single');
+                    this.subagentModes.add("single");
                 }
             }
         }
-        if (event.type === 'tool_execution_end' && event.toolName === 'subagent') {
+        if (event.type === "tool_execution_end" && event.toolName === "subagent") {
             if (event.isError === true)
                 this.subagentFailedCalls += 1;
         }
     }
     formatSubagentStats() {
         if (this.subagentTotalCalls === 0)
-            return 'calls=0';
+            return "calls=0";
         const parts = [`calls=${this.subagentTotalCalls}`];
         if (this.subagentFailedCalls > 0)
             parts.push(`${this.subagentFailedCalls} failed`);
         if (this.subagentModes.size > 0)
-            parts.push(Array.from(this.subagentModes).sort().join('+'));
+            parts.push(Array.from(this.subagentModes).sort().join("+"));
         if (this.subagentAgents.size > 0) {
-            parts.push(`agents=[${Array.from(this.subagentAgents).sort().join(',')}]`);
+            parts.push(`agents=[${Array.from(this.subagentAgents).sort().join(",")}]`);
         }
-        return parts.join(' | ');
+        return parts.join(" | ");
     }
 }
 export function createPiJsonlStreamCollector() {
     return new PiJsonlStreamCollector();
 }
 function withSubagentStats(result) {
-    return { ...result, subagentStats: result.subagentStats ?? extractSubagentStats(result.stdout) };
+    return {
+        ...result,
+        subagentStats: result.subagentStats ?? extractSubagentStats(result.stdout),
+    };
 }
 function withCliBackend(result) {
-    return { ...result, backend: 'cli' };
+    return { ...result, backend: "cli" };
 }
 /** CLI-only orchestration: primary attempt + optional fallback model retry. */
 async function runCliOrchestration(options, meta) {
@@ -534,15 +557,20 @@ async function runCliOrchestrationWithPromptFile(options, promptFilePath, meta)
     }
     const primaryHardFail = !primaryResult.ok;
     const primaryInvalidOutput = primaryResult.ok && primaryIssues.length > 0;
-    const shouldFallback = primary.fallback && ((primaryHardFail
-        && primaryResult.failureCategory !== 'termination-unconfirmed'
-        && shouldRetryWithFallback(primaryResult.stderr, primaryResult.stdout))
-        || primaryInvalidOutput);
+    const shouldFallback = primary.fallback &&
+        ((primaryHardFail &&
+            primaryResult.failureCategory !== "termination-unconfirmed" &&
+            shouldRetryWithFallback(primaryResult.stderr, primaryResult.stdout)) ||
+            primaryInvalidOutput);
     if (shouldFallback) {
         const fallbackResult = await executeSingleCliAttempt(options, primary.fallback, promptFilePath);
         attemptedModels.push(fallbackResult.modelDisplay);
-        const combinedStderr = [primaryResult.stderr, fallbackResult.stderr].filter(Boolean).join('\n--- fallback ---\n');
-        const combinedStdout = [primaryResult.stdout, fallbackResult.stdout].filter(Boolean).join('\n--- fallback ---\n');
+        const combinedStderr = [primaryResult.stderr, fallbackResult.stderr]
+            .filter(Boolean)
+            .join("\n--- fallback ---\n");
+        const combinedStdout = [primaryResult.stdout, fallbackResult.stdout]
+            .filter(Boolean)
+            .join("\n--- fallback ---\n");
         const combinedStdoutTruncated = primaryResult.stdoutTruncated || fallbackResult.stdoutTruncated;
         const combinedStderrTruncated = primaryResult.stderrTruncated || fallbackResult.stderrTruncated;
         const combinedOutputTooLarge = primaryResult.outputTooLarge || fallbackResult.outputTooLarge;
@@ -567,11 +595,11 @@ async function runCliOrchestrationWithPromptFile(options, promptFilePath, meta)
             return withSubagentStats(withCliBackend({
                 ...fallbackResult,
                 ok: false,
-                failureCategory: 'invalid-output',
+                failureCategory: "invalid-output",
                 attemptedModels,
                 fallbackUsed: true,
                 sdkAttempted: meta?.sdkAttempted,
-                stderr: combinedStderr + `\n[invalid-output] ${fallbackIssues.join('; ')}`,
+                stderr: combinedStderr + `\n[invalid-output] ${fallbackIssues.join("; ")}`,
                 stdout: combinedStdout,
                 stdoutTruncated: combinedStdoutTruncated,
                 stderrTruncated: combinedStderrTruncated,
@@ -594,11 +622,12 @@ async function runCliOrchestrationWithPromptFile(options, promptFilePath, meta)
         return withSubagentStats(withCliBackend({
             ...primaryResult,
             ok: false,
-            failureCategory: 'invalid-output',
+            failureCategory: "invalid-output",
             attemptedModels,
             fallbackUsed: false,
             sdkAttempted: meta?.sdkAttempted,
-            stderr: primaryResult.stderr + `\n[invalid-output] ${primaryIssues.join('; ')}`,
+            stderr: primaryResult.stderr +
+                `\n[invalid-output] ${primaryIssues.join("; ")}`,
         }));
     }
     return withSubagentStats(withCliBackend({
@@ -608,29 +637,71 @@ async function runCliOrchestrationWithPromptFile(options, promptFilePath, meta)
         sdkAttempted: meta?.sdkAttempted,
     }));
 }
-function shouldFallbackSdkToCli(sdkResult, validationIssues) {
+function shouldFallbackSdkToCli(sdkResult, validationIssues, options) {
+    // Writers must never fall back to unrestricted CLI mutation tools.
+    if (options?.writerToolPolicy?.requireSdk)
+        return false;
     if (sdkResult.ok && validationIssues.length > 0)
         return true;
-    if (!sdkResult.ok && (sdkResult.failureCategory === 'auth'
-        || sdkResult.failureCategory === 'timeout'
-        || sdkResult.failureCategory === 'termination-unconfirmed')) {
+    if (!sdkResult.ok &&
+        (sdkResult.failureCategory === "auth" ||
+            sdkResult.failureCategory === "timeout" ||
+            sdkResult.failureCategory === "termination-unconfirmed")) {
         return false;
     }
-    if (!sdkResult.ok && shouldRetryWithFallback(sdkResult.stderr, sdkResult.stdout))
+    if (!sdkResult.ok &&
+        shouldRetryWithFallback(sdkResult.stderr, sdkResult.stdout))
         return true;
     return false;
 }
+function writerPolicyFailureResult(options, message, extras) {
+    return {
+        assistantText: "",
+        command: [],
+        durationMs: 0,
+        exitCode: 1,
+        failureCategory: "tool-policy",
+        modelDisplay: options.modelConfig?.model
+            ? `${options.modelConfig.provider ?? "default"}/${options.modelConfig.model}`
+            : "default",
+        ok: false,
+        parsedEvents: 0,
+        stderr: message,
+        stdout: "",
+        timedOut: false,
+        attemptedModels: [],
+        fallbackUsed: false,
+        tokensUsed: 0,
+        backend: extras?.backend,
+        sdkAttempted: extras?.sdkAttempted ?? false,
+    };
+}
 export async function executePiStep(options) {
     const backendMode = resolvePiBackend();
-    if (backendMode === 'cli-only') {
+    const writerRequiresSdk = options.writerToolPolicy?.requireSdk === true;
+    if (backendMode === "cli-only") {
+        if (writerRequiresSdk) {
+            return writerPolicyFailureResult(options, "pi writer tool policy requires SDK backend; CODE_AGENT_PI_BACKEND=cli-only is fail-closed for writers", { sdkAttempted: false, backend: "cli" });
+        }
         return runCliOrchestration(options, { sdkAttempted: false });
     }
-    const { checkPiSdkAvailability, executeSingleSdkAttempt, getActivePiSdkReuseScope, } = await import('./pi-sdk-executor.js');
+    if (writerRequiresSdk) {
+        const customTools = options.writerToolPolicy?.customTools;
+        if (!Array.isArray(customTools) || customTools.length === 0) {
+            return writerPolicyFailureResult(options, "pi writer tool policy missing customTools; refusing uncontrolled writer session", { sdkAttempted: false });
+        }
+    }
+    const { checkPiSdkAvailability, executeSingleSdkAttempt, getActivePiSdkReuseScope, } = await import("./pi-sdk-executor.js");
     const sdkCheck = await checkPiSdkAvailability(options.repoRoot);
     if (!sdkCheck.ok) {
+        if (writerRequiresSdk) {
+            return writerPolicyFailureResult(options, `pi writer tool policy requires SDK; ${sdkCheck.detail}`, { sdkAttempted: false });
+        }
         return runCliOrchestration(options, { sdkAttempted: false });
     }
-    const reuseScope = isPiReuseRuntimeEnabled() ? getActivePiSdkReuseScope() : undefined;
+    const reuseScope = isPiReuseRuntimeEnabled()
+        ? getActivePiSdkReuseScope()
+        : undefined;
     const reuseRuntimeActive = Boolean(reuseScope);
     const primary = options.modelConfig ?? {};
     const sdkResult = await executeSingleSdkAttempt({
@@ -651,10 +722,12 @@ export async function executePiStep(options) {
             reuseRuntimeActive,
         });
     }
-    if (!shouldFallbackSdkToCli(sdkResult, validationIssues)) {
-        const failureCategory = validationIssues.length > 0 ? 'invalid-output' : sdkResult.failureCategory;
+    if (!shouldFallbackSdkToCli(sdkResult, validationIssues, options)) {
+        const failureCategory = validationIssues.length > 0
+            ? "invalid-output"
+            : sdkResult.failureCategory;
         const stderr = validationIssues.length > 0
-            ? sdkResult.stderr + `\n[invalid-output] ${validationIssues.join('; ')}`
+            ? sdkResult.stderr + `\n[invalid-output] ${validationIssues.join("; ")}`
             : sdkResult.stderr;
         return withSubagentStats({
             ...sdkResult,
@@ -676,13 +749,13 @@ export async function executePiStep(options) {
 async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
     const modelDisplay = modelConfig.provider && modelConfig.model
         ? `${modelConfig.provider}/${modelConfig.model}`
-        : modelConfig.model ?? 'default';
+        : (modelConfig.model ?? "default");
     const timeoutMs = options.timeoutMs ?? modelConfig.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
     const abortGraceMs = options.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS;
     let timedOut = false;
     let terminationUnconfirmed = false;
-    let supervisionStderr = '';
+    let supervisionStderr = "";
     let timeoutHandle;
     let stallHandle;
     let sigkillHandle;
@@ -690,22 +763,30 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
     // Build pi CLI arguments (same as before).
     // We invoke pi via `node <pi-cli-path>` instead of relying on `#!/usr/bin/env node`
     // to avoid provider resolution issues when spawned from tsx-managed processes.
-    const piArgs = ['-p', '--mode', 'json', '--no-session', '--no-context-files', '--no-skills'];
+    const piArgs = [
+        "-p",
+        "--mode",
+        "json",
+        "--no-session",
+        "--no-context-files",
+        "--no-skills",
+        "--no-extensions",
+    ];
     if (modelConfig.provider) {
-        piArgs.push('--provider', modelConfig.provider);
+        piArgs.push("--provider", modelConfig.provider);
     }
     if (modelConfig.model) {
-        piArgs.push('--model', modelConfig.model);
+        piArgs.push("--model", modelConfig.model);
     }
     if (modelConfig.thinking) {
-        piArgs.push('--thinking', modelConfig.thinking);
+        piArgs.push("--thinking", modelConfig.thinking);
     }
-    piArgs.push('--tools', options.toolNames.join(','));
-    piArgs.push('--append-system-prompt', promptFilePath);
+    piArgs.push("--tools", options.toolNames.join(","));
+    piArgs.push("--append-system-prompt", promptFilePath);
     piArgs.push(...options.attachedFiles.map((file) => `@${file}`));
     piArgs.push(options.userMessage);
-    const recordedPiArgs = piArgs.map((arg, index) => index > 0 && piArgs[index - 1] === '--append-system-prompt'
-        ? '<system-prompt-file>'
+    const recordedPiArgs = piArgs.map((arg, index) => index > 0 && piArgs[index - 1] === "--append-system-prompt"
+        ? "<system-prompt-file>"
         : arg);
     const startedAt = Date.now();
     return await new Promise((resolve, reject) => {
@@ -718,22 +799,22 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
                 // When tsx runs inside a non-login shell, some vars set in ~/.zshrc
                 // may not be in process.env; this ensures pi can resolve providers.
                 HOME: process.env.HOME,
-                DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? '',
-                AIMAX_API_KEY: process.env.AIMAX_API_KEY ?? '',
-                OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY ?? '',
-                NODE_PATH: process.env.NODE_PATH ?? '',
+                DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? "",
+                AIMAX_API_KEY: process.env.AIMAX_API_KEY ?? "",
+                OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY ?? "",
+                NODE_PATH: process.env.NODE_PATH ?? "",
                 // Prevent upstream Node loader hooks (tsx/preload/import) from leaking into pi.
-                NODE_OPTIONS: '',
-                PATH: process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin',
+                NODE_OPTIONS: "",
+                PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
             },
-            stdio: ['ignore', 'pipe', 'pipe'],
+            stdio: ["ignore", "pipe", "pipe"],
         });
-        const stdoutPreview = new BoundedTextPreview('stdout');
-        const stderrPreview = new BoundedTextPreview('stderr', 16_000, 16_000);
+        const stdoutPreview = new BoundedTextPreview("stdout");
+        const stderrPreview = new BoundedTextPreview("stderr", 16_000, 16_000);
         const stdoutCollector = new PiJsonlStreamCollector();
         let settled = false;
-        child.stdout.setEncoding('utf-8');
-        child.stderr.setEncoding('utf-8');
+        child.stdout.setEncoding("utf-8");
+        child.stderr.setEncoding("utf-8");
         const clearSupervisionTimers = () => {
             if (timeoutHandle)
                 clearTimeout(timeoutHandle);
@@ -752,10 +833,12 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
             const durationMs = Date.now() - startedAt;
             const stdout = stdoutPreview.text();
             const capturedStderr = stderrPreview.text();
-            const stderr = [supervisionStderr, capturedStderr].filter(Boolean).join('\n');
+            const stderr = [supervisionStderr, capturedStderr]
+                .filter(Boolean)
+                .join("\n");
             const collected = stdoutCollector.finish();
             const failureCategory = terminationUnconfirmed
-                ? 'termination-unconfirmed'
+                ? "termination-unconfirmed"
                 : classifyPiFailure({
                     assistantText: collected.assistantText,
                     exitCode: code,
@@ -766,12 +849,15 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
                 });
             resolve({
                 assistantText: collected.assistantText,
-                command: ['pi', ...recordedPiArgs],
+                command: ["pi", ...recordedPiArgs],
                 durationMs,
                 exitCode: code,
                 failureCategory,
                 modelDisplay,
-                ok: !timedOut && code === 0 && collected.assistantText.length > 0 && !collected.outputTooLarge,
+                ok: !timedOut &&
+                    code === 0 &&
+                    collected.assistantText.length > 0 &&
+                    !collected.outputTooLarge,
                 parsedEvents: collected.parsedEvents,
                 stderr,
                 stdout,
@@ -789,7 +875,7 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
                 return;
             timedOut = true;
             supervisionStderr = reason;
-            terminateProcessTree(child, 'SIGTERM');
+            terminateProcessTree(child, "SIGTERM");
             sigkillHandle = setTimeout(() => {
                 if (settled)
                     return;
@@ -797,7 +883,7 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
                     finish(child.exitCode);
                     return;
                 }
-                terminateProcessTree(child, 'SIGKILL');
+                terminateProcessTree(child, "SIGKILL");
                 exitConfirmationHandle = setTimeout(() => {
                     if (settled)
                         return;
@@ -823,29 +909,29 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
         const reportOutputActivity = () => {
             armStallWatchdog();
             try {
-                options.onActivity?.({ kind: 'output', at: new Date().toISOString() });
+                options.onActivity?.({ kind: "output", at: new Date().toISOString() });
             }
             catch {
                 // best-effort: never fail the pi step
             }
         };
-        child.stdout.on('data', (chunk) => {
+        child.stdout.on("data", (chunk) => {
             stdoutPreview.append(chunk);
             stdoutCollector.append(chunk);
             if (chunk.length > 0)
                 reportOutputActivity();
         });
-        child.stderr.on('data', (chunk) => {
+        child.stderr.on("data", (chunk) => {
             stderrPreview.append(chunk);
             if (chunk.length > 0)
                 reportOutputActivity();
         });
-        child.on('error', (err) => {
+        child.on("error", (err) => {
             clearSupervisionTimers();
             settled = true;
             reject(err);
         });
-        child.on('close', (code) => {
+        child.on("close", (code) => {
             finish(code);
         });
         armStallWatchdog();
@@ -858,35 +944,35 @@ async function executeSingleCliAttempt(options, modelConfig, promptFilePath) {
 }
 export function shouldRetryWithFallback(stderr, stdout) {
     const category = classifyPiFailure({
-        assistantText: '',
+        assistantText: "",
         exitCode: null,
         stderr,
         stdout,
         timedOut: false,
     });
-    return ['quota', 'rate-limit', 'unavailable', 'network'].includes(category);
+    return ["quota", "rate-limit", "unavailable", "network"].includes(category);
 }
 export function classifyPiFailure(input) {
     if (input.timedOut)
-        return 'timeout';
+        return "timeout";
     if (input.outputTooLarge)
-        return 'output-too-large';
+        return "output-too-large";
     if (input.exitCode === 0 && input.assistantText.trim())
-        return 'success';
+        return "success";
     const combined = `${input.stderr}\n${input.stdout}`.toLowerCase();
     if (/quota|usage limit|reached.*limit|5\s*小时|5小时/.test(combined))
-        return 'quota';
+        return "quota";
     if (/rate.?limit/.test(combined))
-        return 'rate-limit';
+        return "rate-limit";
     if (/unauthorized|forbidden|invalid api key|authentication|auth failed/.test(combined))
-        return 'auth';
+        return "auth";
     if (/unknown provider|unknown model|model.*unavailable|provider.*unavailable|\bunavailable\b|overloaded|capacity|temporarily unavailable/.test(combined))
-        return 'unavailable';
+        return "unavailable";
     if (/network|econnreset|etimedout|socket hang up|connection reset|dns|fetch failed/.test(combined))
-        return 'network';
+        return "network";
     if (input.exitCode === 0 && !input.assistantText.trim())
-        return 'empty-output';
+        return "empty-output";
     if (input.exitCode !== 0)
-        return 'nonzero-exit';
-    return 'unknown';
+        return "nonzero-exit";
+    return "unknown";
 }