Permissions and posture

Configure two independent safety controls:

1. Permissions decide whether a tool call is allowed, needs approval, or is denied before it runs.
2. Guardrails are an optional model-backed checker that inspects selected tool arguments and results. They are independent of the permission rules.

Permissions always apply. Guardrails require an operator-configured checker model.

For a custom authorization implementation, see PermissionPolicy.

Availability

Permissions and posture apply to mecated, mecak8s, mecatequi, and the embedded server hosted by mecatui. A connected mecatui uses the posture and permission configuration of the remote server; local embedded-server flags do not apply to connect sessions.

Interactive clients such as mecatui can answer approval requests. For headless servers and one-shot jobs, configure the permissions required by the workload before it starts.

Choose a posture

--posture selects the operator posture ladder:

Posture	Behavior
strict	Default for interactive mecated; read-only calls are allowed and mutating calls use the permission rules, normally asking before they run. Project trust is not granted by the posture.
trusted	Interactive roots admit trusted project instructions and project permission allows, but mutating calls still use the normal approval rules.
auto	Enables the allow-all posture for the main agent and children while keeping deny rules and deliberately configured asks effective. Child substitution defenses remain enabled.
yolo	Extends auto by allowing child command substitutions, backticks, and heredoc-style substitutions that auto keeps behind the child safety floor. The main session also accepts external relative ../ paths for Read, ListDir, Write, and Edit. Use only for isolated, disposable, single-tenant deployments.

--yolo, --trust-project, and operator-global posture: settings can raise the posture tier; the highest tier wins. A project file cannot raise it.

Deployment defaults differ: mecated is interactive and defaults to strict, while unattended mecak8s and mecatequi deployments commonly select auto. Check the individual command's help before assuming a default.

For example:

# Interactive, fail-closed default.
mecated serve --posture strict

# Unattended single-tenant deployment; review the trust implications first.
mecated serve --headless --posture auto

Allow-all postures are refused when running as root unless the deployment explicitly declares an isolated sandbox with MECATL_SANDBOX=1 or IS_SANDBOX=1.

A main-session external path can be addressed absolutely at any posture, subject to its escape permission decision. Only yolo also serves external relative ../ paths for Read, ListDir, Write, and Edit; below yolo, those relative paths remain workspace-confined even after approval. Configured denies and asks still apply. Pseudo-filesystems (/proc, /sys, /dev) are never served through these tools. Children, namespace tools, Glob, and Grep remain confined to the workspace; symlink escapes are not a substitute for ../.

Choose a permission mode

A permission mode controls one session. It works alongside the deployment posture and configured rules.

Mode	Behavior
default	Uses the normal permission policy: read-only work is usually allowed, while operations that can mutate state normally ask first.
plan	Exposes a read-only toolset so the model can inspect the workspace and prepare a plan without changing it.
accept-edits	Automatically allows Edit and Write when they would otherwise hit only the built-in approval floor. Shell commands and other tools still use the normal policy, and configured asks and denies still win.

In mecatui, press shift+tab to cycle the active session through default → plan → accept-edits → default. You can remap the ModeSwitch action in the client keymap or with --keymap; see Keybindings.

To select the initial mode when launching mecatui, use --mode:

mecatui --workspace "$PWD" --mode plan
mecatui --workspace "$PWD" --mode accept-edits

The header displays the active mode. Changing modes does not bypass configured permission rules or guardrails.

Approve and constrain work

The built-in permission floor allows read-only exploration and asks before operations that can mutate state:

Default effect	Tools
Allow	Read, ListDir, Grep, Glob, WebFetch, WebSearch, and read-only Subagent exploration
Ask	Shell, Edit, Write, Team, and SkillDraft

A matching deny always wins. Otherwise an ask wins over an allow, and higher configuration scopes break ties. A configured allow can loosen only the built-in default ask; it cannot suppress a configured ask or any deny.

When a call is denied, the model receives a reason and can adapt. When a call needs approval, an interactive client shows the call and lets the operator:

• allow this call once;
• allow the matching call for the session; or
• deny it.

An allow-always decision never overrides a deny or configured ask. Headless deployments have no human approval channel, so configure their required access before starting work.

Plan mode

Plan mode denies Edit, Write, and mutating Shell commands. Read-only exploration remains available so the model can inspect the workspace and prepare a plan. For each current presentation, the model calls PresentPlan once and stops for review before leaving plan mode. Choosing iterate/deny ends that run; your next prompt supplies feedback, and a revised or unchanged plan requires a new PresentPlan call and fresh approval. Later chat assent never starts execution by itself.

In mecatui, Esc from the plan review means iterate/deny. The guarded Ctrl+C quit path instead cancels the run; it is not a neutral dismissal and does not record a deny verdict. The next prompt recovers the cancelled session, which remains in plan mode, before a fresh plan review can be presented. Hiding a client review does not itself clear an ask that remains pending on the server. Headless plan approval is denied by default; --plan-mode-auto-approve is an explicit operator opt-in and should be treated as an autonomous approval capability.

Configure permission rules

Permission configuration is available in YAML files with a permissions: section:

permissions:
  allow:
    - 'Read'
    - 'Shell(go test:*)'
  ask:
    - 'Shell(git push:*)'
  deny:
    - 'Shell(rm:*)'
  subagent:
    deny:
      - 'Shell(gh pr merge:*)'
    allow:
      - 'Shell(go vet:*)'

Rules use Tool(pattern) syntax. A bare tool name applies to the whole tool; patterns use shell-style glob matching. The permissions: section parses strictly, so a misspelled key causes the file to be skipped rather than silently changing the policy.

The configuration scopes, from highest to lowest precedence, are:

1. managed policy;
2. explicit --permission-config files;
3. .mecatl/settings.local.yaml;
4. .mecatl/settings.yaml;
5. the user-global settings.yaml; and
6. the built-in default floor.

Project permission files are resolved per session against that session's workspace. Project deny and ask rules remain effective, but project allow rules require project trust.

Use --import-claude-permissions to import supported rules from Claude Code settings.json. The import is lossy and fail-safe: unsupported or ambiguous rules are dropped or demoted to approval rather than widening access.

Delegated authority

Each child receives an authority set that can only narrow the parent's capabilities. The child runtime posture, an operator-owned specialist ceiling, and call-level restrictions can remove capabilities. A child cannot regain a capability omitted by its parent. Derivation consumes one remaining delegation hop before allocating the child runtime. The child persists its derived set; resuming checks that it remains contained by the current parent's authority, without consuming another hop.

An agent definition's tools: and disallowedTools: fields narrow that specialist. Definitions from an explicit operator --agents-dir can establish a durable ceiling; project and user definitions remain subject to the parent's authority.

mecated uses the local authority evaluator by default. The opt-in cedar evaluator can add denials based on operator-owned policy, but it cannot grant a missing capability. The explicit noop evaluator is intended for local or demo deployments. A bound session without its configured evaluator fails closed.

Cedar requires verified owner identity. Its operator-owned policy is loaded once at startup; an absent, unreadable, or invalid policy prevents startup. Permission policy and authority are independent checks: approving a tool call cannot restore a capability excluded from the child's set or denied by Cedar. See Configure a Cedar authority policy for the daemon setup and a workspace-boundary example.

MCP authority applies to the addressed tool, such as mcp__github__list_pull_requests, rather than granting access to an entire MCP server. Resource operations use a separate capability for each server; granting a tool does not grant access to that server's resources.

Project trust

Project trust controls whether Mecatl admits project-provided authority:

• permission allow rules;
• project instructions and rules;
• project skills, soul, and named agents; and
• the read-only child shell and workspace inspection posture.

Trust can come from an explicit operator flag, a trusted-workspace setting, an undrifted remembered trust decision, or the interactive posture floor. A headless root does not gain project trust merely because it uses trusted, auto, or yolo; it needs an explicit trust source.

On an untrusted headless checkout, --posture auto can allow admitted tools without loading project steering or enabling a read-only child shell. --trust-project asserts that you trust the repository and its .git metadata.

Guardrails

Guardrails add content inspection around selected tool calls. Configure a checker model to enable them:

mecated serve --guardrails-model gpt-5.6-luna

Binding the cheap model tier also enables guardrails when the guardrail slot has no binding of its own, because that slot falls back to cheap.

The checker reviews exact effective actions before execution and already-produced results before delivery. A configured checker with no custom rule list uses the expanded default enforcing set for Shell, local mutation/read/search, web, MCP, and delegation tools; the same applicable rules bind workers. Operators can configure advisory behavior instead. Guardrails remain active in headless deployments and are not a replacement for permission rules.

mecatui's /guardrails command shows the active checker and session-specific coverage. /posture reports permission posture and checker state separately, including off/setup guidance, advisory or enforcing when on, and unknown when an older or unavailable server cannot establish status. When a review needs your decision, the approval prompt shows its explanation. Action reviews offer Run once or Cancel, plus Don't ask again when the server can bind approval to that exact action in this session. Result reviews offer Release once or Cancel; release delivers the same held result without rerunning side effects. For conversation visibility and success diagnostics, see client debug surfaces.

Mode	Behavior
block	For action reviews, stops or asks before execution. For inbound reviews, withholds the result until release.
advisory	Reports a finding without changing the tool call or result.

The default rules cover Shell, local mutation and read tools, web, MCP, and delegation tools. A confidently read-only Shell command skips action review, but its result remains covered. An explicit rules list replaces the default set. Exact tool-name matches take precedence over prefix matches and the * wildcard.

A result review runs after the tool, so it cannot undo the operation. An enforcing result review holds the result before the client, model, or session history receives it. Releasing it delivers the same result without rerunning the tool or its side effects.

Each review has up to 90 seconds for evidence authorization, dependency snapshots, evidence preparation, and checker attempts combined. This limit uses cooperative context cancellation. A reviewer or I/O operation that ignores cancellation can return later, but a late acceptable result cannot approve an action or release a held result. Human approval waits and subsequent tool execution are outside the review limit.

Guardrail configuration is operator-tier only. A project repository cannot weaken or disable the operator's checker. Checker outage is fail-closed by default and is displayed as an operational failure, not an unsafe finding; operators may explicitly choose continue-with-warning. Checker-authored replacement actions are not supported.

Limitations

• strict preserves the built-in read-allow and mutate-ask floor.
• auto and yolo preserve denies and configured asks.
• Headless server deployments can leave main-session asks waiting for a client. mecatequi cancels its one-shot run when an ask surfaces. Headless child asks use the fail-safe child path instead of waiting for a client.
• Project files are untrusted by default. Do not enable project trust for a repository whose instructions, hooks, skills, or Git metadata you have not reviewed.
• Permission rules and guardrails are different controls: an allow does not disable guardrails, and a guardrail advisory does not change the tool's permission result.
• --posture, --trust-project, and permission configuration on a local mecatui invocation do not change a remote server used through connect.

Next steps

• PermissionPolicy to replace the supplied permission policy in an embedding.
• Project instructions and rules for project-ingestion behavior.
• Execution environments for workspace and shell isolation.