Policy layer: deterministic pre-execution rules alongside annotation-based approvals

[cschanhniem]

Summary

The annotation-based approval model in PR #104 is a strong foundation for tool-level gating. This issue explores adding a complementary file-pattern + action-type policy layer that operates deterministically before tool dispatch.

Motivation

Annotations couple approval logic to tool definitions. This works when the tool author knows what needs approval. But there are cases where:

1. The repo maintainer (not the tool author) wants to gate specific file patterns from tool access — e.g. "no agent may read .env files" regardless of what the tool annotation says
2. Different repos have different risk tolerances for the same tool — a monorepo might want shell_execute to always require approval in packages/infra but allow it in packages/docs
3. CI/CD enforcement needs version-controlled, reviewable policy that lives alongside code — not in a runtime annotation

Proposal

A repo-local policy file (e.g. .agentowners.yml or .acp.yml) that declares rules evaluated deterministically at the dispatch boundary:

rules:
  - patterns: ["**/.env*", "**/secrets/**"]
    actions: [file_read, file_write, shell_execute]
    decision: block
    reason: "Sensitive files must not be accessed by agents"

  - patterns: ["**/*.md", "**/docs/**"]
    actions: [file_write]
    decision: allow

Rules are evaluated in order (first match wins) with priority block > require_approval > allow. The evaluation is deterministic — no LLM in the enforcement path.

Relationship to annotations

Annotations remain the default signal. Policy rules act as overrides:

1. Tool dispatches → check policy rules → if no rule matches, fall through to annotation-based approval
2. Policy block overrides any annotation
3. Policy require_approval overrides annotation ReadOnlyHint

This creates a layered governance model: repo-level policy for structural invariants, tool-level annotations for operational defaults.

Related work

AGENTOWNERS (https://github.com/csanhniem/AGENTOWNERS) explores the file-pattern + action-type policy model deterministically. The ACP could either consume .agentowners.yml natively or adopt a similar schema.

Curious if this layering (policy rules → annotations → execution) fits the ACP architecture or if there is a simpler integration path.