Hmbown/CodeWhale · error

Checkpoint continuation requires a source agent

Error message

Checkpoint continuation requires a source agent

What it means

The sub-agent launcher refuses a checkpoint continuation when `checkpoint_continuation` is set but `resume_from_agent_id` is absent. A continuation must know which prior agent to resume from, so the library treats a missing source as an invalid request and fails before any child process is spawned. This is a validation guard inside the agent-spawn path, not a runtime fault.

Solutions

  1. Pass the source agent: set options.resume_from_agent_id to the agent_id (or session name) of the agent being continued.
  2. If you did not intend a continuation, set options.checkpoint_continuation = false instead of leaving the id unset.
  3. If the source id was lost, look it up first via the sub-agent listing/status tool and retry with a valid id.

Example fix

// before
let opts = AgentSpawnOptions { checkpoint_continuation: true, ..Default::default() };
// after
let opts = AgentSpawnOptions {
    checkpoint_continuation: true,
    resume_from_agent_id: Some(source_agent_id.to_string()),
    ..Default::default()
};
Defensive patterns

Strategy: validation

Validate before calling

if (options.checkpointContinuation && !options.resumeFromAgentId) {
  throw new Error("checkpoint_continuation requires resume_from_agent_id");
}

Type guard

function hasResumeSource(o) {
  return !(o.checkpointContinuation === true) || typeof o.resumeFromAgentId === "string" && o.resumeFromAgentId.length > 0;
}

Prevention

When it happens

Trigger: Calling the sub-agent spawn API with options.checkpoint_continuation = true while options.resume_from_agent_id is None/unset. No other combination triggers it.

Common situations: Model or caller code enables the checkpoint-continuation flag after copying option defaults, but forgets to carry over the source agent id from the prior spawn; tool-argument schemas that allow the flag and the id independently so one can be set without the other.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/383bce5c3a14da51. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tools/subagent/mod.rs:6949

            .as_deref()
            .and_then(|id| self.worker_records.get(id))
            .and_then(|record| record.spec.runtime_profile.wall_deadline_ms);
        let deadline_ms =
            narrow_optional_limit(runtime.worker_profile.wall_deadline_ms, source_deadline)
                .map_or(requested_deadline, |deadline| {
                    deadline.min(requested_deadline)
                });
        if deadline_ms <= now_ms {
            return Err(anyhow!(
                "child wall-time budget exhausted; continuation cannot reset its deadline"
            ));
        }
        let wall_time = Duration::from_millis(deadline_ms - now_ms);
        let continuation_from = if options.checkpoint_continuation {
            let source = options
                .resume_from_agent_id
                .as_deref()
                .ok_or_else(|| anyhow!("Checkpoint continuation requires a source agent"))?;
            let source =
                self.resolve_agent_ref_for_session(&runtime.context.state_namespace, source)?;
            if self.resume_targets.contains_key(&source) {
                return Err(anyhow!(
                    "Source already has a continuation; address it with followup"
                ));
            }
            Some(source)
        } else {
            None
        };

        if let Some(model) = options.model.as_deref() {
            runtime.model = model.to_string();
        }
        let effective_model = runtime.model.clone();
        let agent_id = format!("agent_{}", &Uuid::new_v4().to_string()[..8]);
        // Admission into the turn-owned barrier happens before worker records,

View on GitHub (pinned to 73e0f67d83)