Permissions Reference¶

The permission system controls what the agent can do without asking. Each mode has its own rules, and the prompt that appears when a tool is gated offers several scopes for approving the call.

How Rules Work¶

Permissions are split between tool-level rules and subcommand-level rules. The tool name (bash, edit_file, web_fetch, …) decides whether the call needs gating at all; subcommand buckets (bash, web_fetch, mcp, and any tool that registers its own bucket) further refine the decision based on the call's arguments.

Each rule list has three slots:

• allow — execute silently
• ask — prompt for confirmation
• deny — block (deny always wins over allow and ask)

Patterns are globs. For subcommand rules, the most specific (longest) matching pattern wins; on a tie, ask beats allow. Anything not matched defaults to Ask in Normal/Plan/Apply or Allow in Yolo.

Default Tool Permissions¶

— = not registered in that mode.

Default Bash Patterns¶

Read-only commands with no side effects are allowed by default. Commands that can modify files, install packages, or affect system state require approval.

Compound commands split on shell operators (&&, ||, ;, |) are evaluated per subcommand; the worst decision wins, and a single deny blocks the whole command. cd is always allowed.

Configuring Permissions¶

Set rules in init.lua with smelt.permissions.set_rules:

smelt.permissions.set_rules({
  default = {
    tools = {
      allow = { "web_search" },
    },
    web_fetch = {
      allow = { "*" },
    },
    bash = {
      allow = { "git log *", "git diff *" },
    },
  },
  apply = {
    bash = {
      allow = { "git commit *" },
    },
  },
})

default applies to all modes. Mode-specific rules (normal, plan, apply, yolo) are merged on top: their allow/ask/deny lists are appended to the default lists. Since deny always wins, a mode-level deny overrides a default-level allow for the same entry.

Each mode table can contain:

Any key other than tools is treated as a subcommand bucket and routed through that tool's parser. Built-in buckets are bash (shell-aware parsing), web_fetch (URL glob), and mcp (matched against servername_toolname); tools that register their own bucket appear here too.

The Permission Prompt¶

When a call is gated, a confirm dialog appears with the tool summary, a preview (when available — e.g. a diff for edit_file), and these options:

<pattern> is the tool-specific approval pattern (e.g. a shell command stem like git status for bash, or a URL host for web_fetch). When the call touches a path outside the workspace, the dir-based options (allow <dir> / allow <dir> in cwd) appear instead.

Press e to add a freeform reason that the model will see along with your decision.

Approval Scopes¶

The "always allow" options above approve future calls at one of two scopes:

Workspace approvals stay narrow: approving a command pattern only approves calls matching that pattern, and approving an outside directory only approves access under that directory.

Managing Saved Approvals¶

Use /permissions to view and remove session/workspace approvals:

• j/k to navigate
• dd or Backspace to delete the highlighted entry
• Esc to close (changes are persisted on close)

Workspace Restriction¶

When restrict_to_workspace is enabled (default), any tool call targeting a path outside the current workspace has its decision downgraded from Allow to Ask — even if the call would otherwise have been auto-approved by tool, bash pattern, or runtime approval. The prompt then offers per-directory approval options.

Project Trust¶

.smelt/ content (init.lua, plugins/, commands/, runtime/) is only loaded after the user explicitly trusts the project. Run /trust from the project root to record a SHA-256 hash of the current .smelt/ contents; on next startup smelt loads the directory if the hash still matches. Editing any trusted file invalidates the hash and requires re-running /trust.

Trust state is stored in $XDG_STATE_HOME/smelt/trust.json, keyed by canonical project path. See smelt.trust for the Lua API.

Secret Redaction¶

When redact_secrets is enabled (default), smelt scrubs detected secrets from user-submitted text and tool output — including command lines and file contents shown in the confirm prompt — before they reach the LLM or the transcript. Disable it with:

smelt.settings.redact_secrets = false

Headless Mode¶

In --headless, there is no interactive prompt: calls that would be Ask are denied. To run autonomously, combine headless with --mode yolo. See the Headless Mode guide.

Isolation¶

Permissions and workspace restriction guard against accidental mistakes, not against an agent that actively tries to escape. Any approved bash command runs with your user's privileges, so a script like rm -rf ~ works exactly as it would if you typed it yourself.

For untrusted prompts, models, or MCP servers, run smelt inside a container or VM. Anything else is defense in depth, not a sandbox.