Human-in-the-loop approval

Not every tool call should run immediately. Attach a Policy with require_approval so the runtime pauses dispatch until a human decides.

Define a Policy

Policies evaluate at dispatch time—before the worker runs. Conditions match tool arguments; decision.type: require_approval opens an approval row.

apiVersion: phrony.com/v1
kind: Policy

metadata:
  name: high-severity-alert-boundary
  namespace: weather
  version: 1.0.0

spec:
  description: High-severity alerts need a human before dispatch.
  conditions:
    field: severity
    op: gt
    value: 3
  decision:
    type: require_approval
    approvals_required: 1
    reason: Severity above delegated limit.
    on_reject: return_to_agent

Attach it to a tool binding

spec:
  tools:
    - ref: weather.get-forecast
      as: get_forecast
    - ref: weather.send-alert
      as: send_alert
      policies:
        - ref: policies/high-severity-alert-boundary.yaml

Publish and deploy a new agent version, then run a session whose tool args match the condition (for example severity: 5).

Approve from the CLI

The session moves to awaiting_approval. In another terminal:

$ phrony approvals list
$ phrony approvals show APPROVAL_ID
$ phrony approvals approve APPROVAL_ID --comment "verified"

Set PHRONY_ACTOR so decisions are attributed in the audit trail. Reject with phrony approvals reject—behavior follows policy on_reject.

Detached runs

You do not need an interactive --attach session to approve. Operators can decide out-of-band while the run stays paused.

Quorum, timeouts, and comprehension flags: Human-in-the-loop approvals, phrony approvals.

What you end up with

Same layout as tool binding: tools/weather.send-alert.yaml holds the capability (schema, side effect class); agent.yaml only lists ref, as, and the policy on send_alert—no duplicate tool definition on the Agent.

apiVersion: phrony.com/v1
kind: Agent

metadata:
  name: my-agent
  namespace: default
  version: 0.3.0

secrets:
  openai:
    fromEnv: OPENAI_API_KEY

spec:
  purpose: Answer questions clearly and concisely.
  instructions:
    text: |
      You are a helpful assistant. Be accurate and concise.
      Respect approval gates—do not assume a sensitive tool ran until confirmed.
  model:
    provider: openai
    name: gpt-4o
  tools:
    - ref: weather.get-forecast
      as: get_forecast
    - ref: weather.send-alert
      as: send_alert
      policies:
        - ref: policies/high-severity-alert-boundary.yaml

output:
  format: text