Merge pull request #25160 from dvdksn/sbx-kits-agent-settings

sbx: document overriding agent settings from a kit

_vale/config/vocabularies/Docker/accept.txt

@@ -295,6 +295,7 @@ Zsh
 [Ff]iletypes?
 [GgCc]oroutine
 [Hh]ealthcheck
+[Hh]eredoc
 [Hh]ostname
 [Ii]nfosec
 [Ii]nline

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

@@ -181,6 +181,33 @@ See the
 [FAQ](../faq.md#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)
 for details.
 
+## Override agent settings
+
+Sandboxes seed settings files for some built-in agents during setup.
+For example, the sandbox writes `/home/agent/.claude/settings.json`
+for the `claude` agent. This happens after the kit's static files and
+`initFiles`, so a kit can't override those paths with either mechanism.
+Use `commands.startup` instead, which runs after the sandbox seeds its
+files:
+
+```yaml
+commands:
+  startup:
+    - command:
+        - sh
+        - -c
+        - |
+          mkdir -p /home/agent/.claude
+          cat > /home/agent/.claude/settings.json <<'JSON'
+          {"permissions": {"allow": ["Bash(echo:*)"]}}
+          JSON
+      user: "1000"
+      description: Write user-scope claude settings
+```
+
+Startup commands replay on every sandbox start, so the script must be
+idempotent. The heredoc pattern overwrites cleanly each time.
+
 ## Fork an existing agent
 
 Agent kits (`kind: agent`) define a full agent from scratch. The most

content/manuals/ai/sandboxes/customize/kits.md

@@ -97,6 +97,17 @@ commands:
 
 See [`initFiles`](#initfiles) in the spec reference for all fields.
 
+Sandboxes seed settings files for some built-in agents during setup.
+For example, the sandbox writes `/home/agent/.claude/settings.json`
+for the `claude` agent. This happens after the kit's static files and
+`initFiles`, so kit-injected files at those paths get overwritten.
+Workspace files (such as `<workspace>/.claude/settings.local.json`)
+aren't affected, and you can ship them under `files/workspace/` as
+usual. To override a path the sandbox writes to, use a
+[`commands.startup`](#startup) script instead. See
+[Override agent settings](kit-examples.md#override-agent-settings) for
+an example.
+
 ### Set environment variables
 
 Environment variables set by the kit are available to the agent at