Policy v2: grant-based per-repo tool permissions

[chaodu-agent]

Part of #15 (post-v0.4.0 enhancement). From review of the shipped 2a/2b policy model.

Problem

The current per-agent policy is a flat cross product — tools × repos. An agent that should be read-only on repo-A but able to create_issue on repo-B cannot be expressed; the workaround is two agent entries with two keys.

Proposal: grants

[[mcp.agents]]
id   = "my-bot"
keys = ["env:KEY_CURRENT"]

  [[mcp.agents.grants]]
  repos = ["my-org/repo-a"]
  tools = ["issue_read", "pull_request_read"]

  [[mcp.agents.grants]]
  repos = ["my-org/repo-b"]
  tools = ["issue_read", "create_issue"]

• A tools/call must match ≥1 grant (tool ∈ grant AND resolved repo ∈ grant). Default-deny preserved.
• Flat tools + repos remains as sugar for a single grant (fully backward compatible).
• Optional per-grant permissions for mint-time scoping (the App mint API's permissions param is currently unused) — e.g. the repo-B grant mints with issues: write only.

Known design wrinkles (decide before building)

1. X-MCP-Tools upstream becomes the union of granted tools — tools/list shows write tools even to sessions working in read-only repos. Acceptable: the proxy-side per-call pairing check is authoritative; the header stays defense-in-depth. But the pairing is ghpool-enforced only.
2. Token granularity vs session pinning: sessions pin one credential, and mid-session token switching is untested upstream behavior (MCP proxy Phase 0: compliance & compatibility spike (hosted endpoint contract, App tokens) #22 residual). GitHub-side scope would be the union of exact repos across grants; per-pair GitHub enforcement would require per-call credential selection or per-grant sessions — significant design work, evaluate against actual need.
3. Deny-if-unresolvable semantics generalize cleanly (a call with no repo target matches no repo-restricted grant).

Prior art in-tree

• scope_envelope() (per-agent union scoping) and repo_allowed() in src/policy.rs are the extension points.
• Audit records already carry (agent, tool, repo) — grants add a grant id to the record for traceability.

[chaodu-agent]

Design landscape changed since filing — #38 is prior art for wrinkle 2

Wrinkle 2 called per-pair GitHub-side enforcement "significant design work" because sessions pin one credential. v0.5.0's multi-installation routing (#38) has since shipped exactly the needed machinery in one dimension: per-call credential selection keyed on the repository owner resolved from call arguments, with eager per-owner upstream session fan-out at initialize and routing that is never agent-controlled.

Grants would generalize that keying from owner → installation to grant → (credential scope, session). Concretely:

• The per-owner session map from feat(mcp): multi-installation GitHub App routing — one key, many orgs #38 becomes a per-grant session map (same pinning + fan-out pattern, same argument-resolution point)
• Per-grant permissions mint-time scoping slots into the existing per-owner token mint path
• Wrinkle 2's "untested mid-session token switching" concern is moot under this shape — like feat(mcp): multi-installation GitHub App routing — one key, many orgs #38, each grant keeps its own pinned upstream session; nothing switches mid-session

Remaining open design from the original list: wrinkle 1 (X-MCP-Tools union in tools/list) is unchanged, and grant-id in audit records still applies.