Skip to main content

​
Outcome

At the step you chose, the run pauses in awaiting_approval, a person approves or rejects it from the session card or the CLI, and the agent continues or stops according to the decision.

​
Before you start

  • The agent has a runbook skill; approvals are requested by the agent from inside the run, not configured as a policy. If the skill never calls runtm-approval, nothing waits.
  • Someone with the role you will require is watching Sessions, or the run will wait until --timeout expires.
  • The Approvals tab under Settings > Guardrails describes the concept but configures nothing.

​
Do it

1

Find the exact step

In the runbook, mark the line after which a consequence happens: posting a draft back to the ticket, issuing a refund, changing an application status. The approval goes immediately before that line, with the evidence already written to a file the approver can open.
2

Add the request to the skill

Write the call into SKILL.md at that step. --wait blocks until a person resolves it. Exit code 0 means approved, 1 means rejected, 4 means the wait timed out (2 is a usage error, 3 means the helper is not inside a Runtime session); on rejection the runbook must stop and report the note.
To request now and wait later, capture the id:
--required-role <org-role> or --required-team <team-id> restricts who may resolve it. Admins and owners always can. With neither flag, anyone with access to the session can.
3

Rebuild and run a seeded case

Editing the skill rebuilds the templates it is attached to. Run one seeded case that reaches the step. The session flips to awaiting_approval and its card shows Approve and Reject inline with the message in the tooltip.
4

Resolve it

Click Approve or Reject on the card, or resolve from the CLI with a note the agent will see.

​
Verify

session approvals list shows the request with its kind, message, required_role and status. After approval the session returns to working and the transcript continues past the step. After rejection the transcript shows the agent reporting the note and stopping.

​
Gotchas

  • Approvals are not delivered to Slack. The person approving needs the dashboard or the CLI. Tell the on-shift approver where to look.
  • No watcher, no progress. A --required-role nobody on shift holds waits forever. Use wait --timeout so the run fails cleanly instead of idling.
  • Instructions alone are not a gate. “Ask before refunding” in the system prompt is advice. The runtm-approval call in the runbook is what blocks, and a deny rule on the refund command in step 6 of Build is what makes bypassing it impossible.
  • Approval is not permission. An ask allowlist rule produces a harness permission prompt, not an approval record. Use approvals for decisions a person should own and see in the audit trail.

6. Add guardrails and approvals

Allowlist rules, hooks, network rules and the approval gate, added once the agent has proven it can do the job.