fix: explain sandbox escalation prompts accurately

.changeset/sandbox-escalation-prompt-copy.md

@@ -0,0 +1,6 @@
+---
+"@kilocode/cli": patch
+"kilo-code": patch
+---
+
+Explain sandbox escalation prompts accurately: approval runs the whole command outside the sandbox for that command only, and Bash allow rules and auto-approve never cover it.

packages/kilo-docs/pages/getting-started/settings/sandboxing.md

@@ -157,6 +157,26 @@ For HTTP, the proxy checks the requested DNS host and port. For HTTPS `CONNECT`,
 A configured destination is an egress route, not tenant, organization, repository, HTTP-origin, path, action, content, or data-loss-prevention isolation. The allowed service can receive, route, or store readable data and inherited credentials under its own policies. After an HTTPS tunnel passes the SNI check, Kilo cannot inspect encrypted requests, and the service may honor an alternate HTTP `Host` value within that connection. Allowing GitHub therefore grants the operations permitted by the active token, not access to only one organization or repository. HTTP and HTTPS are supported, including HTTPS Git remotes. SSH, arbitrary TCP, UDP, QUIC, SOCKS, CIDR ranges, and wildcard hosts remain blocked.
 {% /callout %}
 
+## Leaving the sandbox
+
+Some commands must write outside the sandbox boundary. Kilo then shows an escalation prompt and waits for an explicit approval before it runs the command.
+
+### Git and linked worktrees
+
+`.git` is always read-only inside the sandbox. A mutating git command, such as `git commit`, `git checkout`, or `git worktree add`, must write to `.git` metadata. In a linked worktree, the `.git` file points into the parent repository's `.git` directory. That directory is outside the worktree, so the write is outside the sandbox write boundary. Read-only git commands, such as `git status` or `git log`, do not trigger the prompt.
+
+| Detail | Behavior |
+|---|---|
+| Trigger | A mutating git command while the sandbox is on |
+| Scope | The whole command and its child processes run without filesystem or network restrictions |
+| Duration | One approval covers one command only |
+| Bash allow rules | Do not approve the escalation prompt |
+| Auto-approve | Does not approve the escalation prompt |
+
+Approving the prompt runs the entire shell command outside the sandbox. Filesystem writes and network access are unrestricted for that command and its child processes. The approval is one-shot and applies to that command only. Bash allow rules and auto-approve never cover the escalation prompt, so Kilo always asks for an explicit reply.
+
+GitHub access is a network question, not an escalation question. The GitHub CLI (`gh`) and HTTPS Git need `github.com:443` and `api.github.com:443` in `sandbox.allowed_hosts`. The escalation prompt does not grant network access by itself. See [Network restrictions](#network-restrictions).
+
 ## Session behavior
 
 The config setting supplies the initial default for new sessions that do not have a saved preference. Use the lock button in the VS Code prompt or `/sandbox` in the CLI to change the current session. Your latest choice is saved as the default for future sessions in that project, takes precedence over the config default, and persists across restarts.

packages/kilo-vscode/package.json

@@ -1112,7 +1112,7 @@
         "kilo-code.new.autoApprove.enabled": {
           "type": "boolean",
           "default": false,
-          "description": "Start Kilo Code with the main auto-approve toggle enabled. When enabled, permission prompts are approved automatically."
+          "description": "Start Kilo Code with the main auto-approve toggle enabled. When enabled, permission prompts are approved automatically. Sandbox escalation prompts are always excluded."
         },
         "kilo-code.new.maxCost": {
           "type": "number",

packages/kilo-vscode/src/commands/toggle-auto-approve.ts

@@ -63,7 +63,7 @@ export function registerToggleAutoApprove(
       return active
     }
 
-    vscode.window.showInformationMessage("Auto-approve enabled")
+    vscode.window.showInformationMessage("Auto-approve enabled. Sandbox escalation prompts are excluded.")
     // Drain any already-pending permission requests across all tracked directories
     const client = tryGetClient(connectionService)
     if (!client) return active

packages/kilo-vscode/tests/unit/auto-approve.test.ts

@@ -143,7 +143,7 @@ describe("registerToggleAutoApprove", () => {
     expect(ctrl.active()).toBe(true)
     expect(changes).toEqual([false, true])
     expect(env.updates).toEqual([{ key: "enabled", value: true, target: vscode.ConfigurationTarget.Workspace }])
-    expect(env.messages).toContain("Auto-approve enabled")
+    expect(env.messages).toContain("Auto-approve enabled. Sandbox escalation prompts are excluded.")
   })
 
   it("uses the SSE directory for worktree permissions before session mappings are available", async () => {

packages/kilo-vscode/webview-ui/src/components/chat/PermissionDock.tsx

@@ -352,6 +352,11 @@ export const PermissionDock: Component<{
                       </div>
                     )}
                   </Show>
+                  <Show when={sandboxEscalation()}>
+                    <div data-slot="permission-hint">
+                      {language.t("notification.permission.descriptionSandboxEscalation")}
+                    </div>
+                  </Show>
                   <Show when={command()}>
                     {(cmd) => <PermissionCommand command={cmd()} plain={props.request.args.heredoc === true} />}
                   </Show>

packages/kilo-vscode/webview-ui/src/i18n/de.ts

@@ -278,6 +278,8 @@ export const dict = {
   "notification.permission.titleSubagent": "Berechtigung erforderlich (Subagent)",
   "notification.permission.titleSkillShell": "Shell-Befehle aus dem Skill „{{skill}}“ ausführen?",
   "notification.permission.titleSandboxEscalation": "Git-Vorgang außerhalb der Sandbox zulassen?",
+  "notification.permission.descriptionSandboxEscalation":
+    "This runs the whole command with filesystem and network restrictions removed, for this command only. Git must write to .git, which is read-only in the sandbox and outside the worktree in a linked worktree. Bash allow rules and auto-approve never approve this prompt automatically.",
   "ui.permission.manageAutoApprove": "Regeln für automatische Genehmigung verwalten",
   "ui.permission.reject": "Ablehnen",
   "ui.permission.feedbackPlaceholder": "Teile Kilo mit, was es anders machen soll",

packages/kilo-vscode/webview-ui/src/i18n/en.ts

@@ -202,8 +202,10 @@ export const dict = {
   "prompt.action.indexing": "Indexing settings",
   "prompt.action.autoApprove.enable": "Enable auto-approve",
   "prompt.action.autoApprove.disable": "Disable auto-approve",
-  "prompt.action.autoApprove.enabled": "Auto-approve is enabled. Permission prompts will be approved automatically.",
-  "prompt.action.autoApprove.disabled": "Auto-approve is disabled. Click to approve permission prompts automatically.",
+  "prompt.action.autoApprove.enabled":
+    "Auto-approve is enabled. Permission prompts will be approved automatically. Sandbox escalation prompts are always excluded.",
+  "prompt.action.autoApprove.disabled":
+    "Auto-approve is disabled. Click to approve permission prompts automatically. Sandbox escalation prompts are always excluded.",
   "prompt.action.sandbox.enable": "Enable sandbox",
   "prompt.action.sandbox.disable": "Disable sandbox",
   "prompt.action.sandbox.enabled":
@@ -218,7 +220,8 @@ export const dict = {
   "prompt.action.sandbox.network.blocked": "Blocked",
   "prompt.action.sandbox.network.allowed": "Allowed",
   "prompt.action.sandbox.unrestricted": "Unrestricted",
-  "prompt.action.sandbox.description.enabled": "Writes are limited to the project and Kilo directories.",
+  "prompt.action.sandbox.description.enabled":
+    "Writes are limited to the project and Kilo directories. Permission rules and auto-approve apply inside the sandbox. Commands that must leave it always ask.",
   "prompt.action.sandbox.description.disabled": "Click to restrict filesystem writes and network access.",
   "prompt.action.sandbox.description.disabledNetworkAllowed":
     "Click to restrict filesystem writes. Network access remains allowed by your sandbox settings.",
@@ -264,7 +267,9 @@ export const dict = {
   "notification.permission.title": "Permission required",
   "notification.permission.titleSubagent": "Permission required (subagent)",
   "notification.permission.titleSkillShell": 'Run shell commands from skill "{{skill}}"?',
-  "notification.permission.titleSandboxEscalation": "Allow Git operation outside the sandbox?",
+  "notification.permission.titleSandboxEscalation": "Run outside the sandbox?",
+  "notification.permission.descriptionSandboxEscalation":
+    "This runs the whole command with filesystem and network restrictions removed, for this command only. Git must write to .git, which is read-only in the sandbox and outside the worktree in a linked worktree. Bash allow rules and auto-approve never approve this prompt automatically.",
   "ui.permission.manageAutoApprove": "Manage Auto-Approve Rules",
   "ui.permission.reject": "Reject",
   "ui.permission.feedbackPlaceholder": "Tell Kilo what to do differently",