Files

Lex Christopherson 6ba850712f feat: add subagent resume capability

Add ability to resume interrupted subagent executions using Task tool's
resume parameter. Tracks agent IDs during execution and enables seamless
continuation after session timeout, rate limits, or crashes.

- New /gsd:resume-task command for resuming interrupted agents
- Agent ID tracking in execute-phase workflow
- Dual storage: current-agent-id.txt (fast) + agent-history.json (audit)
- Auto-detection of interrupted agents in resume-project workflow
- File conflict warnings before resume

Closes #37

Co-Authored-By: davesienkowski <davesienkowski@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-10 14:19:10 -06:00

4.0 KiB

Raw Blame History

Agent History Template

Template for .planning/agent-history.json - tracks subagent spawns during plan execution for resume capability.

File Template

{
  "version": "1.0",
  "max_entries": 50,
  "entries": []
}

Entry Schema

Each entry tracks a subagent spawn or status change:

{
  "agent_id": "agent_01HXXXX...",
  "task_description": "Execute tasks 1-3 from plan 02-01",
  "phase": "02",
  "plan": "01",
  "segment": 1,
  "timestamp": "2026-01-15T14:22:10Z",
  "status": "spawned",
  "completion_timestamp": null
}

Field Definitions

Field	Type	Description
agent_id	string	Unique ID returned by Task tool
task_description	string	Brief description of what agent is executing
phase	string	Phase number (e.g., "02", "02.1")
plan	string	Plan number within phase
segment	number	Segment number (1-based) for segmented plans, null for Pattern A
timestamp	string	ISO 8601 timestamp when agent was spawned
status	string	Current status: spawned, completed, interrupted, resumed
completion_timestamp	string/null	ISO 8601 timestamp when completed, null if pending

Status Lifecycle

spawned ──────────────────────────> completed
    │                                   ^
    │                                   │
    └──> interrupted ──> resumed ───────┘

spawned: Agent created via Task tool, execution in progress
completed: Agent finished successfully, results received
interrupted: Session ended before agent completed (detected on resume)
resumed: Previously interrupted agent resumed via resume parameter

Usage

When to Create File

Create .planning/agent-history.json from this template when:

First subagent spawn in execute-phase workflow
File doesn't exist yet

When to Add Entry

Add new entry immediately after Task tool returns with agent_id:

1. Task tool spawns subagent
2. Response includes agent_id
3. Write agent_id to .planning/current-agent-id.txt
4. Append entry to agent-history.json with status "spawned"

When to Update Entry

Update existing entry when:

On successful completion:

{
  "status": "completed",
  "completion_timestamp": "2026-01-15T14:45:33Z"
}

On resume detection (interrupted agent found):

{
  "status": "interrupted"
}

Then add new entry with resumed status:

{
  "agent_id": "agent_01HXXXX...",
  "status": "resumed",
  "timestamp": "2026-01-15T15:00:00Z"
}

Entry Retention

Keep maximum 50 entries (configurable via max_entries)
On exceeding limit, remove oldest completed entries first
Never remove entries with status "spawned" (may need resume)
Prune during init_agent_tracking step

Example File

{
  "version": "1.0",
  "max_entries": 50,
  "entries": [
    {
      "agent_id": "agent_01HXY123ABC",
      "task_description": "Execute full plan 02-01 (autonomous)",
      "phase": "02",
      "plan": "01",
      "segment": null,
      "timestamp": "2026-01-15T14:22:10Z",
      "status": "completed",
      "completion_timestamp": "2026-01-15T14:45:33Z"
    },
    {
      "agent_id": "agent_01HXY456DEF",
      "task_description": "Execute tasks 1-3 from plan 02-02",
      "phase": "02",
      "plan": "02",
      "segment": 1,
      "timestamp": "2026-01-15T15:00:00Z",
      "status": "spawned",
      "completion_timestamp": null
    }
  ]
}

.planning/current-agent-id.txt: Single line with currently active agent ID (for quick resume lookup)
.planning/STATE.md: Project state including session continuity info

Template Notes

When to create: First subagent spawn during execute-phase workflow.

Location: .planning/agent-history.json

Companion file: .planning/current-agent-id.txt (single agent ID, overwritten on each spawn)

Purpose: Enable resume capability for interrupted subagent executions via Task tool's resume parameter.

4.0 KiB Raw Blame History