Hop/skills/hop/references/protocol.md

Hop agent protocol

State graph

A accepted
├─ P prompt, persisted before effects
│  └─ C checkpoint
│     └─ R proposal
└─ P independent prompt

A + R ──land──> A next accepted state

State prefixes:

Prefix	Kind	Meaning
A_	accepted	Canonical project revision
P_	prompt	Exact instruction and pre-effect context
C_	checkpoint	Immutable workspace progress
R_	proposal	Frozen candidate result
F_	failed	Durable failed execution or validation state
X_	cancelled	Durable cancelled state

Prompt, checkpoint, and proposal states may reference identical Git trees while remaining distinct causal occurrences.

Environment contract

Variable	Purpose
HOP_ROOT	Canonical project root containing .hop/hop.db
HOP_STATE_ID	Prompt state authorizing the current instruction
HOP_TASK_ID	Logical task grouping related prompts and attempts
HOP_ATTEMPT_ID	Current agent approach/run
HOP_WORKSPACE	Only directory the agent may modify

Treat missing variables as an invalid agent launch. Do not infer an attempt from a nearby worktree when causality matters.

Command contract

Human or controller

hop init
hop start --agent <name> "<exact initial prompt>"
hop env <prompt-state>
hop prompt --from <state> "<exact follow-up prompt>"
hop land <proposal> -- <final validation command>
hop undo

hop start creates the task, attempt, prompt state, and detached workspace before returning. The controller may deliver the prompt only after exit 0.

hop prompt captures a checkpoint of current workspace effects before creating the follow-up prompt state.

Agent

hop state "$HOP_STATE_ID" --json
hop status --json
hop check "$HOP_STATE_ID" -- <command>
hop propose --summary "<summary>" "$HOP_STATE_ID"

hop check snapshots the attempt and runs the command in a detached worktree materialized from that exact checkpoint. Edits made concurrently in the live workspace do not change the tested tree.

hop propose freezes the current nonignored workspace tree. Later workspace edits cannot change the proposal.

hop land compares paths changed by the proposal with paths accepted since its base. Any shared changed path blocks landing. Disjoint proposals are composed with Git three-tree plumbing and may then be validated on the final tree.

Exit codes

Code	Meaning
0	Success
1	Git, SQLite, filesystem, or internal error
2	Invalid CLI usage
20	Overlap or conservative conflict block
21	Accepted or attempt head changed during compare-and-swap
22	Validation command failed

A failed hop check or final landing check persists its evidence. A blocked or failed landing does not advance accepted state.

Human launch sequence

hop init
hop start --agent codex "Add password reset emails"

Use the returned workspace and environment to launch the agent. For example, conceptually:

eval "$(hop env P_...)"
<agent-command> "<the same exact prompt>"

The exact agent command is harness-specific. Until a Hop process adapter intercepts prompts automatically, follow-up prompts must also pass through hop prompt before the agent acts.

Failure handling

• Missing Hop environment: stop before editing and request a Hop-controlled launch.
• Check failure: fix the live workspace, checkpoint/check again, then create a new proposal.
• Frozen proposal needs changes: record a follow-up prompt; never mutate the stored proposal.
• Overlap on landing: retain both lineages and reconcile through a new prompt against current accepted state.
• Ref inconsistency: run hop doctor; use hop doctor --repair only outside final validation.
• Secrets: prompt text and check output are stored locally without encryption in the alpha. Never place credentials in them.