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 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.

Default Tool Permissions¶

The optional LSP plugin registers read-effect semantic tools with Allow in Normal, Plan, and Apply. rename_symbol has write effect, so its defaults are Allow in Normal, Deny in Plan, Ask in Apply, and Allow in Yolo.

Plan mode is built in. It ships with a read-only default policy and adds the present_plan tool. Read-only tools stay allowed, enter_worktree and unknown or networked tools require confirmation, and write/process/config effects are denied without prompting. switch_cwd is therefore denied even though the more constrained enter_worktree has an explicit Ask rule. Your config can extend these defaults.

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¶

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 leak into sibling worktrees. Repository rules are loaded alongside the exact CWD's rules in every worktree. Both stay narrow: approving a command pattern only approves matching calls, and approving an outside directory only approves access under that directory.

Running smelt sessions refresh persisted approvals when they evaluate a tool call. A workspace or repository approval added or removed in one session therefore takes effect for the next matching tool call in every other running session with that scope. Repository approvals propagate across sibling Git worktrees. The two stores are loaded independently: if one is malformed or unreadable, that scope fails closed without discarding valid approvals from the other scope or from the current session.

Managing Saved Approvals¶

Use /permissions to view and remove session, workspace, and repository approvals. Each entry is labeled with its scope. Deletions are persisted immediately and transactionally, so an older open dialog cannot overwrite approvals added by another smelt session.

The Lua API applies the same protection to full replacements. smelt.permissions.list() returns a revision for each persisted scope. smelt.permissions.sync() requires the matching revision, rejects stale snapshots, and accepts at most one persisted scope per call. This prevents concurrent grants from being lost and prevents a failed second write from leaving an implicit cross-scope update half applied.

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 of the permission state unchanged. Pass an empty array explicitly when you intend to clear session entries or path grants.

• j/k to navigate
• dd or Backspace to delete the highlighted entry
• Esc to 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. 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, keyed by canonical project path. 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 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.