Guide 36 of 61 · Investigating and recovering
Trace what one agent task did
Find an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last.
Steps marked preview rely on a package that has not passed its release gate.
Open the dashboard, find the agent's task, see which layer enforces each part of it, read every decision its policy made with the rule behind it, and follow one run from its first decision to its last, its subagents included.
1. Open the dashboard
agentgarm ui prints the dashboard's address on 127.0.0.1, carrying a launch code that works once and for 2 minutes; --open also opens it in your browser. The page trades the code for the session's token and clears it from the address bar. The dashboard only reads: it shows your own tasks, and the requests in it were redacted before they were stored. When agentgarm-session restarts, the page stops; open it again with agentgarm ui.
agentgarm uiagentgarm ui --openChecked by the walk: this command ran as written on a no-root Linux install, and the output showed 127.0.0.1.
2. Find the task on the Overview
The Overview's “Running now” lists the live tasks as a tree, each subagent under the task that started it, with its start time and short id, and the assurance level the tasks share said once above them (an unknown level is shown as C; tasks at different levels each show their own). Beside it are “Denied or asked”, the newest five denied or questioned actions, each with its rule, the reason given, a link to its run and a Request button that copies an exception request for that rule, and the five newest alert groups. The Alerts screen lists every recent alert (bypass, assurance lowered, DLP, policy-source conflict, correlation conflict, checkpoints, budget and agent configuration scans), the same alert from the same source as one row with its count.
3. Ask for an exception to a rule
Request copies a short text: “AgentGarm exception request”, the rule, the decision's id, the action, the reason given, and a line for why it should be allowed. AgentGarm sends it nowhere: paste it to whoever owns the policy (a ticket, a chat, an email), and they change the rule and roll it out. For an ask you want to allow for a few minutes in this task only, agentgarm presence grant preview turns that one ask into a short grant once you approve it with your presence key; the Approvals screen shows the command to copy. It is offered only where the rule says pattern_grants: true, on a root install with a presence key, in a launched session, and for a single command it can parse; anywhere else it is refused.
agentgarm presence grant <decision id>See also
Approve risky actions with Touch IDEnrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.
4. See which layer enforces each part
agentgarm status shows each live task on a task line with its agent, the last twelve characters of its id and its assurance level, and under it every class its policy relies on (commands, files, network, model calls and the rest) with its level and the layer that gives it, such as the hooks or the sandbox. --json gives the same with the task's full task_id. A task is rated by the weakest class it relies on. A task whose processes have all exited reads ENDED until agentgarmd drops it from the list, within 5 seconds.
agentgarm statusagentgarm status --jsonChecked by the walk: these commands ran as written on a no-root Linux install.
See also
Check that protection is onSee whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.
5. Read its decisions on Activity
Activity lists what was recorded while the page is open, newest first, 40 at a time: each decision with when it was made, its outcome, the action (a command, file access, connection, tool, MCP or model call, as stored after redaction), its agent and the id of the rule that decided it, and the alerts, model calls and MCP events beside them. Narrow it to denied, asked or allowed decisions or to one kind, or search the actions, rules and agents. Selecting a row opens its whole action with the rule, the reason given, the link to its run and, for a denial or an ask, the exception request to copy.
See also
Watch your agent for a week, then enforceStart a policy in audit mode, see what enforcing it would have blocked in your own history, fix the rules that get in the way, then switch it to enforce.
6. Follow a running task live
previewThe task tree is keyboard-operable: the arrow keys move and open it, and Enter or Space shows the selected task's details, with its full id, why its level is what it is, and each class's level, layer and whether its policy relies on it, and a link to its run. Activity takes in each decision, alert, model call and MCP event as agentgarmd commits it, at most 200. It holds still while your pointer or focus is on it, and a button says how many arrived meanwhile and shows them.
7. Open the run's timeline
previewRuns lists your runs, ended ones too, newest first, over 24 hours, 7 days, 30 days or everything stored, filtered by outcome and agent: each with its agent, start, length, decisions, denials, asks, events and cost (a column no run fills is left out). A run's page, whose address ends in its task id, shows its subagents as links beside its timeline, oldest first, each record in a lane: decisions (with a Why column naming the rule and the reason), model calls (with a Cost column), tools, MCP, files (each read, write or delete with its path), network (each connection, made or refused) and alerts.
A model call belongs to the run when it names the task or, for a client that names none (Codex, for example), when it comes from one of the task's processes. A run's process tree is not shown. Input and capture events never appear in it. A run retention removed, or another user's, reads “No such run”. A run's timeline can be filtered by kind, selecting a record shows it whole, and each view exports what it shows, filter included, as CSV or JSON. Those exports are not signed: for a record of one task someone else can check, export its evidence bundle on the machine (Export evidence for one task).
See also
Undo what an agent changedPreview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started.