Context
agent-kernel already models capabilities, principals, policy decisions, grants, tokens, frames, and action traces. Current CapabilityRequest carries a free-text goal and optional constraints, and PolicyDecision captures allow/deny, reason, and constraints. Existing issues cover broader declarative policy and dry-run work, but there is no small issue focused on making the policy decision explicitly intent/scope aware.
Problem
A capability invocation can be technically allowed but unsafe for a particular intent or scope. Today, downstream audit/review tools need to infer intent from free text and constraints. A structured intent/scope layer would make authorization, audit, and policy explanation more reliable without changing the whole policy engine.
Scope
- Add explicit optional intent and scope metadata to the request/decision path.
- Preserve backward compatibility for existing callers using only
goal and constraints.
- Ensure audit traces can include the evaluated intent/scope metadata where appropriate.
- Add tests for allow/deny decisions that differ by intent or scope.
Out of scope
- Do not replace the existing declarative policy engine.
- Do not implement a full ontology of intents.
- Do not change token signing or federation behavior.
- Do not require callers to provide intent/scope for simple use cases.
Suggested implementation
Inspect src/agent_kernel/models.py, policy engine modules, token/grant issuance, and audit trace creation. A small first step could be optional fields such as intent: str | None, scope: dict[str, Any], or a lightweight InvocationContext model that policy engines can inspect. Keep serialization and public imports stable.
Acceptance criteria
Tests
Add unit tests for model defaults, serialization if present, policy evaluation with intent/scope, and backward compatibility. Include at least one denied request with a useful reason.
Documentation
Update capability/policy docs with a short example showing intent/scope-aware authorization.
Dependencies
Related to existing policy work, including #68 and earlier declarative policy issues. None required.
AI agent notes
Start by reading models.py, policy engine code, and token/grant tests. Keep the first implementation additive and optional. Avoid making free-text goal disappear; it is still useful for human-readable audit context.
Context
agent-kernelalready models capabilities, principals, policy decisions, grants, tokens, frames, and action traces. CurrentCapabilityRequestcarries a free-textgoaland optionalconstraints, andPolicyDecisioncaptures allow/deny, reason, and constraints. Existing issues cover broader declarative policy and dry-run work, but there is no small issue focused on making the policy decision explicitly intent/scope aware.Problem
A capability invocation can be technically allowed but unsafe for a particular intent or scope. Today, downstream audit/review tools need to infer intent from free text and constraints. A structured intent/scope layer would make authorization, audit, and policy explanation more reliable without changing the whole policy engine.
Scope
goalandconstraints.Out of scope
Suggested implementation
Inspect
src/agent_kernel/models.py, policy engine modules, token/grant issuance, and audit trace creation. A small first step could be optional fields such asintent: str | None,scope: dict[str, Any], or a lightweightInvocationContextmodel that policy engines can inspect. Keep serialization and public imports stable.Acceptance criteria
CapabilityRequest(goal=...)continues to work.Tests
Add unit tests for model defaults, serialization if present, policy evaluation with intent/scope, and backward compatibility. Include at least one denied request with a useful reason.
Documentation
Update capability/policy docs with a short example showing intent/scope-aware authorization.
Dependencies
Related to existing policy work, including #68 and earlier declarative policy issues. None required.
AI agent notes
Start by reading
models.py, policy engine code, and token/grant tests. Keep the first implementation additive and optional. Avoid making free-textgoaldisappear; it is still useful for human-readable audit context.