feat: declarative policy engine, denial explanation, and dry-run mode

[dgenio]

Summary

Closes #42, #48, #43.

Implements three related policy DX features. DeclarativePolicyEngine lets teams load access-control rules from YAML or TOML files instead of writing Python. explain() returns a structured diagnosis of why a request would be denied. dry_run=True on invoke() lets callers validate tokens and inspect the resolved execution plan without executing the driver.

What changed

File	Change
src/agent_kernel/policy_dsl.py	New DeclarativePolicyEngine class (~160 LOC) with PolicyMatch and PolicyRule dataclasses; from_dict / from_yaml / from_toml constructors
src/agent_kernel/policy.py	Added explain() to PolicyEngine Protocol; implemented DefaultPolicyEngine.explain() collecting all FailedCondition objects without short-circuiting
src/agent_kernel/kernel.py	invoke() overloads for dry_run: Literal[True/False]; DryRunResult return path; new explain_denial() method
src/agent_kernel/models.py	New dataclasses: FailedCondition, DenialExplanation, DryRunResult
src/agent_kernel/errors.py	New PolicyConfigError for malformed declarative policy files
src/agent_kernel/__init__.py	Export all new public types
pyproject.toml	New policy optional extra; types-PyYAML in dev; ignore_missing_imports overrides for optional deps (tomli, yaml, httpx, mcp.*)
tests/test_policy.py	30+ new tests for DefaultPolicyEngine.explain() and DeclarativePolicyEngine (evaluation, explain, YAML/TOML round-trips, config validation)
tests/test_kernel.py	8 new tests for dry-run and explain_denial()
examples/policies/default.yaml	Example YAML policy file
examples/policies/default.toml	Same policy in TOML format
CHANGELOG.md	Added Unreleased/Added entries

Design decisions

• explain() on the Protocol directly. No opt-in adapter or mixin — every PolicyEngine implementation is required to support it. Breaking change accepted in owner repo; called out in checklist.
• No short-circuit in explain(). Unlike evaluate() which raises on the first denial, explain() collects all failing conditions so callers get a complete picture in one call.
• dry_run via @overload. dry_run: Literal[True] → DryRunResult and dry_run: Literal[False] → Frame are expressed as typed overloads so mypy catches misuse without runtime cost.
• explain_denial() is sync. No I/O is involved — policy evaluation is pure computation — so the convenience method on Kernel is sync, consistent with request_capabilities() and get_token().
• First-match-wins in DeclarativePolicyEngine. Rules are evaluated top-down; the first match determines the outcome. Predictable and easy to reason about from a policy file.
• attributes: {"key": "*"} means key must be present. Wildcard value matches any non-null attribute value, enabling "require tenant" rules without hardcoding values.
• ignore_missing_imports overrides for optional deps. tomli, yaml, httpx, and mcp.* are optional; rather than scattering # type: ignore comments, they are suppressed once in pyproject.toml. Pre-existing mcp.py:28 unused type: ignore also cleaned up.

Testing

ruff format src/ tests/ examples/   → 40 files unchanged
ruff check src/ tests/ examples/    → All checks passed
mypy src/                           → Success: no issues found in 23 source files
pytest -q --cov=agent_kernel        → 291 passed, 95% coverage
python examples/basic_cli.py        → ✓
python examples/billing_demo.py     → ✓
python examples/http_driver_demo.py → ✓

Documentation

• CHANGELOG.md: Added entries under [Unreleased] for all three features.
• examples/policies/: Added default.yaml and default.toml showing a realistic multi-rule policy covering READ/WRITE/DESTRUCTIVE safety classes and PII/SECRETS sensitivity.
• Module docstring in __init__.py updated to mention DeclarativePolicyEngine.

AI agent instruction files reviewed

• AGENTS.md — no change needed; new types follow existing naming and slots=True dataclass conventions; module size delta accepted as owner-repo delta (noted in checklist).
• docs/agent-context/invariants.md — no change needed; new features add surface area but do not alter existing security invariants.
• .github/copilot-instructions.md — no change needed.
• .claude/CLAUDE.md — no change needed.

Checklist

• make ci passes (fmt, lint, mypy strict, pytest, examples)
• Docstrings match final implementation
• No dead code (all new parameters, fixtures, and helpers exercised by tests)
• Naming consistent: capability, principal, grant, Frame throughout
• Backward-compat note: explain() is a breaking addition to PolicyEngine Protocol — external implementers must add the method
• CHANGELOG.md updated
• Example policy files added

[Copilot]

Pull request overview

This PR adds three developer-experience features around policy evaluation and invocation planning: a declarative policy engine (YAML/TOML), structured denial explanations, and a dry-run mode for Kernel.invoke().

Changes:

• Introduces DeclarativePolicyEngine (policy_dsl.py) with rule parsing/evaluation and an explain() API.
• Adds structured denial explanation types (DenialExplanation, FailedCondition) and implements explain() for DefaultPolicyEngine plus Kernel.explain_denial().
• Adds dry_run=True support to Kernel.invoke() returning DryRunResult, plus packaging/docs/examples updates.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 19 comments.

Show a summary per file

File	Description
tests/test_policy.py	Adds tests for DefaultPolicyEngine.explain() and DeclarativePolicyEngine parsing/evaluation/explanation.
tests/test_kernel.py	Adds integration tests for dry-run invocation and Kernel.explain_denial().
src/agent_kernel/policy.py	Extends the PolicyEngine protocol with explain() and implements explanation logic in DefaultPolicyEngine.
src/agent_kernel/policy_dsl.py	New declarative policy engine with YAML/TOML loaders, evaluation, and explanation.
src/agent_kernel/models.py	Adds new public result models: FailedCondition, DenialExplanation, DryRunResult.
src/agent_kernel/kernel.py	Adds dry_run overloads/implementation and explain_denial() helper.
src/agent_kernel/errors.py	Adds PolicyConfigError for malformed/unreadable policy configs.
src/agent_kernel/drivers/mcp.py	Tweaks optional McpError import handling.
src/agent_kernel/init.py	Re-exports new policy engines/types and bumps __version__.
pyproject.toml	Adds policy optional extra deps and mypy overrides for optional imports.
examples/policies/default.yaml	Adds an example YAML declarative policy file.
examples/policies/default.toml	Adds an example TOML declarative policy file.
CHANGELOG.md	Documents the new engines, dry-run mode, and new public exports.