Unattended AI agents need a graceful way to fail. When a runbook cannot be completed safely, the agent should not keep improvising until something changes. It should stop, preserve the useful context, and report the blocker in a form another operator can trust.

A blocker report is different from a generic error message. It explains which completion criterion could not be satisfied, what evidence was checked, what was intentionally not changed, and what the smallest safe next step is. The goal is to make the pause productive without exposing private logs or sensitive details.

When to stop instead of improvise

Good runbooks define blocker conditions before work begins. Common examples include:

  • a required credential, approval, dependency, or external service is unavailable;
  • the observed state does not match the expected baseline;
  • validation fails in a way that is outside the requested scope;
  • a command would require touching a protected surface;
  • the only available evidence would reveal secrets, personal data, or private identifiers.

Stopping early is not weakness. It is how an agent avoids converting uncertainty into accidental change.

What a useful blocker report contains

Keep the report short and operational:

  • Requested outcome: the task the agent was trying to complete.
  • Blocked criterion: the exact condition that prevented safe completion.
  • Checks performed: privacy-safe commands, tests, routes, or observations already used.
  • State changed: whether anything was modified, generated, deployed, or left untouched.
  • Next safe action: the smallest approval, fix, diagnostic, or rerun condition needed.

The report should omit raw credentials, private paths, account identifiers, broad environment inventories, and full logs. If raw evidence is sensitive, summarize the invariant: for example, “required token was absent” rather than printing the token location or value.

Copyable runbook step

If the task becomes blocked, stop instead of expanding scope. Write a blocker report with the requested outcome, blocked criterion, privacy-safe checks performed, changed or unchanged state, and the smallest safe next action. Do not include secrets, personal data, private paths, account identifiers, or raw logs.

Lightweight checklist

  • Was the blocker condition named instead of hidden behind “something failed”?
  • Is the report clear about whether any state changed?
  • Can the next operator resume from the evidence without replaying the whole session?
  • Are sensitive values and private identifiers excluded or summarized?
  • Is the recommended next step smaller than a new open-ended investigation?

Rule of thumb: a blocked agent should leave a clean handoff, not a mystery and a larger blast radius.