diff --git a/docs/approvals.md b/docs/approvals.md index c9d988d2..ff4243ba 100644 --- a/docs/approvals.md +++ b/docs/approvals.md @@ -497,15 +497,18 @@ regular claude turn so the manager can react. Variants The recipient responds via `Answer { id, answer }` and the asker sees the matching `QuestionAnswered`. -Optional `sha` / `tag` fields on `ApprovalResolved`, `Spawned`, and -`Rebuilt` carry the canonical hive-c0re-vouched commit sha plus the -applied-repo's terminal tag (`deployed/` / `failed/` / -`denied/` for approval-driven flows; `approved/` for the -rare bare-approval case where no underlying action runs). Both are -`Option`: `None` on the paths that don't change the deployed commit -(e.g. `auto_update::rebuild_agent` reapplying the existing main, or -the dashboard `↻ R3BU1LD` button when the lock didn't move). When -set, `git show ` against `/agents//applied.git` inside the +Optional `sha` field on `ApprovalResolved`, `Spawned`, and `Rebuilt` +carries the canonical hive-c0re-vouched commit sha. Optional `tag` +on `ApprovalResolved` and `Rebuilt` only — the spawn path always +lands at `deployed/0`, so the tag is implicit and not echoed. The +tag values for the variants that do carry it: `deployed/` / +`failed/` / `denied/` for approval-driven flows; +`approved/` for the rare bare-approval case where no underlying +action runs. Both fields are `Option`: `None` on the rebuild paths +that don't change the deployed commit (e.g. +`auto_update::rebuild_agent` reapplying the existing main, or the +dashboard `↻ R3BU1LD` button when the lock didn't move). When set, +`git show ` against `/agents//applied.git` inside the manager container yields the exact tree that was referenced. To add a new event: new `HelperEvent` variant + call sites + update