Talon Explanation Catalog

This manual lists all explanation codes emitted by Talon evidence records.

Determinism guarantees:

• Explanations are generated by rule-based code only (no LLM generation).
• Items are sorted and deduplicated before persistence.
• Primary explanation is always the first sorted explanation item.

Explanation Item Schema

Every explanation item has:

• code: stable machine-readable explanation code
• decision: allow, deny, modify, filter, or failure
• stage: enforcement stage (for example policy_evaluation, tool_execution, output_validation)
• reason: canonical human-readable reason
• trigger (optional): normalized triggering signal
• fix (optional): remediation guidance
• policy_ref (optional): canonical policy reference (policy:<version_identity>)
• version_identity (optional): immutable policy version identity

Canonical Stage Taxonomy

Canonical stage values for explanation items:

• policy_evaluation
• tool_execution
• output_validation
• pre_execution
• execution

Compatibility alias:

• legacy output_scan is normalized to output_validation during explanation rendering.

Policy and Execution Explanations

Code	Decision	Typical stage	Trigger format	Meaning	Operator fix
POLICY_ALLOWED	allow	policy_evaluation / tool_execution	policy action or tool name	Request allowed by policy.	None required.
POLICY_DENIED	deny	policy_evaluation	free-text reason token	Request blocked by policy.	Inspect policy reasons and align request/policy.
POLICY_DENIED_PII_INPUT	deny	policy_evaluation	comma-separated PII entity list (sorted)	Request blocked because input PII was detected.	Remove or mask sensitive input data.
POLICY_DENIED_PII_OUTPUT	deny	output_validation	output PII token/list	Request blocked because output PII was detected.	Tighten prompt/tool outputs or enable redaction path.
POLICY_DENIED_COST	deny	policy_evaluation	cost/budget reason	Request blocked by cost policy limits.	Reduce token usage or increase cost limits.
POLICY_DENIED_EGRESS	deny	policy_evaluation	gateway egress reason: egress_tier_destination_disallowed: tier N data may not egress to provider <name> (region <region>) or egress_destination_disallowed: no egress rule permits provider <name> for tier N	Request blocked because the destination is not allowed for this data classification.	Route the request to a destination allowed for this data tier, or update the gateway egress rules.
POLICY_DENIED_ROUTING	deny	policy_evaluation	routing/provider reason; gateway names the layer whose rule fired: Model <name> not in agent allowlist, Model <name> not in organization allowlist, Model <name> is blocked for this agent, Model <name> is blocked by organization policy, All models are blocked for this agent / …by organization policy (wildcard), model_required_for_policy_evaluation: … (model-less request under an active model policy), Data tier N exceeds agent restriction, Data tier N exceeds organization restriction, provider not allowed: organization_provider_allowlist / agent_provider_allowlist	Request blocked by model routing policy.	Select an allowed model/provider for the data tier.
POLICY_DENIED_TOOL	deny	tool_execution	tool name or policy reason	Request blocked by tool access policy.	Use allowed tool or extend allowlist.
POLICY_DENIED_HOOK	deny	pre_execution / hook stage	hook deny reason	Request blocked by governance hook.	Review hook policy and approval gates.
POLICY_DENIED_CIRCUIT_BREAKER	deny	pre_execution	circuit breaker reason	Request blocked because circuit breaker is open.	Resolve repeated failures/denials and retry after cooldown.
POLICY_DENIED_EARLY_TERMINATION	deny	pre_execution	early termination reason	Run terminated by governance pre-check.	Inspect failure reason and rerun after correction.
POLICY_MODIFIED	modify	policy_evaluation	modification token	Request was modified by policy before execution.	Usually no action; review modifications if unexpected.
POLICY_FILTERED	filter	output_validation	filtering reason (for example output_pii_redacted)	Request output was filtered/redacted by policy.	None if expected; otherwise adjust filtering policy.
EXECUTION_FAILED	failure	execution / tool_execution	stable failure token (or sanitized error context)	Request failed during execution.	Inspect dependency/tool/provider error and retry.
LEGACY_REASON_UNMIGRATED	deny (default)	policy_evaluation	legacy reason text	Legacy free-text reason not yet mapped to specific code.	Add explicit mapping and structured fact for this path.

Graph Governance Explanations

Code	Decision	Typical stage	Meaning	Operator fix
GRAPH_RUN_ALLOWED	allow	graph_run	Graph run completed within governance limits.	None required.
GRAPH_ITERATION_LIMIT_DENY	deny	graph_step	Graph denied: iteration limit exceeded.	Increase max_iterations or reduce graph steps.
GRAPH_COST_LIMIT_DENY	deny	graph_step	Graph denied: run cost limit exceeded.	Increase max_cost_per_run or optimize step usage.
GRAPH_RETRY_LIMIT_DENY	deny	graph_step	Graph retry denied: node retry limit exceeded.	Increase max_retries_per_node or fix node failures.
GRAPH_TOOL_DENY	deny	graph_step	Graph tool call denied by allowlist/governance.	Add tool to allowed capabilities if compliant.

Surface Mapping

• CLI: talon audit show prints explanation code, decision, stage, reason, trigger, fix, policy_ref, version_identity.
• Dashboard:
  • Evidence table status includes primary explanation code.
  • Trace modal shows primary explanation reason and remediation metadata.
• API:
  • GET /v1/evidence includes primary_explanation_code and primary_explanation_reason.
  • GET /v1/evidence/{id} and GET /v1/evidence/{id}/trace include full explanations[].

Maintenance Rule

When introducing a new explanation code or changing explanation semantics:

1. Add/update the code in internal/explanation/explanation.go.
2. Add/update tests in internal/explanation/explanation_test.go.
3. Update this catalog in the same PR.
4. Verify CLI and dashboard rendering for the new code path.