security: enforce grant constraints during handle expansion

[dgenio]

Context

After inspecting the repository and existing issues, agent-kernel already has policy, trace, handle, and OTel-oriented work. I did not find an existing issue specifically ensuring that grant constraints are persisted with handles and rechecked when handles are expanded.

Problem

A handle should not expand beyond the constraints attached to the original grant. Limits such as allowed fields, max rows/items, expiry, or scope need to remain enforceable after the initial policy decision.

Scope

• Persist relevant grant constraints with handles when they are created.
• Recheck those constraints during handle expansion.
• Cover max rows/items, allowed fields, expiry, and scope constraints where those concepts exist in the current model.
• Return predictable denial/error results when expansion violates constraints.
• Add tests for allowed and denied expansion paths.

Out of scope

• Do not redesign the full policy model.
• Do not add a new storage backend.
• Do not require OpenTelemetry or external logging.
• Do not change unrelated capability execution behavior.

Suggested implementation

Inspect handle creation/expansion code, grant/capability models, policy decision code, firewall/redaction code, and trace/audit behavior. Likely modules to inspect first include handle store/manager, policy/grant models, expansion APIs, and tests around handles.

Acceptance criteria

• Expansion respects max rows/items or equivalent limits when available.
• Expansion respects allowed fields or equivalent projection constraints when available.
• Expired or out-of-scope handles are denied predictably.
• Denied expansion returns a stable error/denial shape.
• Tests cover allowed and denied expansion.

Tests

Add unit tests for a handle that expands successfully, a handle exceeding row/item limits, a handle requesting disallowed fields, and an expired/out-of-scope handle if the model supports it.

Documentation

Document the handle expansion security invariant and the expected denial behavior. A short note in security docs or handle API docs is enough.

Dependencies

None.

AI agent notes

Preserve backwards compatibility where possible. If existing handles do not carry constraint metadata, add a migration-safe default or versioned shape. Keep denial results machine-readable so future policy tests can assert behavior without matching fragile strings.