Permissions¶

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 exist so you can trade safety for speed. In a trusted codebase you might auto-approve every git command; on an unfamiliar repo you may want the agent to ask before every edit. The system lets you set these boundaries per mode, per tool, and per workspace.

Permissions are split between tool-level rules and pattern-level rules. The tool name (bash, edit_file, web_fetch, …) decides whether the call needs gating at all; pattern 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 pattern rules, the most specific (longest) matching pattern wins; on a tie, ask beats allow. Anything not matched falls back to tool, effect, and mode defaults.

Defaults¶

Each mode has built-in defaults for every tool and for common shell commands. Reading is always allowed; editing asks in Normal, is denied in Plan, and is allowed in Apply and Yolo. The full tables are in Permission defaults.

Configuring Permissions¶

Extend the generated policy in init.lua with smelt.permissions.extend:

smelt.permissions.extend({
  default = {
    tools = {
      allow = { "web_search" },
    },
    effects = {
      network = "ask",
      write = "ask",
    },
    patterns = {
      web_fetch = {
        allow = { "https://docs.rs/*" },
      },
      bash = {
        allow = { "git log *", "git diff *" },
      },
    },
  },
  apply = {
    patterns = {
      bash = {
        allow = { "git commit *" },
      },
    },
  },
})

default applies to all registered modes. Mode-specific rules are keyed by mode name (normal, apply, yolo, or plugin-registered names such as plan) and are merged on top of the generated base policy.

Each mode table can contain:

Pattern buckets are routed through the matching tool's parser. Built-in buckets include 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, for example 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 same scopes are offered for a directory prefix instead. The repository option appears whenever smelt can identify a Git repository root.

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

Approval Scopes¶

Approval options can apply at one of three scopes:

Workspace rules do not apply to sibling worktrees; repository rules apply to all of them. Approvals stay narrow: approving a command pattern only approves matching calls, and approving an outside directory only approves access under it.

Approvals take effect in other running smelt sessions for their next matching call, so removing one in /permissions revokes it everywhere. If a stored approval file is unreadable, that scope is treated as empty (calls ask again) and your other approvals are unaffected.

Managing Saved Approvals¶

Use /permissions to view and remove session, workspace and repository approvals. Each entry shows its scope. Deletions are saved immediately and never overwrite approvals another session added.

• j / k to navigate
• dd or Backspace to delete the highlighted entry
• Esc to close

From Lua, smelt.permissions.list() returns a revision per saved scope and smelt.permissions.sync() replaces one scope at a time, rejecting a stale revision so concurrent grants are not lost:

local permissions = smelt.permissions.list()
smelt.permissions.sync({
  workspace = {
    revision = permissions.workspace_revision,
    rules = permissions.workspace,
  },
})

Omit session, path_grants, workspace or repository to leave that part unchanged; pass an empty array to clear it.

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. This catches mistakes like the agent editing a file in your home directory when it meant to edit one in the project root. 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 trust.json in the state directory. See smelt.trust for the Lua API.

Secret Redaction¶

When redact_secrets is enabled, 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. This matters because LLM providers may log or train on prompts; redaction lowers the risk of accidentally leaking API keys or tokens into a third-party system. Enable it with:

smelt.settings.redact_secrets = true

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.

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.