Skip to main content
@clawboo/governance holds Clawboo’s decision rules as pure functions and zod schemas, with no database, network or node:* access. The board, the server and the SPA all import the same rules, so a badge on screen and the check that enforces it cannot disagree. The state the rules decide over lives in @clawboo/db, and the server applies the decisions. Use this page when you change how Clawboo decides whether work passed verification, spend is over a budget, a delegation goes too deep, a run is looping, or an agent may call a connector tool.

What it decides

Budgets: warn is the default

The budget functions compute a status from a limit and the spend so far: active, soft_capped at the soft threshold (SOFT_CAP_PERCENT of the limit), and paused at the limit. They do not decide whether paused stops anything. That depends on the budget’s mode, stored by @clawboo/db:
  • warn, the default. Spend is tracked and warnings fire at the soft threshold and at 100%. A warn budget is stored as soft_capped even past its limit, so it never reads paused and never stops work.
  • cap, opt-in. The budget pauses at 100%, and the task runner, team chat and one-to-one chat refuse to start work for a paused scope (budget_paused).
Spend is kept in micro-cents (MICRO_CENTS_PER_CENT), so sub-cent turns still add up. Which run paths a hard cap can actually stop, and when, is explained in Budgets and guardrails; the user’s view is Budgets and spend.

Caps

The caps are enforced in code below the model, whatever the prompt asks for. The full list of numbers is on Limits and defaults.

Circuit breakers

createBreakerState(config) makes a run-local accumulator, and stepBreaker(state, signal) feeds it one signal taken from a typed RuntimeEvent (a tool call, a tool result, a cost, a policy denial) and returns the first trip it sees. A trip names its reason: iteration-cap, repeat-failure, no-progress, token-velocity or repeat-policy-denied. toolSignature(name, input) identifies a repeated call from its name and a hash of its input, never from prose. BREAKER_DEFAULTS holds the thresholds, and POST /api/runtimes/<id>/run accepts a partial breakerConfig that breakerConfigSchema validates. Breakers run only on the task runner path, not in team chat.

Verification

These rules judge one attempt at a task and decide what happens next. Which runs are verified at all (only task-runner runs in a git worktree with changes to check) is explained in How work is checked.
  • One attempt. verificationStatusFor(deterministic, critic) returns fail when the verify command failed, fail when it passed but the critic found a blocking problem, and pass otherwise.
  • Blocking findings. classifySeverity blocks on security, crash, data_loss, wrong_algorithm and missing_ac; every other finding is recorded as debt.
  • Retries. nextCycleDecision retries a failed attempt until the attempts run out, then marks the work as completed with debt, which sends the task to a person. The server’s attempt budget is CLAWBOO_MAX_FIX_CYCLES plus one (two attempts by default); the package’s DEFAULT_MAX_FIX_CYCLES is not used by the server.
  • Moving to done. isVerdictPromotable is the rule updateStatus applies to a stored verdict on the way to done: pass may move, and completed_with_debt may move only when the latest verify command passed. Any other verdict is refused unless a person overrides it. A task with no stored verdict was never checked, and it moves to done normally.
  • The critic. shouldRunCritic runs the read-only reviewer for delegated work, a risk flag (no caller sets one), or a diff over the size threshold (DEFAULT_CRITIC_THRESHOLD).
  • The verify command. parseVerifyCommand reads VERIFY_CMD from a task’s init.sh and returns null for a missing value or the placeholder Clawboo writes.
  • Where a verdict came from. A gate result records its commandSource (configured, scaffold, agent or none), and a critic verdict that ran records its outcome (reviewed, empty or errored). Both are optional, so verdicts stored before they existed still parse.

Connector grants

A grant says that an agent (or a team) may use one connector, in a mode, under an approval policy. It is both the permission the broker checks and the edge the Org chart draws: the graph asks decideGrant the same question through previewGrant, so the picture and the gate cannot disagree. decideGrant checks a call in a fixed order, and the order matters:
1

Find the grant and check its state

No matching grant denies with no-grant. A revoked, suspended, proposed or expired grant denies, and expiry is checked against the clock as well as the stored state.
2

Check for drift

If the connector’s spec or tool list changed since the grant pinned them, the call is denied (spec-drift). This runs before the scope check, so a renamed or redefined tool is caught as drift.
3

Check scope, mode and rate

The tool must match the grant’s allow and deny patterns, the tool’s required mode must not exceed the grant’s mode, and the grant’s hourly call ceiling must not be reached.
4

Check the run's risk

If the run’s combined reach reads private data, ingests untrusted content and can send data out (the lethal trifecta), or the run is tainted and can send data out, the call needs a person’s approval. These approvals are never remembered, and they run before the approval policy, so a policy of never cannot switch them off.
5

Apply standing rules and the policy

A standing deny rule denies. A never-remember tool always asks, whatever the policy. A policy of always asks next, even for a tool a standing allow rule covers, and marks the request never-remember. Otherwise a standing allow rule allows, and then the policy decides: writes asks for a mutating tool, never allows, and risk asks for a destructive tool or a mutating tool with external effects.
The broker’s grant gate in @clawboo/db calls decideGrant for every call to a connector tool, and charges the hourly window in the same synchronous step as the decision. The broker’s own risk check runs after it: a call that a standing allow rule let through skips that check’s prompt for an external change, but a destructive tool asks every time, rule or not, and its prompt is never remembered. Clawboo’s built-in tools are never grant-governed. Every decision is recorded as a grant_decision event. How users attach a connector to an agent is on Connect tools to your agents.

Test it

Run pnpm --filter @clawboo/governance test. Each group has its own suite, and grants/ tests the decision order case by case. A change to decideGrant usually needs a matching case in the grant gate tests in @clawboo/db.
Last modified on November 3, 2026