@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

[doneumark]

Description

addToolApprovalResponse({ id, approved, reason }) lets a client attach a reason to a tool-approval response. The harness delivers that reason asymmetrically — verified against the published @ai-sdk/harness@1.0.24 dist (processPendingApprovalContinuation in dist/agent/index.js):

• Denied host tool → the reason reaches the model via submitToolResult({ output: { type: 'execution-denied', reason } }). ✅
• Built-in tool approval → the reason is forwarded via control.submitToolApproval({ approved, reason }). ✅
• Approved host tool → maybeExecuteHostTool re-executes the tool with its original input only. The reason is recorded on the tool-approval-response part (so it appears in the transcript), but it never reaches the tool's execute() — and therefore never reaches the model, which only sees the tool result. ❌

This matters because the approval prompt is a natural human-in-the-loop data channel: "approved — and here is the user's answer / the edited plan / the corrected value". The reason field is the documented way to attach context to an approval decision, and it already works on the deny path; the approve path silently drops it.

Reproduction

const tools = {
  ask_user_question: tool({
    inputSchema: z.object({ question: z.string() }),
    needsApproval: true,
    execute: async (input, options) => {
      // options has toolCallId / messages / abortSignal — nothing from the approval
      // response. The user's answer (sent as the approval reason) is not available here.
      return 'answer?';
    },
  }),
};

// client:
addToolApprovalResponse({
  id: part.approval.id,
  approved: true,
  reason: JSON.stringify({ answers: { question_1: '…' } }),
});

The continuation executes the tool with the original input; the reason payload is nowhere in the execution, and the tool result the model consumes cannot include it.

Suggested fix

Forward the approval response into host-tool execution options, e.g.:

execute(input, { toolCallId, messages, abortSignal, approval: { approved: true, reason } })

mirroring what the denial path already does through execution-denied. Additive on the execution options type, so existing tools are unaffected.

Update: PR is up — #17101, generalized per the discussion below: rather than patching only the harness call site, the approval decision ({ approvalId, approved, reason? }) is threaded as options.approval through every execution path — generateText/streamText explicit continuations, automatic toolApproval approvals, and the harness continuation — with tests on each path and docs. Thanks @babyblueviper1 for the "full decision payload threads through every path uniformly" framing that shaped it.

Workaround

We scan the incoming UIMessage[] for tool parts carrying approval.reason, build a toolCallId → parsed payload map out-of-band before starting the turn, and each HITL tool's execute() looks up its own toolCallId so the data reaches the model through the tool result. Works, but it is exactly the plumbing the SDK could do itself — and it only works because the approval response happens to ride the resent messages.

Versions

• @ai-sdk/harness@1.0.24 (latest; first verified on 1.0.18), @ai-sdk/harness-claude-code@1.0.24
• ai@7.0.20

[babyblueviper1]

Good catch, and worth naming the general shape of the bug, not just this instance: an approval decision's reason is part of the decision, not a side-channel to it -- if it only survives on the deny path, the record of "why" silently degrades to second-class information the moment someone approves instead of denies. That's the same asymmetry class as an authorization binding to the wrong scope of what it actually authorized (e.g. approving X but the executed action carrying different bound context than what was reviewed) -- the fix in both cases is the same: the full decision payload threads through every path uniformly, not just the branch someone happened to test first.

Concretely here: maybeExecuteHostTool's re-execution on approval should carry reason into execute()'s input/options the same way submitToolResult's denial path carries it into the model-visible result -- otherwise a tool that wants to act on "approved, and here's the corrected value" has no path to see it, even though the UI already captured it and the transcript already recorded it.

[doneumark]

@babyblueviper1 — agreed, and your framing changed the shape of the fix. The PR I first had in mind patched the single harness call site the report pointed at (maybeExecuteHostTool re-execution); following the "full decision payload threads through every path uniformly" framing, the PR that's now up (#17101) instead makes the decision a first-class part of tool execution everywhere:

• ToolExecutionOptions (what every execute(input, options) receives) gains an optional approval: { approvalId, approved: true, reason? } — the decision object itself, not just the reason string, so the binding between "what was reviewed" and "what executes" stays explicit.
• Every approval-carrying execution path forwards it: generateText/streamText explicit continuations, automatic approvals from the toolApproval configuration (both the step loop and the streaming path), and the harness continuation from the original report.
• Executions with no approval flow carry no approval key at all, and denials keep delivering their reason through execution-denied — so both existing behaviors are untouched and the asymmetry is closed from the approve side.

One scoping note: approved is typed true on the execution option, since denied calls never reach execute() by design — the deny path's payload continues to travel via the model-visible result, which is the correct sink for it.

[babyblueviper1]

Verified the diff, not just the description -- ToolExecutionApproval threading through generateText/streamText/the harness continuation, tests updated for each path, deny path correctly left untouched (its reason still travels via execution-denied, which is the right sink for it). This closes the asymmetry cleanly: the decision payload, not just the reason string, now travels with every approved execution. Appreciate you taking the reframe seriously instead of just patching the one call site the report pointed at.