Configure governance, budgets, and caps in Clawboo

Before you let agents run unattended — on a schedule, across a delegation tree, or through a long-running session — set up governance so a runaway agent can’t drain your API budget. Clawboo has four mechanisms: budgets (a USD kill-switch you opt into), circuit breakers (always on, halt a stuck run before it hits the dollar ceiling), orchestrator caps (depth, fan-out, and per-node cost), and delegation approvals (human sign-off for destructive actions). This guide walks you through each one in the order you’d apply them.

If you haven’t deployed a team yet, complete Deploy your first team first. Governance only does something once runs produce cost events.

What you are setting up

Mechanism	Layer	On by default?	What you do here
Budgets	Executor cost loop	On, but uncapped	Create one in `cap` mode to get the kill-switch
Circuit breakers	Executor cost/tool loop	On, conservative defaults	Understand them — no configuration needed
Caps (depth / fan-out / cost)	Orchestrator boundary	On, conservative defaults	Read them in the dashboard
Approvals	Orchestrator boundary	On for risky delegations	Resolve one when it appears

Every mechanism keys on typed RuntimeEvent values — a cost event’s dollar delta, a tool-call/tool-result pair, a typed error code — never on rendered prose.

Prerequisites

The Clawboo dashboard is running. See Installation.
Open the Governance nav view (GovernancePanel). No flag is needed.
Your resolved API port for curl examples — default 18790, with auto-fallback through 18809.
A team ID to scope the budget to. Grab one from GET /api/teams or the team header.

Steps

Confirm the default posture

Out of the box no budget row exists, so the kill-switch enforces nothing. Confirm it:

curl http://localhost:18790/api/governance/budgets

A fresh install returns { "budgets": [] }. An empty list means uncapped, not zero. You already get the always-on tracking, the audit log, and the circuit breakers for free — budgets are the one piece you opt into.

Create a budget in cap mode

A budget is a USD limit on a scope. There are four scopes:

Scope	What it bounds
`agent`	One agent’s lifetime spend
`mission`	One delegation tree’s spend (keyed to the root task)
`team`	A whole team’s spend
`tenant`	Dormant per-org seam (not active in v0.2.0)

The mode is the difference between watching a budget and enforcing one:

warn (the default) — records spend and emits a warning at the 80% and 100% crossings, but never pauses a run.
cap — identical tracking, but the 100% crossing auto-pauses the run and flips the scope status to paused.

From the dashboard’s inline create form: pick scope (team), enter the scope ID (your team ID), set the limit in dollars, choose hard cap, and click Set budget.The equivalent REST call — a $5.00 hard cap on a team:

curl -X POST http://localhost:18790/api/governance/budgets \
  -H 'Content-Type: application/json' \
  -d '{
    "scope": "team",
    "scopeId": "<team-id>",
    "limitUsdCents": 500,
    "mode": "cap"
  }'

The new row starts at spent 0 / active.

limitUsdCents must be a positive integer. A cap of $0 is rejected with 400 { "error": "invalid body" }. If you omit mode, the budget defaults to warn — you must pass "mode": "cap" to get the auto-pause.

Watch the kill-switch pause at 100%

Dispatch work that spends past the cap (run a task on the team or let group chat drive a delegation). Spend accumulates inside the executor’s cost loop on every cost event — atomically, across all three concrete scopes:

// Inside the executor cost loop (reference only)
recordSpend(db, 'agent', assigneeAgentId, ledgerCents)
recordSpend(db, 'mission', missionId, ledgerCents)      // root task of the tree
recordSpend(db, 'team', task.teamId, ledgerCents)

The moment a cap-mode scope’s spend crosses 100%, the runner:

Adds an auto_pause entry to the governance audit log (eventType: 'budget').
Posts a system comment on the board task: “Auto-paused: <team> budget reached. Raise the cap (or resume) to continue.”
Completes the execution as cancelled with error budget_paused:<scope> and fires an execution_completed observability event.
Releases the task back to todo — retryable once you raise the cap.

Confirm the pause:

curl http://localhost:18790/api/governance/budgets
# The team row now reads "status": "paused"

The status pill in the dashboard turns red.

Resume the paused scope (raise the cap first)

A paused budget shows a Resume button. Before you click it, raise the cap — a bare resume of a scope whose spend already meets its limit re-pauses on the very next cost event.

A bare resume re-arms the kill-switch without granting any new headroom. When the dashboard shows willRepause: true after a resume, you need to raise the cap, not keep resuming.

Two ways to make real forward progress:Raise the cap — re-POST the same /api/governance/budgets route with a higher limitUsdCents. Setting the limit above the current spend un-pauses the scope automatically.Resume with grace — the resume route accepts an optional graceUsdCents body that raises the cap to spent + grace in one call (REST only; the dashboard Resume button sends a bare resume):

curl -X POST http://localhost:18790/api/governance/budgets/team/<team-id>/resume \
  -H 'Content-Type: application/json' \
  -d '{"graceUsdCents": 100}'

Understand the five circuit breakers

Circuit breakers are a deterministic, always-on backstop for a run that is going nowhere. They halt a run that burns turns or tokens on a stuck or looping call before the dollar ceiling is reached. A healthy run never trips them.

Reason	Fires when	Default
`iteration-cap`	Settled tool-calls in one run exceed the ceiling	`> 30`
`repeat-failure`	Same failing tool signature N times in a row	`≥ 3`
`no-progress`	N tool-results that add no new successful output	`≥ 6`
`token-velocity`	Tokens per minute exceeds ceiling over a minimum window	`> 200,000/min`, `≥ 15s` window
`repeat-policy-denied`	Same typed policy-denial code N consecutive times	`≥ 2`

When a breaker trips, the teardown mirrors a budget auto-pause exactly: a circuit_break audit entry, a board comment ([stopped: <reason>] Released to todo for re-planning.), a cancelled execution with error circuit_broken:<reason>, and a release back to todo. The worktree is left intact so a retry resumes from clean state.You can override thresholds per run with the breakerConfig field on POST /api/runtimes/:id/run. Full details are in Governance — the circuit breakers.

Read the enforced-in-code orchestrator caps

Open the Caps (enforced in code) section of the Governance dashboard. These are stateless predicates enforced at the orchestrator boundary — they refuse a delegation before it becomes a board task. They are informational in the UI and not editable from the dashboard.

Cap	Bounds	Default
Depth	How deep a delegation tree may grow	`2`
Fan-out	How many parallel delegations one turn may spawn	`8`
Cost	A single run’s accrued cent ceiling (opt-in per run)	`maxNodeCents` field

The depth cap prevents runaway sub-delegation: a leader → specialist → one more level, and no further. The orchestrator computes depth from the board’s parent_task_id chain and refuses a delegation that would exceed it.
The fan-out cap counts delegations spawned in one turn. Overflow delegations are dropped with a comment.
The per-node cost cap (maxNodeCents) is a per-run cent ceiling. Pass it in POST /api/runtimes/:id/run’s body.

A cap hit is logged to the audit log with eventType: cap_hit.

Resolve a risky-delegation approval

Some delegations require human sign-off before they run — destructive or external actions (matching verbs like delete, deploy, publish, rm -rf, prod, secret, force-push). When a risky delegation fires, the orchestrator creates a pending approval and blocks until you resolve it.Open the Approval queue in the Governance panel (the same queue as the standalone Approvals panel). Each pending row shows the tool name, an expiry countdown, the reason, and an args summary.

Click Allow Once to let this specific delegation proceed.
Click Always to skip the prompt for this scope key in future (allow_always).
Click Deny to skip the delegation — the leader receives a system comment and a reflection so it can revise or reassign.

Forgotten approvals time out rather than deadlock. Each approval carries an expiresAt, and a durable TTL reaper expires abandoned pending approvals and unblocks the linked board task. Configure the TTL with CLAWBOO_APPROVAL_TTL_MS. See environment variables.

The delegation-approval gate fails closed: if the approval endpoint is unreachable, the request resolves as timeout — never allow_once. An unreachable endpoint must not auto-approve a destructive action.

Verify it worked

A new or raised budget appears (or updates) in the Budgets list within the 5-second poll. Confirm with curl http://localhost:18790/api/governance/budgets.
A cap-mode scope that crossed 100% reads "status": "paused" with a red status pill, an auto_pause audit entry, and the budget_paused:<scope> board comment.
A resumed scope flips back to "status": "active". If it shows willRepause: true, raise the cap instead.
A resolved approval disappears from the Approval queue on the next 3-second refetch, and the gated delegation proceeds (or is skipped on a deny).
The audit log carries the full trail. Filter it:

curl 'http://localhost:18790/api/governance/audit?eventType=budget'
curl 'http://localhost:18790/api/governance/audit?eventType=cap_hit'
curl 'http://localhost:18790/api/governance/audit?eventType=circuit_break'

Troubleshooting

A warn-mode budget never stops a run. It records spend and warns at 80% / 100% but never flips to paused. To actually stop runs, re-create the budget in hard cap mode. The dashboard’s Set cap button preserves the existing mode — switch by re-creating with hard cap selected.

A cap-mode budget keeps re-pausing right after Resume. That is expected when spend already meets or exceeds the cap. A bare resume re-arms the kill-switch; the next cost event re-pauses it immediately. Raise the cap above the current spend to grant real headroom.

Setting a $0 budget does nothing. The POST is rejected with 400 invalid body. A cap must be a positive cent amount. “Uncapped” is the absence of a budget row, not a $0 limit.

Governance concept

Budgets, the kill-switch, circuit breakers, caps, and approvals explained in full.

Governance dashboard

Every panel control and the audit log, step by step.

Recurring team work

Schedule the unattended work this guide protects.

Governance API reference

Full request/response shapes for budgets, resume, audit, and approvals.

Observability dashboard

The event log and audit trail governance writes into.

Approvals

The tool-approval queue surfaced as a standalone panel.

​What you are setting up

​Prerequisites

​Steps

​Verify it worked

​Troubleshooting

​Related

Governance concept

Governance dashboard

Recurring team work

Governance API reference

Observability dashboard

Approvals

What you are setting up

Prerequisites

Steps

Verify it worked

Troubleshooting

Related