Governance
Explain a recorded decision
Returns one recorded Trust Fabric decision from the calling credential’s acting organization, explained from recorded evidence only — its disposition, each gate result, and the recorded gate and error-code classification. Requires permissions grants:read, policies:read and audit:read.
GET
Explain one recorded Trust Fabric decision
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.
v2 compatibility notes
Explains one Trust Fabric decision that was recorded for your credential’s acting organization. The explanation comes from recorded evidence only. Forge doesn’t re-run policy or estimate what would happen today.Who can read a decision
The request names only the decisionid. Your credential sets the actor and the organization:
a platform or MCP key, or an External App token, acting within its organization. Any other query
parameter, including orgUnitId, returns 400. A credential with no acting organization
receives 403.
A decision is returned only when all of the following hold:
- It was recorded or reconciled for exactly your acting organization.
- It has no private fence, such as a private chat channel.
- Your actor still holds
grants:read,policies:readandaudit:readat that organization when you make the request.
404 resource_missing. That includes another organization’s
decision, a personal or platform-wide one, one fenced to a private chat, a legacy or unresolved
record, and a decision that doesn’t exist. A 404 doesn’t tell you which case applies.
What is returned
data contains:
decision: theid,timestampanddisposition, plus each gate result asgate,passed,skippedanderrorCode(nullwhen none).causes: one classification per recorded gate result, in the same order.canonicalGateIdandgateLabelname the registered gate.gateResolutionisexact,legacy_unique,ambiguousorunknown.causeRegistrationisregistered,unregistered,absentorambiguous. A gate or error code that the registry doesn’t recognize is reported asunknownorambiguous. Forge doesn’t guess a cause.remediation: always{ "status": "unavailable", "reason": "not_recorded" }. The audit log stores no historical remediation, so Forge can’t say what would have changed the outcome.
includeCorrelation=true, data also contains correlation: the recorded runId, stepId
and dispatchId, as getEvidence returns them. They identify the dispatch and don’t grant access
to that run or step.
Otherwise the response never includes the principal, role, heldBy, reportedBy, run, step, agent, tool,
policy, evidence scope, private fence, any gate message, or the recorded free-text explanation.
That explanation repeats the blocking gate’s message or the holding policy’s name, so it is
withheld too. data contains only the fields above. New metadata can still appear in meta.
Example
forge_explain_governance_decision returns the same data and meta. See
MCP server.
