docs(cli): permissions and profiles - #404
Conversation
Replace the cli/permissions-and-profiles.mdx stub with full content: permission request cards (yes/no/Other), command editing with E and Esc behavior, inline diff approval, /auto-approve (slash command, Ctrl+Shift+I, progress-row control, statusline indicator), and settings-file execution profiles under agents.execution_profiles with the CLI's agent_decides default for shell commands. Dropped from the outline after verifying against warp master: /fast-forward and fast-forward mode (no such slash command or TUI surface) and --dangerously-skip-permissions (flag does not exist on the warp binary). Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR replaces the CLI permissions stub with a full page covering permission cards, auto-approve, and settings-file execution profiles. The overall structure is appropriate, and no approved spec context was available to compare against.
Concerns
- The execution profile TOML example can weaken command-approval protections if copied because it replaces the built-in command denylist with only two entries.
Security
- The sample
command_denylistshould not imply thatrmandcurlare sufficient denylist coverage; users need to preserve or intentionally extend the default denylist.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| apply_code_diffs = "agent_decides" | ||
| read_files = "agent_decides" | ||
| command_allowlist = ['cargo (build|check|test)(\s.*)?'] | ||
| command_denylist = ['rm(\s.*)?', 'curl(\s.*)?'] |
There was a problem hiding this comment.
rm and curl if copied into settings.toml, dropping default prompts for shells, ssh, wget, and other risky commands. Omit this field from the minimal example or explicitly tell readers to preserve/extend the generated default denylist.
There was a problem hiding this comment.
Fixed in 1557266. Removed command_denylist from the minimal example and added a caution: omitting the field keeps the built-in default denylist, while setting it replaces the defaults entirely (verified against the settings deserialization on master: omitted fields fall back to the built-in profile defaults, and a set list is used as-is with no merging), so readers are told to extend the generated list in settings.toml instead of writing a short list from scratch.
The vars transform does not apply to frontmatter parsed by Astro's content
layer, so {{WARP_CLI}} tokens rendered literally in built titles. Replace
them with the literal product name; body prose keeps {VARS.WARP_CLI}.
Co-Authored-By: Oz <oz-agent@warp.dev>
…cli-cli-permissions
Update the literal product name in the title and description to the confirmed launch name. Body prose renders the new name via the merged WARP_CLI var value. Co-Authored-By: Oz <oz-agent@warp.dev>
Remove command_denylist from the minimal execution-profile example: a copied short list would replace the built-in default denylist and drop prompts for other risky commands. Add a caution explaining that omitting the field keeps the defaults and setting it replaces them, so users should extend the generated list instead. Addresses PR #404 review comment 3669356200. Co-Authored-By: Oz <oz-agent@warp.dev>
Use "the CLI" after the intro's first full product-name mention, keeping the full name where the contrast with the Warp app matters and in page title link text. Fold two trailing "See [X]." sentences into their preceding sentences. Co-Authored-By: Oz <oz-agent@warp.dev>
Cut self-evident selector mechanics (Enter to confirm, Esc to reject), output-streaming and diff-header narration, and the slash-menu state sentence. Keep the non-obvious behaviors: Other for replacement guidance, E to edit commands and toggle diffs, the Esc-while-editing gotcha, and all defaults and cautions. Co-Authored-By: Oz <oz-agent@warp.dev>
|
|
||
| When the agent asks "Is it OK if I make these file edits?", the card shows the proposed diffs inline, with one section per file: | ||
|
|
||
| * Each file header shows the change type, the file name, and added/removed line counts. Multi-file edits are grouped under a summary header, and all diffs start expanded while the request is pending. |
There was a problem hiding this comment.
this does not feel necessary to include to an end user
There was a problem hiding this comment.
Fixed in d6bd6e1. Deleted the progress-row control bullet and folded the remaining toggles into one sentence (/auto-approve or Ctrl+Shift+I).
| ## Approving agent actions | ||
|
|
||
| {/* TODO(cli-permissions): permission request cards, command edit/escape behavior, diff approval. */} | ||
| When an action needs your approval, the CLI pauses the conversation and shows a permission card in the transcript: what the agent wants to do, the details (the exact command, the file diffs, or the tool call), and a **yes**/**no** selector. Select **Other** to type a reply instead; the agent receives your guidance in place of the proposed action, which is useful when you want it to take a different approach. |
There was a problem hiding this comment.
this feels like too much to explain to a user, you're basically just describing the UI in plain words at this point
There was a problem hiding this comment.
Fixed in d6bd6e1. Cut the card-anatomy walkthrough; the section now leads with one sentence and lists only the non-obvious actions (Other, E shortcuts, Esc-while-editing).
| {/* TODO(cli-permissions): permission request cards, command edit/escape behavior, diff approval. */} | ||
| When an action needs your approval, the CLI pauses the conversation and shows a permission card in the transcript: what the agent wants to do, the details (the exact command, the file diffs, or the tool call), and a **yes**/**no** selector. Select **Other** to type a reply instead; the agent receives your guidance in place of the proposed action, which is useful when you want it to take a different approach. | ||
|
|
||
| ### Reviewing commands |
There was a problem hiding this comment.
this also feels like describing UI rather than anything novel to the user, can we simplify or combine with another section?
There was a problem hiding this comment.
Fixed in d6bd6e1. Merged Reviewing commands (and Reviewing file edits) into Approving agent actions; each is now a single bullet keeping only the E shortcut and the Esc-while-editing gotcha. No other pages linked to the removed anchors.
Merge the Reviewing commands and Reviewing file edits subsections into Approving agent actions, keeping only the non-obvious behaviors (Other as replacement guidance, E shortcuts, Esc-while-editing). Drop the card anatomy description, the quoted card questions, and the progress-row auto-approve control bullet; fold the remaining toggles into a sentence. Addresses PR #404 comments 3678712189, 3678714624, 3678709662. Co-Authored-By: Oz <oz-agent@warp.dev>
harryalbert
left a comment
harryalbert
left a comment
There was a problem hiding this comment.
nice! Just had a few additions for functionality that was merged recently (last night lol)
| {/* 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/). |
There was a problem hiding this comment.
I feel like this isn't quite the right summary of our permissions model, and makes it sound more unsafe than it is. Like you can set the permissions to agent_decides so that the agent will decide on how safe an action is, but you could also require every single action to get approval or make it so no actions need approval
There was a problem hiding this comment.
Fixed in fe8e58d. Reframed the intro and "How permissions work" around per-action-type configuration rather than implying the agent always self-judges safety: each action type is set independently to always_ask, always_allow, or agent_decides, and the section now explicitly calls out that you can set everything to always_ask to review every action or always_allow for an agent that never stops to ask. The CLI-specific defaults (agent_decides for commands/edits/reads/MCP, always_ask for write_to_pty and run_agents, verified against AIExecutionProfile::default_profile_for_tui) are now described as defaults rather than as the model itself.
| ## 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`. |
There was a problem hiding this comment.
this probably wasn't merged when you wrote these docs (I merged last night), but you can also now run the TUI w/ the --fast-forward flag (so like warp --fast-forward) to auto-enable fast forward for all new conversations. This is like the claude code --dangerously-skip-permissions flag
There was a problem hiding this comment.
Added in fe8e58d. One naming note: the flag as merged is --auto-approve, not --fast-forward — warpdotdev/warp#14483 ("Add --auto-approve to Warp Agent CLI"), TuiArgs::auto_approve in crates/warp_tui/src/session.rs. So the page documents warp --auto-approve, which also keeps it consistent with /auto-approve and Ctrl+Shift+I on the same page.
The Auto-approve section now reads: toggle with /auto-approve or Ctrl+Shift+I, or launch with warp --auto-approve to start every new conversation in that session with it already on. I also corrected the follow-on sentence — new conversations start with auto-approve off unless you launched with the flag, since TuiConversationSelection applies the launch default to each new conversation even after you toggle one off.
Heads up that --auto-approve also needs to land in the flags table on cli/reference.mdx; that page is a stub owned by a separate PR on this stack, so I left it alone here.
|
|
||
| {/* 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. |
There was a problem hiding this comment.
The "commands matching your command denylist still require approval" actually isn't true anymore. There's a new setting that you can flip to change it so that denylisted commands do require approval even when fast forward is on (auto_approve_bypasses_command_denylist), but this setting defaults to on (i.e. fast forward bypasses the command denylist). The one exception is that workspace level denylisted commands still require approval no matter what
There was a problem hiding this comment.
Fixed in fe8e58d. Confirmed against can_autoexecute_command in app/src/ai/blocklist/permissions.rs and the setting definition in app/src/settings/ai.rs (auto_approve_bypasses_command_denylist, default: true, surfaced on all surfaces): with auto-approve on, the user denylist is bypassed and only get_org_execute_commands_denylist is enforced.
The caution is now a :::danger and says auto-approve runs denylisted commands by default, shows how to turn the bypass off:
[agents.warp_agent.other]
auto_approve_bypasses_command_denylist = false...and notes that team-enforced denylist rules from the Admin Panel always require approval regardless of the setting. I also updated the command_denylist bullet in the profile-fields list, which previously claimed the denylist applies "regardless of other settings."
One downstream thing this surfaces: the GUI page at agent-platform/capabilities/agent-profiles-permissions.mdx still has two statements that are now stale — line 60 ("any denylist rules will still override these settings") and the caution at line 39. Line 144 ("Run until completion ignores the denylist entirely") is now the accurate one. Happy to fix that page in a follow-up PR since it's outside this branch's scope; let me know if you'd rather I fold it in here.
… behavior Addresses review feedback on the CLI permissions page: - Reframe the intro and "How permissions work" around per-action-type configuration (always_ask / always_allow / agent_decides) instead of implying the agent always self-judges safety. - Document the new `warp --auto-approve` launch flag (warpdotdev/warp#14483), which starts every new conversation in the session with auto-approve on. - Correct the auto-approve caution: `auto_approve_bypasses_command_denylist` defaults to true, so auto-approve bypasses the user command denylist unless it's turned off. Team-enforced denylist rules are never bypassed. Co-Authored-By: Oz <oz-agent@warp.dev>
Editorial pass, no factual changes: - The three permission values were defined inline in "How permissions work" and again under "Permission values", then restated a third time. Keep the definitions in the reference section and link to them from the overview. - Lift the denylist bypass config out of the :::danger callout into body prose so the callout is a warning rather than a mini-procedure. - Split the auto-approve toggles from the --auto-approve launch flag and state the per-conversation scope once instead of twice. Co-Authored-By: Oz <oz-agent@warp.dev>
2 participants
Pages changed
src/content/docs/cli/permissions-and-profiles.mdx(stub replaced with full draft)Features covered
always_ask/always_allow/agent_decides), CLI defaults (agent_decidesfor commands/edits/reads/MCP,always_askforwrite_to_ptyandrun_agents, verified indefault_profile_for_tui), and the command denylist layered on topEto edit a proposed command (approving runs the edited version;Escexits the editor without cancelling),Eto expand/collapse all diffs/auto-approveslash command,Ctrl+Shift+Ibinding,warp --auto-approvelaunch flag, opt-in statusline indicator via/statusline, per-conversation scope, question-skipping interplay, denylist-bypass safety calloutagents.execution_profilesTOML table, reserveddefaultkey (the CLI always runs withdefault), field and value reference (snake_case values), allowlist/denylist regexes, whole-collection validation and fallback behavior, local-only (no cloud sync, separate from Warp app Agent Profiles)Dropped/unconfirmed
/fast-forwardslash command: no such command exists instatic_commands/commands.rs; the "▶▶" progress-row control is labeled "Auto approve" and the whole surface is documented under Auto-approve insteadcomputer_useprofile field: intentionally omitted from the field list because I could not confirm the computer-use tool is reachable from the CLI; happy to add if eng confirmsReview round 2 (@harryalbert)
always_askoralways_allow.warp --auto-approve([APP-4992] Add --auto-approve to Warp Agent CLI warp#14483). Note the merged flag is--auto-approve, not--fast-forward; seeTuiArgs::auto_approveincrates/warp_tui/src/session.rs. Also corrected the follow-on sentence: new conversations start with auto-approve off unless launched with the flag.auto_approve_bypasses_command_denylistdefaults totrue, so auto-approve runs denylisted commands; the page now shows how to set it tofalseand notes that team-enforced Admin Panel denylist rules are never bypassed. Thecommand_denylistfield bullet was updated to match.--auto-approvestill needs to land in the flags table oncli/reference.mdx, which is a stub owned by a separate PR on this stack.Notes for review
agent-platform/capabilities/agent-profiles-permissions.mdx: with the new bypass default, the caution at line 39 and the note at line 60 ("any denylist rules will still override these settings") are now stale, while line 144 ("Run until completion ignores the denylist entirely") is accurate. Happy to fix in a separate PR or fold it in here.{{WARP_CLI}}frontmatter tokens render literally in built page titles/descriptions. Thevars-transformVite plugin is registered, but Astro's content layer parses frontmatter outside Vite, so only body-prose{VARS.WARP_CLI}substitutes. Needs a fix onhyc/launch-cli(e.g. a remark plugin or frontmatter preprocessing).Validation:
npm run buildpasses (363 pages);style_lint --changedreports 0 issues.Suggested reviewer(s): harry
Co-Authored-By: Oz oz-agent@warp.dev