Permissions

Two layers work together:

1. Permission mode — session posture (how often to ask, whether to bypass)
2. Declarative rules — settings.permissions.{deny,ask,allow}

Permission mode

forgeax --permission-mode default
forgeax --permission-mode acceptEdits
forgeax --permission-mode plan
forgeax --permission-mode bypassPermissions

Or in settings:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Resolution order: --permission-mode flag > settings.permissions.defaultMode > default.

Mode	Meaning (summary)
default	Standard ask policy
acceptEdits	More permissive toward edit-like ops
plan	Planning-oriented posture
bypassPermissions	Bypass normal prompts (dangerous; may refuse under root / killswitch)

Dangerous equivalent:

forgeax --yes    # auto-approve all permission prompts (= dangerously-skip); refused as root

Declarative rules

Syntax matches common coding-agent conventions: Tool or Tool(content).

{
  "permissions": {
    "deny": ["Bash(rm *)", "Write(/etc/*)"],
    "ask": ["Bash(git push*)"],
    "allow": ["Read", "Bash(git *)"]
  }
}

Engine order (strong → weak): deny → ask → … → allow.

Structure-aware shell matching

For Bash/Sh tools, content rules match subcommand structure, not the raw whole line:

• deny Bash(rm *) also catches echo x && rm -rf /
• allow Bash(git *) does not cover git status && rm -rf / (falls to ask / default)
• $() / backticks / subshells force ask

Invalid rule strings are dropped silently (fail-closed: never treated as allow).

OS sandbox

Permission rules constrain what the agent may request; --sandbox constrains where Bash children may write at the OS layer:

forgeax --sandbox

Writes are confined to cwd + temp; paths outside cwd are rejected by the OS; protected segments like .git / .forgeax stay read-oriented. Missing platform tools → loud degrade.

Practical guidance

1. Team-shared: put deny / baseline allow in .forgeax/settings.json
2. Local secrets and looser rules: settings.local.json
3. Headless CI: narrow allow + explicit --permission-mode; avoid --yes unless the runner is isolated
4. Treat deny as the non-bypassable last line of defense

Related

• Configuration
• CLI reference