Interface ApprovalRequest

A pending approval request raised by the HITL subsystem. Passed to HitlConfig.handler and emitted on the approvalRequested callback.

interface ApprovalRequest {
    id: string;
    type: "tool" | "output" | "agent" | "emergent" | "strategy-override";
    agent: string;
    action: string;
    description: string;
    details: Record<string, unknown>;
    context: {
        agentCalls: AgentCallRecord[];
        totalTokens: number;
        totalCostUSD: number;
        elapsedMs: number;
    };
}

Properties

id: string

Unique identifier for this approval request.

type: "tool" | "output" | "agent" | "emergent" | "strategy-override"

What kind of action is awaiting approval.

  • "tool" — a tool invocation.
  • "agent" — an agent invocation.
  • "emergent" — synthesis of a new runtime agent.
  • "output" — the final answer before returning to the caller.
  • "strategy-override" — reserved; nothing raises it (see beforeStrategyOverride).
agent: string

Name of the agent that triggered the approval request.

action: string

Short action label (e.g. tool or agent name).

description: string

Human-readable description of what is being approved.

details: Record<string, unknown>

Structured details about the pending action (tool args, agent config, etc.).

context: {
    agentCalls: AgentCallRecord[];
    totalTokens: number;
    totalCostUSD: number;
    elapsedMs: number;
}

Run context. A beforeReturn ("output") request fills it from the result it approves: its agent calls, token total and cost, and the milliseconds since the call started. An "agent" or "emergent" request carries zeros and the strategy's own list of agent calls, not a copy: it holds the calls made before the request and grows as later calls finish, including calls of the same graph tier that finish while the request waits (under the parallel strategy it is an empty list of its own). A "tool" request carries no agent calls and zeros.

Type declaration

  • agentCalls: AgentCallRecord[]

    Agent call records (see above for which requests carry them).

  • totalTokens: number

    Total tokens of the result, on a beforeReturn request; 0 on the others.

  • totalCostUSD: number

    Total cost in USD of the result, on a beforeReturn request; 0 on the others.

  • elapsedMs: number

    Milliseconds since the call started, on a beforeReturn request; 0 on the others.