Configure the gate

Auto Mode Gate reads policy from the host that loads the adapter. Restart or reload that host after changing a file.

Configuration paths

Scope	OpenCode	Pi
Global	`$OPENCODE_CONFIG_DIR/auto-mode-gate.json`	`$PI_CODING_AGENT_DIR/auto-mode-gate.json`
Global fallback	`~/.config/opencode/auto-mode-gate.json`	`~/.pi/agent/auto-mode-gate.json`
Project	`<project>/.opencode/auto-mode-gate.json`	`<project>/.pi/auto-mode-gate.json`

An empty or absent host root uses the fallback. A non-empty root must be an absolute path to an existing regular directory. Relative roots, symlinks, and non-directory roots fail closed. OpenCode never reads the Pi destination, and Pi never reads the OpenCode destination.

See Migrate configuration when upgrading from 0.2.0.

Global configuration

{
  "mode": "enforce",
  "shell": "powershell",
  "trustedExecutablePaths": [
    "C:\\Windows\\System32\\where.exe",
    "C:\\Program Files\\Git\\cmd\\git.exe"
  ],
  "permissionJudge": {
    "enabled": true,
    "model": {
      "provider": "example-provider",
      "id": "example-model"
    },
    "timeoutMs": 15000
  }
}

Key	Values	Meaning
`mode`	`off`, `shadow`, `enforce`	Controls whether denied actions block. Defaults to `enforce`.
`shell`	`bash`, `powershell`, `cmd`	Required before a Bash call can be allowed.
`trustedExecutablePaths`	Absolute path array	Exact authority for narrow read-only allowances.
`logPath`	Absolute file path	Optional sanitized JSONL decision log.
`permissionJudge`	Strict object	Global opt-in, default Pi model, and timeout from 1,000 through 120,000 ms.

Create the log directory before starting the host when logPath is configured.

Project configuration

{
  "mode": "enforce",
  "trustedExecutablePaths": [
    "C:\\Windows\\System32\\where.exe"
  ],
  "permissionJudge": {
    "enabled": false
  }
}

A project can tighten shadow to enforce, remove trusted paths, disable the judge, or reduce its timeout. It cannot enable a globally off gate, relax enforce, set the shell, add trust absent from the global file, set a log path, authorize the judge, change its model, or increase its timeout.

Each configuration file may contain at most 64 KiB, and each trusted-path list may contain at most 256 entries. Unknown keys, invalid JSON, relative file paths, oversized input, and unreadable files fail closed.

Pi judge preferences

Introduced in 0.4.0 and unchanged in 0.4.3, Pi stores user choices separately from policy in $PI_CODING_AGENT_DIR/auto-mode-gate-preferences.json, with ~/.pi/agent/auto-mode-gate-preferences.json as the fallback. The file persists requested Auto, an optional judge-model override, an optional thinking override, and shortcuts.

Preferences do not authorize the judge and have no project variant. Global permissionJudge.enabled: true and its model remain the authority; project policy can still disable the capability. Use the Pi judge controls instead of editing the preference file by hand when Pi TUI or direct commands are available.

Modes

enforce: denied actions block.
shadow: policy and logs run, but actions do not block.
off: the adapter remains loaded but does not block.

shadow is an observation mode, not a security control.