supercode_harness/

approvals.rs

//! 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.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::subagents::{QueuedApproval, QueuedApprovalOutcome};
use crate::{HarnessEvent, HarnessId};

/// Where a row came from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ApprovalKind {
    /// A request a running turn is blocked on right now.
    Live,
    /// An operator approval a harness keeps in its own store. No harness at
    /// the pinned versions has one; see the module docs.
    Stored,
    /// A mined allowlist proposal rather than an outstanding request. No
    /// harness at the pinned versions has one; see the module docs.
    Proposal,
}

impl ApprovalKind {
    /// Stable wire spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Live => "live",
            Self::Stored => "stored",
            Self::Proposal => "proposal",
        }
    }
}

/// Lifecycle state of one approval row.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ApprovalStatus {
    /// Waiting for an answer.
    Pending,
    /// Answered yes (once or for the session).
    Allowed,
    /// Answered no.
    Denied,
    /// Timed out before anyone answered.
    Expired,
    /// Withdrawn by the side that raised it.
    Cancelled,
}

impl ApprovalStatus {
    /// Stable wire spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Pending => "pending",
            Self::Allowed => "allowed",
            Self::Denied => "denied",
            Self::Expired => "expired",
            Self::Cancelled => "cancelled",
        }
    }
}

/// One answer the door that raised this request accepts.
///
/// `id` is the token the harness's own responder expects — an ACP
/// `optionId`, an opencode reply word, a supercode frontend decision. It is
/// never invented: a row carries options only where the request itself
/// enumerates them or the pinned source documents the responder's vocabulary.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApprovalOption {
    /// Token passed back to the harness.
    pub id: String,
    /// Human label when the request carries one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub label: Option<String>,
    /// The protocol's own classification of the answer, when it states one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kind: Option<String>,
}

impl ApprovalOption {
    fn bare(id: &str) -> Self {
        Self {
            id: id.to_string(),
            label: None,
            kind: None,
        }
    }
}

/// One approval request, in the vocabulary shared by every harness.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApprovalRow {
    /// Stable, addressable identity. Live rows are
    /// `<connection>/<native request id>`; supercode's queued subagent rows
    /// are `supercode/subagent/<child>/<queued_at_ms>/<index>`.
    pub id: String,
    /// Harness whose door raised the request.
    pub harness: HarnessId,
    /// Which source this row came from.
    pub kind: ApprovalKind,
    /// Lifecycle state.
    pub status: ApprovalStatus,
    /// The tool, command, or edit being asked about, on one line.
    pub subject: String,
    /// Harness-native session the request belongs to, when it names one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    /// Live runtime the request arrived on, when there is one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub runtime_id: Option<String>,
    /// Unix-ms wall-clock time the request was first seen.
    pub requested_at_ms: i64,
    /// How long it has been waiting, as of this listing.
    pub age_ms: i64,
    /// Answers the door accepts. Empty where the protocol does not enumerate
    /// them, and always empty on a row that is no longer `pending`.
    #[serde(default)]
    pub options: Vec<ApprovalOption>,
}

/// `harness.v1.approvals.list` request.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct ApprovalsQuery {
    /// Only this harness. Omit for every harness.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub harness: Option<String>,
    /// Only this session (a harness-native session id, or a child agent id
    /// for supercode's queued subagent rows).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub session: Option<String>,
}

impl ApprovalsQuery {
    /// Whether one row survives this query's filters.
    pub fn matches(&self, row: &ApprovalRow) -> bool {
        if let Some(harness) = self.harness.as_deref() {
            if row.harness.as_str() != harness {
                return false;
            }
        }
        if let Some(session) = self.session.as_deref() {
            let hit = row.session_id.as_deref() == Some(session)
                || row.runtime_id.as_deref() == Some(session);
            if !hit {
                return false;
            }
        }
        true
    }
}

/// The uniform decision `harness.v1.approvals.resolve` takes, in the
/// vocabulary shared by every harness rather than any one door's spelling.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ApprovalDecision {
    /// Allow this one call.
    AllowOnce,
    /// Allow this call and every matching one for the rest of the session.
    AllowAlways,
    /// Refuse.
    Deny,
}

impl ApprovalDecision {
    /// Every decision, in escalating order.
    pub const ALL: [Self; 3] = [Self::AllowOnce, Self::AllowAlways, Self::Deny];

    /// Stable wire spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::AllowOnce => "allow_once",
            Self::AllowAlways => "allow_always",
            Self::Deny => "deny",
        }
    }

    /// Parse a wire or CLI spelling. `allow_once` and `allow-once` are the
    /// same decision: the CLI hyphenates its positional, the RPC does not.
    pub fn parse(text: &str) -> Option<Self> {
        let normalized = text.trim().to_ascii_lowercase().replace('-', "_");
        Self::ALL
            .into_iter()
            .find(|decision| decision.as_str() == normalized)
    }
}

/// `harness.v1.approvals.resolve` request.
///
/// Exactly one of `decision` and `option_id` is given: the uniform decision
/// this module translates, or the door's own option token when a caller has
/// already read it off the row and wants it passed through untranslated.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct ApprovalsResolveParams {
    /// The row id `harness.v1.approvals.list` reported.
    pub id: String,
    /// Uniform decision to translate onto this request's own options.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub decision: Option<ApprovalDecision>,
    /// One of the row's own `options[].id` values, passed through as-is.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub option_id: Option<String>,
}

/// What a caller asked for, once the params have been validated.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApprovalChoice {
    /// Translate this uniform decision onto the request's own options.
    Decision(ApprovalDecision),
    /// Send this exact option token, after checking the request offers it.
    Option(String),
}

impl ApprovalChoice {
    /// What the caller asked for, as it will appear in a refusal.
    pub fn asked(&self) -> &str {
        match self {
            Self::Decision(decision) => decision.as_str(),
            Self::Option(option) => option.as_str(),
        }
    }
}

/// Everything `harness.v1.runtimes.respond` needs to answer one request.
///
/// This is a plan, not an effect: building it neither touches a runtime nor
/// forgets the row. The service hands it straight to
/// `harness.v1.runtimes.respond`, so the answer travels the adapter path that
/// already existed and no adapter is changed by this verb.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApprovalResolution {
    /// Runtime connection holding the request.
    pub connection: String,
    /// Native JSON request id the door expects back.
    pub request_id: Value,
    /// Option token actually sent.
    pub option_id: String,
    /// The door's own reply envelope carrying that token.
    pub response: Value,
}

/// Why one resolve could not be planned.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApprovalResolveError {
    /// No live request with this row id is outstanding on this service.
    UnknownId(String),
    /// The row is supercode's own queued subagent record, which is an audit
    /// entry rather than an answerable door.
    QueuedSubagentRow(String),
    /// The request enumerates answers, but none of them is this decision.
    NotOffered {
        /// What was asked for.
        asked: String,
        /// The option ids the request itself offers.
        offered: Vec<String>,
    },
    /// The request enumerates no answers at all, so there is nothing uniform
    /// to select. Codex's reverse approval request is the one such door at
    /// the pin (see [`classify_live_request`]).
    NoOptions {
        /// Door that raised it.
        door: &'static str,
    },
}

impl std::fmt::Display for ApprovalResolveError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::UnknownId(id) => write!(
                formatter,
                "no approval request `{id}` is waiting on this service — a live request \
                 exists only inside the process driving the runtime whose turn it blocks, \
                 and only until it is answered. Answer it there: the SDK client or TUI that \
                 started the runtime, or `harness.v1.approvals.resolve` over that same \
                 `supercode harness serve` stdio session (SUP-62: no cross-process relay)"
            ),
            Self::QueuedSubagentRow(id) => write!(
                formatter,
                "`{id}` is a queued subagent record — supercode's own audit trail of a \
                 request the parent's own handler answers (the terminal's modal, or the \
                 frontend request broker). Answer it on the door that raised it: the \
                 `request` envelope row of the joined supercode runtime"
            ),
            Self::NotOffered { asked, offered } => write!(
                formatter,
                "this request does not offer `{asked}` — it offers: {}",
                if offered.is_empty() {
                    "(nothing)".to_string()
                } else {
                    offered.join(", ")
                }
            ),
            Self::NoOptions { door } => write!(
                formatter,
                "this `{door}` request enumerates no answers, so there is no option to \
                 select — answer it with `harness.v1.runtimes.respond` and that door's own \
                 reply body"
            ),
        }
    }
}

impl std::error::Error for ApprovalResolveError {}

/// Which protocol door raised a live request.
///
/// A door decides two things this module needs and nothing else: the option
/// vocabulary a uniform decision maps onto, and the envelope
/// `harness.v1.runtimes.respond` carries the answer in. Each is the door's
/// own — see [`ApprovalResolution`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ApprovalDoor {
    /// ACP `session/request_permission` (hermes, openclaw, grok, gemini,
    /// goose, supercode's own ACP server).
    Acp,
    /// opencode's `permission.asked` bus event.
    Opencode,
    /// Codex's `*Approval` server-to-client reverse request.
    Codex,
    /// Claude Code's stream-json `can_use_tool` control request, raised to the
    /// permission handler supercode registers with
    /// `--permission-prompt-tool stdio`.
    ClaudeCode,
    /// supercode's own frontend request broker, on a joined runtime.
    SupercodeFrontend,
}

impl ApprovalDoor {
    /// Stable spelling used in refusal messages.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Acp => "acp",
            Self::Opencode => "opencode",
            Self::Codex => "codex",
            Self::ClaudeCode => "claude-code",
            Self::SupercodeFrontend => "supercode-frontend",
        }
    }

    /// How this door spells one uniform decision, best match first.
    ///
    /// Each list is the door's OWN vocabulary, never a coinage:
    ///
    /// * ACP names the classification on the request — `PermissionOptionKind`
    ///   is `allow_once | allow_always | reject_once | reject_always` — so a
    ///   decision is matched against each option's `kind` and, for an agent
    ///   that sends none, against its `optionId`.
    /// * opencode's reply set is `once | always | reject`
    ///   (`docs/composable-harness/inventory/opencode.md` §"Ask/approve flow").
    /// * supercode's frontend broker takes [`FRONTEND_DECISIONS`].
    /// * Claude Code's permission handler answers with a `behavior`, and the
    ///   protocol defines exactly two: `allow` and `deny`
    ///   ([`CLAUDE_CODE_BEHAVIORS`]). `allow_always` is NOT among them —
    ///   persisting a rule is a separate `updatedPermissions` field carrying
    ///   the request's own `permission_suggestions`, which the uniform
    ///   `(door, options, choice)` translation here does not carry — so the
    ///   decision is refused by name with the two that are offered.
    /// * Codex's reverse request enumerates nothing, and this module invents
    ///   no vocabulary for it (ORCH-9's own stance); its rows refuse with
    ///   [`ApprovalResolveError::NoOptions`].
    const fn spellings(self, decision: ApprovalDecision) -> &'static [&'static str] {
        match (self, decision) {
            (Self::Acp, ApprovalDecision::AllowOnce) => &["allow_once"],
            (Self::Acp, ApprovalDecision::AllowAlways) => &["allow_always"],
            (Self::Acp, ApprovalDecision::Deny) => &["reject_once", "reject_always"],
            (Self::Opencode, ApprovalDecision::AllowOnce) => &["once"],
            (Self::Opencode, ApprovalDecision::AllowAlways) => &["always"],
            (Self::Opencode, ApprovalDecision::Deny) => &["reject"],
            (Self::ClaudeCode, ApprovalDecision::AllowOnce) => &["allow"],
            (Self::ClaudeCode, ApprovalDecision::AllowAlways) => &[],
            (Self::ClaudeCode, ApprovalDecision::Deny) => &["deny"],
            (Self::SupercodeFrontend, ApprovalDecision::AllowOnce) => &["allow"],
            (Self::SupercodeFrontend, ApprovalDecision::AllowAlways) => &["allow_for_session"],
            (Self::SupercodeFrontend, ApprovalDecision::Deny) => &["deny"],
            (Self::Codex, _) => &[],
        }
    }

    /// The reply envelope this door carries a chosen option token in.
    ///
    /// `None` for a door with no enumerated answers — nothing is guessed.
    fn reply(self, option_id: &str) -> Option<Value> {
        match self {
            // ACP: the client answers by SELECTING one of the request's own
            // optionIds. This exact envelope cleared a real hermes 0.21.0
            // permission request in
            // `docs/interop/research/orch9-hermes-approval-receipt-2026-09-03.json`.
            Self::Acp => Some(serde_json::json!({
                "outcome": {"outcome": "selected", "optionId": option_id},
            })),
            // opencode: the reply word, POSTed to
            // `/session/{id}/permissions/{permissionID}` by the adapter.
            Self::Opencode => Some(serde_json::json!({"response": option_id})),
            // supercode's own broker takes the decision by name
            // (`crate::runtime::supercode_http::frontend_response`).
            Self::SupercodeFrontend => Some(serde_json::json!({"decision": option_id})),
            // Claude Code: the permission handler's result. `deny` must carry
            // a `message` — measured against claude 2.1.258, which refuses a
            // bare `{"behavior":"deny"}` with "Expected {behavior: 'allow',
            // updatedInput?: object} or {behavior: 'deny', message: string}".
            // Recorded in
            // `docs/interop/research/orc2-claude-respond-receipt-2026-09-04.json`.
            Self::ClaudeCode if option_id == "deny" => Some(serde_json::json!({
                "behavior": "deny",
                "message": "denied through supercode approvals",
            })),
            Self::ClaudeCode => Some(serde_json::json!({"behavior": option_id})),
            Self::Codex => None,
        }
    }
}

/// Translate one caller's choice into the token and envelope a request's own
/// door accepts.
///
/// Kept free of the registry so the whole translation is testable from a
/// request's options alone.
pub fn plan_reply(
    door: ApprovalDoor,
    options: &[ApprovalOption],
    choice: &ApprovalChoice,
) -> Result<(String, Value), ApprovalResolveError> {
    if options.is_empty() {
        return Err(ApprovalResolveError::NoOptions {
            door: door.as_str(),
        });
    }
    let offered = || {
        options
            .iter()
            .map(|option| option.id.clone())
            .collect::<Vec<_>>()
    };
    let chosen = match choice {
        // An explicit token is passed through, but only after the request
        // itself is confirmed to offer it.
        ApprovalChoice::Option(option_id) => options
            .iter()
            .find(|option| &option.id == option_id)
            .ok_or_else(|| ApprovalResolveError::NotOffered {
                asked: option_id.clone(),
                offered: offered(),
            })?,
        ApprovalChoice::Decision(decision) => door
            .spellings(*decision)
            .iter()
            .find_map(|spelling| {
                options.iter().find(|option| {
                    option.kind.as_deref() == Some(*spelling) || option.id == *spelling
                })
            })
            .ok_or_else(|| ApprovalResolveError::NotOffered {
                asked: decision.as_str().to_string(),
                offered: offered(),
            })?,
    };
    let response = door
        .reply(&chosen.id)
        .ok_or(ApprovalResolveError::NoOptions {
            door: door.as_str(),
        })?;
    Ok((chosen.id.clone(), response))
}

/// One live protocol request as the classifier reads it off the wire.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LiveRequest {
    /// Native JSON id the harness expects back through `runtimes.respond`.
    pub request_id: Value,
    /// Protocol door that raised it.
    pub door: ApprovalDoor,
    /// Session the request names, when it names one.
    pub session_id: Option<String>,
    /// One-line description of what is being asked about.
    pub subject: String,
    /// Answers the door accepts.
    pub options: Vec<ApprovalOption>,
}

/// Recognize a permission/approval request in one live runtime event.
///
/// Returns `None` for every other event, including the responses that answer
/// these requests. The three recognized shapes are exactly the ones the
/// adapters in [`crate::runtime`] surface; each is matched on its own
/// protocol's spelling rather than on a guess about the harness.
pub fn classify_live_request(kind: &str, payload: &Value) -> Option<LiveRequest> {
    match kind {
        // ACP `session/request_permission` (hermes, openclaw, grok, gemini,
        // goose, and supercode's own ACP server).
        "session/request_permission" => acp_request(payload),
        // opencode's bus event; the reply goes to
        // `/session/{id}/permissions/{permissionID}`.
        "permission.asked" => opencode_request(payload),
        // supercode's own runtime, joined over the HTTP frontend: the
        // request broker publishes `{"type":"request","request":{…}}` and
        // `runtimes.respond` answers it by the same integer id
        // (`crate::runtime::supercode_http`).
        "request" => supercode_request(payload),
        // Claude Code's stream-json control channel. Only the `can_use_tool`
        // subtype is a permission request; every other control_request the
        // CLI can raise is left alone.
        "control_request" => claude_code_request(payload),
        // Codex app-server / mcp-server reverse requests
        // (`execCommandApproval`, `applyPatchApproval`). A notification with
        // the same name is not a request: only a JSON-RPC message carrying an
        // `id` can be answered.
        _ if kind.ends_with("Approval") => codex_request(payload),
        _ => None,
    }
}

fn request_id(payload: &Value) -> Option<Value> {
    payload
        .get("id")
        .filter(|id| !id.is_null())
        .filter(|id| id.is_string() || id.is_number())
        .cloned()
}

fn acp_request(payload: &Value) -> Option<LiveRequest> {
    let request_id = request_id(payload)?;
    let params = payload.get("params").unwrap_or(&Value::Null);
    let tool_call = params.get("toolCall");
    let subject = tool_call
        .and_then(|call| call.get("title"))
        .and_then(Value::as_str)
        .map(str::to_string)
        .or_else(|| {
            tool_call
                .and_then(|call| call.get("rawInput"))
                .and_then(command_line)
        })
        .or_else(|| {
            tool_call
                .and_then(|call| call.get("kind"))
                .and_then(Value::as_str)
                .map(str::to_string)
        })
        .unwrap_or_else(|| "permission request".to_string());
    let options = params
        .get("options")
        .and_then(Value::as_array)
        .map(|options| {
            options
                .iter()
                .filter_map(|option| {
                    Some(ApprovalOption {
                        id: option.get("optionId").and_then(Value::as_str)?.to_string(),
                        label: option
                            .get("name")
                            .and_then(Value::as_str)
                            .map(str::to_string),
                        kind: option
                            .get("kind")
                            .and_then(Value::as_str)
                            .map(str::to_string),
                    })
                })
                .collect()
        })
        .unwrap_or_default();
    Some(LiveRequest {
        request_id,
        door: ApprovalDoor::Acp,
        session_id: params
            .get("sessionId")
            .and_then(Value::as_str)
            .map(str::to_string),
        subject: one_line(&subject),
        options,
    })
}

fn opencode_request(payload: &Value) -> Option<LiveRequest> {
    let properties = payload.get("properties").unwrap_or(payload);
    let permission = properties
        .get("permission")
        .filter(|value| value.is_object())
        .unwrap_or(properties);
    let id = permission.get("id").and_then(Value::as_str)?;
    let subject = permission
        .get("title")
        .and_then(Value::as_str)
        .or_else(|| permission.get("pattern").and_then(Value::as_str))
        .or_else(|| permission.get("type").and_then(Value::as_str))
        .unwrap_or("permission request");
    Some(LiveRequest {
        request_id: Value::String(id.to_string()),
        door: ApprovalDoor::Opencode,
        session_id: permission
            .get("sessionID")
            .and_then(Value::as_str)
            .map(str::to_string),
        subject: one_line(subject),
        // opencode's own reply vocabulary at the pin
        // (`docs/composable-harness/inventory/opencode.md` §"Ask/approve
        // flow": clients reply `once | always | reject`).
        options: ["once", "always", "reject"]
            .into_iter()
            .map(ApprovalOption::bare)
            .collect(),
    })
}

fn supercode_request(payload: &Value) -> Option<LiveRequest> {
    let request = payload.get("request")?;
    // Only approvals: an MCP elicitation travels the same envelope but is a
    // form to fill in, not a permission to grant.
    if request.get("kind").and_then(Value::as_str) != Some("approval") {
        return None;
    }
    let request_id = request
        .get("id")
        .filter(|id| id.is_number())
        .cloned()
        .filter(|id| !id.is_null())?;
    let inner = request.get("payload").unwrap_or(&Value::Null);
    let subject = inner
        .get("subject")
        .and_then(Value::as_str)
        .filter(|subject| !subject.is_empty())
        .or_else(|| inner.get("tool").and_then(Value::as_str))
        .unwrap_or("permission request");
    Some(LiveRequest {
        request_id,
        door: ApprovalDoor::SupercodeFrontend,
        // A request raised by a background child names that child; a request
        // from the parent's own loop names nothing beyond the runtime.
        session_id: inner
            .get("child_agent_id")
            .and_then(Value::as_str)
            .map(str::to_string),
        subject: one_line(subject),
        // The decisions `runtimes.respond` accepts on this door
        // (`crate::runtime::supercode_http::frontend_response`).
        options: FRONTEND_DECISIONS
            .into_iter()
            .map(ApprovalOption::bare)
            .collect(),
    })
}

/// Claude Code's `can_use_tool` control request.
///
/// Ground truth (claude 2.1.258, recorded live in
/// `docs/interop/research/orc2-claude-respond-receipt-2026-09-04.json`): with
/// `--permission-prompt-tool stdio` the CLI writes
/// `{"type":"control_request","request_id":"<uuid>","request":{"subtype":"can_use_tool","tool_name":"Bash","display_name":"Bash","input":{…},"description":…,"permission_suggestions":[…],"blocked_path":…,"tool_use_id":"toolu_…"}}`
/// and blocks the turn until a `control_response` answers that `request_id`.
fn claude_code_request(payload: &Value) -> Option<LiveRequest> {
    let request = payload.get("request")?;
    if request.get("subtype").and_then(Value::as_str) != Some("can_use_tool") {
        return None;
    }
    let request_id = payload
        .get("request_id")
        .filter(|id| id.is_string())
        .cloned()?;
    let tool = request
        .get("tool_name")
        .and_then(Value::as_str)
        .or_else(|| request.get("display_name").and_then(Value::as_str))
        .unwrap_or("tool");
    let detail = request
        .get("input")
        .and_then(command_line)
        .or_else(|| {
            request
                .get("description")
                .and_then(Value::as_str)
                .map(str::to_string)
        })
        .or_else(|| {
            request
                .get("blocked_path")
                .and_then(Value::as_str)
                .map(str::to_string)
        });
    let subject = match detail {
        Some(detail) if !detail.is_empty() => format!("{tool} {detail}"),
        _ => tool.to_string(),
    };
    Some(LiveRequest {
        request_id,
        door: ApprovalDoor::ClaudeCode,
        // The request names the blocked tool call, never a session: the
        // connection's own runtime id is the session identity here.
        session_id: None,
        subject: one_line(&subject),
        // The two `behavior` values the CLI's permission-result validator
        // accepts; see [`ApprovalDoor::spellings`].
        options: CLAUDE_CODE_BEHAVIORS
            .into_iter()
            .map(ApprovalOption::bare)
            .collect(),
    })
}

fn codex_request(payload: &Value) -> Option<LiveRequest> {
    let request_id = request_id(payload)?;
    let params = payload.get("params").unwrap_or(&Value::Null);
    let subject = params
        .get("command")
        .and_then(command_line)
        .or_else(|| {
            params
                .get("fileChanges")
                .and_then(Value::as_object)
                .map(|changes| {
                    let files = changes.keys().cloned().collect::<Vec<_>>().join(", ");
                    if files.is_empty() {
                        "apply patch".to_string()
                    } else {
                        format!("apply patch: {files}")
                    }
                })
        })
        .or_else(|| {
            params
                .get("reason")
                .and_then(Value::as_str)
                .map(str::to_string)
        })
        .unwrap_or_else(|| "approval request".to_string());
    Some(LiveRequest {
        request_id,
        door: ApprovalDoor::Codex,
        session_id: ["threadId", "conversationId", "sessionId"]
            .into_iter()
            .find_map(|key| params.get(key).and_then(Value::as_str))
            .map(str::to_string),
        subject: one_line(&subject),
        // The Codex reverse request does not enumerate its answers, and this
        // module does not invent a vocabulary for it.
        options: Vec::new(),
    })
}

/// A command as one line, whether the protocol sends a string or an argv.
fn command_line(value: &Value) -> Option<String> {
    match value {
        Value::String(text) => Some(text.clone()),
        Value::Array(parts) => {
            let joined = parts
                .iter()
                .filter_map(Value::as_str)
                .collect::<Vec<_>>()
                .join(" ");
            (!joined.is_empty()).then_some(joined)
        }
        Value::Object(object) => object
            .get("command")
            .or_else(|| object.get("cmd"))
            .and_then(command_line),
        _ => None,
    }
}

fn one_line(text: &str) -> String {
    let flattened = text.split_whitespace().collect::<Vec<_>>().join(" ");
    if flattened.is_empty() {
        "permission request".to_string()
    } else {
        flattened
    }
}

/// Render a native JSON request id into the stable id segment used by
/// [`ApprovalRow::id`].
fn id_segment(request_id: &Value) -> String {
    match request_id {
        Value::String(text) => text.clone(),
        other => other.to_string(),
    }
}

#[derive(Debug, Clone)]
struct LiveEntry {
    request_id: Value,
    door: ApprovalDoor,
    harness: HarnessId,
    runtime_id: String,
    session_id: Option<String>,
    subject: String,
    options: Vec<ApprovalOption>,
    requested_at_ms: i64,
}

/// The live pending requests held by one service's open runtime connections.
///
/// A request enters when the connection surfaces it and leaves when it is
/// answered or the connection goes away. Nothing here survives the process:
/// a live request only exists while the turn that raised it is blocked.
#[derive(Debug, Default)]
pub struct ApprovalRegistry {
    /// Connection id → the requests still outstanding on it, oldest first.
    entries: BTreeMap<String, Vec<LiveEntry>>,
}

impl ApprovalRegistry {
    /// Empty registry.
    pub fn new() -> Self {
        Self::default()
    }

    /// Record one runtime event if it is a permission/approval request.
    ///
    /// Returns `true` when the event was recognized and is now listable. A
    /// repeat of a request already held is not duplicated.
    pub fn observe(
        &mut self,
        connection: &str,
        harness: &HarnessId,
        runtime_id: &str,
        event: &HarnessEvent,
        now_ms: i64,
    ) -> bool {
        let Some(request) = classify_live_request(&event.kind, &event.payload) else {
            return false;
        };
        let entries = self.entries.entry(connection.to_string()).or_default();
        if entries
            .iter()
            .any(|entry| entry.request_id == request.request_id)
        {
            return false;
        }
        entries.push(LiveEntry {
            request_id: request.request_id,
            door: request.door,
            harness: harness.clone(),
            runtime_id: runtime_id.to_string(),
            session_id: request.session_id,
            subject: request.subject,
            options: request.options,
            requested_at_ms: now_ms,
        });
        true
    }

    /// Drop one request because it was answered.
    pub fn answered(&mut self, connection: &str, request_id: &Value) -> bool {
        let Some(entries) = self.entries.get_mut(connection) else {
            return false;
        };
        let before = entries.len();
        entries.retain(|entry| &entry.request_id != request_id);
        let removed = entries.len() < before;
        if entries.is_empty() {
            self.entries.remove(connection);
        }
        removed
    }

    /// Drop everything held for a connection that closed or failed.
    pub fn forget(&mut self, connection: &str) {
        self.entries.remove(connection);
    }

    /// Whether nothing is outstanding.
    pub fn is_empty(&self) -> bool {
        self.entries.values().all(Vec::is_empty)
    }

    /// Plan the answer to one listed row (ORCH-20).
    ///
    /// Looks the row up by the same `id` [`Self::rows`] published, translates
    /// the caller's choice through the door that raised it, and returns what
    /// `harness.v1.runtimes.respond` needs. Nothing is sent and nothing is
    /// forgotten here: the service performs the answer on the existing
    /// respond path, which is also what drops the row.
    pub fn resolution(
        &self,
        row_id: &str,
        choice: &ApprovalChoice,
    ) -> Result<ApprovalResolution, ApprovalResolveError> {
        // A queued subagent record is addressable but not answerable; say so
        // rather than reporting it simply missing.
        if row_id.starts_with(SUBAGENT_ROW_PREFIX) {
            return Err(ApprovalResolveError::QueuedSubagentRow(row_id.to_string()));
        }
        let (connection, entry) = self
            .entries
            .iter()
            .flat_map(|(connection, entries)| entries.iter().map(move |entry| (connection, entry)))
            .find(|(connection, entry)| {
                format!("{connection}/{}", id_segment(&entry.request_id)) == row_id
            })
            .ok_or_else(|| ApprovalResolveError::UnknownId(row_id.to_string()))?;
        let (option_id, response) = plan_reply(entry.door, &entry.options, choice)?;
        Ok(ApprovalResolution {
            connection: connection.clone(),
            request_id: entry.request_id.clone(),
            option_id,
            response,
        })
    }

    /// Every outstanding request as a row, aged against `now_ms`.
    pub fn rows(&self, now_ms: i64) -> Vec<ApprovalRow> {
        self.entries
            .iter()
            .flat_map(|(connection, entries)| {
                entries.iter().map(move |entry| ApprovalRow {
                    id: format!("{connection}/{}", id_segment(&entry.request_id)),
                    harness: entry.harness.clone(),
                    kind: ApprovalKind::Live,
                    status: ApprovalStatus::Pending,
                    subject: entry.subject.clone(),
                    session_id: entry.session_id.clone(),
                    runtime_id: Some(entry.runtime_id.clone()),
                    requested_at_ms: entry.requested_at_ms,
                    age_ms: now_ms.saturating_sub(entry.requested_at_ms).max(0),
                    options: entry.options.clone(),
                })
            })
            .collect()
    }
}

/// The answers supercode's own frontend accepts, mirroring
/// [`crate::frontend::FrontendApprovalDecision`]. Used for both a live
/// request on a joined supercode runtime and a queued subagent request.
const FRONTEND_DECISIONS: [&str; 3] = ["allow", "allow_for_session", "deny"];

/// The `behavior` values Claude Code's permission-handler protocol defines.
///
/// Its own validator names exactly these two: "Expected {behavior: 'allow',
/// updatedInput?: object} or {behavior: 'deny', message: string}" (claude
/// 2.1.258, recorded in
/// `docs/interop/research/orc2-claude-respond-receipt-2026-09-04.json`).
const CLAUDE_CODE_BEHAVIORS: [&str; 2] = ["allow", "deny"];

/// Row-id prefix every queued subagent record carries.
const SUBAGENT_ROW_PREFIX: &str = "supercode/subagent/";

/// supercode's own queued subagent approvals, as uniform rows.
///
/// The queue is append-only, so the index is a stable identity within the
/// process that owns it. A record whose outcome is still unknown is
/// `pending`; one the parent's own handler already answered carries that
/// answer, which is why this listing never has to guess (see
/// [`crate::subagents::QueuedApproval`]).
pub fn subagent_rows(queued: &[QueuedApproval], now_ms: i64) -> Vec<ApprovalRow> {
    queued
        .iter()
        .enumerate()
        .map(|(index, record)| {
            let status = match record.outcome {
                None => ApprovalStatus::Pending,
                Some(QueuedApprovalOutcome::Allowed) => ApprovalStatus::Allowed,
                Some(QueuedApprovalOutcome::Denied) => ApprovalStatus::Denied,
            };
            let subject = match record.subject.as_deref() {
                Some(subject) if !subject.is_empty() => {
                    format!("{} {}", record.tool, subject)
                }
                _ => record.tool.clone(),
            };
            ApprovalRow {
                id: format!(
                    "{SUBAGENT_ROW_PREFIX}{}/{}/{index}",
                    record.child_agent_id, record.queued_at_ms
                ),
                harness: HarnessId::from(HarnessId::SUPERCODE),
                kind: ApprovalKind::Live,
                status,
                subject: one_line(&subject),
                session_id: Some(record.child_agent_id.clone()),
                runtime_id: None,
                requested_at_ms: record.queued_at_ms,
                age_ms: now_ms.saturating_sub(record.queued_at_ms).max(0),
                options: if status == ApprovalStatus::Pending {
                    FRONTEND_DECISIONS
                        .into_iter()
                        .map(ApprovalOption::bare)
                        .collect()
                } else {
                    Vec::new()
                },
            }
        })
        .collect()
}

/// Whether supercode can list approvals for this harness id at all.
///
/// The uniform-verb contract: a harness whose runtime cannot carry a
/// protocol request is refused by name rather than answered with an empty
/// list. An unknown id is refused the same way.
pub fn lists_approvals(harness: &str) -> bool {
    crate::support::harness_support(harness)
        .is_some_and(|descriptor| descriptor.runtime.capabilities.respond_to_requests)
}

/// Every harness id `approvals.list` accepts, in registry order.
pub fn approval_harnesses() -> Vec<String> {
    crate::support::harness_support_registry()
        .harnesses
        .into_iter()
        .filter(|descriptor| descriptor.runtime.capabilities.respond_to_requests)
        .map(|descriptor| descriptor.id.as_str().to_string())
        .collect()
}

/// Wall-clock now in unix milliseconds.
pub fn now_ms() -> i64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|elapsed| elapsed.as_millis() as i64)
        .unwrap_or_default()
}