feat(tools): add AbortSignal support for tool runner (#848)

## Summary

- Adds `AbortSignal` support to `BetaToolRunner` for cancelling API
calls and tool execution
- Introduces `BetaToolRunContext` type passed to `tool.run()` with
`signal` and `toolUseBlock`
- Adds `setRequestOptions()` method for updating signal/headers after
runner creation

## Context

Picks up the design from #877 (which was approved but stalled), adapted
to the current codebase. Multiple users have requested the ability to
cancel tool runner operations.

The signal flows through:
1. Constructor options or `setRequestOptions()` → stored in `#options`
2. `#options` passed to API calls (`messages.create`/`messages.stream`)
3. `generateToolResponse(signal?)` → `tool.run(input, { toolUseBlock,
signal })`

Tools can check `context?.signal?.aborted` or pass the signal to
downstream operations like `fetch()`.

## Test plan

- [x] `./scripts/build` passes
- [x] `./scripts/test -- tests/lib/tools/ToolRunner.test.ts` — 5 new
tests
- [x] Signal + toolUseBlock passed to tool.run via constructor options
- [x] Undefined signal when none provided
- [x] `setRequestOptions()` with direct object
- [x] `setRequestOptions()` with mutator function
- [x] Documentation updated in helpers.md

---------

Co-authored-by: Felix Becker <felix@anthropic.com>
Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>
Co-authored-by: Mike Cluck <mcluck90@gmail.com>

Author: 4 people

helpers.md

@@ -256,6 +256,48 @@ console.log(await runner);
 See [`examples/tools-helpers-advanced-streaming.ts`](examples/tools-helpers-advanced-streaming.ts) for a more
 in-depth example.
 
+#### Cancellation
+
+The `BetaToolRunner` supports cancellation via `AbortSignal`. The signal is passed to both API calls and tool `run` methods via the `BetaToolRunContext`.
+
+```ts
+const controller = new AbortController();
+
+const runner = anthropic.beta.messages.toolRunner(
+  {
+    model: 'claude-sonnet-4-5-20250929',
+    max_tokens: 1000,
+    messages: [{ role: 'user', content: 'Do a long task' }],
+    tools: [
+      betaZodTool({
+        name: 'long_task',
+        inputSchema: z.object({ query: z.string() }),
+        description: 'A long-running task',
+        run: async (input, context) => {
+          // Throws AbortError if already cancelled before run() was called
+          context?.signal?.throwIfAborted();
+          // Pass the signal to downstream operations for mid-flight cancellation
+          const result = await fetch(url, { signal: context?.signal });
+          return result.text();
+        },
+      }),
+    ],
+  },
+  { signal: controller.signal },
+);
+
+// Cancel after 5 seconds
+setTimeout(() => controller.abort(), 5000);
+
+const finalMessage = await runner;
+```
+
+You can also set or update the signal after creating the runner:
+
+```ts
+runner.setRequestOptions({ signal: controller.signal });
+```
+
 ### `betaZodTool`
 
 Zod schemas can be used to define the input schema for your tools:
@@ -386,9 +428,25 @@ runner.pushMessages(
 );
 ```
 
-#### `BetaToolRunner.generateToolResponse()`
+#### `BetaToolRunner.setRequestOptions()`
+
+Updates the request options (e.g., headers, abort signal) for future API calls and tool executions.
+
+```ts
+// Direct options update
+const controller = new AbortController();
+runner.setRequestOptions({ signal: controller.signal });
+
+// Using mutator function to preserve existing options
+runner.setRequestOptions((prev) => ({
+  ...prev,
+  signal: controller.signal,
+}));
+```
+
+#### `BetaToolRunner.generateToolResponse(signal?)`
 
-Gets the tool response for the last assistant message (if any tools need to be executed).
+Gets the tool response for the last assistant message (if any tools need to be executed). Accepts an optional `AbortSignal` parameter that will be passed to tool `run` methods; defaults to the signal from request options.
 
 ```ts
 for await (const message of runner) {

src/helpers/beta/json-schema.ts

@@ -1,5 +1,5 @@
 import { FromSchema, JSONSchema } from 'json-schema-to-ts';
-import { Promisable, BetaRunnableTool } from '../../lib/tools/BetaRunnableTool';
+import { Promisable, BetaRunnableTool, BetaToolRunContext } from '../../lib/tools/BetaRunnableTool';
 import { BetaToolResultContentBlockParam } from '../../resources/beta';
 import { AutoParseableBetaOutputFormat } from '../../lib/beta-parser';
 import { AnthropicError } from '../..';
@@ -16,7 +16,10 @@ export function betaTool<const Schema extends Exclude<JSONSchema, boolean> & { t
   name: string;
   inputSchema: Schema;
   description: string;
-  run: (args: NoInfer<FromSchema<Schema>>) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
+  run: (
+    args: NoInfer<FromSchema<Schema>>,
+    context?: BetaToolRunContext,
+  ) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
 }): BetaRunnableTool<NoInfer<FromSchema<Schema>>> {
   if (options.inputSchema.type !== 'object') {
     throw new Error(

src/helpers/beta/zod.ts

@@ -3,7 +3,7 @@ import type { infer as zodInfer, ZodType } from 'zod';
 import * as z from 'zod/v4';
 import { AnthropicError } from '../../core/error';
 import { AutoParseableBetaOutputFormat } from '../../lib/beta-parser';
-import { BetaRunnableTool, Promisable } from '../../lib/tools/BetaRunnableTool';
+import { BetaRunnableTool, BetaToolRunContext, Promisable } from '../../lib/tools/BetaRunnableTool';
 import { BetaToolResultContentBlockParam } from '../../resources/beta';
 /**
  * Creates a JSON schema output format object from the given Zod schema.
@@ -50,7 +50,10 @@ export function betaZodTool<InputSchema extends ZodType>(options: {
   name: string;
   inputSchema: InputSchema;
   description: string;
-  run: (args: zodInfer<InputSchema>) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
+  run: (
+    args: zodInfer<InputSchema>,
+    context?: BetaToolRunContext,
+  ) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
 }): BetaRunnableTool<zodInfer<InputSchema>> {
   const jsonSchema = z.toJSONSchema(options.inputSchema, { reused: 'ref' });
 

src/lib/tools/BetaRunnableTool.ts

@@ -11,6 +11,7 @@ import {
   BetaToolTextEditor20250124,
   BetaToolTextEditor20250429,
   BetaToolTextEditor20250728,
+  BetaToolUseBlock,
 } from '../../resources/beta';
 
 export type Promisable<T> = T | Promise<T>;
@@ -32,9 +33,17 @@ export type BetaClientRunnableToolType =
   | BetaToolTextEditor20250429
   | BetaToolTextEditor20250728;
 
+export type BetaToolRunContext = {
+  toolUseBlock: BetaToolUseBlock;
+  signal?: AbortSignal | null | undefined;
+};
+
 // this type is just an extension of BetaTool with a run and parse method
 // that will be called by `toolRunner()` helpers
 export type BetaRunnableTool<Input = any> = BetaClientRunnableToolType & {
-  run: (args: Input) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
+  run: (
+    args: Input,
+    context?: BetaToolRunContext,
+  ) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
   parse: (content: unknown) => Input;
 };

src/lib/tools/BetaToolRunner.ts

@@ -152,7 +152,8 @@ export class BetaToolRunner<Stream extends boolean> {
         max_tokens: this.#state.params.max_tokens,
       },
       {
-        headers: { 'x-stainless-helper': 'compaction' },
+        signal: this.#options.signal,
+        headers: buildHeaders([this.#options.headers, { 'x-stainless-helper': 'compaction' }]),
       },
     );
 
@@ -281,6 +282,40 @@ export class BetaToolRunner<Stream extends boolean> {
     this.#toolResponse = undefined;
   }
 
+  /**
+   * Update the request options for future API calls.
+   *
+   * @param optionsOrMutator - Either new options or a function to mutate existing options
+   *
+   * @example
+   * // Direct options update
+   * runner.setRequestOptions({
+   *   signal: controller.signal,
+   * });
+   *
+   * @example
+   * // Using a mutator function
+   * runner.setRequestOptions((prevOptions) => ({
+   *   ...prevOptions,
+   *   signal: controller.signal,
+   * }));
+   */
+  setRequestOptions(options: BetaToolRunnerRequestOptions): void;
+  setRequestOptions(
+    mutator: (prevOptions: BetaToolRunnerRequestOptions) => BetaToolRunnerRequestOptions,
+  ): void;
+  setRequestOptions(
+    optionsOrMutator:
+      | BetaToolRunnerRequestOptions
+      | ((prevOptions: BetaToolRunnerRequestOptions) => BetaToolRunnerRequestOptions),
+  ) {
+    if (typeof optionsOrMutator === 'function') {
+      this.#options = optionsOrMutator(this.#options);
+    } else {
+      this.#options = { ...this.#options, ...optionsOrMutator };
+    }
+  }
+
   /**
    * Get the tool response for the last message from the assistant.
    * Avoids redundant tool executions by caching results.
@@ -293,19 +328,25 @@ export class BetaToolRunner<Stream extends boolean> {
    *   console.log('Tool results:', toolResponse.content);
    * }
    */
-  async generateToolResponse() {
+  async generateToolResponse(signal: AbortSignal | null | undefined = this.#options.signal) {
     const message = (await this.#message) ?? this.params.messages.at(-1);
     if (!message) {
       return null;
     }
-    return this.#generateToolResponse(message);
+    return this.#generateToolResponse(message, signal);
   }
 
-  async #generateToolResponse(lastMessage: BetaMessageParam) {
+  async #generateToolResponse(
+    lastMessage: BetaMessageParam,
+    signal: AbortSignal | null | undefined = this.#options.signal,
+  ) {
     if (this.#toolResponse !== undefined) {
       return this.#toolResponse;
     }
-    this.#toolResponse = generateToolResponse(this.#state.params, lastMessage);
+    this.#toolResponse = generateToolResponse(this.#state.params, lastMessage, {
+      ...this.#options,
+      signal,
+    });
     return this.#toolResponse;
   }
 
@@ -407,6 +448,7 @@ export class BetaToolRunner<Stream extends boolean> {
 async function generateToolResponse(
   params: BetaToolRunnerParams,
   lastMessage = params.messages.at(-1),
+  requestOptions?: BetaToolRunnerRequestOptions,
 ): Promise<BetaMessageParam | null> {
   // Only process if the last message is from the assistant and has tool use blocks
   if (
@@ -441,7 +483,10 @@ async function generateToolResponse(
           input = tool.parse(input);
         }
 
-        const result = await tool.run(input);
+        const result = await tool.run(input, {
+          toolUseBlock: toolUse,
+          signal: requestOptions?.signal,
+        });
         return {
           type: 'tool_result' as const,
           tool_use_id: toolUse.id,
@@ -491,4 +536,4 @@ export type BetaToolRunnerParams = Simplify<
   }
 >;
 
-export type BetaToolRunnerRequestOptions = Pick<RequestOptions, 'headers'>;
+export type BetaToolRunnerRequestOptions = Pick<RequestOptions, 'headers' | 'signal'>;