Popular starting points. Use Tab or arrow keys to browse results.

Skip to content
Aten SecurityThoth docs

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.

FilterMeaning
outcomeallowed, needs_approval or blocked. A held action that was approved counts as allowed; one that was denied or expired counts as blocked
agentOne agent ID
toolOne tool name, matched exactly
reason codeThe deterministic reason the enforcer gave, for example delegation_tool_denied
ruleA policy rule that matched. Recorded for decisions made after this field was added
since, untilAn 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).

# Blocked calls to one tool this month
thothctl decisions list --outcome blocked --tool orders.delete --since 2026-10-01T00:00:00Z
 
# Everything one agent did in a window, as CSV
thothctl decisions export --agent-id billing-agent \
  --since 2026-10-20T00:00:00Z --until 2026-10-21T00:00:00Z --output billing-agent.csv

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.

thothctl approvals get --approval-id ap_123
thothctl approvals resolve --approval-id ap_123 --decision approve --note "refund verified with the customer"

Terraform

thoth_decisions needs provider 0.1.21 or later; in Pulumi it is thoth.governance.getDecisions.

data "thoth_decisions" "blocked_deletes" {
  outcome     = "blocked"
  tool_name   = "orders.delete"
  since       = "2026-10-01T00:00:00Z"
  max_results = 500
}

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

GET /{tenant}/thoth/v1/activity?type=decision&filter=blocked&tool=orders.delete&since=2026-10-01T00:00:00Z
GET /{tenant}/thoth/v1/decisions/export?filter=blocked&since=2026-10-01T00:00:00Z

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.

# What would the last 7 days have looked like with this rule added?
thothctl governance policies replay --candidate-file change.json
 
# One agent, a chosen window, and JSON for a script
thothctl governance policies replay --candidate-file change.json \
  --agent-id billing-agent --since 2026-11-01T00:00:00Z --until 2026-11-05T00:00:00Z --json

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:

SettingDefaultMeaning
DECISION_CAPTURE_ENABLEDfalseCapture each enforced decision, with a snapshot of the policy and request that replay re-evaluates.
DECISION_CAPTURE_RETENTION_DAYS30How 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_corpus means 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_replayable means 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.

On this page