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/components/chat/PromptInput.tsx

@@ -2160,11 +2160,9 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
             </Tooltip>
           </Show>
           <Tooltip
-            value={
-              autoApprove()
-                ? language.t("prompt.action.autoApprove.enabled")
-                : language.t("prompt.action.autoApprove.disabled")
-            }
+            value={`${language.t(
+              autoApprove() ? "prompt.action.autoApprove.enabled" : "prompt.action.autoApprove.disabled",
+            )} ${language.t("prompt.action.autoApprove.sandboxExcluded")}`}
             placement="top"
             openDelay={0}
           >

packages/kilo-vscode/webview-ui/src/components/shared/SandboxButton.tsx

@@ -54,6 +54,7 @@ export const SandboxTooltipContent: Component<{ enabled: boolean; network: boole
               ? "prompt.action.sandbox.description.disabled"
               : "prompt.action.sandbox.description.disabledNetworkAllowed",
         )}
+        {props.enabled ? ` ${language.t("prompt.action.sandbox.description.escalation")}` : ""}
       </div>
     </div>
   )

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

@@ -214,6 +214,7 @@ export const dict = {
     "Automatische Genehmigung ist aktiviert. Berechtigungsanfragen werden automatisch genehmigt.",
   "prompt.action.autoApprove.disabled":
     "Automatische Genehmigung ist deaktiviert. Klicken, um Berechtigungsanfragen automatisch zu genehmigen.",
+  "prompt.action.autoApprove.sandboxExcluded": "Sandbox-Eskalationsanfragen sind immer ausgeschlossen.",
   "prompt.action.enhanceDescription":
     "Die Schaltfläche 'Prompt verbessern' hilft, deine Anfrage durch zusätzlichen Kontext, Klarstellungen oder Umformulierungen zu verbessern. Versuche, hier eine Anfrage einzugeben und klicke erneut auf die Schaltfläche, um zu sehen, wie es funktioniert.",
   "prompt.action.sandbox.enable": "Sandbox aktivieren",
@@ -232,6 +233,8 @@ export const dict = {
   "prompt.action.sandbox.unrestricted": "Uneingeschränkt",
   "prompt.action.sandbox.description.enabled":
     "Schreibvorgänge sind auf die Projekt- und Kilo-Verzeichnisse beschränkt.",
+  "prompt.action.sandbox.description.escalation":
+    "Berechtigungsregeln und automatische Genehmigung gelten innerhalb der Sandbox. Befehle, die sie verlassen müssen, fragen immer.",
   "prompt.action.sandbox.description.disabled":
     "Klicken, um Schreibvorgänge im Dateisystem und den Netzwerkzugriff einzuschränken.",
   "prompt.action.sandbox.description.disabledNetworkAllowed":
@@ -277,7 +280,9 @@ export const dict = {
   "notification.permission.title": "Berechtigung erforderlich",
   "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.titleSandboxEscalation": "Außerhalb der Sandbox ausführen?",
+  "notification.permission.descriptionSandboxEscalation":
+    "Dies führt den gesamten Befehl mit entfernten Dateisystem- und Netzwerkeinschränkungen aus, nur für diesen Befehl. Git muss in .git schreiben, das in der Sandbox schreibgeschützt ist und bei einem verknüpften Worktree außerhalb des Worktrees liegt. Bash-Erlaubnisregeln und die automatische Genehmigung genehmigen diese Anfrage nie automatisch.",
   "ui.permission.manageAutoApprove": "Regeln für automatische Genehmigung verwalten",
   "ui.permission.reject": "Ablehnen",
   "ui.permission.feedbackPlaceholder": "Teile Kilo mit, was es anders machen soll",