feat: add coding-agent least-privilege flagship policy and demo

[dgenio]

Advances #253 with a real embedded least-privilege boundary and maintained flagship demo.

What this adds

• CodingAgentPolicyEngine with a deliberately small capability vocabulary for repository reads/writes, test commands, networked shell commands, secrets, PR creation, and PR merge.
• explicit roles for code writes/tests/network/secrets/merge plus task-bound PR approval.
• path-scoped repository writes using deterministic glob matching.
• signed scope binding: the exact path/command-class/task approved at grant time is written into token constraints.
• enforce_coding_agent_constraints() for drivers to fail closed if invocation arguments are swapped after a valid grant.

That last point is the core security property: a token approved for src/demo.py cannot later be reused to mutate .github/workflows/release.yml.

Flagship proof

python examples/coding_agent_least_privilege.py is hermetic and makes no real repo/GitHub/network side effects. It demonstrates:

• ALLOW normal repo read
• ALLOW bounded source write
• DENY workflow write outside path scope
• DENY secret read
• ALLOW test command class
• DENY PR creation before approval
• ALLOW the same PR creation after task-bound approval
• DENY post-grant scope substitution at execution
• inspect a successful ActionTrace via kernel.explain()

The script drift-checks its semantic output against examples/coding_agent_expected.txt, and make ci now executes it.

docs/coding-agent-security.md explains the three practical authority profiles (review, edit+test, publish-for-review), the driver-side constraint requirement, and explicit non-claims.

Scope

This does not pretend to solve arbitrary host sandboxing or prompt injection. The boundary only applies to actions routed through the embedded kernel and to drivers that enforce the signed constraints before the side effect.

This PR intentionally does not auto-close #253 yet; the issue can remain the canonical place for any richer action-envelope/budget/organizational-authority follow-up after this concrete beachhead is validated.

Merge only after the exact final head passes the repository's full CI.

[Copilot]

Pull request overview

Adds a least-privilege “coding agent” policy surface to weaver-kernel, plus a deterministic flagship demo and supporting match helpers/tests/docs, as the concrete adoption story for #253.

Changes:

• Introduces CodingAgentPolicyEngine + enforce_coding_agent_constraints() to bind grant-time scope into signed token constraints and fail closed on execution-time scope substitution.
• Adds deterministic glob-based scope matching helpers (policy_matching.py) with unit tests.
• Adds a CI-run, hermetic flagship demo (examples/coding_agent_least_privilege.py) with a drift-checked receipt and accompanying security documentation.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_policy_matching.py	Adds unit coverage for new glob/scope matching helpers.
tests/test_coding_agent.py	Adds unit coverage for the coding-agent policy engine and constraint enforcement helper.
src/weaver_kernel/policy_matching.py	Introduces deterministic scope glob matching utilities.
src/weaver_kernel/coding_agent.py	Implements the coding-agent least-privilege policy engine and driver-side constraint enforcement helper.
Makefile	Runs the new flagship demo as part of the example target.
examples/coding_agent_least_privilege.py	Adds a hermetic flagship demo exercising ALLOW/DENY/escalation/scope anti-swap with an ActionTrace receipt.
examples/coding_agent_expected.txt	Adds the maintained expected semantic receipt for drift checking.
docs/coding-agent-security.md	Documents the coding-agent capability vocabulary, signed scope binding, and non-claims.

Suppressed comments (5)

tests/test_coding_agent.py:79

• Per AGENTS.md / the review checklist, tests should assert both exception type and message. Add a match= here so the denial message is covered.

    with pytest.raises(PolicyDenied) as exc:

tests/test_coding_agent.py:103

• Per AGENTS.md / the review checklist, tests should assert both exception type and message. Add a match= here to cover the missing-role error message.

    with pytest.raises(PolicyDenied) as exc:

tests/test_coding_agent.py:119

• Per AGENTS.md / the review checklist, tests should assert both exception type and message. Add a match= here to cover the task-approval denial message.

    with pytest.raises(PolicyDenied) as exc:

tests/test_coding_agent.py:131

• Per AGENTS.md / the review checklist, tests should assert both exception type and message. Add a match= here to cover the missing-role error message.

    with pytest.raises(PolicyDenied) as merge_exc:

tests/test_coding_agent.py:146

• Per AGENTS.md / the review checklist, tests should assert both exception type and message. Add a match= here to cover the missing-role error message for secrets access.

    with pytest.raises(PolicyDenied):

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.