Optional approvalsDeclarative approval triggers. All are opt-in; omitting a field means no pause at that lifecycle point.
Optional beforeTool names whose invocations require approval before execution; '*'
covers every tool. Enforced on every tool loop of a config seat, a
pre-built seat that forwards per-call options, a spawned specialist and
a nested agency, after onBeforeToolExecution has run. A rejection skips
the tool and the run goes on; a handler error (a throw, a decision whose
approved is not a boolean, a failure after the handler answered), or
a timeout under onTimeout: 'error', skips that tool and every later
one unasked, and rejects the call once the strategy settles, after the
run's usage is counted; the model is told only that the approval
handler failed. A strategy that fails after it does not replace that
error: the strategy's error goes to on.error, and with no result
returned, that run adds no usage.
Optional beforeAgent names whose invocations require approval before execution.
Optional beforeWhether emergent agent creation requires approval.
Optional beforeWhether returning the final answer requires approval.
Optional beforeReserved. No strategy asks for a strategy-override approval, so it
pauses nothing; like the other triggers, setting it makes agency()
require a handler.
Optional handlerCustom async handler invoked for every approval request.
On a beforeTool or beforeReturn request, the onTimeout policy
decides when it does not resolve within timeoutMs. A beforeAgent or
beforeEmergent request awaits it with no timer.
Optional timeoutMaximum milliseconds to wait for the handler on a beforeTool or
beforeReturn request. Defaults to 30_000.
Optional onPolicy applied when the handler does not respond within timeoutMs
(beforeTool and beforeReturn requests only).
"reject" — treat as denied; the action is blocked."approve" — treat as approved: the post-approval check still runs
(unless guardrailOverride is false) and can veto the action."error" — the request fails with an AgencyConfigError, and the
call rejects with it (on beforeTool, once the strategy settles).Optional guardrailRun the post-approval check AFTER HITL approval to catch destructive actions.
When enabled (default), even after the HITL handler (auto-approve, LLM
judge, or human) approves a beforeTool, beforeAgent or
beforeReturn request, agency() runs the built-in checks named by
postApprovalGuardrails over the tool call's name and arguments,
the agent's name and input, or the final text. These are fixed pattern
checks inside agency(), not guardrail packs. The agent's input is
checked as the strategy passes it, other agents' output included under
the sequential, graph, review-loop and debate strategies and at the
panel's chair, and as the agent receives it, with the approval's
modifications.instructions that every strategy appends, so
instructions a check blocks override the approval. Where the strategy
writes more text after the task or after another agent's output, the
task and each output are checked on their own too. The final text is
checked as the strategy produced it and, when the approval's
modifications.output replaces it, as the replacement, after the
agency's output guardrails have read it; a replacement does not clear a
strategy text a check blocks. If a check matches, the approval is
overridden: the tool call is skipped, the agent does not run, or the
final output is rejected. A beforeEmergent approval is not checked.
Set to false to disable this safety net and give full autonomy to the
HITL handler's decision.
true
Optional postIds of the built-in post-approval checks to run.
Only evaluated when guardrailOverride is not false, after the
HITL handler approves a beforeTool, beforeAgent or beforeReturn
request. Two ids have a check: code-safety (destructive commands and
statements such as rm -rf / and DROP TABLE) and pii-redaction
(unredacted SSNs and card numbers). Any other id passes without a check;
the guardrail packs registered with a runtime are not consulted.
['pii-redaction', 'code-safety']
Human-in-the-loop (HITL) configuration. Gates specific lifecycle events behind an async approval handler before the agent proceeds.