Skip to main content
comet resume-probe primarily addresses lost workflow context during long-running work. The user still intends to continue a Comet change, but an agent in a new context window, session, or device no longer knows that the request belongs to Comet, and the user has not invoked /comet again. The probe compares the request with active changes read-only and decides whether the agent should re-enter the corresponding Native or Classic workflow instead of treating “continue the login refactor” as an unrelated new task. It first reads the project’s .comet/config.yaml to select Native or Classic, then reads only that workflow’s active changes, current phase, and the user request. Legacy Classic projects without valid workflow configuration retain the fallback. If configuration is malformed, the probe stops and requests repair instead of scanning the other workflow’s directories. The probe only identifies and routes. It does not modify a change, advance a phase, choose between multiple changes, or execute the returned next command. Actual recovery happens when the agent follows nextCommand into /comet-native or /comet-classic.

​
Why the resume probe exists

Long-running work does not always remain in one complete context. An agent may lose the original Comet association when:
  • the conversation is compacted, moved to another window, or continued in a new session;
  • the user continues the same repository and change from another device;
  • a new agent sees only disk state and a request such as “continue the previous work”;
  • the user naturally asks to continue without invoking /comet again.
Recovery instructions installed in the project can ask the agent to run the probe before handling such a request. The probe uses configuration, active changes, phase, selection, and request text to return an explainable result: a unique target receives the permanent Skill entry, ambiguity produces one question, and unrelated work remains outside Comet.
The resume probe is not another command users must remember. It is primarily called by agents and project recovery instructions to bridge natural-language continuation with the explicit /comet entry point.

​
How automatic probing works

Users do not need to run comet resume-probe. Normal interaction remains a direct request to the agent:
Continue the login refactor.
comet init and comet update install recovery instructions in the project’s agent instruction files. With ambient_resume enabled, the agent automatically runs the read-only probe before handling a natural-language request that may belong to long-running work:
  1. read project configuration to choose Native or Classic;
  2. compare the request with active changes, phase, and selection;
  3. when one target matches, follow nextCommand into /comet-native or /comet-classic;
  4. ask one question on ambiguity, or handle unrelated work normally outside Comet.
An explicit /comet invocation enters the configured workflow directly and does not depend on ambient probing. A host-explicitly invoked non-Comet Skill or slash command also skips the recovery probe: the task intent is already explicit, so that Skill runs directly. Setting ambient_resume: false disables probing for ordinary natural-language requests while leaving /comet available.
For users, recovery probing is automatic. The CLI options below are integration details for agents, hooks, project instructions, and automation—not a manual prerequisite for resuming work.

​
Agent and automation integration reference

An agent or integration can pass the request directly:
Or read it from standard input:

​
Understand the result

JSON uses comet.resume_probe.v2 and includes workflow, skill, entrySource, reasonCode, candidates, changeName, phase, nextCommand, and decision evidence. Native resumes from every phase through /comet-native; comet native next advances state and is not a recovery entry point. The v1 probe bundled with the Classic runtime remains compatible internally, while the top-level CLI returns v2.

​
Cases that pause recovery

  • Multiple active changes exist and the user request does not name a target.
  • Multiple active changes exist without a valid selection or user-named target.
  • An active change lacks valid state, or project configuration is malformed.
  • The workflow is at plan-ready, verification failure, archive confirmation, or another user decision point.
  • A request unrelated to existing changes, or an informational request, does not resume and returns out_of_scope instead.
For Native, uncommitted changes are recovery evidence and a reminder; they do not by themselves block a strong model from entering /comet-native and inspecting the worktree. Classic retains its worktree-attribution confirmation rules.
ask_user is not an error. It means the evidence is insufficient or the workflow is waiting for a user decision. The caller should show the reason and ask the user instead of repeatedly running the probe.

​
How it differs from other commands

​
Next steps

Last modified on August 21, 2026