Permission Modes

Permission modes control which tools the agent can invoke automatically and which require explicit human approval. Choose the level that matches your trust in the task and the stakes of a mistake.

The three modes

Setting the mode

Spawn modal (browser)

The mode selector is shown in the spawn modal when starting a new session. Select Yolo, Auto, or Interactive before spawning.

Direct agent command

afk agent --project /path/to/project --mode yolo --task "run the test suite"
afk agent --project /path/to/project --mode auto --task "refactor the auth module"
afk agent --project /path/to/project --mode interactive --task "migrate the database"

afk spawn intentionally exposes only a minimal set of spawn flags. Use the browser spawn modal for permission-mode selection on daemon-managed sessions.

Default

New browser sessions use the selected mode from the spawn modal. Directafk agent invocations default to the CLI command's configured mode unless --mode is passed.

Approvals in the browser

When a tool needs approval (in auto or interactive mode), the browser shows a pending approval card with:

• The tool name and its full input parameters.
• Approve — execute the tool and continue.
• Deny — reject the call; the agent receives an error and must decide how to proceed.
• Edit — modify the tool input before approving (e.g. change a shell command).

If you have the session open in multiple browser tabs or devices, the approval is resolved by the first person to act.

Waiting states

When an agent appears paused, it is usually waiting for one of the browser-visible interaction cards below. These cards may be pinned near the composer so they stay visible while the transcript grows.

If no card is visible, check whether the browser is connected, whether another tab already resolved the interaction, and run /statusto inspect the session runtime.

Which tools are read-only?

In auto mode, these tools run without approval:

• read_file, glob, grep, list_dir
• web_fetch, web_search, web_open, web_click, web_find
• workspace_diff, notebook_read
• cost, todo_read, task_get, task_list, task_output
• parallel (when all child calls are read-only)
• All lsp_* tools

The following always require approval in auto mode:

• bash, bash_background
• write_file, edit_file, apply_patch, parallel_write
• notebook_edit
• agent_spawn, agent_stop, session_spawn, session_close, session_archive, session_restore

Plan mode

Beyond the three permission modes, agents can enter plan mode — a temporary state where all write and execute tools are blocked while the agent explores the codebase with read-only tools and then proposes a plan.

The agent enters plan mode by calling the plan_start tool, then calls plan_finish with a markdown plan. The browser presents the plan with Approve, Deny, and Exit plan mode buttons. If approved, write tools are unblocked and the agent executes the plan.

You can also start plan mode from the browser UI without the agent initiating it. Denying a plan sends your feedback back to the agent and keeps write/execute tools blocked until a revised plan is approved or plan mode is exited. Exiting plan mode abandons the checkpoint and tells the agent not to proceed under the old plan.

Hooks for approvals

The ApprovalRequired hook fires before an approval card is shown in the browser. You can use it to auto-approve specific patterns or log approval requests:

{
  "ApprovalRequired": {
    "command": "python3 - <<'PY'\nimport json, sys\ne = json.load(sys.stdin)\ntool = e['payload'].get('tool_name','')\n# Auto-approve read-only LSP tools even in interactive mode\nif tool.startswith('lsp_'):\n    sys.exit(0)\nsys.exit(1)\nPY",
    "blocking": true
  }
}

See Hooks Reference for the full hook system documentation.