Harness:resume

harness:resume

Overview

harness:resume reads the most-recent saved plan state and presents it as a structured context block so a new agent session can pick up exactly where the previous one left off.

It is the reading complement to the context-handoff skill's write side: where context-handoff tells an ending agent how to write a handoff, harness:resume gives a starting agent the tools to consume it.

Two sources are supported:

Workflow

Do you want to read and display the current plan state? → CLI usage

Do you want to inject plan state into an agent session at startup? → SDK integration

Do you want to verify search hints right now? → Rebuilding context from hints

CLI Usage

# Display full plan state (default):
python -m harness_skills.resume

# Print only search hints (fast orientation):
python -m harness_skills.resume --hints

# Machine-readable JSON:
python -m harness_skills.resume --json

# Read from a non-default path:
python -m harness_skills.resume --md-path .claude/other-progress.md

# Prefer JSONL over Markdown:
python -m harness_skills.resume --prefer jsonl

The helper script scripts/resume.py wraps the CLI for use without installing the full package.

SDK Integration

Use resume_agent_options to inject plan state into a new agent session's system prompt before the first turn:

from harness_skills.resume import load_plan_state, resume_agent_options
from claude_agent_sdk import ClaudeAgentOptions, query

# Load state and inject into options
state = load_plan_state()
options, state = resume_agent_options(
    ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    state=state,
)

# The system prompt now contains the full plan state + rebuild instructions
async for msg in query(prompt="Continue from where we left off.", options=options):
    print(msg)

Or load state yourself and pass it in:

from pathlib import Path
from harness_skills.resume import load_plan_state, resume_agent_options

state = load_plan_state(
    md_path=Path(".claude/plan-progress.md"),
    jsonl_path=Path(".plan_progress.jsonl"),
    prefer="md",   # "md" | "jsonl"
)

if not state.found():
    print("No saved plan state — starting fresh.")
else:
    options, _ = resume_agent_options(base_options, state=state)

Rebuilding Context from Hints

After loading the plan state, a resuming agent should verify the hints rather than trusting them as ground truth:

from harness_skills.resume import load_plan_state

state = load_plan_state()
hints = state.search_hints

# 1. Read key files
for path in hints.file_paths:
    # → call Read tool on each path

# 2. Grep key patterns
for pattern in hints.grep_patterns:
    # → call Grep tool with each pattern

# 3. Glob key directories
for directory in hints.directories:
    # → call Glob on f"{directory}/**/*"

# 4. Search key symbols
for symbol in hints.symbols:
    # → call Grep tool with each symbol name

Programmatic API

load_plan_state

from harness_skills.resume import load_plan_state, PlanState

state: PlanState = load_plan_state(
    md_path=Path(".claude/plan-progress.md"),   # optional override
    jsonl_path=Path(".plan_progress.jsonl"),     # optional override
    prefer="md",                                  # "md" | "jsonl"
)

state.found()          # True when a file was read successfully
state.task             # overall task description
state.status           # "in_progress" | "blocked" | "done"
state.timestamp        # ISO-8601 UTC string
state.accomplished     # list[str] — completed items
state.in_progress      # list[str] — partially-done items
state.next_steps       # list[str] — ordered next actions
state.search_hints     # SearchHints — file_paths, directories, grep_patterns, symbols
state.open_questions   # list[str]
state.artifacts        # list[str] — files created/modified
state.notes            # str — free-form context
state.source           # "markdown" | "jsonl" | "none"

format_resume_context

from harness_skills.resume import load_plan_state, format_resume_context

state = load_plan_state()
print(format_resume_context(state))   # human-readable context block

format_hints_only

from harness_skills.resume import load_plan_state, format_hints_only

state = load_plan_state()
print(format_hints_only(state))   # compact search-hints-only view

build_resume_prompt

from harness_skills.resume import load_plan_state, build_resume_prompt

state  = load_plan_state()
prompt = build_resume_prompt(state)   # system-prompt addendum (empty string if no state)

PlanState Fields

SearchHints Fields

Key Files