Skip to main content
This page describes how Process Manager permissions are configured, where the policy file lives, and how enforcement works for background commands.

​
File location

Process Manager policy is read from:
  • ~/.gg/process-permissions.json
If HOME is unavailable, the runtime cannot resolve this path and falls back to allow-all behavior.

​
Mode behavior

The runtime uses one of three modes:
  1. Allow all: file is missing.
  2. Allow only: file exists and is valid.
  3. Deny all: file exists but JSON/schema is invalid.
In deny-all mode, gg_process_run fails closed until the file is fixed.

​
Permissions file format

allow is required. cwd is optional. 
{
  "allow": [
    "cargo check",
    "cargo clippy *",
    "cargo test *",
    "bun run typecheck",
    "bun run test:run *",
    "npm run lint",
    "git status",
    "git diff *"
  ],
  "cwd": {
    "allow": ["./", "/scripts", "/packages/*", "~/code/*", "//tmp/gg-*"]
  }
}

​
Notes on this format

  • allow must be present and must be an array of non-empty strings.
  • cwd can be omitted entirely.
  • If cwd is omitted, all directories are allowed and only command rules are enforced.
  • If cwd is present, cwd.allow is required for that block and acts as an allowlist gate.
  • deny and cwd.deny are not currently supported in gg process permissions.
  • Unknown keys are rejected as invalid schema (fail-closed mode).

​
allow rules

allow is an array of command patterns:
  • Strings are trimmed before evaluation.
  • * is the wildcard and can appear anywhere in a pattern.
  • "*" allows all commands.
  • Empty strings are invalid.
  • Legacy :* syntax is rejected in gg config.

​
Command-chain behavior

Commands are evaluated segment-by-segment. Segments are split on:
  • &&
  • ||
  • ;
  • |
  • newline
Every executable segment must match at least one allow rule in allow-only mode. If one segment does not match, the whole command is denied.

​
Parse-ambiguity behavior

If command parsing is ambiguous, the runtime asks for approval and waits indefinitely for accept/decline. Examples of parse-sensitive constructs:
  • backticks
  • $()
  • subshell parentheses
  • unterminated quotes
  • trailing escapes

​
cwd.allow rules

cwd.allow is optional. If present, the effective working directory must match at least one pattern. Supported prefixes:
  • // absolute path from filesystem root
  • ~/ path under user home
  • / path relative to the session workspace root
  • ./ path relative to the current session cwd
If no cwd.allow pattern matches, command execution is denied.

​
How directory matching works

For each cwd.allow entry, gg resolves the pattern to an absolute path target and then checks the process cwd:
  1. Resolve pattern root from prefix (//, ~/, /, ./).
  2. If the pattern contains *, use wildcard matching on the full normalized cwd path.
  3. If the pattern has no wildcard, treat it as a directory prefix:
    • exact directory match is allowed
    • any subdirectory under that path is also allowed
Examples:
  • "/" allows the workspace root and anything below it.
  • "./" allows the session cwd and anything below it.
  • "//tmp/build-*" allows /tmp/build-1 and /tmp/build-abc, but not /var/tmp/build-1.

​
Rule evaluation order

In allow-only mode, checks run in this order:
  1. Parse and validate permissions file.
  2. If cwd.allow exists, enforce cwd allowlist first.
  3. Parse command into executable segments.
  4. Evaluate each segment against allow patterns.
Important behavior:
  • If file parsing/schema fails, mode becomes deny-all-invalid-json.
  • If command parsing is ambiguous, runtime requests explicit approval.
  • A single non-matching command segment denies the full command.
  • There is currently no deny phase because deny lists are not part of gg process-permissions syntax.

​
Denial detail codes

When permission checks fail, errors include structured detail codes for UI/tool guidance:
  • invalid_permissions_file
  • command_not_allowed
  • cwd_not_allowed
  • parse_approval_declined

​
Process tools (agent API)

Process Manager runtime tools:
  1. gg_process_run
  2. gg_process_status
  3. gg_process_kill
Permission policy applies to gg_process_run before process spawn.