docs(cli): permissions and profiles

src/content/docs/cli/permissions-and-profiles.mdx

@@ -1,35 +1,92 @@
 ---
-title: "Permissions and profiles in the {{WARP_CLI}}"
+title: "Permissions and profiles in the Warp Agent CLI"
 description: >-
-  Control what the agent can do in the {{WARP_CLI}}: permission requests,
-  auto-approve, fast-forward mode, and execution profiles.
+  Control what the agent can do in the Warp Agent CLI: permission request
+  cards, auto-approve, and execution profiles in the settings file.
 ---
 import { VARS } from '@data/vars';
 
-{/* TODO(cli-permissions): draft per drafts/warp-cli-launch-plan.md — "cli/permissions-and-profiles.mdx" section. Feature-doc content type. */}
-
-The {VARS.WARP_CLI} documentation for this page is in progress.
+The {VARS.WARP_CLI} uses the same permission model as the Warp app: the agent acts on its own when it's confident an action is safe, and asks for your approval when it isn't. This page covers how permission requests appear in the CLI and how to tune the agent's autonomy with auto-approve and execution profiles. For the full permission model, including autonomy levels and organization-wide controls, see [Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/).
 
 ## How permissions work
 
-{/* TODO(cli-permissions): permission model summary; default behavior; cross-link agent-platform/capabilities/agent-profiles-permissions. */}
+Every action the agent proposes, such as running a shell command, editing files, or calling an MCP tool, is checked against your active execution profile before it runs. By default, the CLI behaves as follows:
+
+* **Shell commands** - The agent decides. It runs commands it judges safe, such as read-only commands and commands on your allowlist, and asks before anything else.
+* **File edits** - The agent shows a diff and asks for approval before applying edits.
+* **Reading files** - The agent decides, reading files without prompting in most cases.
+* **Denylisted commands** - Commands matching your command denylist (for example `rm`, `curl`, or `ssh`) always require approval. The denylist takes precedence over every other setting, including auto-approve.
+
+You can change these defaults by [editing your execution profile](#execution-profiles).
 
 ## Approving agent actions
 
-{/* TODO(cli-permissions): permission request cards, command edit/escape behavior, diff approval. */}
+When an action needs your approval, the agent pauses and shows a permission card with the proposed command or file edits. Beyond approving or rejecting it, you can:
+
+* Select **Other** to reply with guidance instead of running the action; the agent adjusts its approach based on what you type.
+* Press `E` on a command card to edit the proposed command; approving then runs your edited version. While editing, `Esc` exits the editor without rejecting the request.
+* Press `E` on a file-edits card to expand or collapse all diffs.
 
 ## Auto-approve
 
-{/* TODO(cli-permissions): /auto-approve toggle and when to use it. */}
+Auto-approve gives the agent full autonomy for the current conversation: proposed actions run immediately, without permission cards, until the task finishes or you turn it off. Toggle it with `/auto-approve` or `Ctrl+Shift+I`.
 
-## Fast-forward mode
+Auto-approve applies per conversation, and new conversations start with it off. To see its state at a glance, add the **Auto-approve indicator** to the statusline with `/statusline`. If your profile sets `ask_user_question = "ask_except_in_auto_approve"`, the agent also skips clarifying questions while auto-approve is on.
 
-{/* TODO(cli-permissions): fast-forward mode and /fast-forward toggle. */}
+:::caution
+With auto-approve on, the agent executes commands and applies file edits without review. Commands matching your command denylist still require approval, but everything else runs immediately. Press `Ctrl+C` to stop the agent if it starts doing something you didn't intend.
+:::
 
 ## Execution profiles
 
-{/* TODO(cli-permissions): settings-file-based execution profiles and defaults. */}
+The CLI reads its permissions from execution profiles stored in its [settings file](/cli/configuration/). Profiles live under the `agents.execution_profiles` table, and the CLI always runs with the profile under the reserved `default` key:
+
+```toml title="settings.toml"
+[agents.execution_profiles.default]
+name = "Default"
+execute_commands = "agent_decides"
+apply_code_diffs = "agent_decides"
+read_files = "agent_decides"
+command_allowlist = ['cargo (build|check|test)(\s.*)?']
+```
+
+:::caution
+Setting `command_denylist` replaces the built-in default denylist, which covers `rm`, `curl`, `wget`, `eval`, `ssh`, shells, and other risky command patterns. Omitting the field keeps the defaults. To deny additional commands, extend the generated list in your settings file rather than writing a short list from scratch.
+:::
+
+Edit the file directly, or ask the agent to change its own permissions and it will update the settings file for you. The CLI picks up saved changes automatically.
+
+Profiles in the {VARS.WARP_CLI} are local to your machine: they never sync to the cloud, and they are separate from the Agent Profiles you configure in the Warp app. You can define additional profiles in the file, but the CLI currently always runs with `default`.
+
+### Permission values
+
+Most permission fields accept one of three values:
+
+* **`agent_decides`** - The agent acts on its own when it's confident and asks when it's uncertain.
+* **`always_ask`** - Every action of this type requires approval.
+* **`always_allow`** - Actions of this type run without prompting.
+
+### Profile fields
+
+* **`execute_commands`** - Permission to run shell commands.
+* **`apply_code_diffs`** - Permission to apply file edits.
+* **`read_files`** - Permission to read files.
+* **`mcp_permissions`** - Permission to call MCP servers.
+* **`write_to_pty`** - Permission to type into running interactive commands. Also accepts `ask_on_first_write`.
+* **`ask_user_question`** - Whether the agent may pause to ask clarifying questions: `always_ask`, `ask_except_in_auto_approve`, or `never`.
+* **`run_agents`** - Permission to launch child agents: `always_ask`, `always_allow`, or `never_allow`.
+* **`command_allowlist`** - Regular expressions for commands that run without approval.
+* **`command_denylist`** - Regular expressions for commands that always require approval, regardless of other settings.
+* **`directory_allowlist`** - Directories the agent may read without approval.
+
+Profiles also hold model overrides such as `base_model`, covered in [Models and usage in the {VARS.WARP_CLI}](/cli/models-and-usage/).
+
+:::note
+The profile collection is validated as a whole. If any profile contains an invalid value, the CLI keeps the last valid configuration while it's running and falls back to the built-in default profile on the next launch, until the file is fixed.
+:::
 
-## Unattended use
+## Related pages
 
-{/* TODO(cli-permissions): flags for skipping permissions — confirm shipped before merge; include safety caution. */}
+* [Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) - The full permission model, autonomy levels, and allowlist/denylist behavior.
+* [Configuring the {VARS.WARP_CLI}](/cli/configuration/) - The settings file, themes, statusline, and keybindings.
+* [Agent conversations in the {VARS.WARP_CLI}](/cli/agent-conversations/) - How tool calls, diffs, and agent questions render in the transcript.