Add terminating tool results and defineTool helper

packages/agent/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added optional `terminate` support for tool results so deterministic tools can end the current turn without an automatic follow-up model call.
+
 ## [14.2.0] - 2026-04-23
 
 ### Changed

packages/agent/src/agent-loop.ts

@@ -285,6 +285,11 @@ async function runLoop(
 			stream.push({ type: "turn_end", message, toolResults });
 
 			pendingMessages = steeringMessagesFromExecution ?? ((await config.getSteeringMessages?.()) || []);
+			if (hasMoreToolCalls && toolResults.length > 0 && toolResults.every(result => result.terminate === true)) {
+				if (pendingMessages.length === 0) {
+					hasMoreToolCalls = false;
+				}
+			}
 		}
 
 		// Agent would stop here. Check for follow-up messages.
@@ -528,6 +533,7 @@ async function executeToolCalls(
 			content: result.content,
 			details: result.details,
 			isError,
+			terminate: result.terminate,
 			timestamp: Date.now(),
 		};
 		record.result = result;

packages/agent/src/types.ts

@@ -199,6 +199,8 @@ export interface AgentToolResult<T = any, _TInput = unknown> {
 	content: (TextContent | ImageContent)[];
 	// Details to be displayed in a UI or logged
 	details?: T;
+	// Whether this result should terminate the current agent turn without a follow-up model call
+	terminate?: boolean;
 }
 
 // Callback for streaming tool execution updates

packages/agent/test/agent.test.ts

@@ -323,6 +323,188 @@ describe("Agent", () => {
 		]);
 	});
 
+	it("prompt() stops after a terminating tool result without a follow-up model call", async () => {
+		const toolSchema = Type.Object({ value: Type.String() });
+		let streamCallCount = 0;
+
+		const alphaTool: AgentTool<typeof toolSchema> = {
+			name: "alpha",
+			label: "Alpha",
+			description: "Alpha tool",
+			parameters: toolSchema,
+			async execute(_toolCallId, params) {
+				return { content: [{ type: "text", text: `alpha:${params.value}` }], terminate: true };
+			},
+		};
+
+		const agent = new Agent({
+			initialState: { tools: [alphaTool] },
+			streamFn: () => {
+				const callIndex = streamCallCount;
+				streamCallCount += 1;
+				const stream = new MockAssistantStream();
+				queueMicrotask(() => {
+					if (callIndex === 0) {
+						const message = createAssistantMessage(
+							[{ type: "toolCall", id: "tool-1", name: "alpha", arguments: { value: "hello" } }],
+							"toolUse",
+						);
+						stream.push({ type: "done", reason: "toolUse", message });
+					} else {
+						stream.push({
+							type: "done",
+							reason: "stop",
+							message: createAssistantMessage([{ type: "text", text: "follow-up" }]),
+						});
+					}
+				});
+				return stream;
+			},
+		});
+
+		await agent.prompt("run alpha");
+
+		expect(streamCallCount).toBe(1);
+		expect(agent.state.messages.map(message => message.role)).toEqual(["user", "assistant", "toolResult"]);
+		const toolResult = agent.state.messages.find(message => message.role === "toolResult");
+		expect(toolResult?.terminate).toBe(true);
+	});
+
+	it("prompt() processes queued follow-up after a terminating tool result", async () => {
+		const toolSchema = Type.Object({ value: Type.String() });
+		let streamCallCount = 0;
+		let agent: Agent;
+
+		const alphaTool: AgentTool<typeof toolSchema> = {
+			name: "alpha",
+			label: "Alpha",
+			description: "Alpha tool",
+			parameters: toolSchema,
+			async execute(_toolCallId, params) {
+				agent.followUp({
+					role: "user",
+					content: [{ type: "text", text: "Queued follow-up" }],
+					timestamp: Date.now(),
+				});
+				return { content: [{ type: "text", text: `alpha:${params.value}` }], terminate: true };
+			},
+		};
+
+		agent = new Agent({
+			initialState: { tools: [alphaTool] },
+			streamFn: () => {
+				const callIndex = streamCallCount;
+				streamCallCount += 1;
+				const stream = new MockAssistantStream();
+				queueMicrotask(() => {
+					if (callIndex === 0) {
+						const message = createAssistantMessage(
+							[{ type: "toolCall", id: "tool-1", name: "alpha", arguments: { value: "hello" } }],
+							"toolUse",
+						);
+						stream.push({ type: "done", reason: "toolUse", message });
+					} else {
+						stream.push({
+							type: "done",
+							reason: "stop",
+							message: createAssistantMessage([{ type: "text", text: "processed follow-up" }]),
+						});
+					}
+				});
+				return stream;
+			},
+		});
+
+		await agent.prompt("run alpha");
+
+		expect(streamCallCount).toBe(2);
+		expect(agent.hasQueuedMessages()).toBe(false);
+		expect(agent.state.messages.map(message => message.role)).toEqual([
+			"user",
+			"assistant",
+			"toolResult",
+			"user",
+			"assistant",
+		]);
+		expect(agent.state.messages.at(-2)).toMatchObject({
+			role: "user",
+			content: [{ type: "text", text: "Queued follow-up" }],
+		});
+		expect(agent.state.messages.at(-1)).toMatchObject({
+			role: "assistant",
+			content: [{ type: "text", text: "processed follow-up" }],
+		});
+	});
+
+	it("prompt() follows up after a mixed terminating and non-terminating tool batch", async () => {
+		const toolSchema = Type.Object({ value: Type.String() });
+		let streamCallCount = 0;
+
+		const alphaTool: AgentTool<typeof toolSchema> = {
+			name: "alpha",
+			label: "Alpha",
+			description: "Alpha tool",
+			parameters: toolSchema,
+			async execute(_toolCallId, params) {
+				return { content: [{ type: "text", text: `alpha:${params.value}` }], terminate: true };
+			},
+		};
+		const betaTool: AgentTool<typeof toolSchema> = {
+			name: "beta",
+			label: "Beta",
+			description: "Beta tool",
+			parameters: toolSchema,
+			async execute(_toolCallId, params) {
+				return { content: [{ type: "text", text: `beta:${params.value}` }] };
+			},
+		};
+
+		const agent = new Agent({
+			initialState: { tools: [alphaTool, betaTool] },
+			streamFn: () => {
+				const callIndex = streamCallCount;
+				streamCallCount += 1;
+				const stream = new MockAssistantStream();
+				queueMicrotask(() => {
+					if (callIndex === 0) {
+						const message = createAssistantMessage(
+							[
+								{ type: "toolCall", id: "tool-1", name: "alpha", arguments: { value: "hello" } },
+								{ type: "toolCall", id: "tool-2", name: "beta", arguments: { value: "world" } },
+							],
+							"toolUse",
+						);
+						stream.push({ type: "done", reason: "toolUse", message });
+					} else {
+						stream.push({
+							type: "done",
+							reason: "stop",
+							message: createAssistantMessage([{ type: "text", text: "follow-up" }]),
+						});
+					}
+				});
+				return stream;
+			},
+		});
+
+		await agent.prompt("run tools");
+
+		expect(streamCallCount).toBe(2);
+		expect(agent.state.messages.map(message => message.role)).toEqual([
+			"user",
+			"assistant",
+			"toolResult",
+			"toolResult",
+			"assistant",
+		]);
+		const toolResults = agent.state.messages.filter(message => message.role === "toolResult");
+		expect(toolResults.map(message => message.terminate)).toEqual([true, undefined]);
+		expect(agent.state.messages.at(-1)).toMatchObject({
+			role: "assistant",
+			content: [{ type: "text", text: "follow-up" }],
+		});
+	});
+
 	it("forwards sessionId and thinkingBudgets to streamFn options", async () => {
 		let receivedSessionId: string | undefined;
 		let receivedBudgets: ThinkingBudgets | undefined;

packages/ai/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added optional `terminate` metadata to tool-result messages for agent runtimes that support terminal tool results.
+
 ## [14.5.3] - 2026-04-27
 ### Added
 

packages/ai/src/types.ts

@@ -378,6 +378,8 @@ export interface ToolResultMessage<TDetails = any> {
 	content: (TextContent | ImageContent)[]; // Supports text and images
 	details?: TDetails;
 	isError: boolean;
+	/** Whether this tool result should terminate the current agent turn without a follow-up model call. */
+	terminate?: boolean;
 	/** Who initiated this message for billing/attribution semantics. */
 	attribution?: MessageAttribution;
 	/** Timestamp when output was pruned (ms since epoch). Undefined if unpruned. */

packages/coding-agent/CHANGELOG.md

@@ -9,6 +9,7 @@
 
 ### Added
 
+- Added the `defineTool()` extension SDK helper and termination metadata propagation through extension and hook `tool_result` handlers.
 - Added internal URL support to the `search` tool, allowing `artifact://`-style paths that resolve to local files to be searched directly
 - Added IRC relay observation in the main agent UI so every IRC exchange between agents is rendered in the main transcript, even when the main agent is not a direct participant
 

packages/coding-agent/src/extensibility/extensions/runner.ts

@@ -496,6 +496,10 @@ export class ExtensionRunner {
 						currentEvent.isError = handlerResult.isError;
 						modified = true;
 					}
+					if (handlerResult.terminate !== undefined) {
+						currentEvent.terminate = handlerResult.terminate;
+						modified = true;
+					}
 				} catch (err) {
 					const message = err instanceof Error ? err.message : String(err);
 					const stack = err instanceof Error ? err.stack : undefined;
@@ -515,6 +519,7 @@ export class ExtensionRunner {
 			content: currentEvent.content,
 			details: currentEvent.details,
 			isError: currentEvent.isError,
+			terminate: currentEvent.terminate,
 		};
 	}
 

packages/coding-agent/src/extensibility/extensions/types.ts

@@ -46,10 +46,10 @@ import type {
 	BashToolInput,
 	FindToolDetails,
 	FindToolInput,
-	SearchToolDetails,
-	SearchToolInput,
 	ReadToolDetails,
 	ReadToolInput,
+	SearchToolDetails,
+	SearchToolInput,
 	WriteToolInput,
 } from "../../tools";
 import type { TodoItem } from "../../tools/todo-write";
@@ -347,6 +347,13 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
 	) => Component;
 }
 
+/** Typed identity helper for defining extension tools. */
+export function defineTool<TParams extends TSchema, TDetails = unknown>(
+	definition: ToolDefinition<TParams, TDetails>,
+): ToolDefinition<TParams, TDetails> {
+	return definition;
+}
+
 // ============================================================================
 // Resource Events
 // ============================================================================
@@ -714,6 +721,7 @@ interface ToolResultEventBase {
 	input: Record<string, unknown>;
 	content: (TextContent | ImageContent)[];
 	isError: boolean;
+	terminate?: boolean;
 }
 
 export interface BashToolResultEvent extends ToolResultEventBase {
@@ -865,6 +873,7 @@ export interface ToolResultEventResult {
 	content?: (TextContent | ImageContent)[];
 	details?: unknown;
 	isError?: boolean;
+	terminate?: boolean;
 }
 
 export interface BeforeAgentStartEventResult {

packages/coding-agent/src/extensibility/extensions/wrapper.ts

@@ -9,6 +9,12 @@ import { applyToolProxy } from "../tool-proxy";
 import type { ExtensionRunner } from "./runner";
 import type { RegisteredTool, ToolCallEventResult } from "./types";
 
+type ToolResultWithTerminate<TDetails> = {
+	content: (TextContent | ImageContent)[];
+	details?: TDetails;
+	terminate?: boolean;
+};
+
 /**
  * Adapts a RegisteredTool into an AgentTool.
  */
@@ -132,7 +138,7 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		}
 
 		// Execute the actual tool
-		let result: { content: any; details?: TDetails };
+		let result: ToolResultWithTerminate<TDetails>;
 		let executionError: Error | undefined;
 
 		try {
@@ -155,11 +161,13 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 				content: result.content,
 				details: result.details,
 				isError: !!executionError,
+				terminate: result.terminate,
 			});
 
 			if (resultResult) {
 				const modifiedContent: (TextContent | ImageContent)[] = resultResult.content ?? result.content;
 				const modifiedDetails = (resultResult.details ?? result.details) as TDetails;
+				const modifiedTerminate = resultResult.terminate ?? result.terminate;
 
 				// Extension can override error status
 				if (resultResult.isError === true && !executionError) {
@@ -170,14 +178,14 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 				}
 				if (resultResult.isError === false && executionError) {
 					// Extension clears the error - return success
-					return { content: modifiedContent, details: modifiedDetails };
+					return { content: modifiedContent, details: modifiedDetails, terminate: modifiedTerminate };
 				}
 
 				// Error status unchanged, but content/details may be modified
 				if (executionError) {
 					throw executionError;
 				}
-				return { content: modifiedContent, details: modifiedDetails };
+				return { content: modifiedContent, details: modifiedDetails, terminate: modifiedTerminate };
 			}
 		}