Permissions

Before any tool runs, Nib decides whether it may run without asking you. PreToolUse hooks run first. Then, in order: deny rules, the checks that always need you (protected paths, secret stores, outward actions, sandbox escapes), ask rules, allow rules, and the session's permission mode, which in auto mode consults a classifier model. If none of them allows the call, Nib asks you; in auto mode, a call the classifier blocks, and most of those checks, are held back instead (see Auto mode).

Permission modesСкопировать ссылку на раздел

A mode decides only which of the agent's calls need your approval. The agent works the same way in every mode: it finishes what you asked, makes routine choices itself and tells you which, and never takes an outward or hard-to-undo action you didn't ask for.

In the CLI, Shift+Tab cycles through default, acceptEdits, plan and auto. Bypass joins the cycle while the session is in it, or when the CLI started in it or with --allow-dangerously-skip-permissions.

There is also dontAsk, for unattended runs: anything that would have prompted is denied instead. Headless nib -p runs behave this way unless you pre-approve tools.

Plan modeСкопировать ссылку на раздел

In plan mode the agent explores, then calls ExitPlanMode with a plan. You approve it (and pick the mode to continue in) or send it back with feedback. While planning, the agent may write its own plan file and the folders the session owns outright: the working folders of its artifacts, its memory folder and its scratch folder. Nothing else is writable. The agent enters plan mode itself with EnterPlanMode only when you ask it for a plan first.

Auto modeСкопировать ссылку на раздел

Auto mode hands the "should I ask?" question to a separate, fast model (the provider's small model). The classifier sees only your own recent messages and the proposed action. It never sees the agent's reasoning or tool output, so text injected into a web page or file can't argue it into approving something.

When the classifier blocks an action, auto mode doesn't ask you. The call is denied, and the agent goes on with other work and tells you in one line what it held back. To allow it, say so in the chat (for example "allow the push"), or use Allow this under the held call:

• Allow this lets exactly that action (the same command, or the same file) run once, the next time the agent tries it. Anything different is judged again.
• A message you type is read by the classifier. If it approves exactly the action that was held back, the agent's next try of it runs once.
• Nothing is saved to your settings. For a command you want to run every time, add an allow rule.

The checks that always need you never go to the classifier. In auto mode most of them hold the action back the same way, even if you asked for it earlier: publishing, outward actions, printing a credential, reading a secret store, commands nothing local can undo, and writes to git's own data in .git. The held line names the exact command or file, and only Allow this, or a message after it that clearly approves that exact action, lets it run. A message that doesn't say which action it approves leaves it held. A few checks still ask you, as the table shows: running outside the sandbox, writes that can make code run, CI workflow changes that widen access, commands Nib can't check, and a crew member's spending.

The classifier fails closed. If it's unavailable, errors, or answers ambiguously, Nib asks you. After 3 consecutive blocks, or 20 in one session, auto mode pauses and asks you instead, so a confused agent can't grind against it. Only a person can answer, and approving resumes auto mode. Apart from these, auto mode asks only for the checks that still ask, ask rules, a hook that asks, and requests only you can approve, such as running an untrusted workspace's workflow script, raising a spending cap or making an artifact public. Archiving a session or adopting a race's lane goes to the classifier like any other action, and deleting a race is held back like a command nothing local can undo. Broad allow rules such as Bash(*) are ignored in auto mode, because they would bypass the classifier entirely.

Auto mode is available by default. Only your organization's managed settings can turn it off (disableAutoMode), and a project's settings can't make it the starting mode.

RulesСкопировать ссылку на раздел

Rules let you pre-approve, always ask, or always deny specific actions. The syntax is Tool or Tool(specifier), the format existing settings.json rules already use.

{
  "permissions": {
    "allow": [
      "Bash(npm run test *)",
      "Bash(git log *)",
      "Edit(src/**)",
      "WebFetch(domain:docs.python.org)",
      "mcp__github__get_issue"
    ],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(.env)", "Read(**/*.pem)", "Bash(curl *)", "WebSearch"]
  }
}

Evaluation orderСкопировать ссылку на раздел

1. Deny rules win over everything. A deny matches in every mode, including bypass.
2. The checks that always need you come next, in every mode but bypass. An ordinary allow rule doesn't skip them.
3. Ask rules force a prompt even if an allow rule also matches.
4. Allow rules approve the call.
5. If no rule matches, the mode decides.

Rules from every settings file are combined: managed, command line, local, project and user. See Configuration for where they live.

Rule referenceСкопировать ссылку на раздел

A Read(…) deny rule also blocks edits there. An Edit(…) rule covers edits only: allowing edits to a path doesn't allow reading it.

Command patternsСкопировать ссылку на раздел

Nib parses shell commands properly before matching. A compound command such as npm test && git push is split, and each part has to be allowed on its own. Command substitutions, heredocs, pipes and wrappers such as env, timeout or xargs are understood, so timeout 60 rm -rf build is treated as rm -rf build.

If you write Bash(git * main), Nib warns that the wildcard before the subcommand matches far more than you probably intended.

A line the agent submits in a Terminal is checked as the whole line, even when it typed it over several calls. When it recalled, completed or edited the line with keys (history, Tab, cursor keys), Nib checks what was typed of it. If that part is a risky command (one that touches credentials, spends money, destroys data, publishes, or reaches people outside), no rule approves it: default and acceptEdits ask, dontAsk denies it, auto mode leaves it to the classifier, and bypass runs it. Plan mode never runs such a line.

Path patternsСкопировать ссылку на раздел

Path patterns follow gitignore conventions:

* matches within a path segment, ** across segments, and a pattern that names a directory covers everything below it.

Protected pathsСкопировать ссылку на раздел

Some files are how a prompt injection would persist or escalate: agent configuration, git internals, shell startup files and tool configs that execute code. Writes to them always need you, auto mode included: auto mode asks about the ones that can make code run, and holds back a write to git's own data in .git (its objects, refs, logs, index and info/exclude) until you allow it. Only bypass, where you've chosen to answer for everything, skips the question. In dontAsk and headless runs they are denied.

Protected directories, at any depth: .git, .nib, .claude, .codex, .cursor, .gemini, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn, .ssh, .gnupg, .aws.

Protected files, at any depth, include .gitconfig, .gitmodules, shell startup files (.bashrc, .zshrc, .profile and friends), .envrc, .npmrc, .yarnrc, bunfig.toml, .pre-commit-config.yaml, lefthook configs, .mcp.json, .claude.json and .nib.json.

A few locations inside protected directories are exempt because agents legitimately write there, such as .nib/worktrees and .nib/agent-memory.

Nib also refuses to run obviously destructive shell commands against critical paths, such as removing your home directory or the filesystem root, until you approve them (in auto mode, with Allow this), except in bypass mode.

Checks that always need youСкопировать ссылку на раздел

Some calls need you in every mode but bypass, whatever the classifier would say. The other modes ask. Auto mode either asks or holds the call back until you allow it, as the table says, and what you said before the call doesn't count. In dontAsk mode and headless runs, where nobody can answer, they are denied.

When one call meets several checks, or an ask rule too, auto mode asks if any of them asks.

For outward actions, credential printers and CI workflow permissions, a rule from a project or local settings file, a session rule, or a rule an agent proposed never pre-approves the call, so an agent can't widen its own reach. That's why "allow": ["Bash(npm publish)"] in a project's settings still asks before publishing.

Answering a promptСкопировать ссылку на раздел

When Nib asks, you can choose:

In the app, Allow and Deny are the prompt's buttons. Allow for this session and Always allow are in Allow's menu, and Send back with a note in Deny's. Each says in words what it lets through, for example "commands starting with “npm run lint”", and Always allow lets you edit the rule before it's saved.

Nib suggests a rule for "always" that is as narrow as is useful, for example Bash(npm run lint *) rather than Bash(npm *).

Hooks and permissionsСкопировать ссылку на раздел

PreToolUse hooks run before the permission engine and can return allow, deny, ask or defer. A hook's deny holds in every mode. A hook's ask holds in every mode too, but in bypass only your own hooks and your organization's can ask (from your user settings, managed settings, the command line, or the program embedding Nib); bypass ignores an ask from a repository's hook (its project or local settings), a plugin's, a skill's or an agent's. A hook's allow skips a routine prompt, never one that needs you: one of the checks that always need you, auto mode's pause after repeated blocks, or a classifier that can't decide. A PermissionRequest hook runs when a prompt would be shown and can answer it for you, with the same limit on approving; denying has none. See Hooks.

Workspace trustСкопировать ссылку на раздел

When you open a folder you haven't trusted, Nib asks whether you trust it: the app and VS Code ask about the folder you're working in, and the terminal asks when the folder's own settings would turn something on. Each asks once per start, and only on the computer the folder is on. Not now leaves the folder untrusted until you quit; once you trust it, that's remembered. Until you do, the project's own settings files can only narrow permissions. They can't add allow rules, hooks, environment variables, additional directories, sandbox network hosts, an API key helper or a status line command.

Independently of trust, project and local settings can never set the default mode to auto or bypass, and can't override sensitive environment variables such as HOME, TMPDIR or XDG_*. Nor can they define MCP servers, approve the project's own servers or switch plugins: a repository's servers go in .mcp.json, where each asks for your approval.

AuditСкопировать ссылку на раздел

Every decision is written to the session's audit file, and every one that isn't a trivial allow (a read-only call the mode allows) is also a permission.decision event in the session log, with the tool, the outcome, what decided it (a rule, the mode, the classifier, a protected path, a hook, or you) and the matching rule. You can review any session's decisions after the fact.

Command-line flagsСкопировать ссылку на раздел

nib --permission-mode acceptEdits
nib --allowedTools "Bash(git log *)" Edit
nib --disallowedTools "Bash(rm *)" WebFetch
nib --dangerously-skip-permissions   # same as --permission-mode bypassPermissions

The flag, or accepting bypass once in any Nib client, is your choice. In the terminal UI, --dangerously-skip-permissions shows the same screen until you've accepted bypass. Where nothing can show it (-p, including a background run with --bg, ACP, mcp serve), the flag is your choice and nothing asks. An editor's mode picker offers bypass once you've accepted it, when the run started in it, or with --allow-dangerously-skip-permissions. A program in SDK mode can switch a run to bypass later only if the run started in it or was given --allow-dangerously-skip-permissions (the Agent SDK's allowDangerouslySkipPermissions). In every case your organization's policy can turn bypass off, deny rules apply, and bypass doesn't run as root outside a container.

Bypass also doesn't run as root, unless Nib runs in a container: run it as a non-root user, or in a container. A session asked to start in bypass as root uses Default mode and says why.

--allowedTools and --disallowedTools accept comma- or space-separated lists and never split inside parentheses. They apply to the session only.