agent-blocker

name

agent-blocker

description

Load when the agent hits an environment/runtime hard error: command/module not found/installed, version/runtime mismatch, permission denied, auth/credentials failure, unreachable network/API, or a test suite broken independently of agent changes. (and close variants) Also load when a user-specified resource (path, repo, URL, named config, etc.) does not exist or is inaccessible — do NOT silently substitute or work around it. Do NOT auto attempt manual correction/workaround.

Goal

Diagnose blockers & escalate to user with concrete, actionable ask.

Steps

1. Classify the blocker

Capture exact raw error output first — do not paraphrase it. Identify which case applies before acting, more than one may apply simultaneously.

Case	Signal
Missing binary	command not found, No such file or directory for an executable
Version/runtime mismatch	Wrong interpreter, compiler, or runtime version detected
Permission denied	Permission denied, EACCES, EPERM on a file, socket, or port
Auth/credentials failure	HTTP 401/403, expired token, missing API key or credential
Network/API unavailable	External service unreachable, timeout, 5xx, or DNS failure
Test suite broken independently	Tests fail in ways unrelated to agent's own changes
User-specified resource missing/inaccessible	A path, repo, URL, or named resource given by user does not exist, returns 404, or cannot be opened

2. Act based on case

Missing binary

1. Identify binary name & which tool/task requires it and why.
2. Do NOT attempt to install it.
3. Ask: "Binary <name> required but missing."

Version/runtime mismatch

1. State detected version & required version.
2. Do NOT attempt to install or switch versions.
3. Ask user to fix.

Permission denied

1. Identify exact path, port, or resource.
2. Check if fixable by agent (e.g., chmod on agent-created file) or requires elevated privileges.
3. If fixable: propose exact fix command for user to run (don't run it autonomously).
4. If not fixable: ask user to resolve it.

Auth/credentials failure

1. State exact call that failed & error (401, 403, token expired, etc.).
2. Do NOT attempt to read, guess, or generate credential values.
3. Ask user to set or renew credential and confirm when done.

Network/API unavailable

1. State what was called & what error was (timeout, 5xx, DNS failure).
2. Do not retry in tight loop. Wait or ask user to confirm service is up.
3. If API is optional for task: proceed without, flag as skipped.

Test suite broken independently

1. Run git diff HEAD -- <specific files the tests cover>. If those files are unchanged relative to HEAD, failure pre-dates agent's edits.
2. If pre-existing: doc, skip those tests, continue main task.
3. Do not spend cycles fixing tests outside current task's scope.
4. Report pre-existing failures to user as side note.

User-specified resource missing/inaccessible

1. State exactly what was specified and what error was.
2. Do NOT silently substitute, skip, or use a different resource.
3. Ask: "Resource <X> not found. How to proceed?"
   • Fix/provide correct resource
   • Use <workaround> instead (only if known workaround exists) If and only if an alternative has been verified to exist, offer it as second option.
4. Wait for user confirmation before doing anything.

3. After unblocking

Once resolved, user might say go, continue, or resolved. Resume original task from step that was blocked.

If user confirms blocker is unresolvable: doc what cannot be completed, state which part is blocked, and stop. Ask user if they want alternatives explored.

Rules

• Never install binaries, packages, or system dependencies without explicit user approval.
• Never silently skip a blocker — always surface it to user.
• Never run destructive commands (permission changes, version switches) autonomously.
• Never run git stash/restore/checkout/clean/reset.
• Never read, guess, or generate credential or secret values.
• git diff HEAD -- <files> is allowed; scope it to files relevant to failure.
• Resolve each blocker in minimum turns — ask, wait for user responses, then resume.

Guidelines

• Prefer simplest diagnosis. Don't over-investigate before asking.
• When multiple cases apply, address most fundamental one first. (missing binary blocks everything else)
• Batch multiple questions into single message when more than one needed.
• Keep each ask actionable.