Skip to content

Permissions

Permissions control which tools and operations AI agents are allowed or denied. They live in .agentsmesh/permissions.yaml.

File format

allow:
- Read
- Grep
- Glob
- Bash(pnpm test:*)
- Bash(pnpm build:*)
- Bash(git add:*)
- Bash(git commit:*)
- Bash(git status)
- Bash(git diff)
- Edit
- Write
deny:
- WebFetch
- Bash(curl:*)
- Bash(wget:*)
- Bash(rm -rf:*)
- Read(.env)
- Read(.env.*)
ask:
- Bash(git push:*)
- Bash(npm publish:*)

Three lists are supported: allow (run without prompting), deny (always blocked), and ask (prompt the user before running, where the tool supports it).

Managed and unmanaged lists

AgentsMesh manages each list on its own:

  • A list in the file is managed. generate writes it to each tool in place of the tool’s own list. An empty list (deny: []) is managed too. It means “none”, but some tools skip an empty list instead of writing it, so their own list stays there.
  • A missing list is unmanaged. This includes a list that is commented out, and a key with no list under it (deny: alone). generate leaves the tool’s own list as it is.
  • No list at all (no file, an empty file, or the init template with every list commented out) means AgentsMesh manages no permissions. Every tool keeps its own.
  • Import never starts managing an empty list. If a tool has no deny list, agentsmesh import (and convert) does not add deny: [], so your other tools keep their own deny lists. A list the file already manages, even [], stays managed.
# Manage allow only. Each tool keeps its own deny and ask lists.
allow:
- Read
- Bash(pnpm test:*)

To stop managing a list, delete it or comment it out. generate then leaves that list alone in every tool, including the entries it wrote there before. A list that an extends source or an installed pack brings in counts as managed too.

Tools that keep all lists in one place

Most tools keep allow, deny and ask in separate settings, so an unmanaged list is simply not written. Some tools keep all three in one structure, where each entry carries its decision:

  • Your entries stay. Kimi Code and Kiro (~/.kiro/settings/permissions.yaml) keep your rules for an unmanaged list. OpenCode, Trae and Gemini CLI never remove entries that AgentsMesh did not write.
  • The structure is rebuilt. Augment Code (toolPermissions), Kilo Code (permission), Rovo Dev (toolPermissions), Zed (agent.tool_permissions) and Junie (the executables allowlist) rebuild that structure from permissions.yaml whenever AgentsMesh writes permissions to them. The tool’s own entries for an unmanaged list can be lost there. To keep them, add them to permissions.yaml first, for example with agentsmesh import.

Files that only AgentsMesh writes (such as the Codex CLI rules file) hold just the managed lists.

Pattern syntax

Patterns support wildcards using :* suffix for Bash commands:

PatternMatches
ReadThe Read tool (any file)
Read(.env)Read of .env specifically
Bash(pnpm test:*)Any pnpm test:... subcommand
Bash(git:*)Any git command
Bash(rm -rf:*)Any rm -rf ... command
WebFetchAll web fetch operations

Permissions from packs and extends

Installed packs and extends sources can ship their own permissions.yaml. Their entries are added to the lists your own permissions.yaml manages, and an entry that is in both is kept once. Generate then writes those full lists to each tool, so an entry that is only in a tool’s own config can be dropped.

This works list by list. A pack’s deny list is used only if your own file has a deny list, and an empty one (deny: []) is enough. For a list your file does not manage (missing or commented out, as init scaffolds them), generate skips the pack’s entries and prints a warning, and that list in your tools stays as it is. To start managing your permissions, run agentsmesh import --from <tool> (add --global for ~/.agentsmesh) to copy in the permissions your tools already have, then run agentsmesh generate.

Tool-specific behavior

See the Permissions row in the supported tools matrix for per-target support levels (native, partial, or unsupported).

Locking permissions from accidental changes

Permissions often represent security boundaries. Use collaboration.lock_features to prevent them from being overwritten:

agentsmesh.yaml
collaboration:
strategy: lock
lock_features:
- permissions
- mcp

With permissions locked, agentsmesh generate will not regenerate the permissions config without --force.

allow:
- Read
- Grep
- Glob
- Edit
- Write
- Bash(git status)
- Bash(git diff)
- Bash(git add:*)
- Bash(git commit:*)
- Bash(git log:*)
- Bash(pnpm install:*)
- Bash(pnpm build:*)
- Bash(pnpm test:*)
- Bash(pnpm lint:*)
- Bash(pnpm typecheck:*)
deny:
- Bash(rm -rf:*)
- Bash(curl:*)
- Bash(wget:*)
- Bash(ssh:*)
- Bash(scp:*)
- Read(.env)
- Read(.env.*)
- Read(*.pem)
- Read(*.key)

This baseline allows common dev operations while blocking destructive commands and secret file access.