ncode

CLI docs Approvals and trust

ncode CLI Using ncode

Approvals and trust

Agents act only through tools, and every tool call that could change something is checked against the project's approval mode first. The mode belongs to the project, not to the conversation, and the desktop app uses the same one. It is always shown on the status line.

The rules#

Approval modes#

Every project has one approval mode. It decides what an agent may do without asking you first.

ModeReads and searchesFile writesShell commandsFetching a local or private address
Read-only (shown as Ask)allowedasksasks, for every commandasks
Autoallowedalloweda safe command runs; any other command asksasks
Full accessallowedallowedallowedallowed

Four rules sit on top of the table:

  • Read-only asks; it no longer refuses. Every file write and every command, even a safe one, opens an approval card. You can approve it once or deny it, and the card for a Read-only project offers only approve, deny, and deny and stop. "Allow for this run" and "always allow" are not offered, and a command you allowed "always" in another mode does not skip the question here, so each write is yours to see.
  • A command ncode classifies as dangerous always asks, even in Full access, and "always allow" can never cover it.
  • A command classified as safe (for example ls, git status or cat notes.txt | grep todo) runs without asking in Auto and Full access.
  • Reading a page on localhost, a private range such as 10.x or 192.168.x, or a link-local address asks in Read-only and Auto. Public pages never ask.

A workflow or swarm in a Read-only project waits on the same cards, and a card nobody answers times out after 10 minutes. A mode change applies to the next step: a card already waiting keeps the answers it was raised with.

Project trust#

A folder you add is untrusted and starts in Read-only, so its agents ask before every write and command. Until you trust it:

  • its instruction files (AGENTS.md and friends) reach no prompt;
  • its hooks do not run.

Trusting a project records your consent and moves it to Auto. A project you already put in Full access stays in Full access.

Remembered commands#

When you allow a command family "always", ncode stores that prefix with the project, so the next matching command in any conversation of that project runs without asking in Auto and Full access. Dangerous commands are never remembered, and a conversation without a project remembers nothing. In Read-only nothing is remembered and every command still asks. You can review and forget remembered prefixes later.

Changing the mode#

text
/approval auto

/approval read-only, /approval auto and /approval full switch the project's mode; /approval alone opens a picker of the three with the current one checked. Every change, from here, from Settings or from the desktop app, is said in the chat:

Approvals: auto → full access

Shift-Tab cycles the modes#

With the composer focused, Shift+Tab cycles Ask → Auto → Plan → Ask, so you can change how much the assistant may do without typing a command. It goes through /approval and /plan, so the answer comes from the same place as when you type them, and a notice says where you are:

StepNotice
Ask (Read-only)Ask · writes and commands ask first · Shift-Tab: Auto (this project)
AutoAuto · edits and safe commands run · Shift-Tab: Plan (this project)
PlanPlan · read-only tools, a plan first · Shift-Tab: Ask

The approval mode belongs to the project, so the change also applies to your other conversations of the project and to the desktop app. Full access is never entered by the cycle: from Full access, Shift+Tab goes to Plan, and only /approval full goes back. An untrusted project refuses Auto with its own message; run /trust first. Outside the composer, Shift+Tab keeps moving the focus back, as before.

/trust trusts the project: its instruction files are read from then on, its hooks may run, and a read-only project moves to auto. In Settings, Approvals & trust shows the mode, the trust switch and the list of always-allowed commands, which you can edit.

The approval card#

When an agent needs your answer, a card opens by itself above the composer. It shows the command in a code block of at most six lines; with your draft empty, Enter shows every line and Enter again folds them back.

KeyAnswer
yallow once
Yallow for the rest of this run
Aalways allow this command family in this project
ddeny
Ddeny and stop the run
nleave this one and show the next thing waiting

A card offers only the answers that apply to it, and only those letters answer it. Three rules keep you from answering by accident:

  • For a moment after a card opens, your keys keep typing into the draft, so a sentence you are in the middle of is never taken as an answer.
  • The letters answer only while your draft is empty. Any other letter types, and Enter with a draft sends the draft; the card stays.
  • The same applies to a card you brought back with Ctrl+N or n.

Ctrl+N opens the next approval or question waiting on you. In an agent overlay the same letters answer that agent's request.

The Ask card in Read-only#

In a Read-only project the card is titled Ask · <tool> and offers only what applies:

KeyAnswer
yallow this one
ddeny
Ddeny and stop the run

There is no "this run" or "always" in Read-only, so a Y or A you answered earlier never skips a later question. For edit_file the card shows a diff of the change, 12 lines and then … N more; for write_file it shows the first 12 lines of the new content. A command waits on the card the same way, whether it is ls or rm.

ncode approval card asking permission to run a three-line mix test command, with once, this run, always, deny, deny-and-stop and next actions beneath it.
Long shell-command approval in ncode folded after six lines, with two more lines hidden and an Enter shows all hint.

Approvals in headless runs#

A headless run (ncode -p) has nobody to ask. It uses the project's approval mode as it is: whatever the mode allows runs, and anything that would still need a person is denied. That includes every write and command in a Read-only project, and a tool call the project's hooks or rules blocked. After the run, one line on stderr says what was denied and how to allow it:

ncode: 2 tool call(s) were denied (approval mode read_only): <what>, <what>.

It names up to five of them, then and K more, and in a Read-only project it adds how to allow them. The same denials are in the denied field of --json. A run stops after 8 denials. In full access nothing asks, and the line says so. An agent's question stops a headless run.

Two flags change this for a script:

  • --fail-on-denied makes a run that finished but had denials exit with code 1, so a pipeline notices that part of the job did not happen.
  • --approval read-only|auto|full sets the approval mode for this one run, in memory; the project's own mode never changes. An untrusted project refuses auto and full with exit code 3, as /approval does.