Add the admin messages, approval ids as numbers, and two turn events

Implemented-By: OpenCode session (model recorded in docs/implementer-log.md)

crates/proto/src/lib.rs

@@ -17,6 +17,7 @@ pub use hash::{HashError, Sha256, sha256};
 pub use ids::{CallId, Epoch, Hash32, SessionId, Timestamp, ValueError};
 pub use log::{LogRecord, ToolCall, Usage};
 pub use wire::{
-    DenyReason, Envelope, ErrorCode, Message, PROTOCOL_VERSION, ToolRequest, ToolResponse, Turn,
-    TurnDone, TurnEvent, WireError,
+    ApprovalList, Approve, ApproveResult, DenyReason, Empty, Envelope, ErrorCode, GrantProblem,
+    GrantsReport, Message, PROTOCOL_VERSION, PendingApproval, Refuse, ToolRequest, ToolResponse,
+    Turn, TurnDone, TurnEvent, WireError,
 };

crates/proto/src/wire.rs

@@ -1,6 +1,6 @@
 use serde::{Deserialize, Serialize};
 
-use crate::{CallId, DataClass, SessionId, Timestamp, Usage};
+use crate::{CallId, DataClass, DecisionRecord, SessionId, Timestamp, Usage};
 
 pub const PROTOCOL_VERSION: u32 = 1;
 
@@ -27,6 +27,14 @@ pub enum Message {
     Turn(Turn),
     TurnEvent(TurnEvent),
     TurnDone(TurnDone),
+    Approvals(Empty),
+    ApprovalList(ApprovalList),
+    Approve(Approve),
+    ApproveResult(ApproveResult),
+    Refuse(Refuse),
+    Ok(Empty),
+    CheckGrants(Empty),
+    GrantsReport(GrantsReport),
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -49,6 +57,8 @@ pub enum ErrorCode {
     NoSuchSession,
     SessionExists,
     Inference,
+    Forbidden,
+    NoSuchApproval,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -64,7 +74,7 @@ pub struct ToolRequest {
 #[serde(tag = "status", deny_unknown_fields, rename_all = "snake_case")]
 pub enum ToolResponse {
     PendingApproval {
-        approval: String,
+        approval: u64,
         expires: Timestamp,
     },
     Result {
@@ -90,6 +100,10 @@ pub enum DenyReason {
     DeniedByGrant,
     ApprovalRefused,
     ApprovalExpired,
+    GrantsInvalid,
+    AuditUnavailable,
+    InvalidArguments,
+    StateUnreadable,
 }
 
 // JSON: {"kind":"turn","body":{"session":"…","content":"…","resume":false}}
@@ -142,6 +156,15 @@ pub enum TurnEvent {
         expected: u64,
         got: u64,
     },
+    ApprovalPending {
+        approval: u64,
+        tool: String,
+        expires: Timestamp,
+    },
+    ToolDenied {
+        name: String,
+        reason: DenyReason,
+    },
 }
 
 // JSON: {"kind":"turn_done","body":{"content":"…","usage":{…}}}
@@ -151,3 +174,61 @@ pub struct TurnDone {
     pub content: String,
     pub usage: Usage,
 }
+
+// The admin messages on admin.sock. JSON: {"kind":"approvals","body":{}}
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Empty {}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PendingApproval {
+    pub approval: u64,
+    pub session: SessionId,
+    pub call: CallId,
+    pub tool: String,
+    pub arguments: String,
+    pub grant: String,
+    pub taint: DataClass,
+    pub created: Timestamp,
+    pub expires: Timestamp,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ApprovalList {
+    pub items: Vec<PendingApproval>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Approve {
+    pub approval: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ApproveResult {
+    pub outcome: DecisionRecord,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Refuse {
+    pub approval: u64,
+    pub reason: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct GrantProblem {
+    pub file: String,
+    pub line: Option<u64>,
+    pub problem: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct GrantsReport {
+    pub problems: Vec<GrantProblem>,
+}

crates/proto/tests/admin_wire.rs

@@ -0,0 +1,257 @@
+//! Tests for the admin messages of `admin.sock` and the two new error codes, against byte-exact
+//! fixtures. Do not edit these or the fixtures.
+
+use proto::{
+    ApprovalList, Approve, ApproveResult, CallId, DataClass, DecisionRecord, DenyReason, Empty,
+    Envelope, ErrorCode, GrantProblem, GrantsReport, Message, PendingApproval, Refuse, SessionId,
+    Timestamp, WireError,
+};
+
+fn fixture(name: &str) -> String {
+    let path = format!("{}/tests/fixtures/wire/{name}", env!("CARGO_MANIFEST_DIR"));
+    let text = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("{path}: {e}"));
+    text.trim_end_matches('\n').to_string()
+}
+
+/// The fixture must decode to `want`, and `want` must encode to exactly the fixture's bytes.
+fn check(name: &str, id: u64, msg: Message) {
+    let want = Envelope {
+        v: 1,
+        id,
+        r#final: true,
+        msg,
+    };
+    let text = fixture(name);
+    let got: Envelope = serde_json::from_str(&text).unwrap_or_else(|e| panic!("{name}: {e}"));
+    assert_eq!(got, want, "{name}: decoded value");
+    assert_eq!(
+        serde_json::to_string(&want).unwrap(),
+        text,
+        "{name}: encoded bytes"
+    );
+}
+
+fn pending() -> PendingApproval {
+    PendingApproval {
+        approval: 41,
+        session: SessionId::new("chat-1789700000-42").unwrap(),
+        call: CallId(3),
+        tool: "shell".to_string(),
+        arguments: r#"{"command":"rm -rf /home/kyle/scratch/build","cwd":"/home/kyle/scratch"}"#
+            .to_string(),
+        grant: "shell-scratch".to_string(),
+        taint: DataClass::Private,
+        created: Timestamp::parse("2026-09-18T08:05:00.000Z").unwrap(),
+        expires: Timestamp::parse("2026-09-18T08:20:00.000Z").unwrap(),
+    }
+}
+
+#[test]
+fn the_three_requests_with_an_empty_body() {
+    check("approvals.json", 5, Message::Approvals(Empty {}));
+    check("check_grants.json", 8, Message::CheckGrants(Empty {}));
+    check("ok.json", 7, Message::Ok(Empty {}));
+}
+
+#[test]
+fn approval_list() {
+    let list = ApprovalList {
+        items: vec![pending()],
+    };
+    check("approval_list.json", 5, Message::ApprovalList(list));
+    let empty = ApprovalList { items: Vec::new() };
+    check("approval_list_empty.json", 5, Message::ApprovalList(empty));
+}
+
+#[test]
+fn approve_and_its_result() {
+    check(
+        "approve.json",
+        6,
+        Message::Approve(Approve { approval: 41 }),
+    );
+    check(
+        "approve_result_allowed.json",
+        6,
+        Message::ApproveResult(ApproveResult {
+            outcome: DecisionRecord::Allowed {},
+        }),
+    );
+    check(
+        "approve_result_denied.json",
+        6,
+        Message::ApproveResult(ApproveResult {
+            outcome: DecisionRecord::Denied {
+                reason: DenyReason::NoGrant,
+            },
+        }),
+    );
+}
+
+#[test]
+fn refuse_with_and_without_a_reason() {
+    check(
+        "refuse.json",
+        7,
+        Message::Refuse(Refuse {
+            approval: 41,
+            reason: Some("not while I am away".to_string()),
+        }),
+    );
+    check(
+        "refuse_no_reason.json",
+        7,
+        Message::Refuse(Refuse {
+            approval: 41,
+            reason: None,
+        }),
+    );
+}
+
+#[test]
+fn grants_report() {
+    let report = GrantsReport {
+        problems: vec![
+            GrantProblem {
+                file: "notes-read.toml".to_string(),
+                line: Some(3),
+                problem: "unknown field `mdoe`".to_string(),
+            },
+            GrantProblem {
+                file: "Bad_Name.toml".to_string(),
+                line: None,
+                problem: "the file name is not a valid grant id".to_string(),
+            },
+        ],
+    };
+    check("grants_report.json", 8, Message::GrantsReport(report));
+    let ok = GrantsReport {
+        problems: Vec::new(),
+    };
+    check("grants_report_ok.json", 8, Message::GrantsReport(ok));
+}
+
+#[test]
+fn the_two_new_error_codes() {
+    check(
+        "error_forbidden.json",
+        9,
+        Message::Error(WireError {
+            code: ErrorCode::Forbidden,
+            detail: "approve is not accepted on broker.sock".to_string(),
+        }),
+    );
+    check(
+        "error_no_such_approval.json",
+        6,
+        Message::Error(WireError {
+            code: ErrorCode::NoSuchApproval,
+            detail: "41".to_string(),
+        }),
+    );
+}
+
+/// An empty body is an object with no keys: not `null`, not a missing body, not an object with a
+/// key in it.
+#[test]
+fn an_empty_body_must_be_an_empty_object() {
+    let good = fixture("approvals.json");
+    assert!(serde_json::from_str::<Envelope>(&good).is_ok());
+    let bad = [
+        good.replacen("\"body\":{}", "\"body\":null", 1),
+        good.replacen(",\"body\":{}", "", 1),
+        good.replacen("\"body\":{}", "\"body\":{\"all\":true}", 1),
+    ];
+    for text in bad {
+        assert_ne!(text, good);
+        assert!(
+            serde_json::from_str::<Envelope>(&text).is_err(),
+            "accepted {text}"
+        );
+    }
+}
+
+/// `reason` and `line` may be null but may not be left out: every field is always written, so a
+/// reader never has to guess what a missing one means.
+#[test]
+fn optional_fields_are_null_not_absent() {
+    let refuse = fixture("refuse_no_reason.json");
+    let cut = refuse.replacen(",\"reason\":null", "", 1);
+    assert_ne!(cut, refuse);
+    assert!(
+        serde_json::from_str::<Envelope>(&cut).is_ok(),
+        "serde reads a missing Option as None; this documents it"
+    );
+    assert!(
+        serde_json::to_string(&Refuse {
+            approval: 1,
+            reason: None
+        })
+        .unwrap()
+        .contains("\"reason\":null")
+    );
+    assert!(
+        serde_json::to_string(&GrantProblem {
+            file: "a.toml".to_string(),
+            line: None,
+            problem: "x".to_string()
+        })
+        .unwrap()
+        .contains("\"line\":null")
+    );
+}
+
+/// An outcome is strict too. serde does not apply `deny_unknown_fields` to unit variants such as
+/// `allowed`, so `DecisionRecord` must not rely on the derive for it.
+#[test]
+fn an_outcome_rejects_unknown_and_misplaced_fields() {
+    for good in [
+        r#"{"outcome":"allowed"}"#,
+        r#"{"outcome":"ask"}"#,
+        r#"{"outcome":"denied","reason":"no_grant"}"#,
+    ] {
+        let value: DecisionRecord = serde_json::from_str(good).unwrap();
+        assert_eq!(serde_json::to_string(&value).unwrap(), good);
+    }
+    for bad in [
+        r#"{"outcome":"allowed","zz":1}"#,
+        r#"{"outcome":"ask","zz":1}"#,
+        r#"{"outcome":"denied","reason":"no_grant","zz":1}"#,
+        r#"{"outcome":"allowed","reason":"no_grant"}"#,
+        r#"{"outcome":"ask","reason":null,"zz":1}"#,
+        r#"{"outcome":"allowed","reason":null}"#,
+        r#"{"outcome":"denied"}"#,
+        r#"{"outcome":"approved"}"#,
+        r#"{"reason":"no_grant"}"#,
+    ] {
+        assert!(
+            serde_json::from_str::<DecisionRecord>(bad).is_err(),
+            "accepted {bad}"
+        );
+    }
+}
+
+#[test]
+fn pending_approvals_reject_bad_values() {
+    let good = fixture("approval_list.json");
+    assert!(serde_json::from_str::<Envelope>(&good).is_ok());
+    let bad = [
+        // an approval id is a number
+        good.replacen("\"approval\":41", "\"approval\":\"41\"", 1),
+        // the session id is validated
+        good.replacen("chat-1789700000-42", "../etc", 1),
+        // the taint is one of the three classes
+        good.replacen("\"taint\":\"private\"", "\"taint\":\"internal\"", 1),
+        // a field is missing
+        good.replacen("\"grant\":\"shell-scratch\",", "", 1),
+        // a field nobody defined
+        good.replacen("\"grant\":", "\"note\":1,\"grant\":", 1),
+    ];
+    for text in bad {
+        assert_ne!(text, good);
+        assert!(
+            serde_json::from_str::<Envelope>(&text).is_err(),
+            "accepted {text}"
+        );
+    }
+}

crates/proto/tests/fixtures/wire/approval_list.json

@@ -0,0 +1 @@
+{"v":1,"id":5,"final":true,"msg":{"kind":"approval_list","body":{"items":[{"approval":41,"session":"chat-1789700000-42","call":3,"tool":"shell","arguments":"{\"command\":\"rm -rf /home/kyle/scratch/build\",\"cwd\":\"/home/kyle/scratch\"}","grant":"shell-scratch","taint":"private","created":"2026-09-18T08:05:00.000Z","expires":"2026-09-18T08:20:00.000Z"}]}}}

crates/proto/tests/fixtures/wire/approval_list_empty.json

@@ -0,0 +1 @@
+{"v":1,"id":5,"final":true,"msg":{"kind":"approval_list","body":{"items":[]}}}

crates/proto/tests/fixtures/wire/approvals.json

@@ -0,0 +1 @@
+{"v":1,"id":5,"final":true,"msg":{"kind":"approvals","body":{}}}

crates/proto/tests/fixtures/wire/approve.json

@@ -0,0 +1 @@
+{"v":1,"id":6,"final":true,"msg":{"kind":"approve","body":{"approval":41}}}

crates/proto/tests/fixtures/wire/approve_result_allowed.json

@@ -0,0 +1 @@
+{"v":1,"id":6,"final":true,"msg":{"kind":"approve_result","body":{"outcome":{"outcome":"allowed"}}}}

crates/proto/tests/fixtures/wire/approve_result_denied.json

@@ -0,0 +1 @@
+{"v":1,"id":6,"final":true,"msg":{"kind":"approve_result","body":{"outcome":{"outcome":"denied","reason":"no_grant"}}}}

crates/proto/tests/fixtures/wire/check_grants.json

@@ -0,0 +1 @@
+{"v":1,"id":8,"final":true,"msg":{"kind":"check_grants","body":{}}}

crates/proto/tests/fixtures/wire/error_forbidden.json

@@ -0,0 +1 @@
+{"v":1,"id":9,"final":true,"msg":{"kind":"error","body":{"code":"forbidden","detail":"approve is not accepted on broker.sock"}}}

crates/proto/tests/fixtures/wire/error_no_such_approval.json

@@ -0,0 +1 @@
+{"v":1,"id":6,"final":true,"msg":{"kind":"error","body":{"code":"no_such_approval","detail":"41"}}}

crates/proto/tests/fixtures/wire/grants_report.json

@@ -0,0 +1 @@
+{"v":1,"id":8,"final":true,"msg":{"kind":"grants_report","body":{"problems":[{"file":"notes-read.toml","line":3,"problem":"unknown field `mdoe`"},{"file":"Bad_Name.toml","line":null,"problem":"the file name is not a valid grant id"}]}}}

crates/proto/tests/fixtures/wire/grants_report_ok.json

@@ -0,0 +1 @@
+{"v":1,"id":8,"final":true,"msg":{"kind":"grants_report","body":{"problems":[]}}}

crates/proto/tests/fixtures/wire/ok.json

@@ -0,0 +1 @@
+{"v":1,"id":7,"final":true,"msg":{"kind":"ok","body":{}}}

crates/proto/tests/fixtures/wire/refuse.json

@@ -0,0 +1 @@
+{"v":1,"id":7,"final":true,"msg":{"kind":"refuse","body":{"approval":41,"reason":"not while I am away"}}}

crates/proto/tests/fixtures/wire/refuse_no_reason.json

@@ -0,0 +1 @@
+{"v":1,"id":7,"final":true,"msg":{"kind":"refuse","body":{"approval":41,"reason":null}}}

crates/proto/tests/fixtures/wire/tool_response_pending.json

@@ -1 +1 @@
-{"v":1,"id":7,"final":false,"msg":{"kind":"tool_response","body":{"status":"pending_approval","approval":"ap-0001","expires":"2026-09-17T08:35:00.000Z"}}}
+{"v":1,"id":7,"final":false,"msg":{"kind":"tool_response","body":{"status":"pending_approval","approval":41,"expires":"2026-09-17T08:35:00.000Z"}}}

crates/proto/tests/fixtures/wire/turn_event_approval_pending.json

@@ -0,0 +1 @@
+{"v":1,"id":3,"final":false,"msg":{"kind":"turn_event","body":{"event":"approval_pending","approval":41,"tool":"shell","expires":"2026-09-18T08:20:00.000Z"}}}

crates/proto/tests/fixtures/wire/turn_event_tool_denied.json

@@ -0,0 +1 @@
+{"v":1,"id":3,"final":false,"msg":{"kind":"turn_event","body":{"event":"tool_denied","name":"read_file","reason":"no_grant"}}}

crates/proto/tests/strict.rs

@@ -75,9 +75,31 @@ fn envelopes_reject_unknown_keys_at_every_depth() {
         "turn_event_retrying.json",
         "turn_done.json",
         "error_session_full.json",
+        "approvals.json",
+        "approval_list.json",
+        "approval_list_empty.json",
+        "approve.json",
+        "approve_result_allowed.json",
+        "approve_result_denied.json",
+        "refuse.json",
+        "refuse_no_reason.json",
+        "ok.json",
+        "check_grants.json",
+        "grants_report.json",
+        "grants_report_ok.json",
+        "error_forbidden.json",
+        "error_no_such_approval.json",
+        "turn_event_approval_pending.json",
+        "turn_event_tool_denied.json",
     ] {
-        // Envelope, msg and body: three objects; turn_done also has a usage object.
-        let want = if name == "turn_done.json" { 4 } else { 3 };
+        // Envelope, msg and body: three objects. Some bodies hold more: turn_done a usage
+        // object, approval_list one item, approve_result an outcome, grants_report two problems.
+        let want = match name {
+            "turn_done.json" | "approval_list.json" => 4,
+            "approve_result_allowed.json" | "approve_result_denied.json" => 4,
+            "grants_report.json" => 5,
+            _ => 3,
+        };
         assert_eq!(
             check::<Envelope>(name, &fixture(&format!("wire/{name}"))),
             want,

crates/proto/tests/turn_wire.rs

@@ -1,8 +1,8 @@
 //! Tests for the channel messages and the usage record, against byte-exact fixtures. Do not edit.
 
 use proto::{
-    CallId, DataClass, Envelope, Epoch, ErrorCode, Hash32, LogRecord, Message, SessionId,
-    Timestamp, ToolCall, Turn, TurnDone, TurnEvent, Usage, WireError,
+    CallId, DataClass, DenyReason, Envelope, Epoch, ErrorCode, Hash32, LogRecord, Message,
+    SessionId, Timestamp, ToolCall, Turn, TurnDone, TurnEvent, Usage, WireError,
 };
 
 fn fixture(kind: &str, name: &str) -> String {
@@ -92,6 +92,29 @@ fn turn_events() {
             }),
         ),
     );
+    check(
+        "turn_event_approval_pending.json",
+        env(
+            3,
+            false,
+            Message::TurnEvent(TurnEvent::ApprovalPending {
+                approval: 41,
+                tool: "shell".to_string(),
+                expires: Timestamp::parse("2026-09-18T08:20:00.000Z").unwrap(),
+            }),
+        ),
+    );
+    check(
+        "turn_event_tool_denied.json",
+        env(
+            3,
+            false,
+            Message::TurnEvent(TurnEvent::ToolDenied {
+                name: "read_file".to_string(),
+                reason: DenyReason::NoGrant,
+            }),
+        ),
+    );
 }
 
 #[test]
@@ -165,6 +188,15 @@ fn every_turn_event_kind_round_trips() {
             expected: 500,
             got: 20,
         },
+        TurnEvent::ApprovalPending {
+            approval: u64::MAX,
+            tool: "http_fetch".to_string(),
+            expires: Timestamp::parse("2026-09-18T08:20:00.000Z").unwrap(),
+        },
+        TurnEvent::ToolDenied {
+            name: "shell".to_string(),
+            reason: DenyReason::StateUnreadable,
+        },
     ];
     for event in all {
         let text = serde_json::to_string(&event).unwrap();

crates/proto/tests/wire.rs

@@ -54,12 +54,23 @@ fn tool_request() {
 #[test]
 fn tool_response_pending() {
     let body = ToolResponse::PendingApproval {
-        approval: "ap-0001".to_string(),
+        approval: 41,
         expires: Timestamp::parse("2026-09-17T08:35:00.000Z").unwrap(),
     };
     check("tool_response_pending.json", response(7, false, body));
 }
 
+#[test]
+fn an_approval_id_is_a_number_not_a_string() {
+    let good = fixture("tool_response_pending.json");
+    let bad = good.replacen("\"approval\":41", "\"approval\":\"41\"", 1);
+    assert_ne!(good, bad);
+    assert!(serde_json::from_str::<Envelope>(&good).is_ok());
+    assert!(serde_json::from_str::<Envelope>(&bad).is_err());
+    let negative = good.replacen("\"approval\":41", "\"approval\":-1", 1);
+    assert!(serde_json::from_str::<Envelope>(&negative).is_err());
+}
+
 #[test]
 fn tool_response_result() {
     let body = ToolResponse::Result {
@@ -113,6 +124,10 @@ fn deny_reasons_and_error_codes_are_snake_case() {
         (DenyReason::DeniedByGrant, "denied_by_grant"),
         (DenyReason::ApprovalRefused, "approval_refused"),
         (DenyReason::ApprovalExpired, "approval_expired"),
+        (DenyReason::GrantsInvalid, "grants_invalid"),
+        (DenyReason::AuditUnavailable, "audit_unavailable"),
+        (DenyReason::InvalidArguments, "invalid_arguments"),
+        (DenyReason::StateUnreadable, "state_unreadable"),
     ];
     for (value, text) in reasons {
         assert_eq!(
@@ -125,6 +140,8 @@ fn deny_reasons_and_error_codes_are_snake_case() {
         (ErrorCode::BadVersion, "bad_version"),
         (ErrorCode::BadMessage, "bad_message"),
         (ErrorCode::Internal, "internal"),
+        (ErrorCode::Forbidden, "forbidden"),
+        (ErrorCode::NoSuchApproval, "no_such_approval"),
     ];
     for (value, text) in codes {
         assert_eq!(