agent-ops

name	agent-ops
description	Operational actions on tasks in an autonomous coding agent — stop, requeue, dead-letter, retry-subtasks, bump-priority. The mechanic's toolbox for running agents.

/agent-ops — Operational Actions

The verbs you need when something needs to be done to a task right now.

Prerequisites

Var	Purpose
AGENT_API_URL	Base URL of the agent's HTTP API
AGENT_API_TOKEN	Bearer token

Subcommands

/agent-ops stop <task-id>

Stop a currently-running task. The task should transition to stopped (or whatever your agent's stopped state is named).

curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
  "$AGENT_API_URL/api/tasks/<task-id>/stop"

When to use:

• Task is in a runaway loop
• Task is doing the wrong thing (operator changed mind)
• Task is consuming excessive cost / time

/agent-ops requeue <task-id>

Move a failed or stopped task back to queued so a worker picks it up again.

curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
  "$AGENT_API_URL/api/tasks/<task-id>/requeue"

When to use:

• Failure was infrastructure (/agent-triage classified as infra)
• Task was stopped to prioritize something else, now ready to resume
• Operator fixed a credential / env issue and wants to retry

/agent-ops dead-letter <task-id> [reason]

Move a task to dead-letter status. It won't be retried automatically. Optional reason logged for audit.

curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "<reason>"}' \
  "$AGENT_API_URL/api/tasks/<task-id>/dead-letter"

When to use:

• Task is wontfix (scope changed, no longer needed)
• Task has hit max retries with no progress
• Task is fundamentally broken in a way operator action can't fix

/agent-ops retry-subtasks <task-id>

If your agent decomposes tasks into subtasks, retry only the failed subtasks of a parent (don't restart the whole tree).

curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
  "$AGENT_API_URL/api/tasks/<task-id>/retry-subtasks"

When to use:

• A 5-subtask plan failed at subtask 3; subtasks 1-2 succeeded
• Don't want to redo the work that already passed
• The retry endpoint should re-examine pending/failed subtasks only

/agent-ops priority <task-id> <priority>

Bump or lower a task's queue priority. Useful when the user/operator decides this task should jump the line.

curl -s -X PATCH -H "Authorization: Bearer $AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority": <priority>}' \
  "$AGENT_API_URL/api/tasks/<task-id>"

Priority semantics depend on your agent. Common conventions:

• Lower number = higher priority (1 = highest, 10 = lowest), OR
• Higher number = higher priority

Document which your agent uses in your env / runbook.

/agent-ops cancel <task-id> [reason]

Like dead-letter but for queued (not yet running) tasks. Removes from queue without ever executing.

curl -s -X POST -H "Authorization: Bearer $AGENT_API_TOKEN" \
  -d '{"reason": "<reason>"}' \
  "$AGENT_API_URL/api/tasks/<task-id>/cancel"

Bulk variant

Each subcommand accepts multiple task IDs:

/agent-ops requeue task-1 task-2 task-3
/agent-ops dead-letter task-4 task-5 "scope changed"

Iterate, but always confirm count + IDs before executing bulk operations. A bulk dead-letter on the wrong list deletes work.

Output

After each action, confirm with:

ACTION    <verb>
TASK      <task-id>
NEW STATE <state>
RESULT    ✓ ok / ✗ <error>

For bulk:

BULK ACTION  <verb> on <N> tasks
SUCCESS      <N>
FAILED       <N>
  • <task-id> — <error>

Notes

• Never run a bulk action without listing the IDs first. Confirm the user wants exactly those IDs to receive the action.
• For irreversible actions (dead-letter, cancel with state cleanup), require explicit user confirmation even for single tasks.
• If your agent's API doesn't expose all these endpoints, omit the subcommands you don't need. The skill is a menu, not a contract.
• After running operational actions, suggest /agent-status to verify the new state.