Approvals

When a policy rule says ask, the run pauses before that call until a person decides, then resumes: in the same process, another one, or over HTTP.

Every output on this page is what the code printed when it was run. The model’s wording, and the ids, will differ on your run.

Pause, decide, resume

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry
from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy

tools = ToolRegistry()

@tools.register_tool("issue_refund")
def issue_refund(order_id: str, amount: float) -> dict:
    """Refund an order."""
    return {"order_id": order_id, "refunded": amount}

policy = build_default_policy("interactive-dev")
policy.rules.ask.append(
    PolicyRule(
        rule_id="ask_before_refunds",
        effect=PolicyEffect.ASK,
        capability="tool.local.call",
        target={"tool_name": "issue_refund"},
        reason="Refunds need a person.",
    )
)

async def main():
    agent = OmniCoreAgent(
        name="support",
        system_instruction="You help with orders. Refund when asked. Answer in plain text, in one sentence.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
        agent_config={"governance_config": {"enabled": True, "policy": policy}},
    )
    result = await agent.run("Please refund order 1042 in full: 42 dollars.")
    print("status:", result["status"])
    approval = result["approvals"][0]
    for key, value in approval.items():
        print(f"  {key}: {value}")

    # Approve a smaller refund than the one asked for.
    await agent.resolve_approval(
        result["run_id"], approval["approval_id"],
        decision="approve", approver="alice", note="partial refund agreed",
        arguments={"order_id": "1042", "amount": 30.0},
    )
    result = await agent.resume(result["run_id"])
    print("status:", result["status"])
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print(call["tool_name"], call["arguments"], call["outcome"])
            for decision in call["governance"]:
                print("  ", decision["effect"], decision["reason_code"],
                      decision["approved_by"], decision["approval_id"])
    await agent.cleanup()

asyncio.run(main())

status: awaiting_approval
  approval_id: approval_b9ab6c7c4a394832975ba69d4def93d5
  tool_call_id: call_VIIA94lbdxEadjdCPYOVmHLB
  tool_name: issue_refund
  capability: tool.local.call
  target: {'path': None, 'host': None, 'resource': None, 'tool_name': 'issue_refund', 'mcp_server': None}
  arguments: {'order_id': '1042', 'amount': 42}
  command: None
  risk_level: low
  reason: Refunds need a person.
  expires_at: 2026-09-27T16:26:21.045398+00:00
  delegated_run_id: None
  delegated_name: None
status: success
Refunded order 1042 for $30.
issue_refund {'order_id': '1042', 'amount': 30.0} success
   ask matched_ask None None
   allow approved alice approval_b9ab6c7c4a394832975ba69d4def93d5

run() returned awaiting_approval; nothing unapproved ran.
Each approval has the tool, the model’s arguments, the rule’s reason and expires_at. command is None here; for a shell command it names the commands the call would run (below).
arguments= replaced the model’s: 30 was refunded, not 42.
On resume, the call was asked again and allowed by the recorded decision.

A run can pause again after a resume, so decide in a loop:

while result["status"] == "awaiting_approval":
    for approval in result["approvals"]:
        await agent.resolve_approval(
            result["run_id"], approval["approval_id"], decision="approve", approver="alice"
        )
    result = await agent.resume(result["run_id"])

On the default profile

The examples on this page start from interactive-dev, which also asks before other things (MCP tool calls, shell commands, high-risk actions). To keep the default profile, permissive-dev, and ask about one tool only, add one ask rule to it. An ask outranks the profile’s allows, so the rule takes effect:

from omnicoreagent import OmniCoreAgent, ToolRegistry
from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy

tools = ToolRegistry()

@tools.register_tool("issue_refund")
def issue_refund(order_id: str, amount: float) -> dict:
    """Refund an order."""
    return {"order_id": order_id, "refunded": amount}

policy = build_default_policy("permissive-dev")
policy.rules.ask.append(
    PolicyRule(rule_id="ask_before_refunds", effect=PolicyEffect.ASK,
               capability="tool.local.call", target={"tool_name": "issue_refund"},
               reason="Refunds need a person.")
)

agent = OmniCoreAgent(
    name="support",
    system_instruction="You help with orders. Refund when asked. Answer in plain text, in one sentence.",
    model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    local_tools=tools,
    agent_config={"governance_config": {"policy": policy}},
)

Every other call is decided as permissive-dev decides it; issue_refund pauses the run for a person, as above.

The three decisions

# Approve the call as the model made it:
await agent.resolve_approval(run_id, approval_id, decision="approve", approver="alice")

# Deny it; the note reaches the model:
await agent.resolve_approval(run_id, approval_id, decision="deny", approver="carol",
                             note="Store credit only for this order.")

# Approve a different call instead:
await agent.resolve_approval(run_id, approval_id, decision="approve", approver="alice",
                             arguments={"order_id": "1042", "amount": 30.0})

After a denial, the call does not run and the model reads the note. With the note above (over HTTP), the run answered:

Refund for order 1042 couldn’t be issued because approval was denied and store credit only is allowed for this order.

A decision applies once, to that exact call (tool, target and arguments). For a shell command, the pending approval names the commands it would run, one per line, in approvals[i]["command"]["summary"], each as written, with its variable settings and redirects (GIT_SSH_COMMAND='…' git push, echo key >> ~/.ssh/authorized_keys); a newline or other control character is shown as \n, so a quoted newline cannot pass for a second command. The decision applies to that exact command text: approving ls approves nothing else. Setting up a sandbox is the one exception: an approved network, file system or environment set-up holds for the rest of the run, for that exact set-up. Each sandbox session asks for it when it opens, and a resume opens a new one; the person is not asked the same question twice in one run.

From another process

A paused run lives in the agent’s memory store. With a durable store, any process with an agent built the same way (same memory store, workspace, tools and policy) can decide and resume it.

One definition, shared

# agent_def.py
import os
os.environ.setdefault("DATABASE_URL", "sqlite:///./runs.db")

from omnicoreagent import MemoryRouter, OmniCoreAgent, ToolRegistry
from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy

tools = ToolRegistry()

@tools.register_tool("issue_refund")
def issue_refund(order_id: str, amount: float) -> dict:
    """Refund an order."""
    return {"order_id": order_id, "refunded": amount}

policy = build_default_policy("interactive-dev")
policy.rules.ask.append(
    PolicyRule(rule_id="ask_before_refunds", effect=PolicyEffect.ASK,
               capability="tool.local.call", target={"tool_name": "issue_refund"})
)

def build_agent() -> OmniCoreAgent:
    return OmniCoreAgent(
        name="support",
        system_instruction="You help with orders. Refund when asked. Answer in plain text, in one sentence.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
        memory_router=MemoryRouter("sql"),
        agent_config={"governance_config": {"enabled": True, "policy": policy}},
    )

Process one: run until it pauses, then exit

# start.py
import asyncio
from agent_def import build_agent

async def main():
    agent = build_agent()
    result = await agent.run("Please refund order 1042 in full: 42 dollars.")
    print(result["status"], result["run_id"])
    for approval in result["approvals"]:
        print(approval["approval_id"], approval["tool_name"], approval["arguments"])
    await agent.cleanup()

asyncio.run(main())

awaiting_approval run_0969e2425de24a57be913bbfd47c1565
approval_5c2368402c1444e38ae3e8977d42311f issue_refund {'order_id': '1042', 'amount': 42}

Process two: decide and resume

# decide.py
import asyncio, sys
from agent_def import build_agent

async def main(run_id: str, approval_id: str):
    agent = build_agent()
    run = await agent.get_run(run_id)
    print("found:", run["status"], [a["status"] for a in run["approvals"]])
    await agent.resolve_approval(run_id, approval_id, decision="approve", approver="bob")
    result = await agent.resume(run_id)
    print(result["status"], "|", result["response"])
    await agent.cleanup()

asyncio.run(main(sys.argv[1], sys.argv[2]))

python decide.py run_0969e2425de24a57be913bbfd47c1565 approval_5c2368402c1444e38ae3e8977d42311f

found: awaiting_approval ['pending']
success | Refunded order 1042 for $42.

The same two processes worked unchanged on each durable store; only the store in agent_def.py changes:

Store	In `agent_def.py`	Install
SQLite (one machine)	`DATABASE_URL=sqlite:///./runs.db`, `MemoryRouter("sql")`	`omnicoreagent[postgres]` (it brings SQLAlchemy, which every `sql` store needs)
PostgreSQL	`DATABASE_URL=postgresql://user:pass@host/db`, `MemoryRouter("sql")`	`omnicoreagent[postgres]`
Redis	`REDIS_URL=redis://host:6379/0`, `MemoryRouter("redis")`	`omnicoreagent[redis]`
MongoDB	`MONGODB_URI=mongodb://host:27017`, `MemoryRouter("mongodb")`	`omnicoreagent[mongodb]`

On Redis, for example, process two printed:

found: awaiting_approval ['pending']
success | Refunded order 1042 for 42 dollars.

The default in-memory store dies with the process (Memory).

Answer in the moment: `approval_resolver`

To answer while the run waits (a console prompt, a chat button), give a resolver. It is called at every ask; the run does not pause:

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry
from omnicoreagent.governance import (
    ApprovalRequest, ApprovalResult, PolicyEffect, PolicyRule, build_default_policy,
)

tools = ToolRegistry()

@tools.register_tool("issue_refund")
def issue_refund(order_id: str, amount: float) -> dict:
    """Refund an order."""
    return {"order_id": order_id, "refunded": amount}

policy = build_default_policy("interactive-dev")
policy.rules.ask.append(
    PolicyRule(rule_id="ask_before_refunds", effect=PolicyEffect.ASK,
               capability="tool.local.call", target={"tool_name": "issue_refund"})
)

class OnCallApprover:
    """Answers each ask in the moment, while the run waits."""

    async def resolve(self, request: ApprovalRequest) -> ApprovalResult | None:
        print("asked:", request.capability, request.metadata["tool_name"], request.reason)
        # Call your chat tool, ticket system or console here.
        return ApprovalResult(
            approved=True,
            approval_id=request.approval_id,  # must be the request's own id
            resolved_by="on-call:dana",
            reason="Refund within policy",
        )

async def main():
    agent = OmniCoreAgent(
        name="support",
        system_instruction="You help with orders. Refund when asked. Answer in plain text, in one sentence.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
        agent_config={"governance_config": {
            "enabled": True, "policy": policy, "approval_resolver": OnCallApprover(),
        }},
    )
    result = await agent.run("Please refund order 1042 in full: 42 dollars.")
    print(result["status"], "|", result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            for decision in call["governance"]:
                print(call["tool_name"], decision["effect"], decision["reason_code"], decision["approved_by"])
    await agent.cleanup()

asyncio.run(main())

asked: tool.local.call issue_refund Matched ask policy rule.
success | Refunded order 1042 for 42 dollars.
issue_refund ask matched_ask None
issue_refund allow approved on-call:dana

ApprovalRequest has capability, target, risk_level, reason, expires_at, and metadata["tool_name"]; not the call’s arguments.
Returning None or approved=False refuses the call; nothing is saved for later.
StaticApprovalResolver(approved=True) approves everything (tests); not high-risk requests unless allow_static_high_risk_approvals is True.

Refuse instead of pausing: `approval_mode="fail"`

For unattended jobs:

agent_config = {"governance_config": {"enabled": True, "policy": policy, "approval_mode": "fail"}}

The same refund request then finished at once:

success | I can’t complete the refund without approval.
issue_refund denied {'type': 'ApprovalRequiredError', 'message': 'Matched ask policy rule.'} ask matched_ask None

The tool did not run, and its outcome is denied. The model was told the call was refused because it needs a person’s approval and none can be asked. (0.4.1 reported it as awaiting_approval and told the model it was waiting.)

Expiry

24 hours by default; per rule:

PolicyRule(rule_id="ask_before_refunds", effect=PolicyEffect.ASK,
           capability="tool.local.call", target={"tool_name": "issue_refund"},
           constraints={"approval_expires_seconds": 900})  # 15 minutes

The window is how long a person has to decide. A decision made in time stands, however late the run resumes. An approval nobody decides in time is a no: resume(run_id) refuses the call, tells the model the approval expired, and the run goes on to finish. (In 0.4.1 an expired approval left its run unable to resume; abandon_run is the way out there.)

Over HTTP, with OmniServe

The refund agent above as a module-level agent in refund_agent.py, served with omniserve run --agent refund_agent.py --port 8765:

curl -s -X POST localhost:8765/run/sync -H "Content-Type: application/json" \
  -d '{"query": "Please refund order 1042 in full: 42 dollars."}'

{
    "status": "awaiting_approval",
    "termination_reason": null,
    "guardrail_result": null,
    "response": null,
    "approvals": [
        {
            "approval_id": "approval_17ef0caeab45476a8111230da88ca123",
            "tool_call_id": "call_lwco7KcQbejqDVaoP274zL4Z",
            "tool_name": "issue_refund",
            "capability": "tool.local.call",
            "target": {
                "path": null,
                "host": null,
                "resource": null,
                "tool_name": "issue_refund",
                "mcp_server": null
            },
            "arguments": {
                "order_id": "1042",
                "amount": 42
            },
            "command": null,
            "risk_level": "low",
            "reason": "Matched ask policy rule.",
            "expires_at": "2026-09-27T16:31:43.848500+00:00",
            "delegated_run_id": null,
            "delegated_name": null
        }
    ],
    "budget_request": null,
    "session_id": "omni_core_agent_support_5a3ab1cb",
    "agent_name": "support",
    "metric": null,
    "trace_id": "trace_00ee4a1be1e0419389108690ddfa9e53",
    "run_id": "run_4a33c9adb579417ba7a47fb607ecb384"
}

Decide, then resume:

curl -s -X POST localhost:8765/runs/$RUN_ID/approvals/$APPROVAL_ID \
  -H "Content-Type: application/json" \
  -d '{"decision": "deny", "approver": "carol", "note": "Store credit only for this order."}'

curl -s -X POST localhost:8765/runs/$RUN_ID/resume

The decision returns the approval (status denied, decision deny, approver, note, decided_at); the resume returns the finished run.

Route	Body	Errors
`POST /runs/{run_id}/approvals/{approval_id}`	`decision`, `approver`, `note`?, `arguments`?	`404`, `409` decided or expired
`POST /runs/{run_id}/resume`	none	`404`, `409` still waiting or finished
`GET /runs/{run_id}`	none	`404`

Who decided, in the evidence

Where	What
Run record: `get_run(run_id)`, `GET /runs/{run_id}`	each approval’s `status` (`pending`, `approved`, `denied`, `expired`, then `used` once applied), `decision` (`approve` or `deny`, set when the person decides), `approver`, `note`, `decided_at`, `edited_arguments`
Trajectory: the call’s `governance`	the `ask`, then the decision: `allow` with `reason_code` `approved` and `approved_by`, or `deny` with `reason_code` `denied` and `denied_by` (the person), or `deny` with `expired_policy` and `denied_by` `system` when nobody decided in time; each with `approval_id`

Each pause and resume is its own trace segment; get_run_trajectory(run_id) joins them (Durable runs).

Options

In agent_config["governance_config"]:

Key	Default	What it does
`approval_mode`	`"suspend"`	`suspend` pauses, `fail` refuses
`approval_resolver`	`None`	Answers each ask in the moment
`allow_static_high_risk_approvals`	`False`	Static approvals for high-risk requests
rule `constraints.approval_expires_seconds`	24 hours	How long an approval waits

Methods: resolve_approval(run_id, approval_id, *, decision, approver, note=None, arguments=None), resume(run_id) (reference). Asks from inside a call (sandbox network, a command, a sub-agent) pause the run the same way; a worker’s ask shows on its lead’s run with delegated_run_id (Sub-agents, Background agents).

When things go wrong

ValueError: Run ... is still waiting for approval

resume was called before every approval was decided:

ValueError: Run run_243180db3831427c8d064f76696879ed is still waiting for approval: approval_b8f052bbfd504443a74345e7d3026860

Decide each approval the run lists first. Over HTTP this is a 409.

ValueError: Approval ... expired at ...

The approval waited longer than its window:

ValueError: Approval approval_b8f052bbfd504443a74345e7d3026860 expired at 2026-09-26T16:30:33.295381+00:00; resuming the run refuses the call

It is recorded as expired and nothing runs on it. resume(run_id) refuses the call (the model is told the approval expired) and the run finishes, or end the run instead:

ended = await agent.abandon_run(run_id, status="cancelled", reason="approval expired")
print(ended["status"], ended["error"])

cancelled {'type': 'RunEndedOutside', 'message': 'approval expired'}

Set a longer approval_expires_seconds if people need more time.

ValueError: Approval ... is already denied

A decision is final; it cannot be changed or made twice:

{"detail":"Approval approval_17ef0caeab45476a8111230da88ca123 is already denied"}

That is the 409 OmniServe returned; in Python it is a ValueError. Once a resume has applied the decision, the message says already used; the record’s decision still says which it was.

LookupError: No approval ... on run ...

The approval id is not one of this run’s, or the run is not in this agent’s memory store:

LookupError: No approval approval_nope on run run_b597df1120d849f0815c074b30874d42

In another process, build the agent with the same memory_router. ValueError: approver is required means approver was empty: every decision carries a name.

The run did not pause; the model said it needs approval

approval_mode is "fail", or an approval_resolver returned None. Either refuses the call on the spot. Remove both to pause for a person.

Policies

Decide what is asked about, and test the rules.

Durable runs

Run records, resuming after a crash, and how long evidence is kept.

Budgets

The other pause: a run that needs more budget.

OmniServe

Every route, including approvals and resume.

Security model

How approvals fit with the policy, sandbox and the rest.

Execution

Commands and scripts, and the asks they can raise.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Approvals

Approvals

Pause, decide, resume

On the default profile

The three decisions

From another process

Answer in the moment: `approval_resolver`

Refuse instead of pausing: `approval_mode="fail"`

Expiry

Over HTTP, with OmniServe

Who decided, in the evidence

Options

When things go wrong

Next

Policies

Durable runs

Budgets

OmniServe

Security model

Execution

​Approvals

​Pause, decide, resume

​On the default profile

​The three decisions

​From another process

​Answer in the moment: approval_resolver

​Refuse instead of pausing: approval_mode="fail"

​Expiry

​Over HTTP, with OmniServe

​Who decided, in the evidence

​Options

​When things go wrong

​Next

Policies

Durable runs

Budgets

OmniServe

Security model

Execution

Approvals

Pause, decide, resume

On the default profile

The three decisions

From another process

Answer in the moment: `approval_resolver`

Refuse instead of pausing: `approval_mode="fail"`

Expiry

Over HTTP, with OmniServe

Who decided, in the evidence

Options

When things go wrong

Next