From 41b27024bbfc4e42654845c9fc7058ef528dd461 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 25 Apr 2026 23:24:36 +0100 Subject: [PATCH] docs(gateway): clarify backend RPC pairing --- docs/gateway/protocol.md | 6 ++++-- docs/tools/subagents.md | 8 ++++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 6d0b4d10694..47a95f474db 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -577,11 +577,13 @@ rather than the pre-handshake defaults. trusted shared-secret helper flows. - Same-host tailnet or LAN connects are still treated as remote for pairing and require approval. -- All WS clients must include `device` identity during `connect` (operator + node). - Control UI can omit it only in these modes: +- WS clients normally include `device` identity during `connect` (operator + + node). The only device-less operator exceptions are explicit trust paths: - `gateway.controlUi.allowInsecureAuth=true` for localhost-only insecure HTTP compatibility. - successful `gateway.auth.mode: "trusted-proxy"` operator Control UI auth. - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, severe security downgrade). + - direct-loopback `gateway-client` backend RPCs authenticated with the shared + gateway token/password. - All connections must sign the server-provided `connect.challenge` nonce. ### Device auth migration diagnostics diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index 520871aeaa8..899be1c9df6 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -383,6 +383,14 @@ child session is marked `abortedLastRun: true`. Those restart-aborted child sessions remain recoverable through the sub-agent orphan recovery flow, which sends a synthetic resume message before clearing the aborted marker. +If a sub-agent spawn fails with Gateway `PAIRING_REQUIRED` / `scope-upgrade`, +check the RPC caller before editing pairing state. Internal `sessions_spawn` +coordination should connect as `client.id: "gateway-client"` with +`client.mode: "backend"` over direct loopback shared-token/password auth; that +path does not depend on the CLI's paired-device scope baseline. Remote callers, +explicit `deviceIdentity`, explicit device-token paths, and browser/node clients +still need normal device approval for scope upgrades. + ## Stopping - Sending `/stop` in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it, cascading to nested children.