Govern agents
Control which actions agents in Orca Agent Engine may take, with per-tool permission policies and guardrails that inspect context and apply across agents.
In Orca Agent Engine, two mechanisms govern what an agent may do. A permission policy is part of an agent's tool configuration and decides whether a tool runs immediately or waits for your approval. A guardrail is a rule stored in the registry that evaluates requests, tool calls, and tool results in context: the tool and its input, the model, and state the session has accumulated, such as spend and recent calls. A guardrail can apply to one session, one agent, every session in a Workspace, or every Workspace in an organization.
Permission policies and guardrails
| Permission policy | Guardrail | |
|---|---|---|
| Where you set it | permission_policy in the agent's tool configuration | A registry resource in the policy.runorca.ai API group, applied by scope or attached by ID |
| What it decides | Tool calls | User requests, tool calls, and tool results |
| What it can read | The tool name | The tool name and input, the tool result, the model, and session state |
| State | None | Counters and history kept for the session, such as spend, token use, and recent tool calls |
| Reach | One agent's tools | A session, an agent, a Workspace, or an organization |
| Outcomes | always_allow, always_ask | allow, ask, deny |
Use a permission policy to decide which of an agent's tools need approval. Use a guardrail when the decision depends on arguments or accumulated state, or when it must hold for agents you do not own.
How a decision is made
At each evaluation point, every applicable guardrail returns a verdict, and the strictest one wins:
| Verdict | Effect |
|---|---|
| allow | The action proceeds. A guardrail with no opinion abstains, which counts as allow. |
| ask | At tool_call, the session pauses and waits for a user.tool_confirmation event. At any other phase there is no approval exchange, so ask becomes deny. |
| deny | The action is blocked, and the first denying guardrail stops evaluation. |
Verdicts only tighten: allow < ask < deny. For a tool call, the agent's permission policy is the
starting verdict, so a guardrail can raise an always_allow tool to ask or deny but cannot relax an
always_ask tool. Rules that need no state run first, then stateful rules, each group in authority
order from session to organization. The first deny stops evaluation, so later rules neither run nor
record state.
Phases
A guardrail runs at one or more phases:
| Phase | Runs | The rule can read | If the rule cannot be evaluated |
|---|---|---|---|
request | Before a user message reaches the model | The user message (builtins only), the model, and session state | The request is denied |
tool_call | Before a tool runs | The tool name and input, the model, and session state | The call is denied |
tool_result | After a tool returns | The tool call, its result, and session state | The rule abstains |
The API also defines response, llm_request, and llm_response. No Agent Engine runtime evaluates
them, so the registry rejects a new guardrail that asks for one.
Where a guardrail applies
| Level | Set by | How | Applies to |
|---|---|---|---|
| Session | Whoever creates the session | guardrail_ids in an agent_with_overrides agent reference | That session |
| Agent | The agent's author | guardrail_ids on the agent | Sessions pinned to an agent version that lists it, including the subagents it dispatches |
| Subagent | The subagent's author | guardrail_ids on an agent in a multiagent roster | Actions taken by that subagent |
| Workspace | A Workspace credential holder | scope: "workspace", the default | Every session in the Workspace |
| Organization | An organization administrator | scope: "organization", written on the admin listener | Every session in every Workspace of the organization |
A session, agent, or subagent attaches a guardrail by ID. Those references usually point at
explicit guardrails, which apply nowhere else. A session's references add to its agent's; they
cannot remove any. See Guardrails for each operation.
Where guardrails are enforced
The registry stores guardrails and composes the set that applies to a session. The runtime that runs
the session enforces them, and these pages cover harnesses in separate mode: the
claude_agent_sdk harness evaluates all three phases, and the Codex SDK and Pi SDK harnesses
enforce a subset. On a self_hosted environment, only stateless request rules are enforced.
Depending on the runtime, a rule it cannot enforce stops the session, produces a warning, or goes
unenforced.
colocated mode - the claude_code harness, and Codex SDK or Pi SDK agents with
mode: colocated - does not fully support guardrails yet.
AI Gateway can evaluate block_tools and the budget rules
again on the model and MCP traffic it proxies. See Enforcement
before you apply a rule at Workspace or organization scope.
What's next
Guardrails
Create a guardrail, attach it to an agent or session, and retire it.
Builtin guardrails
Choose a rule from the catalog of tool, shell, integration, and budget checks.
Custom guardrails
Write a rule as a CEL expression over the request or tool call.
Enforcement
See what each runtime enforces and what a session reports when a rule fires.
Permission policies
Decide which tools run automatically and which pause for approval.