@pencil-agent/nano-pencil 1.14.4 → 1.14.6

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.14.4",
-  "commitHash": "092b256",
+  "version": "1.14.6",
+  "commitHash": "111a12b",
   "branch": "main",
-  "builtAt": "2026-05-27T16:26:12.388Z"
+  "builtAt": "2026-05-28T14:39:06.773Z"
 }

package/dist/cli/args.d.ts

@@ -4,7 +4,7 @@
  * [TO]: Consumed by main.ts, core/model-resolver.ts
  * [HERE]: cli/args.ts - CLI argument parsing and help display
  */
-import type { ThinkingLevel } from "@pencil-agent/agent-core";
+import { type AgentLoopFrameworkInput, type AgentLoopPolicyOptions, type ThinkingLevel } from "@pencil-agent/agent-core";
 import { type ToolName } from "../core/tools/index.js";
 export type Mode = "text" | "json" | "rpc";
 export interface Args {
@@ -29,6 +29,16 @@ export interface Args {
     extensions?: string[];
     noExtensions?: boolean;
     print?: boolean;
+    /** In text print mode, emit the final agent loop result as stderr JSON. */
+    printLoopResult?: boolean;
+    /** In print mode, exit non-zero when the final agent result is an error. */
+    failOnAgentError?: boolean;
+    /** In print mode, exit non-zero when any tool permission denial occurred. */
+    failOnToolDenial?: boolean;
+    /** Non-persistent agent loop framework override for this process/session. */
+    agentLoopFramework?: AgentLoopFrameworkInput;
+    /** Non-persistent loop policy overrides for this process/session. */
+    loopPolicy?: Pick<AgentLoopPolicyOptions, "maxTurnsPerPrompt" | "maxToolCallsPerPrompt" | "maxToolConcurrency" | "maxToolResultBatchSizeChars" | "outputTokenBudget" | "maxOutputTokenRecoveryAttempts" | "maxModelErrorRecoveryAttempts" | "maxStopHookContinuations">;
     export?: string;
     noSkills?: boolean;
     skills?: string[];

package/dist/cli/args.js

@@ -1,3 +1,10 @@
+/**
+ * [WHO]: Args, Mode, parseArgs(), printHelp()
+ * [FROM]: Depends on agent-core, chalk, config.ts, core/tools
+ * [TO]: Consumed by main.ts, core/model-resolver.ts
+ * [HERE]: cli/args.ts - CLI argument parsing and help display
+ */
+import { normalizeAgentLoopFramework, } from "@pencil-agent/agent-core";
 import chalk from "chalk";
 import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config.js";
 import { allTools } from "../core/tools/index.js";
@@ -5,12 +12,45 @@ const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh
 export function isValidThinkingLevel(level) {
     return VALID_THINKING_LEVELS.includes(level);
 }
+function parseAgentLoopFramework(value) {
+    const normalized = normalizeAgentLoopFramework(value);
+    if (normalized === "standard" || normalized === "weak-model-compatible") {
+        return normalized;
+    }
+    return undefined;
+}
+function parsePositiveIntegerOption(flag, value) {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed > 0)
+        return parsed;
+    console.error(chalk.yellow(`Warning: Invalid ${flag} value "${value}". Expected a positive integer.`));
+    return undefined;
+}
+function parseNonNegativeIntegerOption(flag, value) {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed) && parsed >= 0)
+        return parsed;
+    console.error(chalk.yellow(`Warning: Invalid ${flag} value "${value}". Expected a non-negative integer.`));
+    return undefined;
+}
+function parseUnitIntervalOption(flag, value) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0 && parsed <= 1)
+        return parsed;
+    console.error(chalk.yellow(`Warning: Invalid ${flag} value "${value}". Expected a number in (0, 1].`));
+    return undefined;
+}
+function setLoopPolicyOption(result, key, value) {
+    result.loopPolicy = result.loopPolicy ?? {};
+    result.loopPolicy[key] = value;
+}
 export function parseArgs(args, extensionFlags) {
     const result = {
         messages: [],
         fileArgs: [],
         unknownFlags: new Map(),
     };
+    const outputTokenBudget = {};
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h") {
@@ -89,6 +129,75 @@ export function parseArgs(args, extensionFlags) {
         else if (arg === "--print" || arg === "-p") {
             result.print = true;
         }
+        else if (arg === "--print-loop-result") {
+            result.printLoopResult = true;
+        }
+        else if (arg === "--fail-on-agent-error") {
+            result.failOnAgentError = true;
+        }
+        else if (arg === "--fail-on-tool-denial") {
+            result.failOnToolDenial = true;
+        }
+        else if (arg === "--agent-loop" && i + 1 < args.length) {
+            const framework = args[++i];
+            const normalized = parseAgentLoopFramework(framework);
+            if (normalized) {
+                result.agentLoopFramework = normalized;
+            }
+            else {
+                console.error(chalk.yellow(`Warning: Invalid agent loop framework "${framework}". Valid values: standard, weak-model-compatible.`));
+            }
+        }
+        else if (arg === "--max-turns-per-prompt" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxTurnsPerPrompt", value);
+        }
+        else if (arg === "--max-tool-calls-per-prompt" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxToolCallsPerPrompt", value);
+        }
+        else if (arg === "--max-tool-concurrency" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxToolConcurrency", value);
+        }
+        else if (arg === "--max-tool-result-batch-size-chars" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxToolResultBatchSizeChars", value);
+        }
+        else if (arg === "--output-token-budget" && i + 1 < args.length) {
+            const value = parsePositiveIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                outputTokenBudget.targetTokens = value;
+        }
+        else if (arg === "--output-token-budget-threshold" && i + 1 < args.length) {
+            const value = parseUnitIntervalOption(arg, args[++i]);
+            if (value !== undefined)
+                outputTokenBudget.thresholdPct = value;
+        }
+        else if (arg === "--output-token-budget-continuations" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                outputTokenBudget.maxContinuations = value;
+        }
+        else if (arg === "--max-output-token-recovery-attempts" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxOutputTokenRecoveryAttempts", value);
+        }
+        else if (arg === "--max-model-error-recovery-attempts" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxModelErrorRecoveryAttempts", value);
+        }
+        else if (arg === "--max-stop-hook-continuations" && i + 1 < args.length) {
+            const value = parseNonNegativeIntegerOption(arg, args[++i]);
+            if (value !== undefined)
+                setLoopPolicyOption(result, "maxStopHookContinuations", value);
+        }
         else if (arg === "--export" && i + 1 < args.length) {
             result.export = args[++i];
         }
@@ -168,6 +277,13 @@ export function parseArgs(args, extensionFlags) {
             result.messages.push(arg);
         }
     }
+    if (outputTokenBudget.targetTokens !== undefined) {
+        setLoopPolicyOption(result, "outputTokenBudget", {
+            targetTokens: outputTokenBudget.targetTokens,
+            thresholdPct: outputTokenBudget.thresholdPct,
+            maxContinuations: outputTokenBudget.maxContinuations,
+        });
+    }
     return result;
 }
 export function printHelp() {
@@ -194,6 +310,20 @@ ${chalk.bold("Options:")}
   --append-system-prompt <text>  Append text or file contents to the system prompt
   --mode <mode>                  Output mode: text (default), json, or rpc
   --print, -p                    Non-interactive mode: process prompt and exit
+  --print-loop-result            In text print mode, write final loop result JSON to stderr
+  --fail-on-agent-error          In print mode, exit non-zero when final loop result is an error
+  --fail-on-tool-denial          In print mode, exit non-zero when tools were denied
+  --agent-loop <framework>       Override loop framework: standard or weak-model-compatible
+  --max-turns-per-prompt <n>     Stop a prompt after n assistant turns
+  --max-tool-calls-per-prompt <n> Stop a prompt after n tool calls
+  --max-tool-concurrency <n>     Max concurrent safe tool calls in compatible loop
+  --max-tool-result-batch-size-chars <n> Max aggregate tool result chars per turn
+  --output-token-budget <n>      Continue when final output is below n tokens
+  --output-token-budget-threshold <n> Continuation threshold ratio in (0,1], default loop policy
+  --output-token-budget-continuations <n> Max output-budget continuations
+  --max-output-token-recovery-attempts <n> Max recovery turns after output-token stops
+  --max-model-error-recovery-attempts <n> Max in-loop model error recoveries
+  --max-stop-hook-continuations <n> Max stop-hook validation continuations
   --continue, -c                 Continue previous session
   --resume, -r                   Select a session to resume
   --session <path>               Use specific session file

package/dist/core/extensions/index.d.ts

@@ -8,6 +8,6 @@ export type { SlashCommandInfo, SlashCommandLocation, SlashCommandSource } from
 export { createExtensionRuntime, discoverAndLoadExtensions, loadExtensionFromFactory, loadExtensions, } from "./loader.js";
 export type { ExtensionErrorListener, ForkHandler, NavigateTreeHandler, NewSessionHandler, ShutdownHandler, SwitchSessionHandler, } from "./runner.js";
 export { ExtensionRunner } from "./runner.js";
-export type { AgentEndEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppAction, AppendEntryHandler, BashToolCallEvent, BashToolResultEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, CompactOptions, ContextEvent, ContextEventResult, ContextUsage, CustomToolCallEvent, CustomToolResultEvent, EditToolCallEvent, EditToolResultEvent, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, FindToolResultEvent, GetActiveToolsHandler, GetAllToolsHandler, GetCommandsHandler, GetThinkingLevelHandler, GrepToolCallEvent, GrepToolResultEvent, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, LsToolResultEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ModelSelectEvent, ModelSelectSource, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, ReadToolResultEvent, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, ResourcesDiscoverResult, SendMessageHandler, SendUserMessageHandler, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeForkEvent, SessionBeforeForkResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionCompactEvent, SessionEvent, SessionForkEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, SetActiveToolsHandler, SetLabelHandler, SetModelHandler, SetThinkingLevelHandler, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, ToolResultEventResult, TreePreparation, TurnEndEvent, TurnStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WriteToolCallEvent, WriteToolResultEvent, } from "./types.js";
+export type { AgentEndEvent, AgentResultEvent, AgentStartEvent, AgentToolResult, AgentToolUpdateCallback, AppAction, AppendEntryHandler, BashToolCallEvent, BashToolResultEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, CompactOptions, ContextEvent, ContextEventResult, ContextUsage, CustomToolCallEvent, CustomToolResultEvent, EditToolCallEvent, EditToolResultEvent, ExecOptions, ExecResult, Extension, ExtensionActions, ExtensionAPI, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFactory, ExtensionFlag, ExtensionHandler, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, ExtensionUIDialogOptions, ExtensionWidgetOptions, FindToolCallEvent, FindToolResultEvent, GetActiveToolsHandler, GetAllToolsHandler, GetCommandsHandler, GetThinkingLevelHandler, GrepToolCallEvent, GrepToolResultEvent, InputEvent, InputEventResult, InputSource, KeybindingsManager, LoadExtensionsResult, LsToolCallEvent, LsToolResultEvent, MessageEndEvent, MessageRenderer, MessageRenderOptions, MessageStartEvent, MessageUpdateEvent, ModelSelectEvent, ModelSelectSource, ProviderConfig, ProviderModelConfig, ReadToolCallEvent, ReadToolResultEvent, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, ResourcesDiscoverResult, SendMessageHandler, SendUserMessageHandler, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeForkEvent, SessionBeforeForkResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionCompactEvent, SessionEvent, SessionForkEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, SetActiveToolsHandler, SetLabelHandler, SetModelHandler, SetThinkingLevelHandler, TerminalInputHandler, ToolCallEvent, ToolCallEventResult, ToolDefinition, ToolExecutionEndEvent, ToolExecutionStartEvent, ToolExecutionUpdateEvent, ToolInfo, ToolRenderResultOptions, ToolResultEvent, ToolResultEventResult, TreePreparation, TurnEndEvent, TurnStartEvent, UserBashEvent, UserBashEventResult, WidgetPlacement, WriteToolCallEvent, WriteToolResultEvent, } from "./types.js";
 export { isBashToolResult, isEditToolResult, isFindToolResult, isGrepToolResult, isLsToolResult, isReadToolResult, isToolCallEventType, isWriteToolResult, } from "./types.js";
 export { wrapRegisteredTool, wrapRegisteredTools, wrapToolsWithExtensions, wrapToolWithExtensions, } from "./wrapper.js";

package/dist/core/extensions/types.d.ts

@@ -4,7 +4,7 @@
  * [TO]: Consumed by core/extensions/index.ts, core/extensions/runner.ts, core/extensions/wrapper.ts, all extension entry points (defaults/loop, defaults/team, defaults/mcp, defaults/soul, defaults/presence, defaults/security-audit, defaults/link-world, defaults/interview, optional/simplify, optional/export-html), modes/interactive/components/tool-execution.ts, modes/interactive/components/custom-message.ts, modes/acp/acp-mode.ts
  * [HERE]: core/extensions/types.ts - type definitions for extension system API
  */
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, AgentLoopFramework, ThinkingLevel } from "@pencil-agent/agent-core";
+import type { AgentMessage, AgentRunResult, AgentToolResult, AgentToolUpdateCallback, AgentLoopFramework, ThinkingLevel } from "@pencil-agent/agent-core";
 import type { Api, AssistantMessageEvent, AssistantMessageEventStream, Context, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, SimpleStreamOptions, TextContent, ToolResultMessage, Usage } from "@pencil-agent/ai";
 import type { AutocompleteItem, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "@pencil-agent/tui";
 import type { Static, TSchema } from "@sinclair/typebox";
@@ -418,6 +418,10 @@ export interface AgentEndEvent {
     type: "agent_end";
     messages: AgentMessage[];
 }
+/** Fired with structured loop outcome metadata before agent_end */
+export interface AgentResultEvent extends AgentRunResult {
+    type: "agent_result";
+}
 /** Fired at the start of each turn */
 export interface TurnStartEvent {
     type: "turn_start";
@@ -628,7 +632,7 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
+export type ExtensionEvent = ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | AgentResultEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
 export interface ContextEventResult {
     messages?: AgentMessage[];
 }
@@ -723,6 +727,7 @@ export interface ExtensionAPI {
     on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
     on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
     on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
+    on(event: "agent_result", handler: ExtensionHandler<AgentResultEvent>): void;
     on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
     on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
     on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;

package/dist/core/runtime/agent-session.d.ts

@@ -1,5 +1,5 @@
-import type { Agent, AgentEvent, AgentLoopFramework, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "@pencil-agent/agent-core";
-import type { ImageContent, Model, TextContent } from "@pencil-agent/ai";
+import type { Agent, AgentEvent, AgentLoopFramework, AgentLoopPolicyOptions, AgentMessage, AgentState, AgentTool, ThinkingLevel } from "@pencil-agent/agent-core";
+import type { AssistantMessage, ImageContent, Model, TextContent } from "@pencil-agent/ai";
 /**
  * Custom error for model cycling with additional context.
  */
@@ -37,6 +37,7 @@ export interface ParsedSkillBlock {
  * Returns null if the text doesn't contain a skill block.
  */
 export declare function parseSkillBlock(text: string): ParsedSkillBlock | null;
+export declare function pruneRecoverableErrorTail(messages: AgentMessage[], assistantMessage: AssistantMessage): AgentMessage[];
 /** Session-specific events that extend the core AgentEvent */
 export type AgentSessionEvent = AgentEvent | {
     type: "auto_compaction_start";
@@ -465,6 +466,8 @@ export declare class AgentSession {
     setThinkingLevel(level: ThinkingLevel): void;
     /** Set the session-level agent loop framework override. */
     setAgentLoopFramework(framework: AgentLoopFrameworkInput | undefined): void;
+    /** Update runtime loop policy options for subsequent turns. */
+    setLoopPolicy(options: Partial<AgentLoopPolicyOptions>): void;
     /**
      * Cycle to next thinking level.
      * @returns New level, or undefined if model doesn't support thinking

package/dist/core/runtime/agent-session.js

@@ -1,5 +1,5 @@
 /**
- * [WHO]: AgentSession class, session lifecycle, event emission, in-loop context-overflow recovery adapter
+ * [WHO]: AgentSession class, session lifecycle, event emission, in-loop recovery adapter, pruneRecoverableErrorTail()
  * [FROM]: Depends on agent-core, ai, core/tools/*, core/session/*, core/config/*
  * [TO]: Consumed by core/index.ts, core/runtime/sdk.ts, modes/interactive/interactive-mode.ts, modes/print-mode.ts, modes/rpc/rpc-mode.ts, modes/acp/acp-mode.ts, modes/rpc/rpc-types.ts, modes/rpc/rpc-client.ts, modes/interactive/components/footer.ts, modes/interactive/components/skill-invocation-message.ts
  * [HERE]: Central runtime hub; all modes delegate to this class
@@ -58,6 +58,34 @@ export function parseSkillBlock(text) {
         userMessage: match[4]?.trim() || undefined,
     };
 }
+export function pruneRecoverableErrorTail(messages, assistantMessage) {
+    const interruptedToolCallIds = new Set(assistantMessage.content
+        .filter((part) => part.type === "toolCall")
+        .map((part) => part.id));
+    let end = messages.length;
+    while (end > 0 &&
+        isRecoverableTailToolResult(messages[end - 1], interruptedToolCallIds)) {
+        end--;
+    }
+    if (end > 0 &&
+        isSameRecoverableAssistantMessage(messages[end - 1], assistantMessage)) {
+        end--;
+    }
+    return messages.slice(0, end);
+}
+function isRecoverableTailToolResult(message, interruptedToolCallIds) {
+    return (message.role === "toolResult" &&
+        interruptedToolCallIds.has(message.toolCallId));
+}
+function isSameRecoverableAssistantMessage(message, assistantMessage) {
+    return (message.role === "assistant" &&
+        message.stopReason === assistantMessage.stopReason &&
+        message.timestamp === assistantMessage.timestamp &&
+        message.provider === assistantMessage.provider &&
+        message.model === assistantMessage.model &&
+        message.api === assistantMessage.api &&
+        message.errorMessage === assistantMessage.errorMessage);
+}
 // ============================================================================
 // Constants
 // ============================================================================
@@ -432,6 +460,10 @@ export class AgentSession {
             this._turnIndex = 0;
             await this._extensionRunner.emit({ type: "agent_start" });
         }
+        else if (event.type === "agent_result") {
+            const extensionEvent = { ...event };
+            await this._extensionRunner.emit(extensionEvent);
+        }
         else if (event.type === "turn_start") {
             const extensionEvent = {
                 type: "turn_start",
@@ -1334,6 +1366,10 @@ export class AgentSession {
     setAgentLoopFramework(framework) {
         this.agent.setAgentLoopFramework(framework);
     }
+    /** Update runtime loop policy options for subsequent turns. */
+    setLoopPolicy(options) {
+        this.agent.setLoopPolicy(options);
+    }
     /**
      * Cycle to next thinking level.
      * @returns New level, or undefined if model doesn't support thinking
@@ -1589,8 +1625,7 @@ export class AgentSession {
             const shouldRetry = await this._retryCoordinator.handleErrorInLoop(assistantMessage);
             if (!shouldRetry)
                 return { action: "stop" };
-            const messages = this.agent.state.messages;
-            const retryMessages = messages.at(-1)?.role === "assistant" ? messages.slice(0, -1) : messages;
+            const retryMessages = pruneRecoverableErrorTail(this.agent.state.messages, assistantMessage);
             this.agent.replaceMessages(retryMessages);
             return {
                 action: "retry",
@@ -1617,10 +1652,7 @@ export class AgentSession {
         if (errorIsFromBeforeCompaction)
             return { action: "stop" };
         const messages = this.agent.state.messages;
-        if (messages.length > 0 &&
-            messages[messages.length - 1].role === "assistant") {
-            this.agent.replaceMessages(messages.slice(0, -1));
-        }
+        this.agent.replaceMessages(pruneRecoverableErrorTail(messages, assistantMessage));
         const recoveredMessages = await this._runAutoCompaction("overflow", true, {
             triggerContinue: false,
         });

package/dist/core/runtime/sdk.d.ts

@@ -1,4 +1,4 @@
-import { type ThinkingLevel } from "@pencil-agent/agent-core";
+import { type AgentLoopFrameworkInput, type AgentLoopPolicyOptions, type ThinkingLevel } from "@pencil-agent/agent-core";
 import type { Model } from "@pencil-agent/ai";
 import { AgentSession } from "./agent-session.js";
 import { AuthStorage } from "../config/auth-storage.js";
@@ -41,6 +41,26 @@ export interface CreateAgentSessionOptions {
     model?: Model<any>;
     /** Thinking level. Default: from settings, else 'medium' (clamped to model capabilities) */
     thinkingLevel?: ThinkingLevel;
+    /** Session-level agent loop framework override. Default: from settings/model. */
+    agentLoopFramework?: AgentLoopFrameworkInput;
+    /** Optional runtime loop policy overrides applied at session creation. */
+    loopPolicy?: Pick<AgentLoopPolicyOptions, "maxTurnsPerPrompt" | "maxToolCallsPerPrompt" | "maxToolConcurrency" | "maxToolResultBatchSizeChars" | "outputTokenBudget" | "maxOutputTokenRecoveryAttempts" | "maxModelErrorRecoveryAttempts" | "maxStopHookContinuations">;
+    /** Maximum assistant turns allowed for one prompt. */
+    maxTurnsPerPrompt?: number;
+    /** Maximum tool calls allowed for one prompt. */
+    maxToolCallsPerPrompt?: number;
+    /** Maximum concurrent safe tool calls in compatible loops. */
+    maxToolConcurrency?: number;
+    /** Aggregate tool-result batch budget in characters. */
+    maxToolResultBatchSizeChars?: number;
+    /** Optional target for automatic continuation when output is under-complete. */
+    outputTokenBudget?: AgentLoopPolicyOptions["outputTokenBudget"];
+    /** Maximum automatic output-token recovery turns per prompt. */
+    maxOutputTokenRecoveryAttempts?: number;
+    /** Maximum in-loop model error recoveries per prompt. */
+    maxModelErrorRecoveryAttempts?: number;
+    /** Maximum stop-hook validation/correction continuations per prompt. */
+    maxStopHookContinuations?: number;
     /** Models available for cycling (Ctrl+P in interactive mode) */
     scopedModels?: Array<{
         model: Model<any>;

package/dist/core/runtime/sdk.js

@@ -1,5 +1,5 @@
 /**
- * [WHO]: createAgentSession(options) → AgentSession + load results, runtime loop setting wiring
+ * [WHO]: createAgentSession(options) → AgentSession + load results, loop framework/policy override wiring
  * [FROM]: Depends on agent-core, ai, core/config/*, core/tools/*, core/session/*, core/mcp-*, i18n/*
  * [TO]: Consumed by index.ts, main.ts, test/presence-opening.test.ts, extensions/defaults/team/index.ts
  * [HERE]: SDK factory; creates all services with DI, wires up extensions
@@ -247,10 +247,19 @@ export async function createAgentSession(options = {}) {
         steeringMode: settingsManager.getSteeringMode(),
         followUpMode: settingsManager.getFollowUpMode(),
         transport: settingsManager.getTransport(),
-        agentLoopFramework: settingsManager.getAgentLoopFramework(),
+        agentLoopFramework: options.agentLoopFramework ?? settingsManager.getAgentLoopFramework(),
         thinkingBudgets: settingsManager.getThinkingBudgets(),
         maxRetryDelayMs: settingsManager.getRetrySettings().maxDelayMs,
-        maxToolResultBatchSizeChars: settingsManager.getAgentLoopSettings().maxToolResultBatchSizeChars,
+        maxToolResultBatchSizeChars: options.maxToolResultBatchSizeChars ??
+            options.loopPolicy?.maxToolResultBatchSizeChars ??
+            settingsManager.getAgentLoopSettings().maxToolResultBatchSizeChars,
+        maxToolConcurrency: options.maxToolConcurrency ?? options.loopPolicy?.maxToolConcurrency,
+        maxTurnsPerPrompt: options.maxTurnsPerPrompt ?? options.loopPolicy?.maxTurnsPerPrompt,
+        maxToolCallsPerPrompt: options.maxToolCallsPerPrompt ?? options.loopPolicy?.maxToolCallsPerPrompt,
+        outputTokenBudget: options.outputTokenBudget ?? options.loopPolicy?.outputTokenBudget,
+        maxOutputTokenRecoveryAttempts: options.maxOutputTokenRecoveryAttempts ?? options.loopPolicy?.maxOutputTokenRecoveryAttempts,
+        maxModelErrorRecoveryAttempts: options.maxModelErrorRecoveryAttempts ?? options.loopPolicy?.maxModelErrorRecoveryAttempts,
+        maxStopHookContinuations: options.maxStopHookContinuations ?? options.loopPolicy?.maxStopHookContinuations,
         getApiKey: async (provider) => {
             // Use the provider argument from the in-flight request;
             // agent.state.model may already be switched mid-turn.

package/dist/extensions/defaults/AGENT.md

@@ -68,11 +68,11 @@ loop/scheduler-controller.ts: SchedulerController - in-memory recurring task sto
 loop/scheduler-parser.ts: Loop command parsing with flags/subcommands, parseSchedulerCommand/parseDurationSpec/buildSchedulerHelp, --name/--max/--quiet
 loop/scheduler-types.ts: Scheduled loop types, LoopPayloadKind/ScheduledLoopTask/LoopStartSpec/ParsedSchedulerCommand
 loop/README.md: Loop extension documentation - recurring scheduler usage and flags
-sal/index.ts: SAL extension entry, enabled by default, registers flags, /sal:* commands, lifecycle hooks, terrain snapshot refresh, eval event emission, and stale-run cleanup scheduling; delegates config, context, runtime contracts, and tool_trace analytics to focused SAL modules
+sal/index.ts: SAL extension entry, enabled by default, registers flags, /sal:* commands, lifecycle hooks including agent_result, terrain snapshot refresh, eval event emission, and stale-run cleanup scheduling; delegates config, context, runtime contracts, and tool_trace analytics to focused SAL modules
 sal/sal-config.ts: SAL build metadata, eval environment constants, credential loading, truthy parsing, stale-cleanup/A-B flag resolution, experiment id normalization, and sidecar directory resolution
 sal/sal-context.ts: SAL anchor system-prompt injection formatting plus A/B sidecar turn-record persistence
-sal/sal-runtime.ts: SAL shared BuildMeta/TurnState/SalRuntime contracts used across config, context, trace, and entry modules
-sal/sal-trace.ts: SAL tool path extraction, task intent inference, and bounded tool_trace payload construction
+sal/sal-runtime.ts: SAL shared BuildMeta/TurnState/SalRuntime contracts used across config, context, trace, and entry modules, including per-turn loop outcome state
+sal/sal-trace.ts: SAL tool path extraction, task intent inference, and bounded tool_trace payload construction with loop outcome summary
 sal/terrain.ts: TerrainSnapshot/TerrainNode/TerrainEdge model, buildTerrainIndex(), checkDipCoverage(), isSnapshotStale(), moduleIdForPath(), parses P2 AGENT.md and P3 file headers
 sal/anchors.ts: StructuralAnchor/AnchorResolution model, locateTask(), locateAction(), evidence-driven scoring with tunable SalWeights, CJK bigram tokenization
 sal/weights.ts: SalWeights interface, SAL_DEFAULT_WEIGHTS, loadSalWeights() reads sal-config.json from workspace or .memory-experiments/sal/

package/dist/extensions/defaults/CLAUDE.md

@@ -49,7 +49,7 @@ plan/exit-plan-mode-tool.ts: createExitPlanModeTool() - ExitPlanMode tool with p
 plan/plan-agents.ts: Explore/Plan subagent definitions with read-only tools for plan mode workflow
 plan/plan-validation.ts: validatePlan() - validates plan has required sections (Context, Approach, Files, Verification)
 plan/teammate-approval.ts: isInTeammateContext(), submitPlanToLeader(), formatPlanSubmittedMessage() - teammate plan approval integration
-sal/index.ts: SAL extension entry, enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_end hooks; /sal:setup writes ~/.memory-experiments/credentials.json with adapter inference (insforge/jsonl/noop); publishes structuralAnchor via core/runtime/turn-context (no SAL-specific globals); emits run_start/turn_anchor/memory_recalls/tool_trace/run_end eval events through pluggable EvalSink; reads memoryRecallSnapshot from turn-context bus in agent_end; runtime no-op when --nosal is set; auto-injects pencil_version from build-meta.json into run_start; emergency flush on beforeExit/SIGHUP/SIGTERM; stale run cleanup is opt-in via NANOPENCIL_EVAL_CLEANUP_STALE_RUNS / credentials cleanup_stale_runs; tool_trace is a bounded per-turn summary and includes no-tool turns
+sal/index.ts: SAL extension entry, enabled by default, registers --nosal/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_result/agent_end hooks; /sal:setup writes ~/.memory-experiments/credentials.json with adapter inference (insforge/jsonl/noop); publishes structuralAnchor via core/runtime/turn-context (no SAL-specific globals); emits run_start/turn_anchor/memory_recalls/tool_trace/run_end eval events through pluggable EvalSink; reads memoryRecallSnapshot from turn-context bus in agent_end; runtime no-op when --nosal is set; auto-injects pencil_version from build-meta.json into run_start; emergency flush on beforeExit/SIGHUP/SIGTERM; stale run cleanup is opt-in via NANOPENCIL_EVAL_CLEANUP_STALE_RUNS / credentials cleanup_stale_runs; tool_trace is a bounded per-turn summary and includes no-tool turns plus loop outcome
 sal/terrain.ts: TerrainSnapshot/TerrainNode/TerrainEdge model, async buildTerrainIndex()/isSnapshotStale() (fs/promises + periodic yields so TUI can flush under block terminals like Warp), checkDipCoverage(), moduleIdForPath(), parses P2 CLAUDE.md and P3 file headers
 sal/anchors.ts: StructuralAnchor/AnchorResolution model, locateTask(), locateAction(), evidence-driven scoring with tunable SalWeights, CJK bigram tokenization
 sal/weights.ts: SalWeights interface, SAL_DEFAULT_WEIGHTS, loadSalWeights() reads sal-config.json from workspace or .memory-experiments/sal/

package/dist/extensions/defaults/sal/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-ab/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_end hooks; runtime no-op when --nosal is set
+ * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-ab/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_result/agent_end hooks; runtime no-op when --nosal is set
  * [FROM]: Depends on core/extensions/types.ts (ToolExecutionStartEvent, ToolExecutionEndEvent), core/runtime/turn-context.ts (publishes structuralAnchor), extensions/defaults/sal/terrain.ts, anchors.ts, weights.ts, eval/index.ts (pluggable adapters)
  * [TO]: Loaded by builtin-extensions.ts as a default extension entry point
- * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/tool_trace/run_end eval events with best-effort flush/close isolation; tool_trace captures per-turn tool usage profile (call counts, sequences, intent, errors) for self-awareness analytics
+ * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/tool_trace/run_end eval events with best-effort flush/close isolation; tool_trace captures per-turn tool usage and loop outcome for self-awareness analytics
  */
 import type { ExtensionAPI } from "../../../core/extensions/types.js";
 import { SAL_DEFAULT_WEIGHTS } from "./weights.js";

package/dist/extensions/defaults/sal/index.js

@@ -1,8 +1,8 @@
 /**
- * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-ab/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_end hooks; runtime no-op when --nosal is set
+ * [WHO]: SAL extension entry - enabled by default, registers --nosal/--sal-ab/--sal-rebuild-terrain flags, /sal:coverage /sal:status /sal:setup commands, before_agent_start/tool_execution_start/tool_execution_end/agent_result/agent_end hooks; runtime no-op when --nosal is set
  * [FROM]: Depends on core/extensions/types.ts (ToolExecutionStartEvent, ToolExecutionEndEvent), core/runtime/turn-context.ts (publishes structuralAnchor), extensions/defaults/sal/terrain.ts, anchors.ts, weights.ts, eval/index.ts (pluggable adapters)
  * [TO]: Loaded by builtin-extensions.ts as a default extension entry point
- * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/tool_trace/run_end eval events with best-effort flush/close isolation; tool_trace captures per-turn tool usage profile (call counts, sequences, intent, errors) for self-awareness analytics
+ * [HERE]: extensions/defaults/sal/index.ts - pluggable Structural Anchor Localization (SAL) extension; emits run_start/turn_anchor/tool_trace/run_end eval events with best-effort flush/close isolation; tool_trace captures per-turn tool usage and loop outcome for self-awareness analytics
  */
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -549,6 +549,20 @@ export default async function salExtension(api) {
             record.isError = event.isError;
         }
     });
+    api.on("agent_result", async (event, _ctx) => {
+        runtime.turn.agentResult = {
+            stopReason: event.stopReason,
+            turnCount: event.turnCount,
+            toolCallCount: event.toolCallCount,
+            durationMs: event.durationMs,
+            usage: event.usage,
+            permissionDenialCount: event.permissionDenialCount,
+            permissionDenials: event.permissionDenials,
+            lastTransition: event.lastTransition,
+            errorMessage: event.errorMessage,
+            errorSubtype: event.errorSubtype,
+        };
+    });
     api.on("agent_end", async (_event, _ctx) => {
         const turnDuration = Math.max(0, Date.now() - runtime.turn.startedAtMs);
         const taskRes = runtime.turn.taskResolution;

package/dist/extensions/defaults/sal/sal-runtime.d.ts

@@ -2,9 +2,10 @@
  * [WHO]: Provides BuildMeta, ToolCallRecord, TurnState, SalDiagnosticReporter, SalRuntime shared contracts for the SAL extension
  * [FROM]: Depends on eval sink types, SAL anchors/terrain/weights types for runtime state shape
  * [TO]: Consumed by extensions/defaults/sal/index.ts plus SAL config, trace, and context helpers
- * [HERE]: extensions/defaults/sal/sal-runtime.ts - runtime contract boundary for Structural Anchor Localization modules
+ * [HERE]: extensions/defaults/sal/sal-runtime.ts - runtime contract boundary for Structural Anchor Localization modules, including per-turn loop outcome state
  */
 import type { CreateEvalSinkOptions, EvalAdapterId, EvalSink, EvalVariant } from "./eval/index.js";
+import type { AgentRunResult } from "@pencil-agent/agent-core";
 import type { AnchorResolution } from "./anchors.js";
 import type { TerrainSnapshot } from "./terrain.js";
 import type { SalWeights } from "./weights.js";
@@ -24,6 +25,7 @@ export interface TurnState {
     turnId: number;
     startedAtMs: number;
     taskResolution?: AnchorResolution;
+    agentResult?: AgentRunResult;
     touchedFiles: Set<string>;
     toolCalls: ToolCallRecord[];
     prompt?: string;

package/dist/extensions/defaults/sal/sal-runtime.js

@@ -2,6 +2,6 @@
  * [WHO]: Provides BuildMeta, ToolCallRecord, TurnState, SalDiagnosticReporter, SalRuntime shared contracts for the SAL extension
  * [FROM]: Depends on eval sink types, SAL anchors/terrain/weights types for runtime state shape
  * [TO]: Consumed by extensions/defaults/sal/index.ts plus SAL config, trace, and context helpers
- * [HERE]: extensions/defaults/sal/sal-runtime.ts - runtime contract boundary for Structural Anchor Localization modules
+ * [HERE]: extensions/defaults/sal/sal-runtime.ts - runtime contract boundary for Structural Anchor Localization modules, including per-turn loop outcome state
  */
 export {};

package/dist/extensions/defaults/sal/sal-trace.d.ts

@@ -2,7 +2,7 @@
  * [WHO]: Provides SAL tool-path extraction, task intent inference, and bounded tool_trace payload construction
  * [FROM]: Depends on node path helpers and terrain path normalization
  * [TO]: Consumed by extensions/defaults/sal/index.ts and SAL tool trace tests
- * [HERE]: extensions/defaults/sal/sal-trace.ts - per-turn tool analytics boundary for Structural Anchor Localization
+ * [HERE]: extensions/defaults/sal/sal-trace.ts - per-turn tool and loop-outcome analytics boundary for Structural Anchor Localization
  */
 import type { TurnState } from "./sal-runtime.js";
 export type TaskIntent = "fix" | "feat" | "refactor" | "explain" | "explore" | "unknown";

package/dist/extensions/defaults/sal/sal-trace.js

@@ -2,7 +2,7 @@
  * [WHO]: Provides SAL tool-path extraction, task intent inference, and bounded tool_trace payload construction
  * [FROM]: Depends on node path helpers and terrain path normalization
  * [TO]: Consumed by extensions/defaults/sal/index.ts and SAL tool trace tests
- * [HERE]: extensions/defaults/sal/sal-trace.ts - per-turn tool analytics boundary for Structural Anchor Localization
+ * [HERE]: extensions/defaults/sal/sal-trace.ts - per-turn tool and loop-outcome analytics boundary for Structural Anchor Localization
  */
 import { isAbsolute, join, relative } from "node:path";
 import { toPosixPath } from "./terrain.js";
@@ -108,7 +108,7 @@ export function buildToolTracePayload(turn, turnDuration) {
     }));
     const sequence = turn.toolCalls.slice(0, MAX_TOOL_SEQUENCE).map((tc) => tc.tool);
     const completedToolCalls = turn.toolCalls.filter((tc) => tc.endMs != null).length;
-    return {
+    const payload = {
         turn_id: turn.turnId,
         tool_calls: summarizedTools,
         tool_sequence: sequence,
@@ -126,4 +126,15 @@ export function buildToolTracePayload(turn, turnDuration) {
         truncated_tool_summary: Math.max(0, toolSummary.size - summarizedTools.length),
         duration_ms: turnDuration,
     };
+    if (turn.agentResult) {
+        payload.agent_loop = {
+            stop_reason: turn.agentResult.stopReason,
+            turn_count: turn.agentResult.turnCount,
+            tool_call_count: turn.agentResult.toolCallCount,
+            duration_ms: turn.agentResult.durationMs,
+            permission_denial_count: turn.agentResult.permissionDenialCount ?? 0,
+            last_transition_reason: turn.agentResult.lastTransition?.reason,
+        };
+    }
+    return payload;
 }

package/dist/main.js

@@ -515,6 +515,12 @@ function buildSessionOptions(parsed, scopedModels, sessionManager, modelRegistry
     if (parsed.thinking) {
         options.thinkingLevel = parsed.thinking;
     }
+    if (parsed.agentLoopFramework) {
+        options.agentLoopFramework = parsed.agentLoopFramework;
+    }
+    if (parsed.loopPolicy) {
+        options.loopPolicy = parsed.loopPolicy;
+    }
     // Scoped models for Ctrl+P cycling - fill in default thinking level for models without explicit level
     if (scopedModels.length > 0) {
         const defaultThinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
@@ -894,16 +900,19 @@ export async function main(args) {
         await mode.run();
     }
     else {
-        await runPrintMode(session, {
+        const printResult = await runPrintMode(session, {
             mode,
             messages: parsed.messages,
             initialMessage,
             initialImages,
+            printLoopResult: parsed.printLoopResult,
+            failOnAgentError: parsed.failOnAgentError,
+            failOnToolDenial: parsed.failOnToolDenial,
         });
         stopThemeWatcher();
         if (process.stdout.writableLength > 0) {
             await new Promise((resolve) => process.stdout.once("drain", resolve));
         }
-        process.exit(0);
+        process.exit(printResult.exitCode);
     }
 }