@ai-sdk/harness: host tool execute() never receives tool context (options.context is always undefined)

[ckvv]

Summary

Host tools declared with a contextSchema never receive their context when executed by HarnessAgent: execute(input, options) is called with options.context === undefined. The same tool receives the expected context with streamText + toolsContext (and with ToolLoopAgent), so a tool definition that needs request-scoped identity has to be duplicated as a per-request closure factory to work with harness runtimes.

Environment

• @ai-sdk/harness@1.0.115
• @ai-sdk/harness-pi@1.0.117
• ai@7.0.105 (@ai-sdk/provider-utils@5.0.43)
• Node 24, pnpm

Reproduction

const probe = tool({
  inputSchema: z.object({ value: z.string() }),
  contextSchema: z.object({ userId: z.string() }),
  execute: async (input, { context }) => {
    console.log(context); // HarnessAgent: undefined / streamText + toolsContext: { userId: 'u1' }
    return { ok: true };
  },
});

const agent = new HarnessAgent({ harness, sandbox, tools: { probe } });
// Ask the model to call `probe` → options.context is undefined.

Under streamText the same tool is invoked with { userId: 'u1' } when passing toolsContext: { probe: { userId: 'u1' } }.

Root cause

Both places that would carry the tool context are hardcoded to empty:

1. The turn's tool context is created empty and there is no way for the caller to populate it (packages/harness/src/agent/internal/run-prompt.ts:150):

   const toolsContext = {} as InferToolSetContext<TOOLS>;

   That empty object is what HarnessStreamTextResult and the turn lifecycle receive, so step results and telemetry report toolsContext: {} as well.

2. maybeExecuteHostTool passes undefined as the tool context (packages/harness/src/agent/internal/run-prompt.ts:1469):

   const stream = executeTool({
     tool,
     input: args as never,
     options: {
       toolCallId: input.event.toolCallId,
       messages: [],
       abortSignal: input.abortSignal,
       context: undefined as never,
       experimental_sandbox: input.sandboxSession,
     },
   });

   executeTool from @ai-sdk/provider-utils only forwards options to tool.execute(input, options), so nothing fills the gap. There is also no contextSchema validation on this path, so a tool that reads context.userId fails with a TypeError inside execute instead of a context validation error.

The non-harness path does the opposite: executeToolCall resolves the per-tool context from toolsContext[toolName], validates it against the tool's contextSchema, and passes it as options.context.

Expected behavior

Host tools should receive the same per-tool context as they do everywhere else in the AI SDK. Either shape works:

1. a toolsContext setting on HarnessAgentSettings (or a field returned from the existing prepareCall hook) that maybeExecuteHostTool forwards as context: toolsContext[toolName], reusing the existing contextSchema validation; or
2. a documented per-call hook for binding context, if harness host tools are intentionally meant to be per-request closures.

prepareCall can already swap tools between turns, so option 1 would sit naturally next to it.

Impact

Any host tool that needs request-scoped identity (user / tenant / space id, message id, a stream writer for streaming UI parts, a per-request citation registry, DB session options) cannot be reused with HarnessAgent as-is. Consumers either duplicate the tool as a closure factory — including its carefully written description, which then drifts from the shared definition — or they cannot use the tool at all.

Workaround

Bind the context per request before handing the tool set to the agent:

const boundTools = Object.fromEntries(
  Object.entries(tools).map(([name, t]) => [
    name,
    {
      ...t,
      execute: (input, options) => t.execute(input, { ...options, context }),
    },
  ]),
);

new HarnessAgent({ harness, sandbox, tools: boundTools });

(prepareCall works too if the context is per call rather than per agent instance.)

Related

• HarnessAgent: support generic toolApproval callbacks for host tools #20607 / feat: support generic tool approval callbacks for HarnessAgent host tools #20611 — generic toolApproval callbacks for host tools. The PR description says callbacks are evaluated with host-visible toolsContext and runtimeContext, so this plumbing is already being touched for approval; this issue is the execution counterpart.
• @ai-sdk/harness: approval reason for an APPROVED host tool is dropped — forwarded for denials and built-in tools, never reaches the tool's execute() or the model #17083 — an approved host tool's approval reason never reaches execute() or the model (same family: host tool options are lossy).
• fix(harness): Execute host tools through telemetry context wrappers #17671 — host tools executed through telemetry context wrappers, i.e. the call site where context: undefined lives.

[ai-sdk-factory]

Identify issue type

Identified as Bug
Confidence: High

Rationale

This is a concrete inconsistency and failure in existing AI SDK behavior: HarnessAgent drops declared host-tool context rather than validating and forwarding it as other execution paths do.

Evidence

• HarnessAgent invokes host tool execute(input, options) with options.context always undefined despite the tool declaring a contextSchema.
• The same tool receives its expected per-tool context through streamText with toolsContext and through ToolLoopAgent.
• The report identifies a concrete harness execution path that hardcodes context: undefined, causing tools that access required context to throw.

[ai-sdk-factory]

Bug Reproduction - AI SDK 7

Bug was reproduced.

Branch: main
PR: successful reproduction pull request

Details

• The checked-out packages exactly match the report: @ai-sdk/harness@1.0.115, @ai-sdk/harness-pi@1.0.117, ai@7.0.105, and @ai-sdk/provider-utils@5.0.43.
• Reproduction artifact examples/ai-functions/src/reproduction/harness-agent-tool-context.ts uses the issue's proposed prepareCall-bound context and verifies that streamText passes { userId: "u1" } to the same contextual tool.
• HarnessAgent invoked the tool with context === undefined, causing TypeError: Cannot read properties of undefined (reading 'userId') and submitting an error instead of the expected successful output containing userId: "u1".
• The resulting harness step exposed toolsContext: {}; packages/harness/src/agent/internal/run-prompt.ts initializes that map as empty and passes context: undefined to host-tool execution.
• The separate ToolLoopAgent comparison was not executed; the primary HarnessAgent failure and the reported streamText comparison were both directly observed.

[ai-sdk-factory]

Bugfix - AI SDK 7

Created bugfix and opened PR: #21086

Root Cause

The harness prompt runner initialized toolsContext as an empty map and explicitly passed undefined to host-tool execution, confirmed by the original reproduction showing toolsContext {} and a context access TypeError.

Summary

Added typed static and prepareCall-derived toolsContext support, preserved it through turn execution and continuations, validated each contextSchema before execution, and forwarded context to host tools and result lifecycle data.

Testing

Added runtime regression coverage for prepareCall context forwarding, step-result exposure, and schema validation, plus type coverage for deriving toolsContext from call options.