05. Permissions, Plan Mode, and Safety

The first permission prompt

When Matcha CLI wants to edit a file, run a command, or call an external tool, it can pause and ask. The first card is a one-shot decision, not a silent switch into always-approve.

Allow, reject, and cancel

These are three different outcomes. They all stop the tool from running until you answer, but they do not mean the same thing afterwards.

Outcome	What you did	Tool runs?	Transcript marker
Allow	Confirm an allow row (`Enter` on the highlighted row, or its number)	Yes	The tool proceeds
Reject	Choose the reject row (`No, reject`)	No	`Permission denied in …`
Cancel	`Ctrl+C` on the card	No	`Turn cancelled by user in …`

Reject is a no to that tool. Cancel abandons the permission request — and the turn — without recording a deny. Do not treat them as the same key.

What's on the card

A permission card is a blocking prompt in the composer. Typical rows on the first bash-style card, numbered from 1:

Yes, and don't ask again for anything (always-approve mode)
Yes, proceed
No, reject (type to add feedback)

The first row is prepended for the TUI. It allows this call and then turns the session to always-approve (· always-approve on the prompt, toast ⚠ Always-approve ON: all tool actions auto-run). That is the most powerful choice. It is not the default highlight.

On a fresh session the cursor lands on Yes, proceed (allow once). Enter therefore allows this invocation and leaves the session in ask. You can still pick always-approve with 1 or Ctrl+O.

File-edit cards add Yes, allow all edits during this session (in-memory only; it does not survive a restart). Extra Always allow: <command> rows appear only when you opt in — see Ask, auto, and always-approve.

Reads, searches, and a fixed list of read-only shell segments (ls, git status, rg, and others) usually run without a card. Chained commands are split: ls && rm -rf tmp still prompts for rm. A matching ask or deny rule, or a PreToolUse hook, can still stop a “free” read.

Answer the card

Key	Effect
`Enter`	Confirm the highlighted row. On the first card, that is allow once.
`1`–`9`	Select that numbered row immediately.
`↑` / `↓` or `j` / `k`	Move the highlight.
Type on the reject row	Attach feedback, then `Enter` to reject with that text.
`Ctrl+C`	Cancel the request. Marker: `Turn cancelled by user`.
`Ctrl+O`	Toggle always-approve without using row `1`.
`Esc` (options focused)	Park the card and give the keyboard to the scrollback. It does not reject or cancel. `Tab` or `Space` returns to the card.
`Esc` while typing reject feedback	Return to the option list. Draft text is kept.

Arrow keys (← / →) adjust command or MCP scope on the “always allow this …” rows when those rows are shown.

What each choice does

Allow once

Yes, proceed runs this invocation. The session stays in ask. Later prompts remember the last allow kind you confirmed (once vs always-this-command) and highlight that kind next time. Picking always-approve, “allow all edits this session”, or reject does not steer the next cursor that way.

Enable always-approve

Row 1 allows this invocation once, then the session flips to always-approve and remaining queued cards drain. Administrators can lock that flip off — the current call can still be allowed once. See Ask, auto, and always-approve.

Reject

No, reject does not run the tool. The turn ends with Permission denied in …. Typing before Enter sends that text with the rejection.

Cancel

Ctrl+C does not run the tool. The turn ends with Turn cancelled by user in …. This is not a recorded deny.

Change the first-card highlight

The unset default is allow once. To land somewhere else on the first prompt only:

# ~/.matcha/config.toml
[ui]
default_selected_permission = "allow_once"   # default
# always_allow_all_sessions | allow_command_always | reject

MATCHA_DEFAULT_SELECTED_PERMISSION overrides the file for that process (GROK_DEFAULT_SELECTED_PERMISSION is the registered alias). After you confirm any allow row, later cards follow that last-used kind until the process exits.