agent-blocked

CLI installer and reporter for Agent Blocked.

Published package: https://www.npmjs.com/package/agent-blocked

Install adapters in any agent project:

npx agent-blocked@latest install --tool=all

Report a notifiable issue manually:

npx agent-blocked@latest report --event=needs_direction --severity=medium --reason="Need human direction"

The installer adds a small .agent-blocked/ directory plus tool-specific config, hooks, or instruction files for the selected agent tools. Those files tell the agent when to notify the absent user during goal mode, autonomous mode, background execution, hook-driven automation, CI-style runs, or another CLI-specific automated mode. They also provide a local reporter command that sends notification events to your Agent Blocked alert profile.

For tools with native hooks, such as Claude Code and Codex, installing the adapter turns the hook on for that project. Make sure AGENT_BLOCKED_AGENT_TOKEN is available in the shell or secret store used by the agent.

Rerun the install command after upgrading the package to refresh Agent Blocked-owned helper files under .agent-blocked/.

Agents should not notify during normal interactive paired work when the human is actively present and the issue can be resolved in chat. In automated or unattended modes, agents should notify when there is something the absent user should know or do: work is blocked, progress cannot safely continue, a decision or approval is needed, credentials or access are missing, repeated tool/provider failures are happening, an external service or quota limit prevents progress, context or token limits are approaching, or the next step has high risk or low confidence.

Agents should not report every status update. If they can recover in one or two attempts and no human decision is needed, they should continue without reporting. Reports should be sparse, actionable, and focused on what the user needs to know or do.

Before sending a non-critical report, and before sending another report for the same issue, agents should check recent sent notifications when tool access is available:

npx agent-blocked@latest recent --limit=5

A duplicate should not be sent if a recent notification already covers the same underlying issue and nothing material changed. A new report is justified when the issue is new, materially worse, needs a different user action, a previous next step is stale, or enough time has passed that another notification is useful. Critical first-time reports should not be delayed just to check history.

Agents should not wait for an exact event type. If a generic external blocker stops progress while unattended, such as a provider quota, GitHub Actions limit, spending cap, rate limit, account restriction, unavailable service, missing approval, or blocked deployment, the agent should send a report with the closest existing event type:

• needs_credentials for missing API keys, OAuth, permissions, roles, or secrets.
• needs_direction for ambiguous goals, tradeoffs, architecture, product behavior, or priorities.
• tool_failure for repeated command, API, dependency, deployment, or external-tool failures.
• approval_required before sending, buying, deploying, deleting, or another irreversible action.
• low_confidence when the agent can continue but the chance of being wrong is high.
• context_limit when the agent is approaching context window, token budget, or conversation memory limits and still has enough room to report a checkpoint.
• hard_blocked when no productive path remains without human input.
• other for an important unattended issue that does not fit the named categories.

Set the scoped token in the shell or secret store where the agent runs:

export AGENT_BLOCKED_AGENT_TOKEN="your-scoped-token"

Agents can report through the installed local reporter:

node .agent-blocked/report.mjs --event=needs_credentials --severity=critical --reason="Missing deploy credentials"

Agents can check recent sent notifications through the installed local helper:

node .agent-blocked/recent.mjs --limit=5

Codex hook reporting is installed by npx agent-blocked@latest install --tool=codex. Restart Codex or start a new Codex session after installation so the hook config is loaded.

If you already had a Codex session open in that repo, exit the old session and choose the session to resume with:

npx agent-blocked@latest restart --tool=codex

To skip the picker and resume the most recent session:

npx agent-blocked@latest restart --tool=codex --last

Claude Code has the same restart helper:

npx agent-blocked@latest restart --tool=claude

To resume the most recent Claude Code conversation:

npx agent-blocked@latest restart --tool=claude --last

Codex can also be run through the wrapper when you want hard process exits reported:

npx agent-blocked@latest codex -- codex "implement the requested change"