policy: govern grapharc agent by policy document

[DhineshPonnarasan]

Summary

Closes #6.

This wires policy documents into the grapharc agent tool-execution path so --policy <doc.toml> governs the same PermissionPolicy boundary consumed by the agent harness.

---

What changed

• Load a PolicyDocument from --policy and compile it through PolicyEngine.permission_policy().

• Combine document policy with CLI --allow / --deny / --ask restrictions using a fail-closed, most-restrictive composition:

  • DENY > ASK > ALLOW
  • CLI flags can narrow document authority but cannot widen a document deny.

• Propagate the selected tenant into policy evaluation and reject undeclared tenants.

• Route document ask decisions through the existing approval boundary.

• Fail closed for document ask when running non-interactively / with JSON output.

• Preserve policy provenance including source, version, digest, tenant, and audit information.

• Record document-driven denials in the policy audit path while retaining run-trace visibility.

• Prevent policy-bearing runs from bypassing the governed path through claude-cli delegation.

• Keep denied tools out of the model-visible tool set.

• Add focused tests covering policy composition, tenant handling, approval behavior, audit/provenance, denied-tool visibility, and end-to-end CLI behavior.

---

Design

The policy flow is:

PolicyDocument → PolicyEngine → PermissionPolicy → Harness/AgentNode

There is one permission boundary rather than a second policy engine in the CLI.

The document is the authority ceiling. CLI restrictions may make that ceiling narrower, but an --allow flag cannot widen authority granted by the document.

---

Verification

• uv run ruff check . — passed
• git diff --check — passed (Windows emitted only LF→CRLF warnings)
• Focused Issue policy: grapharc agent cannot be governed by a policy document #6 tests were added and exercised.

The full test suite was also exercised on Windows. The remaining failures are environment/platform-related and pre-existing to this change, including sandbox fork behavior on Windows, missing claude CLI/provider environment, Windows symlink privileges, and platform-specific timing behavior. No silent platform fallback was introduced to mask those failures.

---

Scope

This PR intentionally does not modify the README, roadmap, cookbook, or deep-dive documentation. The implementation is limited to the policy/harness/CLI integration and its tests.