Guardrail governance and graduated HITL

Hard guardrails answer yes or no. Real operations need a middle setting: route this to a human. Graduated HITL (v0.54-0.55) adds approval policies that return 202 awaiting_approval instead of a refusal.

• tx_approval_policy: matching transactions wait for a human decision.
• typed_data_policy: escalates EIP-712 signing.
• simulation_failure_policy: escalates when a simulation fails rather than blindly proceeding.
• raw_signing_policy: escalates or denies raw digest signing, which bypasses other guardrails.

Separately, guardrail governance (v0.56) lets you measure a rule before it ever blocks anything. Set enforcement to log and the rule runs in shadow mode: it records what it would have denied, and denies nothing.

1. 1

   Put a new rule in shadow mode. It will record decisions without affecting traffic.

   bash Copy

   curl -s -X PATCH https://api.1claw.co/v1/agents/$AGENT_ID \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "execution_guardrails": {
         "enforcement": "log",
         "allowed_hosts": ["api.stripe.com"]
       }
     }'

2. 2

   After it has seen real traffic, read the shadow report to find out what it would have blocked.

   bash Copy

   curl -s https://api.1claw.co/v1/org/guardrail-shadow-report \
     -H "Authorization: Bearer $ONECLAW_TOKEN"
   # or: 1claw guardrails shadow-report

3. 3

   Replay the rule against recent transactions as a dry run, before you commit to it.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/agents/$AGENT_ID/guardrails/replay \
     -H "Authorization: Bearer $ONECLAW_TOKEN"
   # or: 1claw guardrails replay

4. 4

   Happy with it? Flip enforcement to enforce.

   bash Copy

   1claw agent update $AGENT_ID --execution-guardrails '{"enforcement":"enforce","allowed_hosts":["api.stripe.com"]}'

5. 5

   Add an approval policy so large transfers reach a human rather than failing.

   bash Copy

   curl -s -X PATCH https://api.1claw.co/v1/agents/$AGENT_ID \
     -H "Authorization: Bearer $ONECLAW_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "tx_approval_policy": { "min_value_usd": 100, "action": "approve" } }'

An approval prompt saying an agent wants to send 2 ETH was flagged above as too thin to decide on. Approvals for business actions (v0.59.14) fix the same problem for non-transaction actions: a refund, a post, an invoice. POST /v1/approvals/request now accepts a payload, the fields that describe what the action will actually do, separately from summary, the sentence a human reads. The risk tier is derived from the payload, never from the summary, so a summary that flatters the request changes what your operator sees and nothing about how strong the approval must be.

• declared_risk_tier is advisory. 1claw derives its own floor from the payload and takes the higher of the two, so an agent declaring tier 1 on a $500 refund still gets tier 2.
• Five actions are rejected on this endpoint when an agent requests them directly: policy_change, card_order, agent_transaction, agent_execution, agent_sign_intent. These are the approvals 1claw itself executes when a human approves, so the wording a human reads has to come from the same place as the side effect that follows, not from whatever text the agent supplied.
• human_summary is the exact line your operator receives on SMS, push, or email, rendered from the agent's own summary_template on action_approval_policy. Widening that policy (raising a threshold, changing what auto-approves) counts as widening a guardrail and routes through the same approval flow as raising a spend cap.

Learned auto-approval closes the loop the other direction: instead of writing action_approval_policy rules by hand, GET /v1/org/approval-learning/shadow-report reports which patterns would already have been automated, based on every decision made through the approvals path since it shipped. Promotion is the only write, and it is human-only, for the same reason creating a peer is human-only: an agent that could promote a rule for itself could grant itself standing authority.

• A promoted rule is bounded by the amount band it was earned in. A run of $5 approvals never licenses a $500 one, the same fingerprint-bucket narrowness taught for peer memory's derived approval tendencies.
• A profile promotes onto the agent whose approvals built it, and no other. It does not transfer the way a template's settings do across a fleet.
• Promotion refuses entirely while the org is in shadow mode. The report is a read over data being collected now; turning it into authority is a separate, deliberate step.

Where this goes wrong in practice. Graduated HITL introduces a human decision into an automated path, and the humans are the part that degrades.

• Approval fatigue sets in. A threshold that fires many times a day produces reflexive approval, at which point the queue is theatre and everyone believes it is a control.
• Approval context is too thin to decide on. A prompt that says an agent wants to send 2 ETH is not a decision, it is a coin flip. Recipient, purpose and precedent are what make review meaningful.
• Shadow mode is enabled and never read. Running a rule in log mode is only useful if someone reads the shadow report, and rules commonly sit in shadow indefinitely because nobody owns the promotion.
• Widening approvals are rubber-stamped. Since v0.56.2 widening a guardrail queues behind an approval, which is a real control and becomes a formality if the same person requests and approves it.
• There is no timeout policy. A pending approval that nobody actions blocks the work, and the pressure to add an auto-approve fallback arrives quickly.