Synchronize Desktop landings into the visible project root without overwriting user work

Hop-State: A_06FN3Z6G7Y16KA22KZSK9WR
Hop-Proposal: R_06FN3Z5WYDG1WMRE9YJQ10R
Hop-Task: T_06FN3MBF98GWD4NA5PA1RWG
Hop-Attempt: AT_06FN3MBF98FBDSE1BZDP5DG
This commit is contained in:
Hop
2026-07-11 09:22:30 -07:00
parent a70773826f
commit 4c0c504935
12 changed files with 1153 additions and 47 deletions
+33 -8
View File
@@ -62,7 +62,7 @@ hop state <HOP_STATE_ID> --json
hop status --json
```
## Execute and submit
## Execute and auto-accept
1. Inspect and modify only the Hop workspace.
2. Keep the change scoped to the captured prompt.
@@ -79,7 +79,17 @@ hop status --json
hop propose --summary "<behavioral summary>" <HOP_STATE_ID>
```
6. Report the prompt state, proposal state, checks, and remaining risks.
6. Unless the user explicitly requested review-only mode, immediately accept
the proposal and validate the exact final tree:
```bash
hop land <proposal-state> -- <final-test-command> [args...]
```
7. Report the accepted result, validation, and remaining risks. Keep internal
state and evidence IDs out of the normal response unless they help explain a
failure or the user asks for them. Confirm that `hop land` reported the
selected visible project root as synchronized.
For a read-only or informational turn, the prompt state is sufficient; do not
invent a proposal when the workspace tree is unchanged.
@@ -88,16 +98,31 @@ Do not edit a frozen proposal. A user follow-up triggers this skill again;
run `hop begin` again before acting. Session binding selects the existing
attempt automatically, so the user never needs to carry state IDs.
## Land only with explicit authority
## Auto-accept by default
Capture the landing request with `hop begin` first. Then, only when the user
explicitly authorizes landing, run:
The captured task prompt authorizes accepting the local project changes needed
to complete that task. Do not ask for separate landing permission and do not
capture a second prompt merely to land. After checks pass and the proposal is
frozen, run `hop land` as part of the same turn.
```bash
hop land <proposal-state> -- <final-test-command> [args...]
```
Use the strongest relevant final validation command. If the task truly has no
runnable validation, `hop land <proposal-state>` is allowed and the final
response must say that acceptance was not validated by a command.
Stop before acceptance only when:
- the user explicitly says `review first`, `proposal only`, `do not land`, or
otherwise asks to approve the result before it is accepted;
- validation fails;
- Hop reports overlap, a changed accepted head, or visible-root divergence; or
- acceptance would require a destructive, external, or out-of-scope action not
authorized by the captured task.
On overlap or validation failure, preserve the proposal and report the block.
If visible-root synchronization is blocked, do not bypass it with `hop accept`,
force checkout, reset, or file copying. Preserve the proposal and identify the
user-owned paths that must be resolved. `hop accept` is reserved for an
explicitly controller-only workflow; Desktop work always uses `hop land`.
Use `hop undo` only after a separately captured, explicit user request.
Read [references/protocol.md](references/protocol.md) for state semantics, exit
+1 -1
View File
@@ -1,7 +1,7 @@
interface:
display_name: "Hop Version Control"
short_description: "Capture every coding prompt before project effects"
default_prompt: "Use $hop to capture this prompt first, complete the task in its isolated workspace, and submit a validated proposal."
default_prompt: "Use $hop to capture this prompt first, complete the task in its isolated workspace, validate it, and auto-accept the proposal unless I explicitly request review first."
policy:
allow_implicit_invocation: true
+19 -2
View File
@@ -48,7 +48,8 @@ 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 accept <proposal> -- <final validation command>
hop sync
hop undo
```
@@ -66,13 +67,25 @@ hop state "$HOP_STATE_ID" --json
hop status --json
hop check "$HOP_STATE_ID" -- <command>
hop propose --summary "<summary>" "$HOP_STATE_ID"
hop land <proposal-state> -- <final validation command>
```
`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.
The initial task prompt authorizes the agent to run `hop land` after successful
validation; a second user approval is not required. Manual review is an opt-in
mode: stop at the proposal only when the user explicitly asks to review or
approve before acceptance. Validation failure, overlap, a stale accepted head,
or newly required destructive/external scope also stops automatic acceptance.
`hop land` is the Desktop operation. It compares paths changed by the proposal with paths accepted since its base, validates and advances accepted state, then safely materializes that tree into the selected visible project root. The root must still match an accepted Hop ancestor, and ignored or untracked destination collisions block before acceptance. Materialization uses a disposable index and never moves HEAD, the active branch, or the user's real index.
`hop accept` is the controller/kernel operation. It advances SQLite and
`refs/hop/accepted` but intentionally leaves the visible root untouched.
`hop sync` safely catches a stale accepted-ancestor root up to the current
accepted state, including projects created with older Hop builds.
`hop begin` is the Codex Desktop entry point. It initializes Hop when necessary,
captures the current message before the agent performs project work, and uses
@@ -95,6 +108,7 @@ command, summary, output, or source file.
| `20` | Overlap or conservative conflict block |
| `21` | Accepted or attempt head changed during compare-and-swap |
| `22` | Validation command failed |
| `23` | Visible project root diverged or contains an overwrite collision |
A failed `hop check` or final landing check persists its evidence. A blocked or failed landing does not advance accepted state.
@@ -130,8 +144,11 @@ provide the same boundary inside compatible agent clients.
- **Missing Hop environment:** run `hop begin` before project work and use the returned state and workspace.
- **Check failure:** fix the live workspace, checkpoint/check again, then create a new proposal.
- **Review-only request:** preserve and report the proposal without landing it.
- **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.
- **Visible-root conflict:** preserve the proposal and the user's files. Do not substitute controller-only `hop accept`; resolve or capture the visible changes, then land again.
- **Controller-accepted root is stale:** run `hop sync`; it succeeds only from an accepted ancestor and never overwrites divergence.
- **Ref inconsistency:** run `hop doctor`; use `hop doctor --repair` only outside final validation.
- **Secrets:** Hop redacts high-confidence provider keys plus contextual tokens,
passwords, private keys, authorization headers, and credential-bearing URLs