Asoba Asoba Open Source

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

PERMISSION EVALUATION ENGINE — deny > ask > allow > defaultMode Model Emits tool_use Block evaluatePermission(permissions, toolName, toolInput, phase) Explicit deny list? → return 'deny' (immediate block) Explicit ask list? → return 'ask' (prompt human) Explicit allow list? → return 'allow' (execute) no explicit list match → check Phase & defaultMode SDLC Phase Overrides & defaultMode default · bypassPermissions · dontAsk · acceptEdits · plan deny Error returned to model transcript ask Prompt TUI · BlockConfirmMenu allow Execute immediately in-process PHASE OVERRIDE: create_tests · implement · verify · safety All execution tools are auto-allowed during approved execution phases (human plan gate already passed) lib/permissions.mjs · evaluatePermission() · cacheSessionApproval()

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:

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:


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:

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;