# Policy Engine

## Overview

Aegis uses a YAML policy engine to authorize tool execution before any Gitea API call is made.

## Behavior Summary

- Global tool allow/deny supported.
- Per-repository tool allow/deny supported.
- Optional repository path allow/deny supported.
- Write operations are denied by default.
- Write operations also require `WRITE_MODE=true` and either:
  - `WRITE_REPOSITORY_WHITELIST` match, or
  - `WRITE_ALLOW_ALL_TOKEN_REPOS=true`.

## Example Configuration

```yaml
defaults:
  read: allow
  write: deny

tools:
  deny:
    - search_code

repositories:
  acme/service-a:
    tools:
      allow:
        - get_file_contents
        - list_commits
    paths:
      allow:
        - src/*
      deny:
        - src/secrets/*
```

## Failure Behavior

- Invalid YAML or invalid schema: startup failure (fail closed).
- Denied tool call: HTTP `403` + audit `access_denied` entry.
- Path traversal attempt in path-scoped tools: denied by validation/policy checks.

## Operational Guidance

- Keep policy files version-controlled and code-reviewed.
- Prefer explicit deny entries for sensitive tools.
- Use repository-specific allow lists for high-risk environments.
- Test policy updates in staging before production rollout.