Permissions & Safety Governance
Every tool call the model produces passes through the permission gate before execution. The gate evaluates the tool name, active SDLC phase, and session-level approval cache to return one of three decisions: allow, deny, or ask.
When commands violate system boundaries, the interactive safety system intercepts execution and surfaces the BlockConfirmMenu, providing instant escalation to an isolated OS-primitives sandbox.
How Permission Evaluation Works
The evaluation order is strict: deny > ask > allow > defaultMode. If a tool matches the deny list, it is always blocked regardless of the default mode.
Permission Modes
The defaultMode setting controls the fallback behavior when a tool doesn’t match any explicit list:
default (recommended)
The standard mode. Read-only and informational tools are auto-allowed; mutating actions require human confirmation:
| Tool | Decision |
|---|---|
Read, Glob, Grep, WebFetch, WebSearch, ToolSearch, ListMcpResources, ReadMcpResource, AskUserQuestion, Brief, TodoWrite, TaskOutput, TaskStop, Skill |
allow (auto-allowed) |
Write, Edit, Bash, NotebookEdit, Agent, EnterWorktree, ExitWorktree, MCP tools |
ask (prompt user) |
acceptEdits
File editing tools (Read, Write, Edit) are auto-allowed to streamline code writing. Terminal executions (Bash) and external MCP tools continue to require confirmation.
plan
Mutating tools (Write, Edit, Bash, NotebookEdit) are denied. Read-only tools are allowed.
dontAsk
All tools that would normally prompt (ask) are denied. Only safe, read-only tools operate.
bypassPermissions
All tools are auto-allowed across all phases. Use strictly in automated CI pipelines.
Phase-Aware Overrides
During approved execution phases of the SDLC, the user has already explicitly vetted the issue and approved the Plan Triad. Prompting on every file edit or test command would be redundant and disrupt test runners.
In lib/permissions.mjs:
// In execution phases the operator already approved the plan — auto-allow execution tools
if (phase === 'create_tests' || phase === 'implement' || phase === 'verify' || phase === 'safety') {
return 'allow'
}
In other phases:
idle: Free-form exploration mode (mutatingBashcommands refused).explore: OnlyRead,Glob,Grepare allowed. Mutating tools return a phase-mask error.diagnose: Read-only analysis.create_issue: Writes restricted strictly to the.issues/directory.planning: Zero tools available (model emits structured text plan only).
Interactive Safety: The BlockConfirmMenu
When static analyzers or bashguard detect high-risk operations (such as opening network listening sockets, touching host credential paths, writing outside the working directory, or running unvetted shell scripts), execution pauses.
Rather than aborting, the TUI displays the interactive BlockConfirmMenu:
⚠️ Blocked Command: bash -c "npm test -- --watch"
Reason: Background watcher command detected outside approved pipeline.
Risk Score: 0.85
[A] Approve for Session
[S] Run in OS Sandbox
[C] Cancel
1. [A] Approve for Session
Approves the operation and records the approval in an in-memory session cache (cacheSessionApproval). Subsequent calls with the same signature in the same REPL session execute without re-prompting.
2. [S] Run in OS-Primitives Sandbox
Confines execution to an ephemeral, disposable project snapshot:
- macOS: Enforced via
/usr/bin/sandbox-execusing Apple Seatbelt with a deny-default sandbox profile. - Linux: Enforced via
bubblewrap(bwrap). - Isolation Guarantees:
- File writes are confined strictly to a disposable temporary project copy (capped at 256 MiB / 10,000 entries; credential and dependency paths omitted).
- Direct network egress is blocked by default.
- Host credentials (
~/.ssh,~/.aws, tokens) are never forwarded. - Changes are automatically discarded after execution.
- Optional Allowlist Proxy: To permit access to designated package hosts from inside the sandbox, export
NEHANDA_SANDBOX_ALLOWLIST:export NEHANDA_SANDBOX_ALLOWLIST="registry.npmjs.org,github.com"The sandbox routes outbound traffic through an internal unix-domain-socket forward proxy (
NEHANDA_SANDBOX_PROXY_SOCKET), refusing all other destinations.
3. [C] Cancel
Immediately cancels execution and feeds a clean cancellation result back to the model.
Canonical Documentation Approvals
During repository exploration, models frequently re-examine canonical architecture files (docs/MAP.md, README.md, schema.sql).
Nehanda registers successful inspections in cacheCanonicalReadApproval(sessionId, canonicalPath). Once verified during exploration, subsequent inspections of these canonical documentation paths bypass repetitive confirmation prompts.
Audit Logging
Every permission evaluation is durably logged to the tool_permission_log table in ~/.config/nehanda/ona-session.db:
SELECT tool_name, decision, created_at
FROM tool_permission_log
ORDER BY created_at DESC
LIMIT 20;