Hop
68d8bf2f7d
Hop-State: A_06FN69X2VW0BAXG4A4DT6V0 Hop-Proposal: R_06FN69VET1STZNKPWK913K8 Hop-Task: T_06FN637799RW5Q7WH9H6PJR Hop-Attempt: AT_06FN63779BJRBK1VFQ94GRR
2.3 KiB
Core concepts
Hop versions intent and source together. Git remains the content store; Hop adds the causal state graph that explains which instruction produced which result.
States
| Prefix | State | Meaning |
|---|---|---|
A_ |
Accepted | Canonical Hop project revision |
P_ |
Prompt | Durable instruction and pre-effect context |
C_ |
Checkpoint | Immutable snapshot of attempt progress |
R_ |
Proposal | Frozen candidate result |
F_ |
Failed | Durable failed execution or validation result |
X_ |
Cancelled | Terminal cancelled result |
Two states can reference the same Git tree and still be distinct occurrences. For example, a prompt and checkpoint may contain identical files but represent different moments and causal roles.
Task
A task groups the prompts and attempts pursuing one user outcome. Follow-up
messages pursuing unfinished work stay connected automatically through
a stable session ID supplied by the integration. Codex Desktop supplies
CODEX_THREAD_ID automatically. Once that outcome is accepted, the next message
starts a new Hop task at the latest accepted state even when the client
conversation stays open.
Attempt and workspace
An attempt is one agent approach. Each attempt has a detached Git worktree under
.hop/workspaces/. Agents edit there instead of racing in the visible project
root.
Evidence
hop check snapshots the workspace and runs validation against that immutable
tree. Evidence stores the command, redacted output, exit code, and exact tree
hash.
Proposal
hop propose freezes a candidate tree. Later workspace edits cannot mutate the
proposal.
Landing
hop land composes the proposal onto the current accepted state, runs optional
final-tree validation, advances accepted history with compare-and-swap, and
safely materializes the result into the visible project directory.
hop accept is lower-level controller behavior: it advances internal accepted
state but intentionally leaves the visible folder unchanged.
Visible root
The visible root is the project directory selected in an agent client or passed as the controller's working directory. Hop only materializes into it when it still matches an accepted Hop ancestor. Untracked, ignored, staged, or ordinary file divergence that could be overwritten causes a fail-closed error.