SDK Documentation

Risk composition (risk_breakdown)

Every guard response carries a risk_breakdown sibling next to risk_score: an itemized ledger of how the score was composed, so no decision ever rests on an unexplained number: base (the action type's base score) → modifiers (server risk factors, each named with its points) → server_total → template (a matching risk template, if any) → client_reported (the risk_score you passed) → effective (the max of those; the server never lets a client under-report below its own floor) → predictive(history-based adjustment from the agent's failure rate and velocity) → final. The breakdown is persisted with the decision and rendered as the Risk composition panel on the action, decision, and replay detail pages.

Risk calibration proposals

The score behind guard is pinned by a golden-vector corpus. DashClaw mines your own decision ledger for shapes where the scorer looks miscalibrated (over-scored benign actions, under-scored dangers, repeatedly approved shapes) and renders them as evidence cards on /policies → Calibration proposals; ratify and dismiss are buttons. The same proposals are available at GET /api/calibration/proposals; a ratified proposal is a recorded judgment (?status=ratifiedis the maintainer's forge queue). Nothing changes scoring until the vector is forged and committed.

Tightening proposals

Policy-tuning proposals only ever loosen (raise thresholds that over-interrupt). Tightening proposals own the other direction: when the same high-risk action type repeatedly reaches allow with no policy in its way, the pattern (mirrored one-to-one from the posture finding) is rendered as an evidence card on /policies → Tightening proposals. Ratify creates an active require_approval policy for that action type in the same click and resolves the posture finding; dismiss records why and stops the re-proposal. The same queue is available at GET /api/policies/tightening. Nothing auto-applies: every policy exists because a human ratified it.

Loosening proposals

The tightening mirror. When a policy's interruptions are approved ~100% of the time (a wrong interrupt by definition), the pattern renders as an evidence card in the /policies judgment queue. Ratify relaxes the policy in the same click: carve the always-approved action type out of its envelope (the rest stays governed) or, when no surgical fix exists, deactivate it. Undo keeps the change; the policy is a first-class row at /policies. The same queue is available at GET /api/policies/loosening. Harness traffic never counts as evidence, and risk-threshold policies stay with tuning.

Policy tuning proposals

DashClaw mines your own decision outcomes for policies whose thresholds look wrong in practice (a gate every human rubber-stamps, a cap that never fires) and renders each as an evidence-backed proposal on /policies, where Apply and Dismiss are buttons (apply is a two-step confirm with an inline reason). The same feed is available at GET /api/policies/proposals, which returns { policies, proposals, degradation }. Nothing changes a policy until a human clicks Apply.

Degradation observability

Guard evaluation runs under a deadline (DASHCLAW_GUARD_DEADLINE_MS, default 3500 ms). When the deadline fires or an evaluation phase fails (for example a policy webhook), the guard does not silently allow: it falls back, using the per-policy on_failure override first, then the instance-wide DASHCLAW_GUARD_FALLBACK, then fail-closed require_approval, and marks the decision degraded.

Degradations are observable, not just recorded: GET /api/policies/proposals?days=30 returns a degradation rollup: { window_days, total, degraded, rate, last_degraded_at, by_day }. /policiesrenders it as a strip ("N of M decisions were deadline degradations") whenever the count is non-zero. A rising rate means your policies are being decided by fallback, not evaluation; tune the deadline or the failing phase.