feat(tools): FunctionTool require_confirmation — HITL approval (Part 7)

[kalenkevich]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

• Related: Support for Workflows #366

Problem: A FunctionTool may perform sensitive actions that should pause for human approval before executing.

Solution — Part 7 of 8. Stacked on Part 6.

Included:

• tools/function_tool.ts — a requireConfirmation option so a FunctionTool pauses for human approval before running.
• agents/processors/request_confirmation_llm_request_processor.ts — handles the confirmation request/resume round-trip for such tools.

This tool-approval HITL is independent of the workflow engine (it works for any FunctionTool), so it's a small, self-contained slice and could equally target main directly.

Testing Plan

• Unit tests added/updated; all pass locally.

Tests: tools/function_tool_confirmation_test (5). Full core suite 2481 green; docs:check + tsc clean.

Manual E2E: N/A (unit-level; the request/resume round-trip is covered by the test).

Checklist

• I have read CONTRIBUTING.md.
• I have performed a self-review.
• Commented hard-to-understand areas.
• Added tests.
• New and existing unit tests pass locally.
• Manually tested end-to-end.
• Dependent changes merged.

Additional context

Stacked split — merge in order (…Part 6 → Part 7 → Part 8). Diff: 3 files, +317.

[AmaadMartin]

Verified against the head tree at c7aac5b. The gate itself is correct for an LlmAgent turn: it runs after schema validation so the predicate sees validated args, it fails closed, denial returns a clean {error: 'This tool call is rejected.'} without executing, and the default is opt-in (requireConfirmation ?? false) with no false convenience knob — which matches Python and is the right default for a generic function wrapper. Two things I would want resolved before this lands: requireConfirmation is not enforced end-to-end for a workflow ToolNode (the request is dropped and the node returns an error string as ordinary output — details inline), and the new plain-text approval fallback lets a single ok approve every pending confirmation in the session, on any surface, not just the CLI.

[AmaadMartin]

Re-checked at 34ed5af2. All seven findings are resolved, and the two security ones were fixed at the cause rather than papered over: the plain-text path is now opt-in behind runConfig.plainTextToolConfirmation (off everywhere except the CLI), and mapPlainTextConfirmation resolves exactly one gate — the most recent pending id, only when the reply immediately follows it, with unrecognized text left as no decision instead of a silent denial. I traced the immediacy scan by hand: it breaks at any intervening user turn, so a stale gate can't be resolved by a later message.

The round-trip tests are the ones that were missing. They drive a real event list through the real processor with a real LlmAgent and FunctionTool — no mocks — and the no-broadcast case asserts orig-2 is invoked and orig-1 is not, which is the assertion that would have caught the original bug. as never is gone in favour of a real agent, and RequireConfirmation is named, camelCased and exported.

CI: the earlier macOS/Windows reds were timeout flakes (AgentLoader discovery, 40s) in a package this PR doesn't touch; both passed on re-run and all three platforms are green now.

One cosmetic note below. LGTM.

[AmaadMartin]

Nit, optional. runFromInputFile is the one call site where "Interactive CLI" isn't true.

      // Interactive CLI: let a plain-text "yes"/"no" resolve a pending tool
      // confirmation (opt-in; off by default on non-interactive surfaces).
      runConfig: {plainTextToolConfirmation: true},

This is the --input_file replay path — queries come from a JSON file, nobody is at a prompt. Enabling the flag here is still the right call (the file is authored by whoever runs the CLI, so it's the same trust boundary), but the comment says the opposite of what this function does, and it's the justification a future reader will lean on. The copy at :153 in runInteractively is accurate as written.

Something like "Local CLI surface (interactive prompt or replayed input file)" covers both.