Process Manager

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 mode 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 exposes one gg_process tool with run, list, status, and cancel modes. Permission policy applies to run mode before process admission.