Docs / Reference

Outcome codes

Outcome and nested codes let callers distinguish malformed input, version mismatch, unavailability, denial, timeout, and host failure.

Plain English

The top-level outcome says success, failure, denied, or skipped; nested codes explain why.

Why it exists

Public protocol callers need stable branches for expected failure, not framework-specific exceptions or generic status text.

Formal definition

InvocationResult.outcome is one of success, failure, denied, or skipped; denial.code and error.code carry stable protocol reasons for rejected or failed attempts.

Concrete example

Ground the concept before the schema.

approval_required tells a caller that policy paused or denied schedule_technician before side effects.

outcome.json
json
{  "invocation_id": "inv_session_abc_001",  "capability_id": "schedule_technician",  "capability_version": "1.0.0",  "correlation": { "correlation_id": "session-abc" },  "outcome": "denied",  "success": false,  "data": null,  "error": null,  "denial": {    "code": "approval_required",    "message": "manager_approval must approve before execution.",    "retryable": true,    "details": { "policy": "manager_approval" }  },  "evidence_ids": ["evt_8f3a1c"],  "started_at": null,  "completed_at": "2026-06-16T15:14:22.104Z"}

Developer reference

Outcome code reference

Use stable codes so agents, applications, and infrastructure can branch consistently.

CodeRecord locationProtocol meaning
successoutcome

Capability handler completed and returned data.

failureoutcome

Execution began but failed; inspect error.code for the reason.

deniedoutcome

The host rejected execution before the handler completed; inspect denial.code.

skippedoutcome

The host intentionally did not execute a registered capability, commonly because it is disabled.

input_schema_validation_faileddenial.code or error.code

Invocation or payload shape is invalid or missing required fields.

unsupported_protocol_versiondenial.code or discovery error

Host and caller do not share a compatible CHP protocol version.

unknown_hostdiscovery error

Caller addressed a host identity that cannot be resolved or trusted before reaching a host boundary.

capability_disableddenial.code

Capability exists but is not currently invokable.

entitlement_denieddenial.code

Subject lacks the host-recognized grant or entitlement required by the capability.

approval_requireddenial.code

Policy requires approval before execution can proceed.

timeouterror.code

Execution exceeded a host timeout policy after the boundary accepted the invocation.

host_errorerror.code

Host failed after accepting the invocation boundary.

Relationships

Where this sits in the protocol.

Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.

Reference pages turn protocol concepts into implementation checks.

Field names, outcome codes, and conformance cases should stay stable across hosts.

Examples should map every field back to capability, host, policy, context, or evidence.

Visual model

  1. 01Read the field or code before implementation.
  2. 02Map it into manifest, invocation, outcome, or evidence behavior.
  3. 03Add route, conformance, or unit coverage for each failure-sensitive field.

Implementation notes

  • Prefer explicit protocol fields over framework-specific inference.
  • Treat absent required fields as malformed protocol input.
  • Keep examples close to the failure cases they are meant to prevent.

Common mistakes

  • Letting transport status codes carry protocol meaning alone.
  • Hiding required protocol state in logs or application glue.
  • Testing only successful invocations.

Related concepts

Keep reading through the boundary.

Failure examples →Conformance cases →Policy states →