Choose a permission mode
Understand the default bypass mode, path approval, plan mode, and autonomous safety gates.
A new CLI installation starts in bypassPermissions: the agent can use file tools outside the working directory without a path approval prompt. Choose default when you want out-of-root file access to require approval. Neither mode is a sandbox or a per-command confirmation system.
Start with path approval
afk config set permissionMode default
afk iThe setting takes effect in new sessions. For a single run, use afk i --permission-mode default or afk chat "Inspect this project" --permission-mode default. The --dangerously-skip-permissions flag forces bypass mode for a run. An unconfigured CLI uses bypass mode; the daemon also runs unattended in bypass mode. Check the active mode in the REPL status line (⚡ bypass for bypass).
| Mode | Behavior |
|---|---|
bypassPermissions | New-install CLI default. No path containment or out-of-root approval for file tools. |
default | File tools within granted roots run; access outside them asks for approval on an interactive surface. No per-bash-command confirmation. |
plan | Read-only investigation, with write-class tools blocked until the plan is approved. |
autonomous | /afk posture with a risk gate that refuses high-risk actions, including for children. |
In an interactive session, Shift+Tab cycles default → plan → bypassPermissions → default. From autonomous mode it exits to default. The old /bypass slash command is retired; use Shift+Tab to enter bypass during a session. /plan and /afk control their respective modes. The --dangerously-skip-permissions flag does not make irreversible actions safe.
What path approval covers
read_file, write_file, edit_file, list_directory, glob, and grep check granted roots in default mode. The initial working directory is granted. For an outside path, you can allow once, allow for the session, persist a grant for later sessions, or deny. Use /allow-dir to grant a directory in advance; forked subagents cannot answer an interactive path prompt, so authorize access in the parent first. Noninteractive requests cannot answer a prompt.
A separate protected credential-path floor still refuses typed read tools even in bypass mode. On interactive surfaces a bash restriction hook also detects certain credential-path references and interpreter one-liners; it is not an OS security boundary, and headless bash has different restrictions. Do not treat default mode as a shell sandbox. See Safety and Tool access.
Read-only exceptions to the credential floor
A few files inside protected directories are readable as exact exceptions: ~/.afk/config/mcp.json (the MCP registry holds ${VAR} placeholders, not literal secrets), ~/.afk/config/schedules.json, ~/.ssh/config, and ~/.ssh/known_hosts. SSH public keys are readable by pattern: any direct child of ~/.ssh whose name ends in .pub, resolved through symlinks first, so foo.pub -> id_rsa stays blocked. Subdirectories and private keys stay blocked. A private key misnamed *.pub would be readable, because the name is the only signal.
Every exception is read-only. Writes to ~/.ssh and ~/.afk/config are blocked on every surface, because a ProxyCommand in ~/.ssh/config or a server in mcp.json is code execution. In bash, an exception applies only to a provably read-only command: a pipeline of plain readers (cat, grep, head, tail, wc, ls, diff, and similar) with no redirection, chaining, or substitution. ssh -i ~/.ssh/<key> stays blocked; use a host alias with IdentityFile in ~/.ssh/config.
Add your own protected paths with AFK_READ_DENYLIST (colon-separated absolute paths; a leading ~/ is expanded). Operator entries are matched before the exceptions, so AFK_READ_DENYLIST=~/.afk/config/mcp.json re-protects the registry if yours holds inline secrets, and AFK_READ_DENYLIST=~/.ssh re-denies every ~/.ssh exception. Built-in entries always apply and cannot be removed.
Bypass grants broad file access. For work on untrusted code, use a disposable environment or isolated worktree, and set permissionMode to default if you need path prompts. Built-in credential protections do not replace an OS sandbox.
Hook controls are separate
Configured shell hooks and plugin hooks have distinct user-global trust gates (enableShellHooks and enablePluginHooks). Hook events include tool use, failures, session boundaries, compaction, and turn boundaries. Hooks can block a call or inject context where supported; a Stop hook can request bounded same-turn continuation. Project hook definitions require a separate opt-in. Hook output and outbound network access need the same scrutiny as other third-party code. See Configure hooks for setup and Hook reference for event payloads and supported outputs.