claude-code - 💡(How to fix) Fix Docs: --dangerously-skip-permissions still shows confirmation dialog; --permission-mode dontAsk is the headless flag, but nothing says so [1 comments, 2 participants]

Summary

claude --help lists three permission-related flags that overlap in confusing ways:

--allow-dangerously-skip-permissions   Enable bypassing all permission checks as an option, without it being enabled by default. Recommended only for sandboxes with no internet access.
--dangerously-skip-permissions         Bypass all permission checks. Recommended only for sandboxes with no internet access.
--permission-mode <mode>               choices: acceptEdits, bypassPermissions, default, dontAsk, plan, auto

For autonomous / headless / scripted sessions, the user needs the session to avoid human-interactive prompts. The discoverable-named flag --dangerously-skip-permissions sounds like it does exactly that. But in practice:

• --dangerously-skip-permissions → session still shows the one-time "Bypass Permissions mode … 1. No, exit / 2. Yes, I accept" dialog, and parks there waiting for keypress.
• --permission-mode bypassPermissions → same dialog, same park.
• --permission-mode dontAsk → works. No dialog. Session proceeds to process the first prompt immediately.

The name dontAsk is the opposite end of the spectrum from the dramatic-sounding flags, so users reach for --dangerously-skip-permissions first, hit the dialog, and have no clear signal that they should try dontAsk instead.

Requests (docs + UX, no code changes needed)

1. Rename or alias --dangerously-skip-permissions to make clear it still requires interactive acceptance on first use. Proposed phrasing for the --help line:

   --dangerously-skip-permissions   Enable bypass mode; first run in a new session still requires interactive confirmation. For non-interactive sessions use --permission-mode dontAsk.

2. Cross-reference dontAsk as the right flag for headless use in both --help and the permissions docs page. The existing docs describe the modes but don't steer users to the right choice for the scripted-sessions case.
3. Detect the anti-pattern: if claude is started with --dangerously-skip-permissions + stdin not a TTY, either automatically route to dontAsk behaviour OR print a one-line hint ("Note: first-time bypass confirmation is interactive. For scripted use pass --permission-mode dontAsk.") before parking at the dialog.

Context

Found while deploying a 20-peer choir swarm on WSL2 where every peer is a detached GNU screen window with no TTY. With --dangerously-skip-permissions, all 20 peers park at the dialog and the swarm produces zero work. With --permission-mode dontAsk, all 20 peers process their charters immediately.

This is the secondary issue on top of #52501 (no pre-accept flag for the bypass dialog) — but even if #52501 is not fixed, clearer docs and a better flag-choice hint would have saved ~1h of diagnosis.

Environment

• Claude Code v2.1.117
• WSL2 Ubuntu, GNU screen (detached, no controlling TTY)