@gajae-code/agent-core 0.12.8 → 0.12.11

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.12.11] - 2026-08-03
+
+## [0.12.10] - 2026-08-03
+
+### Fixed
+
+- Composer repository-file shell policy rejections now receive one bounded, tool-enabled recovery turn without persisting the synthetic instruction. Generic loops retain their repository tools with `toolChoice: auto`; Cursor remote turns continue only when native tools did not already recover, queued user follow-ups take priority, and a second policy block terminates instead of looping. Existing malformed-tool recovery remains tool-free and does not consume dynamic tool-choice state.
+
 ## [0.12.8] - 2026-08-02
 
 ## [0.12.7] - 2026-07-31

package/dist/types/types.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TransportFailureFacts, TSchema } from "@gajae-code/ai";
+import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TransportFailureFacts, TSchema, UserMessage } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AttemptMinter, AttemptRunHandle, AttemptScope } from "./attempt-scope";
 import type { HarmonyAuditEvent } from "./harmony-leak";
@@ -292,6 +292,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * continues with another turn.
      */
     getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Supplies one bounded synthetic recovery instruction before the loop would
+     * otherwise yield. Unlike a follow-up, it is sent only to the provider and
+     * is not committed to durable agent message history.
+     */
+    getSyntheticRecoveryMessage?: () => Promise<UserMessage | undefined>;
     /**
      * Cooperative pause checkpoint evaluated at safe loop boundaries.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.12.8",
+	"version": "0.12.11",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.12.8",
-		"@gajae-code/natives": "0.12.8",
-		"@gajae-code/utils": "0.12.8",
+		"@gajae-code/ai": "0.12.11",
+		"@gajae-code/natives": "0.12.11",
+		"@gajae-code/utils": "0.12.11",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -20,6 +20,10 @@ import {
 	validateToolArguments,
 	zodToWireSchema,
 } from "@gajae-code/ai";
+import {
+	COMPOSER_BASH_POLICY_RECOVERY_PROMPT,
+	isCurrentComposerBashPolicyBlockedError,
+} from "@gajae-code/ai/providers/composer-discipline";
 import { isInvalidPromptError, neutralizeReservedControlTokens } from "@gajae-code/ai/utils";
 import { sanitizeText } from "@gajae-code/utils";
 import type { AttemptScope } from "./attempt-scope";
@@ -123,6 +127,15 @@ const standaloneOwnershipStates = new WeakMap<StandaloneRunOwnership, Standalone
  * bounded too.
  */
 const MAX_CONSECUTIVE_MALFORMED_TURNS = 5;
+
+function isComposerBashPolicyBlockedToolResult(result: ToolResultMessage): boolean {
+	return (
+		result.isError &&
+		result.toolName === "bash" &&
+		result.content.some(content => content.type === "text" && isCurrentComposerBashPolicyBlockedError(content.text))
+	);
+}
+
 function managedContextOverflow(message: AssistantMessage, config: AgentLoopConfig): boolean {
 	const transportFailure = managedTransportFailure(message);
 	// Managed empty-stop responses may be repaired by the managed shell below; only
@@ -150,12 +163,11 @@ function managedRetryableFailure(failure: unknown): boolean {
 	const facts = managedTransportFailure(failure);
 	if (!facts) return false;
 	const trigger = classifyFallbackTrigger(facts);
-	return (
-		trigger.class === "rate_limit" ||
-		trigger.class === "quota" ||
-		trigger.class === "auth" ||
-		trigger.class === "server"
-	);
+	// A plain `forbidden` is terminal: retrying it just re-sends a request the
+	// caller is not authorized to make, and the credential-mutating consumers
+	// downstream would block healthy credentials on the way.
+	if (trigger.class === "auth") return trigger.authDisposition !== "forbidden";
+	return trigger.class === "rate_limit" || trigger.class === "quota" || trigger.class === "server";
 }
 
 /**
@@ -1407,12 +1419,16 @@ async function runLoopBody(
 	// `invalid_prompt` circuit breaker below.
 	let invalidPromptRepairAttempted = false;
 	let previousMalformedToolSignatures = new Set<string>();
-	const recoveryState: {
-		pending: boolean;
-		inserted: boolean;
-		syntheticMessage?: UserMessage;
-	} = { pending: false, inserted: false };
+	type SyntheticRecoveryKind = "malformed-tool-call" | "composer-bash-policy" | "provider";
+	let pendingRecovery:
+		| {
+				kind: SyntheticRecoveryKind;
+				inserted: boolean;
+				syntheticMessage?: UserMessage;
+		  }
+		| undefined;
 	let malformedToolRecoveryAttempted = false;
+	let composerBashPolicyRecoveryAttempted = false;
 	// Deterministic terminal circuit breaker for argument-validation loops.
 	//
 	// Counts CONSECUTIVE turns whose tool calls were all malformed, regardless of
@@ -1507,6 +1523,8 @@ async function runLoopBody(
 			let recovered: HarmonyRecoveredToolCall | undefined;
 			let message: AssistantMessage;
 			const attemptTransaction = transaction;
+			const recoveryAttempt = pendingRecovery;
+			const wasMalformedToolRecoveryAttempt = recoveryAttempt?.kind === "malformed-tool-call";
 			try {
 				const attemptConfig = attemptTransaction
 					? {
@@ -1515,14 +1533,22 @@ async function runLoopBody(
 								attemptTransaction.stageAssistantMessageEvent(partial, event),
 						}
 					: config;
-				if (recoveryState.pending && !recoveryState.inserted) {
-					recoveryState.syntheticMessage = {
-						role: "user",
-						content: repeatedToolFailureRecoveryPrompt,
-						synthetic: true,
-						timestamp: Date.now(),
-					};
-					recoveryState.inserted = true;
+				if (recoveryAttempt && !recoveryAttempt.inserted) {
+					const recoveryContent =
+						recoveryAttempt.kind === "composer-bash-policy"
+							? COMPOSER_BASH_POLICY_RECOVERY_PROMPT
+							: recoveryAttempt.kind === "malformed-tool-call"
+								? repeatedToolFailureRecoveryPrompt
+								: undefined;
+					if (recoveryContent) {
+						recoveryAttempt.syntheticMessage = {
+							role: "user",
+							content: recoveryContent,
+							synthetic: true,
+							timestamp: Date.now(),
+						};
+					}
+					recoveryAttempt.inserted = true;
 				}
 				message = await streamAssistantResponse(
 					currentContext,
@@ -1535,8 +1561,12 @@ async function runLoopBody(
 					attemptScope,
 					streamFn,
 					harmonyRetryAttempt,
-					recoveryState.pending && recoveryState.syntheticMessage
-						? { syntheticMessage: recoveryState.syntheticMessage }
+					recoveryAttempt?.syntheticMessage
+						? {
+								syntheticMessage: recoveryAttempt.syntheticMessage,
+								disableTools: wasMalformedToolRecoveryAttempt,
+								forceAutoToolChoice: !wasMalformedToolRecoveryAttempt,
+							}
 						: undefined,
 				);
 				const detection = detectHarmonyLeakInAssistantMessage(message);
@@ -1708,8 +1738,6 @@ async function runLoopBody(
 			if (config.fallbackManaged && message.stopReason !== "error" && message.stopReason !== "aborted") {
 				await config.onManagedAttemptAccepted?.();
 			}
-			const wasRecoveryAttempt = recoveryState.pending;
-
 			if (message.stopReason === "error" || message.stopReason === "aborted") {
 				// Create placeholder tool results for any tool calls in the aborted message
 				// This maintains the tool_use/tool_result pairing that the API requires
@@ -1749,8 +1777,9 @@ async function runLoopBody(
 
 			const toolResults: ToolResultMessage[] = [];
 			let repeatedMalformedToolCall = false;
+			let sawComposerBashPolicyBlock = false;
 			if (hasMoreToolCalls) {
-				if (wasRecoveryAttempt) {
+				if (wasMalformedToolRecoveryAttempt) {
 					for (const toolCall of toolCalls) {
 						const result = createAbortedToolResult(
 							toolCall,
@@ -1781,6 +1810,7 @@ async function runLoopBody(
 
 					toolResults.push(...executionResult.toolResults);
 					steeringMessagesFromExecution = executionResult.steeringMessages;
+					sawComposerBashPolicyBlock = executionResult.toolResults.some(isComposerBashPolicyBlockedToolResult);
 
 					const malformedSignatures = executionResult.malformedToolCallSignatures;
 					const allToolCallsMalformed =
@@ -1804,10 +1834,8 @@ async function runLoopBody(
 				}
 			}
 
-			if (wasRecoveryAttempt) {
-				recoveryState.pending = false;
-				recoveryState.inserted = false;
-				recoveryState.syntheticMessage = undefined;
+			if (recoveryAttempt) {
+				pendingRecovery = undefined;
 			}
 
 			stream.push({ type: "turn_end", message, toolResults, scope: attemptScope });
@@ -1828,10 +1856,26 @@ async function runLoopBody(
 				stream.end(newMessages);
 				return;
 			}
-			if (repeatedMalformedToolCall && !malformedToolRecoveryAttempted) {
-				recoveryState.pending = true;
-				recoveryState.inserted = false;
-				recoveryState.syntheticMessage = undefined;
+			if (sawComposerBashPolicyBlock && !composerBashPolicyRecoveryAttempted) {
+				pendingRecovery = { kind: "composer-bash-policy", inserted: false };
+				composerBashPolicyRecoveryAttempted = true;
+			} else if (sawComposerBashPolicyBlock) {
+				message.stopReason = "error";
+				const recoveryLimitMessage =
+					"Composer bash policy blocked repository file I/O again after its one automatic recovery turn. Continue with dedicated repository tools.";
+				message.errorMessage = message.errorMessage
+					? `${message.errorMessage} | ${recoveryLimitMessage}`
+					: recoveryLimitMessage;
+				publishAgentEnd(
+					stream,
+					config,
+					buildAgentEndEvent(newMessages, telemetry, stepCounter.count, "completed", attemptScope),
+					attemptScope,
+				);
+				stream.end(newMessages);
+				return;
+			} else if (repeatedMalformedToolCall && !malformedToolRecoveryAttempted) {
+				pendingRecovery = { kind: "malformed-tool-call", inserted: false };
 				malformedToolRecoveryAttempted = true;
 			} else if (consecutiveMalformedTurns >= MAX_CONSECUTIVE_MALFORMED_TURNS) {
 				// Deterministic terminal circuit breaker. The one-shot recovery turn
@@ -1868,12 +1912,23 @@ async function runLoopBody(
 			stream.end(newMessages);
 			return;
 		}
+		// Poll the consume-on-read recovery candidate before follow-ups so a real
+		// user message can supersede it without letting the stale recovery resurface
+		// after that follow-up turn.
+		const syntheticRecoveryMessage = await config.getSyntheticRecoveryMessage?.();
 		const followUpMessages = (await config.getFollowUpMessages?.()) || [];
 		if (followUpMessages.length > 0) {
 			// Set as pending so inner loop processes them
 			pendingMessages = followUpMessages;
 			continue;
 		}
+		if (syntheticRecoveryMessage) {
+			// Provider-side tool protocols (such as Cursor) can finish their remote
+			// turn after a local policy rejection. Continue once without committing
+			// the recovery instruction to durable history.
+			pendingRecovery = { kind: "provider", inserted: true, syntheticMessage: syntheticRecoveryMessage };
+			continue;
+		}
 
 		// No more messages, exit
 		break;
@@ -1920,7 +1975,11 @@ async function streamAssistantResponse(
 	scope?: AttemptScope,
 	streamFn?: StreamFn,
 	harmonyRetryAttempt = 0,
-	recoveryMode?: { syntheticMessage: UserMessage },
+	recoveryMode?: {
+		syntheticMessage: UserMessage;
+		disableTools?: boolean;
+		forceAutoToolChoice?: boolean;
+	},
 ): Promise<AssistantMessage> {
 	// Apply context transform if configured (AgentMessage[] → AgentMessage[])
 	let messages = context.messages;
@@ -1951,7 +2010,11 @@ async function streamAssistantResponse(
 				await config.convertToLlm([recoveryMode.syntheticMessage]),
 				config.model,
 			);
-			llmContext = { ...llmContext, messages: [...llmContext.messages, ...syntheticMessages], tools: [] };
+			llmContext = {
+				...llmContext,
+				messages: [...llmContext.messages, ...syntheticMessages],
+				tools: recoveryMode.disableTools ? [] : llmContext.tools,
+			};
 		} else {
 			llmContext = {
 				...llmContext,
@@ -1959,7 +2022,7 @@ async function streamAssistantResponse(
 					await config.convertToLlm([...messages, recoveryMode.syntheticMessage]),
 					config.model,
 				),
-				tools: [],
+				tools: recoveryMode.disableTools ? [] : llmContext.tools,
 			};
 		}
 	}
@@ -1977,6 +2040,8 @@ async function streamAssistantResponse(
 
 	const resolvedMetadata = config.metadataResolver ? config.metadataResolver(config.model.provider) : config.metadata;
 
+	// Synthetic recovery requests choose their tool mode explicitly below and
+	// must never consume a queued dynamic choice intended for an ordinary turn.
 	const dynamicToolChoice = recoveryMode ? undefined : config.getToolChoice?.();
 	const dynamicReasoning = config.getReasoning?.();
 	const harmonyMitigationEnabled = isHarmonyLeakMitigationTarget(config.model);
@@ -1994,7 +2059,11 @@ async function streamAssistantResponse(
 				: AbortSignal.any(requestSignals);
 	const effectiveTemperature =
 		harmonyRetryAttempt > 0 && config.temperature !== undefined ? config.temperature + 0.05 : config.temperature;
-	const effectiveToolChoice = recoveryMode ? "none" : (dynamicToolChoice ?? config.toolChoice);
+	const effectiveToolChoice = recoveryMode?.disableTools
+		? "none"
+		: recoveryMode?.forceAutoToolChoice
+			? "auto"
+			: (dynamicToolChoice ?? config.toolChoice);
 	const effectiveReasoning = dynamicReasoning ?? config.reasoning;
 
 	const chatStepNumber = stepCounter.count;
@@ -2633,7 +2702,9 @@ async function executeToolCalls(
 				caughtError = e;
 				result = {
 					content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
-					details: {},
+					details: {
+						failureKind: record.argumentValidationFailed ? "argument_validation" : "execution",
+					},
 				};
 				isError = true;
 			}

package/src/agent.ts

@@ -20,6 +20,10 @@ import {
 	type ToolChoice,
 	type ToolResultMessage,
 } from "@gajae-code/ai";
+import {
+	CURSOR_COMPOSER_BASH_POLICY_RECOVERY_PROMPT,
+	isCurrentComposerBashPolicyBlockedError,
+} from "@gajae-code/ai/providers/composer-discipline";
 import { extractHttpStatusFromError } from "@gajae-code/utils";
 import { agentLoop, agentLoopContinue } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
@@ -67,6 +71,20 @@ function assertUserImagePlaceholdersHavePayload(messages: readonly AgentMessage[
 	}
 }
 
+const CURSOR_NATIVE_REPOSITORY_RECOVERY_TOOL_NAMES = new Set(["read", "grep", "search", "find", "write", "delete"]);
+
+function isCursorComposerBashPolicyBlockedResult(message: ToolResultMessage): boolean {
+	return (
+		message.isError &&
+		message.toolName === "bash" &&
+		message.content.some(content => content.type === "text" && isCurrentComposerBashPolicyBlockedError(content.text))
+	);
+}
+
+function isSuccessfulCursorNativeRepositoryToolResult(message: ToolResultMessage): boolean {
+	return message.isError !== true && CURSOR_NATIVE_REPOSITORY_RECOVERY_TOOL_NAMES.has(message.toolName);
+}
+
 /**
  * Whether persisted history ends at a point where a new model turn can resume.
  * Assistant-ended histories require an in-memory queued message and are handled
@@ -1488,6 +1506,11 @@ export class Agent {
 			messages: this.#state.messages.slice(),
 			tools: this.#state.tools,
 		};
+		// Cursor can execute native tools inside one remote turn, then return
+		// `turnEnded` without another model request. Remember a Composer policy
+		// rejection until the loop reaches that safe continuation boundary.
+		let cursorComposerBashRecoveryPending = false;
+		let cursorComposerBashRecoveryAttempted = false;
 
 		const cursorOnToolResult =
 			!fallbackManaged && (this.#cursorExecHandlers || this.#cursorOnToolResult)
@@ -1507,6 +1530,16 @@ export class Agent {
 								}
 							} catch {}
 						}
+						if (isCursorComposerBashPolicyBlockedResult(finalMessage)) {
+							cursorComposerBashRecoveryPending = true;
+						} else if (
+							cursorComposerBashRecoveryPending &&
+							isSuccessfulCursorNativeRepositoryToolResult(finalMessage)
+						) {
+							// The same remote turn already replanned through a native tool,
+							// so do not create a redundant local continuation afterward.
+							cursorComposerBashRecoveryPending = false;
+						}
 						// Cursor executes tools server-side during streaming, so the assistant message
 						// already incorporates results. We buffer here and emit in correct order
 						// when the assistant message ends.
@@ -1652,6 +1685,23 @@ export class Agent {
 				}
 				return queued;
 			},
+			getSyntheticRecoveryMessage: async () => {
+				if (
+					this.#activeRunId !== runId ||
+					!cursorComposerBashRecoveryPending ||
+					cursorComposerBashRecoveryAttempted
+				) {
+					return undefined;
+				}
+				cursorComposerBashRecoveryPending = false;
+				cursorComposerBashRecoveryAttempted = true;
+				return {
+					role: "user",
+					content: CURSOR_COMPOSER_BASH_POLICY_RECOVERY_PROMPT,
+					synthetic: true,
+					timestamp: Date.now(),
+				};
+			},
 			onBeforeYield: async () => {
 				if (this.#activeRunId !== runId) return;
 				await this.#onBeforeYield?.();

package/src/types.ts

@@ -15,6 +15,7 @@ import type {
 	ToolResultMessage,
 	TransportFailureFacts,
 	TSchema,
+	UserMessage,
 } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { AttemptMinter, AttemptRunHandle, AttemptScope } from "./attempt-scope";
@@ -319,6 +320,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * continues with another turn.
 	 */
 	getFollowUpMessages?: () => Promise<AgentMessage[]>;
+	/**
+	 * Supplies one bounded synthetic recovery instruction before the loop would
+	 * otherwise yield. Unlike a follow-up, it is sent only to the provider and
+	 * is not committed to durable agent message history.
+	 */
+	getSyntheticRecoveryMessage?: () => Promise<UserMessage | undefined>;
 	/**
 	 * Cooperative pause checkpoint evaluated at safe loop boundaries.
 	 *