Decision context

An Action can carry a Decision Brief alongside its interaction. Use it when a title and description do not give the reviewer enough information to understand the change, the risk, and the way back.

Decision context is optional. When present, ActionBox displays it by default in the web and mobile review screens. A reviewer can collapse the details, but they do not need to ask for information the Source already supplied.

What belongs in the brief

Keep the summary short enough to scan:

• proposed_change: the operation the reviewer is deciding on.
• reason: why a human judgment is needed now, not merely why the automation ran.
• risk_level and risk_summary: the credible downside if the decision is wrong.
• reversibility and rollback_plan: whether the change can be undone and how.
• current_state and expected_effect: the before-and-after state.
• affected_scope: the services, users, regions, or resources in scope.

Decision context schema

decision_class is a separate top-level field. It accepts 1 to 120 letters, numbers, underscores, hyphens, or periods. Do not put it inside decision_context.

The Source supplies these claims. ActionBox preserves and displays them; it does not independently verify that they are correct. A reviewer should still inspect the evidence for a consequential decision.

{
  "title": "Approve production deployment",
  "options": [
    {"id": "approve", "label": "Approve"},
    {"id": "reject", "label": "Reject"}
  ],
  "decision_class": "production_deployment",
  "decision_context": {
    "schema_version": 1,
    "reason": "The release changes the write path and requires an accountable reviewer.",
    "current_state": "Production is running 2.17.4.",
    "proposed_change": "Deploy 2.18.0 to production.",
    "expected_effect": "Replace all six API replicas.",
    "risk_level": "high",
    "risk_summary": "A schema mismatch could interrupt customer writes.",
    "reversibility": "reversible",
    "rollback_plan": "Restore the 2.17.4 image and verify write health.",
    "affected_scope": ["api-production", "customer writes"]
  }
}

Add evidence, not a wall of text

Use typed context blocks for the material that supports the brief. A focused diff, a small metric set, the relevant log excerpt, or links to the run and rollback procedure are easier to review than one long description. See Context blocks for every supported shape and limit.

{
  "context": [
    {
      "type": "diff",
      "title": "Write-path change",
      "content": "- use cached schema\n+ use live schema"
    },
    {
      "type": "metrics",
      "title": "Staging checks",
      "items": [
        {"label": "Passed", "value": 482, "unit": "checks"},
        {"label": "Error rate", "value": 0.02, "unit": "%"}
      ]
    },
    {
      "type": "links",
      "title": "Runbooks",
      "items": [
        {"label": "Rollback procedure", "url": "https://example.com/runbooks/rollback"}
      ]
    }
  ]
}

Do not include passwords, tokens, signing secrets, or unrestricted customer data. Keep excerpts bounded and link to the system of record when the full artifact is large.

Send a brief from each client

The REST API, Python SDK, Node SDK, CLI, and MCP ask_human tool all accept the same decision_class and decision_context fields. MCP update_action and the SDK/API update methods can replace a brief when the Source learns something material.

actionbox ask "Deploy 2.18.0?" \
  --option approve --option reject \
  --decision-class production_deployment \
  --decision-context-json @decision-context.json \
  --wait

{
  "title": "Deploy 2.18.0?",
  "interaction": {"type": "boolean", "label": "Proceed?"},
  "decision_class": "production_deployment",
  "decision_context": {
    "schema_version": 1,
    "reason": "Production writes could be affected.",
    "proposed_change": "Deploy 2.18.0.",
    "risk_level": "high",
    "reversibility": "reversible"
  }
}

These clients create and transport the brief; the web and mobile review apps render it. Command-line and older clients can still read the generated compatibility summary in context.

When the reviewer needs more information

If an open Action has no Decision Brief, an approver can request more information from the web or mobile review screen. The request contains a plain-language question and may identify the missing fields: reason, risk, impact, reversibility, rollback plan, affected scope, or evidence. It does not resolve or block the Action, and it is available on every plan.

The pending request appears as context_request on Action reads and as a context_requested audit event. A Source with a callback URL receives a signed action.context_requested webhook. Sources that poll can observe the same field through GET /v1/source/actions/{action_id} or MCP get_action.

Respond by updating the existing Action. Do not create a second Action:

actionbox update act_123 \
  --decision-class production_deployment \
  --decision-context-json @decision-context.json \
  --context-json @evidence.json

The Python and Node SDKs expose client.update(...), and MCP sources use update_action. Supplying a non-empty context or decision_context records context_provided, clears the pending request, advances the Action version, and changes its fingerprint. The reviewer must decide against that latest snapshot.

Only one information request may be pending at a time. A viewer cannot send one, a revoked Source cannot receive one, and a terminal Action cannot be changed. A reviewer can still answer while a request is pending, which keeps urgent workflows from being trapped when the Source is unavailable.

Sometimes the honest answer is that the information cannot be provided. The Source should close the request explicitly instead of leaving the reviewer waiting or inventing context:

actionbox update act_123 \
  --context-unavailable "Production customer data is not accessible to this worker." \
  --context-unavailable-code cannot_access

The REST equivalent is POST /v1/source/actions/{action_id}/context-request/unavailable. Node exposes markContextUnavailable, Python exposes mark_context_unavailable, and MCP update_action accepts context_unavailable_reason with an optional reason code. Codes are not_available, cannot_access, not_applicable, sensitive, or unknown. ActionBox records context_unavailable, shows the explanation to the reviewer, and allows a different follow-up request. The Action remains open.

Bound to what the reviewer saw

decision_class, decision_context, and Source-provided context contribute to the Action fingerprint. A material update increments action_version and changes the fingerprint. A response submitted against an older reviewed snapshot fails with ACTION_CHANGED, so the caller must fetch and present the latest Action before trying again.

The structured context is also included in Action reads, signed webhook payloads, and account exports. Decision receipts bind the exact reviewed brief through the signed Action fingerprint rather than embedding the brief itself. Older clients receive a generated text projection in the context array; current ActionBox clients hide that projection when they can render the structured brief.

Decision Briefs do not execute controls

Decision context explains the pending choice. Action Controls ask a Source to perform a separate operation such as retrying or stopping work. Expanding, collapsing, or following a link in the brief never invokes a control and never resolves the Action.

See Actions for the complete create contract and Decision receipts for downstream verification.