Merge pull request #25810 from dvdksn/fix/issue-434-credential-binding

docs: warn about extended-agent OAuth

Author: dvdksn

content/manuals/ai/sandboxes/customize/kit-examples.md

@@ -364,6 +364,26 @@ the child kit's name:
 $ sbx run claude-sonnet --kit ./claude-sonnet
 ```
 
+Proxy-managed OAuth isn't supported for a third-party kit that extends the
+built-in `claude` agent. Store an Anthropic API key on the host before the first
+launch:
+
+```console
+$ sbx secret set anthropic
+```
+
+When you launch the kit for the first time, `sbx` prompts you to approve its
+inherited Anthropic credentials. Because this is a third-party schema v2 kit,
+`sbx` records your approval as a
+[credential binding](../security/credentials.md#credential-bindings). The
+sandbox receives a sentinel value, and the proxy injects the real API key into
+requests to the domains declared by the kit.
+
+> [!WARNING]
+> The approval prompt also lists OAuth, but OAuth doesn't work for the extended
+> agent. If you use Claude Code's `/login` command, Claude Code stores the real
+> OAuth tokens inside the sandbox.
+
 OpenCode supports an additional config file through `OPENCODE_CONFIG`. Keep the
 kit's config separate from the sandbox-managed
 `/home/agent/.config/opencode/opencode.json`, for example at
@@ -431,7 +451,9 @@ sandbox:
 
 The child inherits the built-in image, credentials, network permissions,
 persistent volumes, settings, MCP integration, and agent instructions. Its
-`sandbox.entrypoint` replaces the inherited entrypoint.
+`sandbox.entrypoint` replaces the inherited entrypoint. Proxy-managed OAuth
+isn't supported for the extended agent, so follow the
+[Anthropic API-key setup](#customize-agent-settings) before launching it.
 
 Launch with the kit's `name:` as the agent argument to `sbx run`:
 

content/manuals/ai/sandboxes/security/credentials.md

@@ -317,6 +317,7 @@ bindings:
 
 A binding is only an approval record: the presence of `apiKey` or `oauth`
 authorizes that mechanism. Declining a credential writes no entry at all.
+The real credential isn't stored in this file.
 
 ### First-run approval
 
@@ -340,10 +341,19 @@ constrain which requests can carry the credential.
 
 Only third-party kits that declare `schemaVersion: "2"` require a binding.
 Built-in agents also use `schemaVersion: "2"`, but credentials declared only by
-embedded kits are authorized by provenance and inject automatically. If a
-third-party kit also declares the same service, that service requires approval.
-Kits on `schemaVersion: "1"` inject their declared credentials without a
-binding.
+embedded kits are authorized by provenance and inject automatically. A
+third-party kit that extends a built-in agent inherits its credentials, but not
+its built-in provenance. The inherited credentials therefore require approval.
+If a third-party kit declares the same service itself, that service also
+requires approval. Kits on `schemaVersion: "1"` inject their declared
+credentials without a binding.
+
+> [!WARNING]
+> Proxy-managed OAuth isn't supported for third-party sandbox agents, including
+> kits that extend a built-in agent. Repeating the parent's OAuth declaration in
+> the child kit doesn't activate OAuth interception. Use a stored API key when
+> the service supports one. Otherwise, an OAuth login performed inside the
+> sandbox stores the real token there.
 
 ## Registry credentials