DashClaw Governance Protocol

Governance Decision Tree

For every action you consider, assess risk and follow this protocol:

Risk Assessment

Guard Decision Handling

When you call dashclaw_guard, you will receive one of four decisions:

allow — Proceed with the action. No restrictions.

warn — Proceed with caution. The action is permitted but flagged. Include the warning context in your action record (dashclaw_record).

block — Stop immediately. Do NOT proceed with the action. Do NOT attempt the action through another path or tool. Report the block reason to the user. The policy exists for a reason.

require_approval — A human must approve this action in DashClaw Mission Control.

1. Record the pending action: dashclaw_record with status: 'pending_approval'
2. Inform the user: "This action requires human approval in Mission Control."
3. Wait: call dashclaw_wait_for_approval with the action ID
4. Inspect the response — approved is true only when the action reaches status: 'completed' AND has an approved_by operator. Anything else (denied, cancelled, failed, or timed_out: true) means do not proceed:
   • approved: true → proceed and PATCH the outcome.
   • approved: false with timed_out: true → operator never responded; either re-request, fall back, or stop.
   • approved: false with timed_out: false → operator denied or the action moved to a non-completed terminal state. Stop and report error_message from the action record.

External API Calls

Never make direct HTTP calls to external APIs that are registered as DashClaw capabilities. Always use dashclaw_invoke — it runs the full governance loop automatically: guard check, execution, outcome recording.

Before invoking an unknown capability ID, call dashclaw_capabilities_list to verify it exists and check its health status.

Recording Rules

Record all significant actions with dashclaw_record. This powers the audit trail visible in Mission Control and the Decisions ledger.

Always record:

• Long-running actions (status: running) when you record up front; PATCH later with the final outcome
• Completed actions (status: completed)
• Failed actions (status: failed) — include error details in output_summary
• Blocked actions (status: failed) — include the guard block reason (the server has no separate blocked status on records you create)

Write meaningful fields:

• declared_goal — Write as if explaining to an auditor. Bad: "Deploy the app". Good: "Deploy v2.3.1 to staging after all tests passed".
• reasoning — Why you chose this action over alternatives.
• output_summary — What was produced or what went wrong.
• risk_score — Your honest assessment. Don't lowball to avoid guards.

For LLM-driven actions, include token usage (cost is auto-derived):

• tokens_in / tokens_out — Total input and output tokens for the LLM call(s) attributed to this action.
• model — Model identifier (e.g. claude-opus-4-6, gpt-5-codex). The server uses this to look up pricing.
• cost_estimate — Optional. Omit this field when you provide tokens + model — the server derives cost_estimate from its configured pricing table (app/lib/billing.js) so cost stays consistent across all agents. Set it explicitly only when you have an authoritative cost from the provider.

Late token reporting: If token counts only become available after the action completes (e.g. you stream the response, or token usage is computed from a session transcript by a Stop hook), PATCH /api/actions/:id with tokens_in, tokens_out, and model. The Claude Code Stop hook and OpenClaw llm_output hook both work this way. Cost is still derived server-side.

Session Lifecycle

Every governed session has a clean lifecycle:

1. dashclaw_session_start — Register at the beginning
2. Governance loop — Guard, act, record for each action
3. dashclaw_session_end — Close when done (status: completed, failed, or cancelled)

Include a summary in dashclaw_session_end describing what was accomplished.

Best Practices

1. Guard before act — When in doubt about risk, guard. False positives are cheap. Unauthorized actions are expensive.

2. Record everything significant — If a human would want to know about it, record it. Silent failures are governance gaps.

3. Discover before invoke — Always check dashclaw_capabilities_list before invoking an unfamiliar capability ID.

4. Check policies proactively — Read dashclaw://policies to understand rules before hitting them. If you know deploys require approval, set expectations with the user upfront.

5. Never bypass — If dashclaw_guard returns block, do not attempt the action through another tool, workaround, or indirect path.

6. Fail loudly — Record failures with status: 'failed' and a clear output_summary. Never silently retry without recording the failure first.

7. Be honest about risk — Use accurate risk_score values. Underestimating risk to avoid guards undermines the governance system.

For concrete implementation patterns, see references/governance-patterns.md.