Tool Permissions & Security

While Elftia's Agent system grants AI powerful execution capabilities, it also provides a multi-layer security protection mechanism. This page details permission modes, tool sensitivity classification, the confirmation dialog flow, and how each security layer works.

Permission Modes

The permission mode determines the security level when an Agent executes tools. It is set via the permissionMode field in the Agent configuration.

Mode Overview

Mode	ID	Behavior	Best For
Default	default	Sensitive tools require the user to confirm each time	Daily use; security first
Accept Edits	acceptEdits	File reads and writes are approved automatically; Shell/MCP tools still require confirmation	Coding scenarios where file operations are trusted
Bypass Permissions	bypassPermissions	All tools execute automatically	Fully trusting the Agent
Plan	plan	Only read-only tools are permitted	Information gathering, analysis, planning

Mode Behavior Comparison

Tool	default	acceptEdits	bypassPermissions	plan
Read / Glob / Grep	Auto	Auto	Auto	Auto
Write / Edit	Confirm	Auto	Auto	Blocked
Bash	Confirm	Confirm	Auto	Blocked
spawn_agent	Confirm	Confirm	Auto	Blocked
MCP tools	Confirm	Confirm	Auto	Blocked
WebSearch / WebFetch	Auto	Auto	Auto	Auto

Tools Allowed in plan Mode

In plan mode, only the following read-only tools are permitted:

• Read — read files
• ListDir — list directories
• Glob — file matching
• Grep — content search
• WebSearch — web search
• WebFetch — fetch web pages
• list_skills — list skills
• read_skill — read skills

Tool Sensitivity Classification

The TinyElf engine classifies tools into two categories: safe tools and sensitive tools.

Safe Tools (Never Require Confirmation)

Tool	Description
Read	Read file contents
ListDir	List directories
Glob	Filename pattern search
Grep	File content search
WebSearch	Web search
WebFetch	Fetch web content
list_skills	List available skills
read_skill	Read skill content
Notify	Send desktop notifications
SessionsYield	End the Agent loop
SessionsHistory	View session history

Sensitive Tools (Confirmation Depends on Permission Mode)

Tool	Risk Description
Bash	Can execute arbitrary shell commands
Write	Can create or overwrite files
Edit	Can modify existing file content
spawn_agent	Can launch sub-Agents to execute tasks
MCP tools (mcp__*)	External tools with unpredictable behavior

:::info MCP Tools Are Sensitive by Default All MCP tools are treated as sensitive tools by default. This is because MCP tools come from external servers whose behavior cannot be pre-audited by Elftia. :::

Confirmation Dialog Flow

When an Agent attempts to use a sensitive tool (in a permission mode that requires confirmation), the system presents the user with a confirmation dialog.

Desktop Mode Flow

Agent requests to execute Bash("npm test")
     ↓
System sends a permission request (IPC: permissionRequest)
     ↓
Frontend displays confirmation dialog:
  ┌─────────────────────────────┐
  │  Bash: npm test             │
  │                             │
  │  [Allow] [Deny] [Allow for Session] │
  └─────────────────────────────┘
     ↓
User chooses → result returned to the Agent

User Options

Option	Behavior
Allow	Approve this one execution
Deny	Deny this execution; Agent receives a rejection notification
Allow for Session	Approve this time, and auto-approve subsequent calls to the same tool within the session

Session-Level Tool Allowlist

After selecting "Allow for Session," the tool name is added to the current session's allowlist. Subsequent calls to the same tool will be approved automatically without further confirmation. The allowlist is cleared when the session ends.

Timeout Handling

If the user does not respond to the confirmation dialog within 5 minutes, the system automatically denies the request.

Three-Layer Security Protection

The TinyElf engine implements a three-layer security protection pipeline, executed in the following order:

Tool call request
     ↓
[Layer 1] ExecutionFirewall — path and command validation
     ↓ (pass)
[Layer 2] GuardianAgent — AI security assessment
     ↓ (pass)
[Layer 3] Permission Callback — user confirmation
     ↓ (pass)
Execute tool

If any layer denies the request, tool execution terminates immediately.

Layer 1: ExecutionFirewall

ExecutionFirewall is a deterministic security gateway that blocks access to sensitive system files and directories based on path rules.

Blocked path types:

Path Type	Example	Operations
System directories	C:\Windows\, /etc/, /usr/	Read and write both blocked
Program directories	C:\Program Files\, /sbin/	Read and write both blocked
Credential files	.ssh/, .aws/, .gnupg/	Read and write both blocked
SSH keys	id_rsa, id_ed25519	Read and write both blocked
Environment variables	.env, .env.production	Read and write both blocked
Browser data	Chrome/Firefox/Edge user data	Read and write both blocked
Registry	System32\config\SAM etc.	Read and write both blocked
Config files	.gitconfig, .bashrc, .npmrc	Readable, not writable

Layer 2: GuardianAgent

GuardianAgent uses an LLM to perform security assessments of tool calls. It is optional and enabled via configuration.

Operating modes:

Mode	ID	Behavior
Off	off	Disabled (zero overhead)
Monitor	monitor	Reviews sensitive tools; logs only, does not block
Guard	guard	Reviews sensitive tools; blocks high and critical risk
Strict	strict	Reviews all tools; blocks medium risk and above

Risk levels:

Risk Level	Meaning	Example
none	Completely safe	Reading files within the workspace
low	Low risk	Writing project files
medium	Medium risk	Installing npm packages, modifying state
high	High risk	Accessing sensitive paths, network operations
critical	Critical risk	rm -rf, privilege escalation, data exfiltration

Critical rules (always flagged as high/critical):

• File deletion outside the workspace
• Recursive deletion commands
• System directory operations
• Privilege escalation (sudo, runas)
• Pipe execution (curl | sh)
• Credential access or exfiltration
• Bypassing security features

Error handling strategy:

Mode	Behavior on timeout/error
monitor / guard	Fail-open (allow execution)
strict	Fail-closed (deny execution)

Layer 3: Permission Callback

The final layer is user confirmation, which sends a confirmation request to the frontend via an IPC message.

Channel Permission Gating

When an Agent receives messages via a Channel (Discord, Telegram, etc.), the permission confirmation flow differs.

Channel User Roles

Role	Tool Use	Confirmation Required
Admin	Permitted	Per permission mode
Member	Permitted	All tools require confirmation
Guest	Not permitted	Cannot use any tools

Channel Confirmation Flow

Confirmation in a Channel session is handled through Channel messages rather than desktop dialogs:

1. Agent requests to execute a sensitive tool
2. System sends a confirmation message to the Channel
3. User replies y (allow) / n (deny) / always (always allow)

Scope of "Always Allow":

The scope of the always reply is bounded by the combination of "tool name + argument fingerprint." For example:

• Allowing Bash: npm test does not automatically allow Bash: rm -rf /
• Each distinct command/path combination requires separate authorization

Timeout handling: Auto-denies after 5 minutes of no response. A maximum of 5 pending confirmation requests can exist simultaneously per Channel.

Audit Log

All security-related events are recorded in the audit log for retrospective tracing.

Event Type	Description
firewall_block	Access blocked by ExecutionFirewall
guardian_review	GuardianAgent review result
permission_granted	User approved tool execution
permission_denied	User denied tool execution
permission_timeout	Confirmation timed out; auto-denied
command_blocked	Shell command blocked by blocklist
injection_detected	Prompt injection detected
rate_limited	Rate limit triggered

FAQ

Problem	Cause	Solution
Constant confirmation prompts are annoying	Permission mode is default	Set to acceptEdits or bypassPermissions
Firewall blocked a legitimate operation	The operation involves a system path or credential file	This is expected behavior; system files should not be modified
GuardianAgent incorrectly blocked a safe operation	Assessment is overly conservative	Change the mode from strict to guard
Channel user cannot use tools	User role is "Guest"	Promote the user to "Member" or "Admin"
Session allowlist suddenly stopped working	Session ended and restarted	Session allowlists do not persist across sessions; re-authorize
Cannot edit files in plan mode	plan mode only allows read-only tools	Switch to default or acceptEdits mode

Related Links

• Agent Overview — Agent system overview
• Creating Custom Agents — Configure permission modes
• Skill System — Tool allowlist in skills