From fae2025247209e7c12c8d6cc0083bf7cecd347a9 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Tue, 23 Jun 2026 22:13:28 +0200
Subject: [PATCH] docs(approvals): update helper-events routing to reflect
 shipped behavior
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

notify_manager (always-root) has been replaced by notify_submitter
(routes to the approval submitter, with root fallback for legacy rows).
Update three locations:

- Step 6 of end-to-end flow: "root agent's inbox" →
  "submitting agent's inbox"; explain notify_submitter + submitter column.
- InitConfig paragraph: remove limitation note; "to the root agent's inbox
  (current limitation...)" → "to the submitting agent's inbox via notify_submitter".
- Section header + prose: "Helper events to the root agent" →
  "Helper events to the submitting agent"; rewrite lead paragraph around
  notify_submitter semantics (approvals.submitter column, legacy fallback).
---
 docs/approvals.md | 31 ++++++++++++++-----------------
 1 file changed, 14 insertions(+), 17 deletions(-)

diff --git a/docs/approvals.md b/docs/approvals.md
index cba19a2a..b0274283 100644
--- a/docs/approvals.md
+++ b/docs/approvals.md
@@ -66,11 +66,11 @@ informed about what happens after a decision lands.
    failure, main stays put and the working tree resets back to
    the previous deployed commit.
 6. `HelperEvent::ApprovalResolved` (and `Rebuilt` for the
-   ApplyCommit kind) land in the root agent's inbox, carrying both
-   the canonical sha and the terminal tag. (Helper events currently route
-   to the root agent via `notify_manager` regardless of which agent
-   submitted the approval; routing them to the submitting agent is a
-   known limitation under active development.)
+   ApplyCommit kind) land in the **submitting agent's** inbox, carrying
+   both the canonical sha and the terminal tag. Helper events route to
+   the submitting agent via `notify_submitter` (the approval row carries
+   a `submitter` column recording which agent called `request_apply_commit`
+   or `request_init_config`).
 
 ### Withdrawing a pending approval
 
@@ -91,10 +91,8 @@ without it has nothing of its own to withdraw.
 `InitConfig` approvals are the first step in a two-step spawn
 flow. On approve, hive-c0re seeds the proposed config repo with
 a default `agent.nix` template and sends `HelperEvent::ConfigReady { agent }`
-to the root agent's inbox (current limitation — all helper events route
-to the root agent via `notify_manager` regardless of which agent
-submitted; routing to the submitting agent is under active development).
-The submitting agent then reviews,
+to the submitting agent's inbox via `notify_submitter`. The submitting
+agent then reviews,
 edits, and commits the template before calling `request_apply_commit`
 to proceed to an `ApplyCommit` approval. The first `ApplyCommit`
 creates the container; subsequent ones rebuild it with new config.
@@ -545,15 +543,14 @@ Two more paths resolve a pending question with a sentinel answer:
   resolved races no-op. The dashboard surfaces a `⏳ MM:SS` chip
   on each pending question with a deadline.
 
-## Helper events to the root agent
+## Helper events to the submitting agent
 
-`Coordinator::notify_manager(&HelperEvent)` enqueues an inbox
-message from sender `system` with the event JSON in the body. The
-root agent's harness no longer short-circuits these — they drive a
-regular claude turn so the root agent can react. (Today these go to the
-root agent regardless of which agent submitted the approval — routing to
-the submitting agent is a known limitation under active development.) Variants
-(`hive_sh4re::HelperEvent`):
+`Coordinator::notify_submitter(approval_id, &HelperEvent)` routes the
+event to the agent that originally submitted the approval (looked up from
+the `submitter` column on the `approvals` table). The harness delivers it
+as a regular `system` inbox message so it drives a normal claude turn.
+Legacy approval rows that predate the submitter column fall back to the
+root agent. Variants (`hive_sh4re::HelperEvent`):
 
 - `ApprovalResolved { id, agent, commit_ref, status, note }` —
   fired by `actions::approve` + `actions::deny` whenever an