> ## Documentation Index
> Fetch the complete documentation index at: https://goldengoose.zue.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Process Manager

> Permissions file format, matching rules, and process-manager APIs.

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.

```json theme={null}
{
  "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.