Permissions

AI agents can take potentially destructive actions — editing files, running shell commands, making network requests. The permissions system lets you decide how much autonomy to grant an agent, and how much oversight you want to exercise.

The mental model

When an agent wants to use a tool (e.g. write to a file or run a bash command), it does not act unilaterally. It sends a permission request to Magia via a Unix socket. Magia evaluates the request against the active preset and tool-level overrides, then either auto-approves it, auto-denies it, or surfaces a dialog for the user to decide in real time.

This flow is only active for providers that support the permissions capability (currently Claude Code). Other providers (Gemini CLI, Codex CLI) use their own sandboxing mechanisms and are not routed through Magia’s permission dialog.

Permission presets

The global preset is set in Settings → Permissions and applies to all new sessions. Six presets are available:

Preset	Behaviour
default	Standard Claude Code behaviour — the agent asks before any write/execute action.
acceptEdits	File edits are auto-approved; shell commands still prompt.
dontAsk	All tool calls are auto-approved without prompting. Use when you trust the task completely.
plan	Read-only mode — the agent can read files and browse but cannot write or execute.
auto	Magia decides based on the tool’s risk level.
bypassPermissions	Disables the permission handler entirely; the agent runs with no oversight layer.

The default preset for new installations is default.

Per-tool auto-approve overrides

In addition to the global preset, individual tools can be configured for automatic approval regardless of the preset. Each override is a ToolPermission record:

interface ToolPermission {
  toolName: string;   // e.g. "Bash", "Edit", "Read"
  autoApprove: boolean;
}

These overrides are stored in toolPermissions in settings and are evaluated before the preset. If autoApprove is true for a tool, Magia approves it immediately without showing a dialog.

Session-scoped approvals

When a user approves a tool call in the permission dialog, they have the option to approve “just this once” or “for this session”. Session-scoped approvals are stored in session.sessionAllowedTools (an array of tool names). They are applied for the remainder of the session and cleared when the session ends or is restarted.

Session-scoped approvals have lower precedence than the global toolPermissions overrides but higher precedence than the preset’s default behaviour.

How a permission request flows

1. The agent (Claude Code) calls the registered MCP tool mcp__magia-permissions__permission_prompt when it wants to perform an action.
2. The MCP permission handler (a Node.js sidecar) connects to Magia’s permission Unix socket ($TMPDIR/magia-{uid}/permissions.sock) and sends a JSON payload containing the tool_name, tool_use_id, and tool_input.
3. The Rust permission listener receives the request, generates a unique request_id, and emits a permission.requested Tauri event to the frontend.
4. The React UI displays a permission dialog showing the tool name and its parameters.
5. The user clicks Allow or Deny (or the session’s auto-approve rules resolve it without user interaction). The response is sent back via the respond_permission_request Tauri command.
6. Magia forwards the response over the same socket connection. The MCP handler receives it and returns the decision to Claude Code.
7. If no response arrives within 5 minutes, Magia automatically denies the request.

Permission request payload

The data shown in the permission dialog comes from the request payload:

Field	Description
tool_name	Name of the tool being invoked (e.g. Bash, Write, Edit)
tool_use_id	Unique identifier for this specific tool call
tool_input	The arguments the agent is passing to the tool

For Bash calls this includes the full command string. For Write / Edit this includes the file path and content.

Interaction with providers

The permission system is only available when capabilities.permissions is true for the provider. Currently:

• Claude Code — full permissions support via MCP hook injection
• Gemini CLI — uses its own --sandbox / --approval-mode yolo flags; not routed through Magia’s dialog
• Codex CLI — sandboxing is configured via codex.toml; Magia does not intercept individual tool calls

When a session is created with a non-Claude provider, the permission preset setting has no effect on the agent’s behaviour — it is stored but not enforced at the Magia level.

Changing permissions mid-session

The global preset and per-tool overrides can be changed at any time in Settings → Permissions. Changes take effect for the next permission request in any running session — there is no need to restart sessions.