docs(eventing): Phase 4 design — enrollment, and asking a human for permission

[mrsabath]

Phase / scope

Phase	Phase 4 — enrollment, and asking a human for permission. A delta over DESIGN_PHASE2.md (identity) and DESIGN_PHASE3.md (tenancy, ntfy isolation).
What this changes	One new document plus a row and a reading-order entry in the agentdocs index. No code, no manifests, no tests.
Why a separate PR	It is a phase design, and the convention here is that one lands as a reviewable record before its implementation — the same shape as #881 for Phase 3. Nothing in it is implemented.
Phases it does not touch	All of them. Disjoint files from #892 and #893, both now merged; rebased onto them.

Adds eventing/agentdocs/DESIGN_PHASE4.md. Two gaps Phase 2 and Phase 3 leave, which
turn out to be the two halves of one idea — the notification channel is
bidirectional.

The two gaps

Nothing connects a GitHub login to a phone. Phase 3 §4.2 derives the unguessable
per-user ntfy topic and §4.3 provisions the reader account, but both are operator-side
(k8s_tenant.py, kubectl exec), and §4.3 has the per-user token "handed to the user
once, at provisioning time" — printed to the operator's terminal. A user who has
signed in with GitHub still has no way to learn their own topic. That is a provisioning
story, not an enrollment story, and the operator is a required participant in every
signup.

Permission is decided before the run, and cannot be revisited. Phase 3 §5.1 fixes
each agent's permission_mode and tool allowlists — "the sandbox" — in the AgentSpec.
There is no approval vocabulary anywhere in the tree or in any design document: an
agent that needs a permission it was not granted cannot ask, and a human cannot answer.

The second gap is what makes Phase 3's triggers risky to enable. §7.4 concedes a
trigger's rendered prompt is attacker-influenced text and §5.1 answers with default-deny
tools — but default-deny with no escalation path means the operator's rational move is to
widen the allowlist permanently, for a capability needed once. An approval path is what
keeps a narrow allowlist narrow.

§2 is the measured part, and the rest depends on it

The whole design rests on one question: can a tool call be paused mid-run, in headless
claude -p, until an external system answers? If not, this is a notification after the
fact rather than a gate. Phase 2 §8.6's rule applied — and it earned its keep twice,
because the documentation was wrong about which flag to use and I mispredicted the
permission mode.

Measured against the CLI, --output-format stream-json --verbose --max-turns 2 --settings <file>:

Check	Result
PreToolUse hook fires in -p (non-interactive) mode	yes
Hook blocks 75 s; the tool does not run while it waits	yes — 93 s wall clock
Per-hook "timeout": 120 honoured	yes — the 75 s hook was not killed
permissionDecision: "deny" → tool never executes	yes
permissionDecisionReason reaches the agent as the tool result	yes — it then explained the refusal in its answer
permissionDecision: "allow" → tool executes	yes — echo HELLO_FROM_TOOL → HELLO_FROM_TOOL

Two negative findings, recorded because each is an attractive wrong turn:

• --permission-prompt-tool does not exist on this CLI. The flag is
  --permission-prompts <host|none>, and its own help text defines host as "the SDK
  host" — it needs the Agent SDK driving the session in-process, as does canUseTool.
  EventRunner spawns a subprocess, so the hook is the only mechanism available to it.
  That is a constraint, not a preference.
• plan is the wrong mode for an agent subject to approval, and Phase 3 §5.1
  proposes it as the safe default. Measured: under plan the agent wrote a plan file and
  reached for ExitPlanMode instead of attempting the guarded tool, so the hook
  adjudicated nothing — the call never happened.

The hook also needs no new plumbing: AgentSpec already carries settings_file,
resolved under the agent dir by _resolve_under and passed as --settings, and Phase 3
§5.2 already requires that directory be unwritable by the agent ("an agent definition the
agent itself could rewrite is not a policy, it is a suggestion" — that sentence is the
whole security argument for where the hook lives, and it was already written down).

The control that matters most, which Phase 3 §4.4 does not have

Phase 3 §4.4 MACs userkey|corr|exp. That is right for continuing a conversation,
where the only thing to bind is the correlation. Authorising an action has to bind
the action: the approval key covers a digest of the canonical tool input, and the hook
re-computes that digest before returning allow. Without it, a key that approved
echo hi is replayable against a rewritten command on the same approval id.

Three more decisions that follow the repository's existing discipline rather than
inventing anything:

• The verdict is a row read from the store, never an attribute off the event — Phase 2
  §8.5.4, whose cautionary tale is group-member push suppression being defeated by
  omitting the attribute it reads.
• Once-only is a guarded UPDATE … WHERE decided_utc IS NULL on rowcount == 1, the
  pattern mark_member_finished and complete_group already use. In SQL rather than in
  memory, for the reason those are.
• A timeout is recorded as timeout, not deny. "Nobody was awake" and "a human said
  no" need different fixes, and collapsing them hides which is happening. §5.7 also pins
  the budget inequality, because a killed hook is a non-blocking error — execution
  proceeds, i.e. the tool runs unapproved. That is the one failure direction this
  phase cannot have.

Two constraints that ruled out the obvious shapes

• Three ntfy action buttons is a hard ceiling, and _publish already fills it (Open
  history, Raw CloudEvents, Continue…). So "add an Approve button to the result
  notification" silently drops one. An approval is its own notification shape.
• A pod cannot wait indefinitely — it holds a Kafka partition against the
  ER_DRAIN_TIMEOUT_S budget test_manifests.py already pins, and KEDA will not scale it
  away mid-run. Hence §6: deny on timeout, keep the approval row alive, and let a late
  approval start a new turn scoped to the recorded input digest. The cost is honest (the
  agent redoes that work) and it trades a bounded cost for an unbounded one.

§9 answers Phase 2 §8.5's five questions before this ships

Including the hole that remains, stated rather than discovered: the hook runs in the pod
the agent runs in, so an agent with an unexpected write primitive over
/etc/rossoctl/agents disables its own guard. The mitigation is a filesystem permission,
not a cryptographic control.

§9.3 tabulates all four half-configured cases, and the one that matters is deliberately
the opposite of Phase 2 §8.1's worst finding: guarded tools with EventBridge unreachable
→ the hook denies, loudly. Both sides fail closed, and both say so.

Not verified, and not claimed

• Nothing has run on a cluster. Written without cluster access; §10 says so in the
  same place docs(eventing): KubeCon NA knowledge base — abstract, status, plan, slides #893 does, rather than implying observation.
• The CLI version is not the pinned one. §2 was measured on 2.1.270;
  Dockerfile-eventrunner-claude pins 2.1.278. The contract is expected to hold
  across that gap and has not been confirmed on 2.1.278 — which is exactly what
  §9.1's test is for, and T10 is the first thing to build.
• No implementation exists. eventbridge/capability.py is not in the tree and
  NtfyPublisher is still single-topic, so §11 orders the tasks behind Phase 3's ntfy
  isolation and capability key.

Verification

Design-only, so what was verified is the claims, per Phase 2 §8.6:

• §2's table was run, not read — transcripts reproducible with the flags above.
• Every §N.N reference resolves to a heading that exists, and is phase-qualified where
  ambiguous — §4.2, §4.3, §4.4, §8.1 and §8.3 all exist in both Phase 2 and
  Phase 3, so a bare reference is genuinely ambiguous. Checked with a script, then
  deleted.
• Every count reconciles with its enumeration (§5.9's three actions, §9.3's four cases,
  §6's three steps, T1–T10 contiguous) — docs(eventing): Phase 2 — make §8's count checkable, and correct one mechanism #892's lesson.
• The ntfy limits in §5.9 are cited from ntfy's publish documentation rather than inferred
  from ntfy.py's constants.
• Rebased onto docs(eventing): Phase 2 — make §8's count checkable, and correct one mechanism #892 and docs(eventing): KubeCon NA knowledge base — abstract, status, plan, slides #893; all Phase 2 §8 references re-checked against docs(eventing): Phase 2 — make §8's count checkable, and correct one mechanism #892's
  corrected text. No Python touched, so ruff is unaffected.

Open question for review

§3.4 records a recommendation rather than a decision: the terminal QR code for
enrollment would mean ~150 lines of hand-rolled encoder forever (Phase 1 §1.1 forbids
qrcode/Pillow). I recommend shipping the ntfy:// deep link as text first and adding
the QR only if a demo shows the link is not enough. Worth a second opinion before T9.

[mrsabath]

Two findings came out of reviewing how identity reaches ntfy in this design. Both are Phase 3 defects rather than Phase 4 ones, so they are filed separately per DESIGN_PHASE2.md §8.7 — but this PR inherits both, so recording the dependency here.

• 🐛 eventing: tenancy key derives from the GitHub login, so a released login inherits the previous holder's tenant #898 — the tenancy key derives from the GitHub login, which GitHub documents as renameable ("can change over time") while the numeric id is durable. A rename moves a user to an empty tenant; a released login lets a new holder inherit the previous one’s store, topics and ntfy topic. Demonstrated with tenancy.userkey, and id is already in the GET /user response fetch_login parses — so the fix needs no extra call. §3 of this PR derives the same key, so it inherits the defect.

• 🐛 eventing: no owned policy for who may read which alert topic — alert authorization lives in ntfy's auth db #899 — there is no owned policy for who may read which alert topic. Alert authorization is the unguessable topic name plus, in incluster mode, ACLs in ntfy’s own SQLite auth db provisioned by kubectl exec. Nothing in eventbridge/ or shared/ evaluates or audits it. §3.5 of this document already records the narrow version of this bound ("enrollment proves the GitHub account asked for a topic […] not that this topic reaches only that person’s phone"); 🐛 eventing: no owned policy for who may read which alert topic — alert authorization lives in ntfy's auth db #899 is the general case, and its A-vs-B question is worth settling before EB_TENANCY_MODE=multi is recommended for anything real.

Neither blocks this PR — it is a design record and both findings are about the code it builds on. Flagging because #899 in particular bears on whether the approval channel in §5 should treat the ntfy topic as an authorization boundary at all.

[aslom]

Summary

A design-only phase record that holds up under the claim-check its own §10 invites. I
verified every code reference with a line number, every file-existence claim, every count,
and the numeric constants — all of them are exact, including the three ntfy action labels,
the 5 if phase == "error" else 3 priorities, MSG_CAP = 3500, CLAUDE_VERSION=2.1.278,
and the sessions.sqlite schema-comment convention. §2 being measured rather than read is
what makes the rest of the document worth trusting, and the two negative findings
(--permission-prompt-tool absent, plan never attempting the guarded call) are the kind
that usually go unrecorded. §5.4's input-digest binding is the right control and §9.4
names the hole it does not close. Approving.

Five findings, none blocking: two duplicated-word typos from line wrapping, one real gap in
§5.7's budget inequality, and two consistency nits.

The one worth acting on before T8 is §5.7. The inequality pins
ER_APPROVAL_TIMEOUT_S < per-hook timeout < turn wall clock, and §6 separately names the
ER_DRAIN_TIMEOUT_S / terminationGracePeriodSeconds budget as the reason an unbounded
wait is unavailable — but never connects the two. The current defaults are fine (110 < 570
< 600, with a comfortable margin), so nothing is broken; the gap is that the one knob an
operator will reach for, when humans complain the approval window is too short, has
nothing pinning it below the drain budget. §7.2's description of
ER_APPROVAL_TIMEOUT_S repeats only the per-hook bound.

Author: mrsabath (MEMBER — maintainer)
Areas reviewed: Docs (2 files, +723/-0); cross-references and code claims verified
against pr897 @ dc1d432, which sits directly on current main (8ab8b30)
Agent/IDE config (.claude/.vscode): none — supply-chain gate clean, no secrets in diff
Commits: 1 commit, signed-off: yes (DCO passing)
CI status: passing — all 12 checks green

Claim-hygiene check, for the record

Ran the §10 / #892 check mechanically. Of the 95 §N.N references in the document (126
counting top-level §N too), the only
ones that do not resolve to an existing heading are the three Phase 1 §1.1 citations
(§1, §2.1, §3.4) — DESIGN_PHASE1.md has no §1.1 heading; the pure-Python rule is a
bullet inside its §1.

This is not a defect in this PR. §1.1 is how the whole document set names that rule
already: DESIGN_PHASE1.md cites its own §1.1 three times, and so do DESIGN_PHASE2.md,
DESIGN_PHASE3.md (×6), IMPLEMENTATION_REPORT1.md (×3) and KUBECON_NA_2026.md. This
document follows the convention correctly. Worth noting only because the PR description
states "Every §N.N reference resolves to a heading that exists" slightly more broadly
than holds — the document's own §10 wording ("here or in the Phase 2/3 document it names")
is accurate as written, and deliberately scoped. A one-line ### 1.1 Pure-Python discipline in Phase 1 would retire the whole class, but that is a separate PR.

Everything else reconciled: §5.9's three actions against _publish's three, §9.3's four
cases, §6's three steps, T1–T10 contiguous, and §9.3's characterisation of Phase 2 §8.1's
worst finding against that document's actual text.