← Reference

Permission modes

Top-level posture for tool calls, set per session.

Full notes from the app

A new session starts in permissions.default_mode, which is Auto unless you set it; a session keeps its own mode when it is resumed, restarted after a crash or carried across a daemon reload, and a fork starts in its parent's. A worker an agent starts with spawn_worktree_session takes its parent's mode or this one, whichever lets less run without a prompt. Switch live via /permissions <mode> (the rule editor on no-args). The status bar names the mode in the warning colour: plan mode always, another mode once the session has left the one it started in. Set it at launch with kcode --permission-mode <default|accept-edits|auto|plan> or --bypass-permissions / --yolo, the same as --permission-mode auto (given with another mode, the launch is refused): the launch mode applies to the sessions this window spawns and to the session a kcode --resume <id> or -c launch opens, with a confirmation line in the chat. A lone sed -i or gsed -i that edits one file named before it runs, and does nothing else, needs permission as the file write it is: the prompt names the target file, edit-allow rules apply, and AcceptEdits auto-allows it like any edit; an edit whose script runs a command or reads or writes another file, one run with another command, multi-file or dynamic targets, and perl -pi (its program can do anything) need permission as command execution. Writing to /dev/null, /dev/stdout or /dev/stderr (a redirect such as 2>/dev/null, or sed's w /dev/stdout) writes no file and reaches nothing outside the project, so a shell command that otherwise only reads still runs without a prompt, and an in-place edit that sends its errors there is still a file write. A shell command that sets a variable, a prefix such as PATH=/x ls, a statement, a loop, a builtin that stores into one (printf -v, read, mapfile, getopts, let), run directly or through builtin or command, a redirection that stores its descriptor in one ({fd}>file), or the bash tool's env argument, stays a read only when the variable can't change what runs: a name on a short list that only changes how output looks, turns off a prompt or a lock, or sets a build tool's log level or mode (LANG, NO_COLOR, RUST_LOG, CI), or a lowercase name (count=3; ls) other than a proxy's or a package manager's setting (https_proxy, npm_config_registry). Any other variable (PATH, LD_PRELOAD, PAGER, GIT_DIR) makes the command need permission, and an allow rule for the command doesn't cover it. export, declare, typeset, local and readonly follow the same rule for the variables they set, a quoted export "PATH=…" included (they always needed permission before); a name reference (-n), an integer (-i) or export -f needs permission. A git -c setting keeps a read-only git command a read when it only changes what git shows: colours, columns, hints and named formats (color.*, column.*, advice.*, pretty.*), a listed display setting such as log.date, diff.algorithm or status.short, or a pager turned off. Any other setting (core.fsmonitor, diff.external, include.path) makes the command need permission, as --config-env does. A cd keeps a shell command a read, so cd src && cat main.rs runs without a prompt; a relative path in the command is judged from the folder it starts in and from each folder a cd in it may move to, so a read that reaches a secret location still needs permission. Tools whose registry descriptor declares them read-only (pure observation: shell_plan, shell_status, LSP queries, memory recalls) classify as reads and auto-allow like fs_read instead of showing a prompt; mutating tools keep the permission prompt. An MCP tool its server marks read-only (readOnlyHint) is one of these, and runs without a prompt in every mode unless a rule denies it. The web reads web_fetch and web_search run without a prompt in every mode unless a rule denies them. So do the browser tools' navigations to web pages (http, https or data URLs, which a url(…) rule judges as it judges web_fetch), clicks and fills; a navigation to any other scheme, such as a file: page, needs permission. session_search, await_subagent, advisor, meta_ask_user_question and notify declare themselves read-only, so they run without a prompt in every mode unless a rule denies them, as do session_manager's list and rename; its delete, which is permanent, needs permission. Tools declared internal, the agent's own bookkeeping, changing only kcode's own state: the task list, the mailbox tools send_message, check_inbox and manage_session, set_timer, cancel_timer, set_activity, run_command, fork_session, memory_save and memory_delete, are auto-granted in every mode unless a deny rule names them, so bookkeeping never raises a prompt even in an untrusted project. What a timer, a command or a fork goes on to do is still judged call by call, and a fork starts in its parent's mode. run_skill for a script skill still needs permission outside Auto mode, because its code can write files. Once you accept a skill's allowed-tools, the calls it lists run without a prompt during the turn that runs the skill (see run_skill). Stopping the agent's own work is internal too: shell_kill, shell_signal, test_cancel and a shell_proceed that aborts its plan run without a prompt unless a rule denies them. Your own ! commands run in the session's shell, so the agent can stop one of those without a prompt too; shell_write_stdin still needs permission, since text typed at a prompt can run a command. Starting an agent runs without a prompt in every mode but Plan, which refuses it, unless a rule denies it: spawn_subagent, spawn_subagent_async and spawn_worktree_session. What the agent does is still judged call by call: a subagent's calls by this session's rules and mode, a worker's in its own session, which starts in its parent's mode or permissions.default_mode, whichever lets less run without a prompt. A subagent's permission prompt shows in the session's chat, and its prompt names the subagent as its row does (from subagent general (catalog)); a plugin's own tool call names the plugin (from plugin tail). Confirming Deny on the permission prompt arms an optional feedback line in the composer: Enter denies with that reason handed back to the agent (reject-with-feedback); Esc backs out to the choice list.

6 entries · kcode 0.6.5097

6 shown
ModeAllowsUse it for
DefaultRead + write (rules enforced)Normal interactive use. Reads (including tools whose descriptor is read-only) auto-allow; rules can deny specific tools/paths, reads included, and a path(…) deny rule refuses a shell command that names a path it covers; ask gate triggers for risky ops.
PlanRead-only on this machine (reads + grep + web + browser + shell commands that only read)Planning & analysis. No writes, no commands except shell commands that only read (git log, rg, ls), which run as they do in Default mode: without a prompt, except that one reading a secret location outside the project (permissions.secret_paths) needs permission. No subagent spawns: spawn_subagent, spawn_subagent_async and spawn_worktree_session are refused even when a tool(…) rule allows them. The GET-class web reads (web_fetch, web_search) run without a prompt, as they do in every mode, and a url(…) deny rule still blocks its hosts. So do the browser tools' navigations to web pages, clicks and fills; a navigation that opens a local file needs permission. The advisor runs without a prompt, since the agent it starts is held to reads, and so do session_search, await_subagent, questions to you (meta_ask_user_question), notify, and session_manager's list and rename. The session's own controls run without a prompt too: the timers, the activity line, run_command, fork_session (the fork starts in Plan mode as well) and memory saves and deletes. So does stopping the agent's own work: shell_kill, shell_signal, test_cancel and a shell_proceed abort. So do the MCP tools a server marks read-only (readOnlyHint); any other MCP tool needs permission.
AcceptEditsRead + write to project filesEditing without prompts. A write to a file in the project runs without a prompt: fs_write, fs_edit, a lone sed -i edit, and a patch (apply_patch) whose files all lie in the project. A write outside the project needs permission, and so does a shell command that does more than read, as in Default mode. Deny rules still apply.
AutoEvery tool call a deny rule doesn't refuse; secret locations still need permissionWorking without prompts, as most coding agents now do. Tool calls run without a permission prompt (writes and commands anywhere) except calls a deny rule refuses and calls that read or write a secret location (permissions.secret_paths), such as cat ~/.ssh/id_rsa. Those need permission, unless one of your allow rules covers them; kcode -p shows no prompt and refuses them. Plan mode is the one that refuses changes. While a deny rule is set, a shell line whose braces expand past what kcode can read needs permission, since it may name what the rule refuses. A new session starts in this mode unless permissions.default_mode names another, and the prompt choice Allow all except secret locations in this session turns it on for the session.
The ask dialogAllow once / Allow every <tool> command in <project> / Allow every <tool> command in every project / Allow all except secret locations in this session / DenyThe interactive gate a risky tool call raises: up to five choices, each sending its own answer, Allow once, Allow every <tool> command in <project> (persisted as a ProjectAlways rule for this tool in this project), Allow every <tool> command in every project (persisted as a UserAlways rule for this tool, so it holds in every project), Allow all except secret locations in this session (puts the session in Auto mode, which it keeps when it is resumed; the chat says so, and /permissions changes it back: a prompt in Auto mode, which only a secret location raises, leaves it out, and a prompt still waiting when its session turns to Auto shows again without it), Deny. The prompt names who provides a tool that isn't kcode's own (Tool todo_count from the user plugin hello, Tool files__move from the project MCP server files) so a plugin tool can't pass for a built-in one, even one that takes a built-in's name. A call whose target is only its tool's name: any plugin or MCP tool, and kcode's own tools that name no file, command or address. Shows its arguments on an args line, as compact JSON on one line, cut short past 1,000 characters. The labels name the tool and the project folder, since an always answer covers every call of the tool, not just the one the prompt names; a tool that runs no command reads 'call'. ↑/↓ move the highlight and Enter confirms it from an empty composer, and a click on a choice picks it as Enter would: on Deny a line for the reason follows; a line typed while the prompt is up is sent on Enter, queued behind the turn, and the prompt keeps waiting, its hint saying so. With Deny chosen, the typed line is the reason the agent reads. A rule one session stores reaches every other open session at once: each reads the stored rules again and lets through the waiting calls the rule covers. An Allow always or Allow all except secret locations in this session answer (like a rule added in /permissions or a change of mode) also decides every other waiting call it covers: their prompts close in every window, and the calls go on without another answer. A shell prompt names the whole command line: each command after &&, ; or |, and every line of a command that spans several. Interactive bash prompts show the planner's evidence, not just the command string: the resolved binary, argv, side-effect class, and glob counts, worked out where the command will run, in the folder the agent's shell is in, with the PATH and variables its earlier commands exported. Bash rules classify per pipeline stage, so a safe first stage (e.g. ls … |) doesn't taint the whole command into a prompt. A turn parked on an open prompt is still interruptible (Esc denies it, while a subagent's prompt stays open) and the chat's working strip names the park (tool · agent · how long). If an 'Allow always' rule fails to persist, the failure surfaces as an in-transcript notice instead of vanishing. A session in a folder that is not a project: the home folder, a folder above it, /, or the folder that holds the data folder, has no project store, so the second choice there reads 'Allow every <tool> command in this session' and holds for that session only. A call that can't run whatever the answer: a file tool whose project_root names no folder, or a write, edit or patch whose path leads out of the folder it writes in, fails with its error and shows no prompt.
Project trustUntrusted ⇒ project .kcode, .claude/rules + .mcp.json ignoredNew-session spawns and resumes into other projects gate the same way (Esc there cancels the action instead). Several opened at once show the dialog in turn, in the order you opened them, and one whose project you answered for meanwhile opens without the dialog. Headless kcode -p never shows a dialog: an untrusted project runs untrusted with a stderr notice that names the project's folder (which may be above the folder the run started in) and the kcode trust <folder> command that trusts it. The CLI's commands never read an untrusted project's config.toml, and kcode mcp list lists its MCP servers without starting them. A project trusted in one window is trusted in every window, and an open dialog about it closes, or shows again only what the grant doesn't cover. Code a running session holds back, a plugin, a skill that runs a script, or a hook new or changed since you trusted the project, waits while the window shows Trust new code in this project?: Trust & remember, This session only, or Not now, which opens highlighted so a stray Enter runs nothing; Not now (or Esc) fails a skill the agent started and keeps plugins and hooks held until you trust the project, and a project this window opened untrusted gets Not now without a question. Granting trust live-re-applies the boot project's theme without a relaunch; the project's config, commands, skills and .kcode instructions reach the sessions that start or resume there after the grant. The client dialog is consent UX: the daemon re-checks trust at every session spawn, so the gate holds whatever the client.