AI Agent Policy Decision Response Schema
A policy decision response records the policy identity, protected inputs, canonical outcome, matched rules, reason codes, and evaluation time. This standalone reference preserves the policy sub-object from the published audit event and adds an addressable policy_decision_event_id plus correlation for independent use.
JSON Schema draft 2020-12 · Version 1.0.0 · Four canonical decision values
Quick reference
- Definition
- A standalone response from policy evaluation with policy identity, input and policy digests, one canonical decision, matched rules, and reason codes.
- When used
- Create it after an action request is evaluated and before the execution route continues, pauses for approval, or stops.
- Decision values
- allow, warn, require_approval, and block are the canonical values in the shared policy contract.
- Denied action
- The block example records destination_outside_declared_boundary in reason_codes and carries no execution fields because this page describes the decision object.
01
Schema and decision examples
The schema and four decision examples are available as immutable versioned artifacts. Each decision value has a concrete record.
/ai-agent-policy-decision/v1/schema.jsonDownload Allow exampleDecision for an action inside the declared scope./ai-agent-policy-decision/v1/examples/allow.jsonDownload Warn exampleDecision that continues the current worker route with a warning marker./ai-agent-policy-decision/v1/examples/warn.jsonDownload Require approval exampleDecision that routes the action to a human approval request./ai-agent-policy-decision/v1/examples/require-approval.jsonDownload Block exampleDenied-action decision with a boundary reason code./ai-agent-policy-decision/v1/examples/block.jsonDownload 02
Object and execution order
The response follows the action request. Its decision selects the route before a tool call or business effect.
- 01RequestThe agent action request supplies the action, purpose, resource, data boundary, and environment.
- 02EvaluateThe evaluator binds the result to policy_id, policy_version, policy_digest, inputs_digest, matched rules, and reason codes.
- 03Routeallow continues the action. warn continues the current worker route and emits a warning marker. require_approval creates a human approval path. block stops the action.
- 04RecordThe decision remains linkable to later approval, tool, and audit records through correlation.
03
Field dictionary
The dictionary covers every required and optional member, including the standalone identity and correlation additions.
Standalone identity and correlation
| Field | Status | Purpose |
|---|---|---|
| schema_version | Required | Selects the compatibility contract used to parse the record. |
| policy_decision_event_id | Required | Independently addresses this decision record and links it to an audit event. Added for standalone publication. |
| correlation.correlation_id / execution_id | Required | Joins the policy result to the request, approval, tool, and audit sequence. Added for standalone publication. |
| correlation.trace_id / span_id / parent_event_id | Optional | Carries OpenTelemetry trace context and an optional parent event. All-zero W3C identifiers are invalid. |
Policy identity and protected inputs
| Field | Status | Purpose |
|---|---|---|
| decision_id | Required | Identifies the policy evaluation decision inside the source governance system. |
| policy_id / policy_version | Required | Names the policy and exact policy version used for evaluation. |
| policy_digest / inputs_digest | Required | Binds the result to protected policy and input representations. |
Decision explanation
| Field | Status | Purpose |
|---|---|---|
| decision | Required | Carries allow, warn, require_approval, or block. |
| evaluated_at | Required | Records when the policy evaluation completed as an RFC 3339 date-time. |
| matched_rule_ids | Required | Lists unique rule identifiers that matched during evaluation. |
| reason_codes | Required | Lists at least one unique identifier explaining the selected outcome. |
04
Minimal example
The allow record shows the smallest complete decision object. The downloads add warn, require_approval, and block cases.
{
"schema_version": "1.0.0",
"policy_decision_event_id": "evt_policy_decision_demo_0001",
"correlation": {
"correlation_id": "corr_credit_review_demo_0001",
"execution_id": "exec_credit_review_demo_0001"
},
"decision_id": "dec_demo_0001",
"policy_id": "policy_credit_case_access",
"policy_version": "4.2.1",
"policy_digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"inputs_digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
"decision": "allow",
"evaluated_at": "2026-07-21T09:14:29.180Z",
"matched_rule_ids": [
"rule_case_summary_read"
],
"reason_codes": [
"within_declared_scope"
]
}05
Validation and digest verification
JSON Schema validation checks shape. The companion verifier reproduces a sha256: digest over the canonical record and can check an optional detached Ed25519 signature.
- 01Load the versioned schema from the JSON Schema download URL.
- 02Validate the JSON document with a draft 2020-12 validator and a date-time format plugin.
- 03Canonicalize the complete standalone record with recursively sorted object keys, matching the published audit-event verifier approach.
- 04Compute SHA-256 over the canonical bytes and represent the result with the sha256: prefix.
- 05Compare the computed digest with the digest retained by the calling evidence procedure.
- 06When a detached Ed25519 signature is supplied, resolve its public key independently and verify the signature over the 32-byte digest.
- 07Record a hash mismatch or signature failure as a failed verification result. A valid shape alone does not establish an unchanged record.
Four schema-valid outcomes
The allow, warn, require_approval, and block examples validate against draft 2020-12 and produce reproducible sha256: digests from their canonical content.
Tamper check
Changing reason_codes keeps the document structurally readable while changing the canonical digest. The verifier reportsrecord_hash_mismatch.
The standalone verifier accepts an optional detached Ed25519 signature. Trust in a public key comes from the caller’s independently governed key registry.
06
Compatibility and versioning
Version the response contract independently from policy packs and evaluator releases.
Patch
Clarifications, descriptions, and examples can change while validation behavior remains stable. A corrected immutable artifact receives a new versioned URL.
Minor
New optional fields require a new schema_version and versioned URL. Consumers declare support before processing the new version.
Major
Removed or renamed fields, changed meanings, stricter required status, or changed canonicalization require a new major path.
Consumers preserve unknown versions for review and stop semantic processing until support is declared. The v1 path uses schema_version 1.0.0.
07
How KLA implements this
The shared policy contract defines the decision vocabulary. Worker and execution routes record the evaluation and subsequent governance path.
| Contract area | Current source | Mapping | Status |
|---|---|---|---|
| Canonical decision vocabulary | services/shared/src/policy/contracts.ts | GateDecisionValueSchema and POLICY_SCHEMA_VERSION define allow, warn, require_approval, block and policy schema version 1.0.0. | Current shared contract |
| Decision recording | services/execution-worker/src/services/audit-events.ts | recordPolicyDecisionAuditEvent records policy identity, decision, reason, rule, workflow, and execution details. Its legacy helper accepts deny for the blocked outcome, so this page uses the shared canonical block value. | Current producer with normalization |
| Route selected by the decision | services/execution-worker/src/workflows/workflow-spec-runner.ts | The workflow route continues allow and warn, marks warn as a warning, requests approval for require_approval, and stops block. | Current execution consumer |
| Audit linkage | services/execution-worker/src/services/audit-events.ts | Policy and approval audit producers retain execution identifiers and active trace context so a decision can be joined to the surrounding execution record. | Current related producer |
Deliberate abstractions and unsupported fields
- •The schema omits Cerbos policy documents, JSON Logic rule bodies, entitlements payloads, and evaluator configuration.
- •The schema records digests for policy and inputs. It does not publish the protected policy text, request arguments, prompts, model output, or raw personal data.
- •The schema records one canonical decision. It does not encode every internal control signal, classification, remediation, or judge trace carried by the wider shared GateDecision contract.
- •The schema records matched rule IDs and reason codes. It does not claim that a reason code proves authorization, tenant isolation, or source-population completeness.
- •The standalone policy_decision_event_id and correlation object are additions for standalone publication. The embedded policy object has neither field.
- •The examples are synthetic records. Their digest values demonstrate field constraints and carry no customer or production identifiers.
08
Related references
Follow request, policy decision, approval when required, and the complete audit event in execution order.
The requested action evaluated by this policy response.
The maker-checker record used when the result is require_approval.
The full event envelope for the request, policy, approval, tool, outcome, and integrity record.
Apply the contract
Keep the policy result beside the request it evaluated.
Use the action request and approval references with this response, then use the audit log schema to retain the complete governed execution sequence.