# agent-status-protocol

> Standardized status reporting for agents and subagents. Ensures consistent progress tracking and machine-readable results.

- Author: engelbr
- Repository: Primadetaautomation/claude-dev-toolkit
- Version: 20260118180546
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/Primadetaautomation/claude-dev-toolkit
- Web: https://mule.run/skillshub/@@Primadetaautomation/claude-dev-toolkit~agent-status-protocol:20260118180546

---

---
name: agent-status-protocol
description: Standardized status reporting for agents and subagents. Ensures consistent progress tracking and machine-readable results.
triggers: [status, progress, report, agent result]
version: 1.0.0
applies_to: [all agents, subagents, Task tool]
---

# Agent Status Protocol

## Purpose

Ensure every agent/subagent returns a structured status block that enables:
- Clear progress tracking
- Early stagnation detection
- Consistent handoffs between agents
- Machine-readable results

## Status Block Format

Every agent completing a task SHOULD include:

```
---AGENT_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED | FAILED
TASK: [one-line task description]
FILES_MODIFIED: [list of files actually changed]
FILES_READ: [list of files consulted]
TESTS_RUN: [test command and result]
COMMITS: [commit hashes if any]
WORK_SUMMARY: [2-3 sentence summary of what was done]
BLOCKERS: [any issues preventing completion]
NEXT_STEPS: [what should happen next]
CONFIDENCE: HIGH | MEDIUM | LOW
EXIT_READY: true | false
---
```

## Field Definitions

### STATUS
| Value | Meaning |
|-------|---------|
| IN_PROGRESS | Still working, not done yet |
| COMPLETE | Task fully done, verified |
| BLOCKED | Cannot proceed without input |
| FAILED | Attempted but couldn't complete |

### CONFIDENCE
| Value | When to use |
|-------|-------------|
| HIGH | Tests pass, code works, verified |
| MEDIUM | Code written, not fully tested |
| LOW | Best effort, needs review |

### EXIT_READY
- `true`: This agent's work is done, can terminate
- `false`: More work needed in this context

## Usage Patterns

### Subagent Task Completion
```markdown
Task: "Implement login function"

---AGENT_STATUS---
STATUS: COMPLETE
TASK: Implement login function with JWT auth
FILES_MODIFIED: [src/auth/login.ts, src/auth/types.ts]
FILES_READ: [src/auth/register.ts, package.json]
TESTS_RUN: npm test -- --grep "login" (4 passed)
COMMITS: [abc123: "feat(auth): implement login endpoint"]
WORK_SUMMARY: Created login function with email/password validation,
  JWT token generation, and error handling. Follows patterns from
  existing register.ts.
BLOCKERS: None
NEXT_STEPS: Implement protected route middleware
CONFIDENCE: HIGH
EXIT_READY: true
---
```

### Blocked Status
```markdown
---AGENT_STATUS---
STATUS: BLOCKED
TASK: Connect to external payment API
FILES_MODIFIED: []
FILES_READ: [src/payments/stripe.ts, .env.example]
TESTS_RUN: None (blocked before implementation)
COMMITS: []
WORK_SUMMARY: Analyzed payment integration requirements.
  Stripe SDK is installed but API keys are missing.
BLOCKERS: STRIPE_SECRET_KEY not in environment
NEXT_STEPS: User needs to add Stripe API keys to .env
CONFIDENCE: N/A
EXIT_READY: false
---
```

### Failed Status
```markdown
---AGENT_STATUS---
STATUS: FAILED
TASK: Fix database connection timeout
FILES_MODIFIED: [src/db/connection.ts]
FILES_READ: [src/db/config.ts, logs/db-errors.log]
TESTS_RUN: npm test (3 failed - same error)
COMMITS: []
WORK_SUMMARY: Attempted 3 approaches to fix timeout:
  1. Increased pool size - no effect
  2. Added retry logic - same error
  3. Changed connection string format - same error
BLOCKERS: Root cause unclear - may be infrastructure issue
NEXT_STEPS: Recommend checking database server status or
  spawning fresh context with different specialist
CONFIDENCE: LOW
EXIT_READY: false
---
```

## Integration Points

### With Circuit Breaker
Status block provides data for stagnation detection:
- `FILES_MODIFIED: []` → No progress signal
- `STATUS: FAILED` repeated → Trip threshold
- `CONFIDENCE: LOW` → Heightened monitoring

### With TodoWrite
```markdown
On COMPLETE:
- Mark corresponding todo as completed
- Add NEXT_STEPS as new todo if applicable

On BLOCKED:
- Mark todo as blocked
- Add blocker resolution as new todo

On FAILED:
- Keep todo as in_progress
- Add investigation todo
```

### With GSD Workflow
```markdown
Status block enables:
- Verification phase checks (TESTS_RUN)
- Atomic commit tracking (COMMITS)
- Context handoff (WORK_SUMMARY, NEXT_STEPS)
```

## Parsing Status Block

For automation, status can be parsed:

```javascript
function parseAgentStatus(output) {
  const match = output.match(/---AGENT_STATUS---\n([\s\S]*?)\n---/);
  if (!match) return null;

  const lines = match[1].split('\n');
  const status = {};

  for (const line of lines) {
    const [key, ...valueParts] = line.split(':');
    if (key && valueParts.length) {
      status[key.trim()] = valueParts.join(':').trim();
    }
  }

  return status;
}
```

## When to Include Status Block

| Scenario | Include? |
|----------|----------|
| Subagent completing task | YES |
| Main agent finishing milestone | YES |
| Quick single-file edit | Optional |
| Research/exploration | Optional |
| Failed attempt | YES |
| Blocked state | YES |

## Quality Checklist

Before returning status block, verify:
- [ ] FILES_MODIFIED matches `git status`
- [ ] TESTS_RUN includes actual command and result
- [ ] COMMITS exist (run `git log --oneline -1`)
- [ ] WORK_SUMMARY is specific, not generic
- [ ] CONFIDENCE reflects actual verification done
- [ ] EXIT_READY matches task completion state

---

*Extracted from: RALPH_STATUS block concept (frankbria/ralph-claude-code)*
*Adapted for: Skill-based agent system with multiple specialists*