Tool outcomes and cancellation

For a tool that catches an operational error and returns an application-specific value, use createOutcomeTool({ definition, execute: async (args, invocation) => ... }). Call invocation.reportFailure(new Error('Public-safe failure message')) inside that callback; read the existing optional signal from invocation.context?.signal. The helper returns a normal ToolFunction, raw results stay intact, and a business decline without a report remains a succeeded execution. First report wins and the reporter becomes inert after settlement. Existing callbacks/defaults are unchanged. See the complete recipe and boundaries and npm run example:outcome-aware-tools. This helper does not automatically convert bundled connector tools. Rich remote outcomes require the separately negotiated remote protocol.

Use agent.tools.executeWithOutcome(name, args, { signal, timeoutMs, callId, runId }) when the host needs { result, outcome }; execute() still returns raw data. The manager recognizes its normalizer's failures without reinterpreting arbitrary application success: false objects. Agent tool results and streaming completion events expose optional outcome metadata. Failure/timeout counters now reflect those semantic results; async acceptance placeholders are not completed work. Settlement is counted before streaming completion events, including early stream exit. A tool retains its admitted implementation, definition, permission metadata, and resolved connector access through asynchronous waits. Later registration or account changes affect future calls. Queued background delivery checks scope again, and throwing completion/error/timeout observers cannot replace or double-count a settled result.

Tools may observe their existing optional ToolContext.signal. agent.cancel() and async cancellation methods request cancellation of the corresponding calls. Late settlement is diagnostic-only, correlated to the original call, and never counted twice or automatically delivered to a different account. A noncooperative tool can still finish; cancellation does not prove that a remote write was prevented.

Connector requests compose caller signals with deadlines. Header timeouts and legacy retry policy remain defaults. Opt in to timeoutScope: 'operation' for one deadline through token waiting, retries, and body consumption, and retryPolicy: 'safe' to retry eligible GET/HEAD/OPTIONS only. Consume or cancel response bodies. Safe retry and operation-body cleanup remain cancellation/deadline aware, and chained response clones preserve metadata and native body checks. skipRetry skips both network and status retries. Generic API tools forward the signal; specialized tools/transports require their own support.

See Tool outcomes and cancellation for public signatures, status/evidence meanings, listener cleanup, persistence and breaker boundaries, examples, AMOS behavior, and current live-validation limits.

Explicit Anthropic named-tool requests advertise only the selected local function alongside configured native tools. A different returned local tool raises the existing ProviderError before execution, without automatic retries or model switching. Later auto/required calls retain their normal tool set. To modify request options in both managed modes, mutate context.options in before:llm and return {}; streaming hook return semantics are unchanged. See the selection contract and opt-in live example.