agent-blocked 0.1.0 → 0.1.3

package/README.md

@@ -2,20 +2,47 @@
 
 CLI installer and reporter for Agent Blocked.
 
+Published package: https://www.npmjs.com/package/agent-blocked
+
 Install adapters in any agent project:
 
 ```bash
-npx agent-blocked install --tool=all
+npx agent-blocked@latest install --tool=all
 ```
 
 Report a blocker manually:
 
 ```bash
-npx agent-blocked report --event=needs_direction --severity=medium --reason="Need human direction"
+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 or instruction files for the selected agent tools. Those files tell the agent when to escalate and provide a local reporter command that sends blocker events to your Agent Blocked alert profile.
+
+Agents should notify when continuing would waste time, create risk, or require a decision only the human can make:
+
+- `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.
+- `hard_blocked` when no productive path remains without human input.
+
+Set these environment variables in the shell where the agent runs:
+
+```bash
+export AGENT_BLOCKED_WEBHOOK_URL="https://agentblocked.com/api/agent-blocked"
+export AGENT_BLOCKED_AGENT_TOKEN="your-scoped-token"
+export AGENT_NAME="prod-agent"
 ```
 
-After `install`, the project gets local helper files under `.agent-blocked/`, so agents can report without depending on the Agent Blocked app repository:
+Agents can report through the installed local reporter:
 
 ```bash
 node .agent-blocked/report.mjs --event=needs_credentials --severity=critical --reason="Missing deploy credentials"
 ```
+
+Codex can also be run through the wrapper so hard stops are reported automatically:
+
+```bash
+npx agent-blocked@latest codex -- codex "implement the requested change"
+```

package/bin/agent-blocked.mjs

@@ -158,6 +158,8 @@ const instructions = `# Agent Blocked instructions for coding agents
 
 When you are blocked by missing credentials, unclear direction, approval requirements, repeated tool failures, low confidence, or external context, stop burning tokens and report the blockage.
 
+Notify the human when continuing would waste time, create risk, or require a decision only the human can make. Do not notify for routine recoverable errors that you can fix yourself in one or two attempts.
+
 Preferred report command from the repository root:
 
 \`\`\`bash
@@ -174,14 +176,23 @@ export AGENT_NAME="your-agent-name"
 
 Event types:
 
-- hard_blocked
-- needs_credentials
-- needs_direction
-- tool_failure
-- approval_required
-- low_confidence
-- lonely_agent
-- other
+- hard_blocked: no productive path remains without human input.
+- needs_credentials: missing API keys, OAuth, login, permissions, roles, or secrets.
+- needs_direction: the goal, tradeoff, architecture, product behavior, or priority is ambiguous.
+- tool_failure: the same command, API, dependency install, deployment, or external tool keeps failing.
+- approval_required: human approval is needed before sending, buying, deploying, deleting, or taking another irreversible action.
+- low_confidence: you can continue, but the risk of being wrong is high enough that a human should know.
+- lonely_agent: you need reassurance, tone guidance, or emotional support before continuing.
+- other: important blocker that does not fit the categories above.
+
+Severity guidance:
+
+- low: informational, no immediate action required.
+- medium: work can wait briefly, but human input is needed.
+- high: important work is blocked or likely to go wrong without help.
+- critical: production, customer, billing, security, data loss, or irreversible-action risk.
+
+Include a short reason and concrete details: what you tried, what failed, what decision is needed, and the safest next option.
 
 Never include secrets, API keys, passwords, OAuth tokens, or private customer data in the report payload.
 `;
@@ -389,8 +400,8 @@ Usage:
   agent-blocked codex -- codex "your task"
 
 Examples:
-  npx agent-blocked install --tool=all
-  npx agent-blocked report --event=needs_credentials --severity=critical --reason="Missing AWS credentials"
+  npx agent-blocked@latest install --tool=all
+  npx agent-blocked@latest report --event=needs_credentials --severity=critical --reason="Missing AWS credentials"
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-blocked",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "CLI installer and reporter for Agent Blocked AI agent escalation alerts.",
   "type": "module",
   "bin": {