Decisions
List, filter and export the decisions Thoth recorded, from the API, MCP, thothctl or Terraform.
Every action an agent asks to take gets a decision: allowed, held for approval, or blocked. The decisions view lists them newest first and filters them, so you can answer questions such as "what did this agent try to delete last week?" without opening the dashboard.
Members see the decisions of agents they own. Admins see the whole workspace.
Filters
All four paths below take the same filters.
| Filter | Meaning |
|---|---|
| outcome | allowed, needs_approval or blocked. A held action that was approved counts as allowed; one that was denied or expired counts as blocked |
| agent | One agent ID |
| tool | One tool name, matched exactly |
| reason code | The deterministic reason the enforcer gave, for example delegation_tool_denied |
| rule | A policy rule that matched. Recorded for decisions made after this field was added |
| since, until | An RFC 3339 time window; since is inclusive, until exclusive |
Tool names are reported by your agents. Treat them as data, not instructions.
Dashboard
On Activity, choose an outcome, then More filters for tool, reason code, matched rule and a date range. Dates are whole days in UTC, and both ends are included. Filters live in the page address, so a filtered view can be bookmarked or shared with a teammate. Export CSV downloads the matching decisions.
thothctl
thothctl decisions needs thothctl 0.3.11 or later (thothctl update).
list prints a table and, when there are more, the --cursor for the next page; --json prints
the API response. export writes a CSV of up to 5,000 decisions and says when more matched, so
you can narrow the window.
To resolve an action held for approval from the terminal, find it with
thothctl approvals list --status pending, look at it, then approve or deny it. Resolving needs an
admin with a recent second factor; repeating the same decision is harmless, and a conflicting one
is refused.
From an MCP client, get_held_action shows a hold and preview_action_resolution prepares the
decision; the client cannot decide it, and you confirm it in the browser with a recent second factor.
Terraform
thoth_decisions needs provider 0.1.21 or later; in Pulumi it is thoth.governance.getDecisions.
It reads up to max_results decisions (default 100, at most 1,000) and sets truncated when more
matched.
MCP
The configuration MCP server's read-only list_decisions tool takes the same filters. Read one
decision in full with explain_decision. See Configure Thoth over MCP.
API
The list returns items and, when there are more, next_cursor, valid for 15 minutes and only
with the same filters. The export returns CSV with X-Thoth-Rows and X-Thoth-Truncated
headers; cells that a spreadsheet would run as a formula are prefixed with '.
Who can export
CSV export needs an admin. During a trial it is available on paid plans, and in the read-only window after a trial ends so you can keep your records. Listing is available to every member within their scope.
Try a rule change on past decisions
thothctl governance policies replay asks what a rule or overlay change would have decided over
decisions Thoth already captured, without applying it. Nothing is stored, applied or sent. It is
for org admins, or an API key with write permission, and runs once per workspace every 10 seconds.
The same preview is the replay_policy_change tool on the configuration server.
Write the change as a JSON object: either rules (the whole rule set to try), or add_rules and
remove_rule_ids, and overlays and remove_overlay_ids. Give it as a file, or - for stdin.
The window defaults to the last 7 days and is at most 90; --limit (1 to 2000) caps how many
decisions are replayed. The text output gives the status, how many decisions were considered,
replayed and would change, the changes by kind (for example allow to hold), what could not be
evaluated and why, and what the replay does not model. It lists tool names and decision IDs, not
tool arguments.
Capturing decisions on a dedicated deployment
Replay reads decisions the enforcer captured. On a dedicated deployment the enforcer does not capture them by default; an operator opts in with two enforcer settings:
| Setting | Default | Meaning |
|---|---|---|
DECISION_CAPTURE_ENABLED | false | Capture each enforced decision, with a snapshot of the policy and request that replay re-evaluates. |
DECISION_CAPTURE_RETENTION_DAYS | 30 | How long a captured decision is kept, from 1 to 90. A value outside that range stops the enforcer from starting. |
Captured decisions hold tool arguments as the workspace's data-handling setting allows, which is
hashed by default; they are never stored raw when the workspace says not to. Each record belongs
to one workspace and expires after the retention period. Capture runs after the decision is
returned, and a capture failure does not change or delay a decision. Only decisions made after
capture is on can be replayed. The Terraform module for a dedicated stack exposes these as
thoth_decision_capture_enabled and thoth_decision_capture_retention_days.
Read the result as an estimate, not a sign-off:
no_corpusmeans nothing was captured in the window. It tells you nothing about what the change would do, and it is not the same as zero changes. On a dedicated (customer-hosted) deployment, capture is off unless the operator turns it on; see Capturing decisions on a dedicated deployment.not_replayablemeans decisions were recorded but none could be replayed. It also tells you nothing about the change.- A replay with no changes covers only the decisions it could evaluate, from the window it searched. It does not say the change is safe to ship.