Permissions

Overview

Permissions are implemented by packages/nikcli/src/permission/next.ts. The service combines config rules with persisted project approvals, evaluates wildcard matches, publishes pending requests, and resolves tool execution only after the user replies.

Permission modes

The TUI and mobile app surface three named presets plus a derived Custom label. Open the TUI command palette and choose Permissions, or use the permission_mode keybind, to switch modes. A preset writes the current primary agent's permission map; agent-level settings take precedence over the global config.permission value. The same preset definitions are shared by mobile and web through permission-presets.ts.

Approve for me defaults

Selecting an individual tool cycles its action through allow, ask, and deny. The mode then appears as Custom unless the resulting map still matches one of the presets. A preset is just a starting map; once it lands in config.permission (or in an agent-level override), the ruleset evaluator treats it the same as a hand-written permission object.

Actions and rules

A rule has permission, pattern, and action. The permission is a tool or capability name. The pattern is tool-specific: command text for bash, file paths for edit/read-style tools, or * for capability-wide matching.

Config forms

The schema accepts three useful forms:

{
  "permission": "ask"
}

{
  "permission": {
    "bash": "ask",
    "edit": "ask",
    "webfetch": "ask",
    "lsp": "ask"
  }
}

{
  "permission": {
    "bash": {
      "git status*": "allow",
      "git diff*": "allow",
      "rm *": "deny",
      "*": "ask"
    },
    "edit": {
      "src/**": "ask",
      "package.json": "ask",
      ".env*": "deny"
    }
  }
}

Evaluation order

PermissionNext.evaluate merges all rulesets and uses the last matching rule. A rule matches only when both the permission wildcard and the pattern wildcard match. If no rule matches, the fallback action is ask.

1. Config permission is converted with PermissionNext.fromConfig.
2. Persisted project approvals are loaded from storage.
3. Tool-specific extra rules can be merged by callers.
4. The service uses findLast, so later rules override earlier matching rules.
5. For each requested pattern, deny fails, ask prompts, allow continues.

Ask and reply lifecycle

1. A tool calls ctx.ask or directly reaches PermissionNext.ask.
2. The request is parsed and assigned a permission id if none was supplied.
3. Each requested pattern is evaluated against config and stored approvals.
4. A deny immediately rejects execution.
5. An ask stores a pending request and publishes permission.asked.
6. The TUI, mobile app, or API client lists pending requests and sends a reply.
7. The reply publishes permission.replied and resolves, rejects, or persists approvals.

Always approvals

Always approvals are scoped to the current project id. They are not written into nikcli.json. They live in the JSON storage service under a permission key and are loaded into the permission service state when the project instance starts.

Tool integration

Different tools provide different patterns and always scopes.

API and mobile approvals

Pending permissions are exposed by classic routes and typed HttpApi routes. Mobile routes expose the same request/reply behavior inside the session composer approval controls.

curl http://127.0.0.1:4096/permission

curl -X POST http://127.0.0.1:4096/permission/per_example/reply \
  -H "Content-Type: application/json" \
  -d '{"reply":"once"}'

Common policies

Failure modes

Source anchors