Module approvals

Expand description

ORCH-9 (observed tier): one uniform listing of the approval requests waiting for an answer, across every harness supercode drives.

What a source is, at the pinned harness versions. An approval is only listable where some door holds it. At the pin there is exactly one uniform source plus supercode’s own queue:

Live protocol requests — a request exists while a driven runtime’s turn is blocked on it, and it is delivered to supercode as an ordinary runtime event (crate::HarnessEvent) on the connection that raised it: ACP’s session/request_permission (hermes, openclaw, grok, gemini, goose, supercode), opencode’s permission.asked bus event, Codex’s server-to-client *Approval reverse requests, Claude Code’s stream-json can_use_tool control request, and — on a joined supercode runtime — the frontend broker’s own request envelope. It stops existing the moment harness.v1.runtimes.respond answers it.
supercode’s own queued subagent approvals (crate::subagents::QueuedApproval) — the requests background children raised on the parent’s queue.

There is no file or database source at the pin. hermes 0.21.0 has no hermes approvals at all, and openclaw 2026.7.1-2 has no approvals pending | resolve | grants (both are upstream-main-only; see the version note in docs/composable-harness/inventory/orchestration.md and the committed help fixtures in crates/harness/src/parity/fixtures/). ApprovalKind::Stored and ApprovalKind::Proposal are therefore defined here and never produced: they are the shapes a later pin’s stored operator approvals and allowlist proposals will land in, and nothing in this module invents them today.

pi is a further honest absence: its adapter can respond, but pi has no per-tool-call approval system at all at its pin (docs/composable-harness/inventory/pi.md §4), so no pi request shape is recognized — none is ever emitted.

Answering (ORCH-20, controlled tier). This module never talks to a harness itself. It TRANSLATES one uniform decision — allow_once, allow_always, deny — into the option token and reply envelope the door that raised the request already accepts, and harness.v1.approvals.resolve hands that envelope to harness.v1.runtimes.respond, the harness’s own door, unchanged. A decision the request does not offer is refused by name with the offered ones listed; nothing is ever guessed at, and no adapter learns a new vocabulary because of this module.

Structs§

ApprovalOption: One answer the door that raised this request accepts.
ApprovalRegistry: The live pending requests held by one service’s open runtime connections.
ApprovalResolution: Everything harness.v1.runtimes.respond needs to answer one request.
ApprovalRow: One approval request, in the vocabulary shared by every harness.
ApprovalsQuery: harness.v1.approvals.list request.
ApprovalsResolveParams: harness.v1.approvals.resolve request.
LiveRequest: One live protocol request as the classifier reads it off the wire.

Enums§

ApprovalChoice: What a caller asked for, once the params have been validated.
ApprovalDecision: The uniform decision harness.v1.approvals.resolve takes, in the vocabulary shared by every harness rather than any one door’s spelling.
ApprovalDoor: Which protocol door raised a live request.
ApprovalKind: Where a row came from.
ApprovalResolveError: Why one resolve could not be planned.
ApprovalStatus: Lifecycle state of one approval row.

Functions§

approval_harnesses: Every harness id approvals.list accepts, in registry order.
classify_live_request: Recognize a permission/approval request in one live runtime event.
lists_approvals: Whether supercode can list approvals for this harness id at all.
now_ms: Wall-clock now in unix milliseconds.
plan_reply: Translate one caller’s choice into the token and envelope a request’s own door accepts.
subagent_rows: supercode’s own queued subagent approvals, as uniform rows.