Add human approval for tools used by Orka v2 agents

[sozercan]

Problem

A tool is an operation an agent asks to run, such as reading inventory or creating a work order. Some operations should wait for a person's approval.

Orka's v2 agent path cannot do that yet. It rejects tools configured to require approval, both when preparing the task and before executing a tool call. This affects AgentKit running directly under Orka and agents reached through the Foundry runtime.

For example, an agent should be able to read inventory automatically, propose creating a work order, and wait while a person reviews that exact action. Today, enabling approval for the second step prevents this workflow from running.

Why this matters

Users need a practical way to review consequential actions while keeping ordinary lookups automatic. The review must control whether the action runs; asking the model to request permission in its instructions is insufficient.

Orka already has task approval records, a decision API, and an approval panel. The missing work is connecting those features to the v2 tool-execution path and its rules for cancellation and recovery.

This is a separate feature from the read-only Fibey demo in #518. That demo can continue to use tools that do not need human approval.

What should happen

1. The agent proposes a tool call that requires approval.
2. Orka saves a pending review and shows the proposed action and a safe preview of its inputs. The tool has not run.
3. An authorized person approves or declines in Orka.
4. On approval, Orka verifies that the task and proposed action are still valid, executes that action, and returns the real result to the waiting agent.
5. On decline, cancellation, or expiry, the action does not run. The task and agent receive the outcome defined by the shared approval behavior.

The review must cover the actual proposed operation and inputs. If a general tool such as call-tool wraps another operation, the review must still make that operation clear.

How to approach it

• Start with the existing approval records, decision API, and task approval panel. Reuse them where they fit; document any v2-specific behavior instead of introducing a second review system.
• Keep Orka responsible for deciding who may review, saving the decision, and allowing tool execution. AgentKit and the Foundry runtime should use Orka's decision.
• Save enough information to bind a review to the exact task run, tool call, inputs, and relevant tool configuration. Use the existing safe previews and argument fingerprints where possible. A decision for one call must not authorize a different call.
• Define how a runtime waits for a decision and receives a result or denial. Use existing tool-result continuation where it is sufficient. Specify any required communication changes in Orka first so both integrations use the same behavior.
• Define the approval wait limit and its interaction with task and session time limits. A person may take longer than a normal tool request. Waiting must remain cancellable, and a late approval must not revive a cancelled or expired task.
• Resume only the stored, approved action. Repeated clicks, repeated delivery of a decision, or controller recovery must not repeat a completed tool action. If an interrupted action may already have run, keep its outcome explicitly unknown and preserve its evidence.
• Revalidate the task's authority immediately before execution. A policy change, task replacement, lost ownership, or completed task must not be bypassed by an older approval.
• Remove the current rejection guards only when the complete flow is connected. Advertise support only for runtime combinations that pass the matching checks.
• Document setup and the user experience with one automatic lookup and one simulated action requiring approval.

Acceptance checks

• Existing tasks with no approval-required tools continue to work.
• A v2 task reaches a visible pending approval through the normal task API and UI, while the simulated tool's execution count stays at zero.
• Approval runs the expected action once and resumes the agent with its real result, without submitting the original prompt again.
• Decline produces a clear outcome and zero tool executions. A tool execution error after approval remains distinguishable from a declined review.
• Unauthorized reviewers, altered inputs, another task's approval, and stale decisions cannot authorize execution.
• Repeated or competing decisions have one recorded final decision and cannot repeat the action.
• Cancellation, task timeout, approval expiry, and a decision arriving afterward all prevent an unstarted action from running.
• Controller restart during a pending review preserves the request. Resume happens only when the original call is still valid; unsupported runtime-loss cases stay blocked with their evidence intact.
• An interruption after execution but before its result is recorded never triggers automatic repetition of an uncertain action.
• With available runtime capacity, an unrelated task using a separate runtime session can progress while another waits for review.
• The history records the proposed action, reviewer decision, and execution outcome without credentials or unsafe input previews.
• Deterministic integration tests use a simulated tool with an execution counter. Live acceptance covers direct AgentKit and AgentKit hosted in Foundry through Orka's real approval API, using disposable tasks and no real equipment or purchases.

Scope and related work

This issue owns Orka's implementation and the shared behavior the runtimes follow. The dependent runtime work is tracked separately:

• AgentKit compatibility and validation.
• Foundry bridge integration.

Keep this focused on tools Orka executes for v2 agents. Approving shell commands or file access performed directly inside a runtime is a separate capability. Existing AI-worker approvals must continue to work.

• feat(runtime): complete ACP runtime capabilities and qualification #290 tracks broader runtime capabilities; this is a focused implementation follow-up.
• test(acp): cover tools, permissions, streaming events, usage, and large results in execution workspaces #418 tracks execution-workspace qualification and is related test coverage.
• test(ai): verify approval decisions survive worker environment limits #495 covers the existing AI-worker approval path, which does not implement this v2 flow.

Code starting points

The rejection is present on main at commit 6a7ca5bd:

• Rejecting an approval-required v2 tool policy.
• Rejecting an approval-required call before execution.
• Existing task approval API.
• Existing task approval panel.