upsert_progress
Save a checkpoint to an active thread and project PROGRESS.md so coding agents can resume unfinished work with clear goals, next steps, and blockers.
Instructions
Save a checkpoint to active thread state and project PROGRESS.md.
Prefer a known thread_id so the checkpoint cannot land on the wrong
thread. Update structured Goal/Focus/Next/Blocked/Resume only on routine
checkpoints — do not pass ritual content such as "Thread upserted from …".
Reserve content for rare human-meaningful events (decision, blocker note,
ship note). If selection is ambiguous the tool can request a thread_id;
force_new_thread explicitly starts another outcome. Depending on
create_thread_if_missing, a missing thread may be created as a side effect.
When completion.ready is false, prefer this plus pause_thread over mark_done.
Saving thread progress clears paused_at and may sync to a configured
forge/wiki or refresh scan-line AI. The returned thread.return_cue is
advisory coaching on resume_step (missing / vague / concrete); weak cues
do not reject a save. Name the first action using only facts you know.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "upsert_progress"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | Finishable outcome; null preserves it on update, empty string clears it. | |
| focus | No | Current focus, whitespace collapsed and truncated to 500 characters; null or blank preserves existing focus. | |
| title | No | Optional thread title and new-project title; also used for outcome matching. Null preserves an existing thread title. | |
| content | No | Optional meaningful history note (decision, blocker or ship note); omit for routine structured checkpoints. Boilerplate is dropped; exclude secrets. | |
| thread_id | No | Exact existing thread ID in the resolved project; preferred for checkpoints. Takes precedence over force_new_thread. | |
| next_steps | No | Ordered actions; retains the first 3 nonblank entries, each at most 500 characters. Null preserves; [] clears. | |
| resume_step | No | Concrete first action on return; null preserves it, empty string clears it. Updating thread progress clears paused_at. | |
| source_tool | No | Optional originating client/tool name for attribution; null preserves an existing thread source. | |
| project_slug | No | Project identifier; takes precedence over workspace_path. Either this or workspace_path is required, even with thread_id. | |
| blocked_reason | No | Current blocker; null preserves it, empty string clears it. Does not change thread status. | |
| workspace_path | No | Client workspace folder path for project resolution; required when project_slug is absent and may register a missing project. | |
| force_new_thread | No | Defaults to false. True bypasses outcome matching when thread_id is absent; requires create_thread_if_missing=true. | |
| create_thread_if_missing | No | Defaults to true: select or create a thread when thread_id is absent. False saves project notes only unless thread_id is supplied. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | ||
| error | No | Present only when the checkpoint fails. | |
| forge | No | Configured forge/wiki sync outcomes; may contain sync errors. | |
| detail | No | Additional detail for a missing thread. | |
| thread | No | Saved state on success; null for notes-only. | |
| thread_id | No | Selected thread; null for notes-only or selection-required. | |
| candidates | No | Present when explicit thread selection is required. | |
| project_slug | No | ||
| progress_path | No | Written PROGRESS.md path; null while selection is required. | |
| created_thread | No | Present on success; whether a thread was created. | |
| needs_thread_selection | No | If true, choose a candidate thread_id or explicitly force a new thread. |