policy: grapharc agent cannot be governed by a policy document

[Shashankss1205]

Summary

grapharc agent cannot be governed by a policy document. PolicyEngine.permission_policy() exists at grapharc/policy/engine.py:187 and produces exactly the PermissionPolicy the agent harness consumes — and nothing calls it. The same is true of check_tool() and approval_router(). The agent's tool gating is instead assembled from --allow / --deny / --ask globs at grapharc/cli/agent.py:91-97.

So the edge half of policy is wired (edge_policy() is called by cli/plan.py:145 and cli/generate.py:202) while the tool half is not. Note this also means README's blanket claim that "nothing in the package imports grapharc.policy" is now stale and should be narrowed to this remaining seam as part of the fix.

Why this matters

A TOML document with tiered evaluation, per-tenant scoping, versioning, digests and an audit record naming the rule that decided is the difference between governance you can review and governance buried in Python. Declarative, reviewable authority over what a tool may do is the centre of the graph engineering argument this project makes; today the most dangerous surface in the repo — an agent that can write files and run commands — is the one the document cannot reach.

Where in the code

• grapharc/policy/engine.py:187 — permission_policy(), the unused producer
• grapharc/policy/engine.py:119 — check_tool(); :251 — approval_router(), also unused
• grapharc/cli/agent.py:91-97 — _policy_from_flags, the flag-built policy that currently wins
• grapharc/harness/core.py:28 — where a PermissionPolicy is consumed
• grapharc/cli/plan.py:139-145 — the already-working precedent for loading a document
• grapharc/policy/audit.py — the decision record that must survive this path

Confirm the seam:

grep -rn "permission_policy()\|\.check_tool(\|approval_router(" grapharc/ --include=*.py | grep -v "^grapharc/policy/"

What to change

This needs design judgement, not just wiring. Decisions to make and defend:

1. Precedence. grapharc agent --policy doc.toml plus --deny 'run_command' — which wins? The tiered model says every deny beats every allow, so a flag deny should probably still bite, but a flag allow must not be able to widen a document deny. State the rule and test it.
2. Tenant. permission_policy() takes tenant=. Decide where a tenant comes from on the CLI path and what happens when none is given.
3. Audit. A denial must land in the policy audit log naming the rule id, version and digest, and on the run trace. Two records that can disagree would be worse than one.
4. The ask tier. approval_router() exists; the CLI has an interactive input() prompt at agent.py:113. Decide whether the document's ask drives that prompt and what happens under --json (non-interactive) — failing closed is the only safe answer.
5. Config layer. --policy already resolves through grapharc.toml for other commands; keep the provenance (policy_source) reporting honest.
6. Narrow the stale README paragraph to the seam that actually remains.

How to verify

uv run pytest -q
uv run ruff check .

New tests must include: a document deny refusing a tool the model asked for, with the tool never reaching the sandbox and its schema never shown to the model; a flag that cannot widen a document deny; and a denial appearing in both the audit log and the trace.

Acceptance criteria

• grapharc agent --policy <doc.toml> governs tool execution
• Precedence between document and flags is documented and tested
• A denied tool's schema is never shown to the model (the existing invariant must hold on this path too)
• Every decision is auditable to the rule id, policy version and digest
• ask under --json fails closed rather than prompting
• README's policy paragraph describes the real remaining seam
• uv run pytest green, uv run ruff check . clean

Skill level — experience required

This is not a starter task. It changes who has authority over the most security-sensitive path in the codebase, and a mistake here is a policy that looks enforced and is not. You should be comfortable reading the whole of grapharc/policy/ and grapharc/harness/ before proposing anything, and you should expect to argue for your precedence rules in the issue before writing code. If you have built permission or authorization systems before and want this, say so here and outline your approach first.