Implement session-scoped Agent Definitions

[kantord]

Stage: Implementation (ready for review)

Implements ADR 0353 and its acceptance plan, both reviewed and merged before the ADR/acceptance-plan scaffolding was removed in #2105. They are no longer on main; read them from history:

• ADR: merged in docs: ADR 0350 — use AgentDef for sessions #1783 (862bb4632) as ADR 0352, renumbered 0353 in docs: retire the readiness tracker and completed mecak8s plan #1812 (c2c4e1ae4). git show b6fdf3df0^:docs/adr/0353-session-scoped-agent-identity.md
• Acceptance plan: plan: session-scoped agent identity (Plan / Interface) #1815 (a9dfd84c6). git show a9dfd84c6:docs/acceptance/session-scoped-agent-identity.md

The task letters and AC numbers below and in commit messages refer to that plan; treat them as a partial reference point, not a live contract.

Relates to: #1053 (motivating Slack-bot use case).

What this does

CreateSessionRequest.agent_definition_name binds a session's root to a named AgentDef. The session gets a strict, non-widenable tool ceiling taken from that definition and otherwise behaves like an ordinary main session (same guardrails, permission ask flow, persistence, fork/clear). An unknown name is InvalidArgument.

• Catalog and authority: the root engine is built from the definition's own tools; its Authority carries a write-once Ceiling that GrantToolAuthority and CompleteWorkspaceEnrollment cannot widen past.
• Provider/model, limits, mode: ADR 0353's 5-case provider/model resolution; limits and permission mode are tighten-only against the definition.
• Persistence and rebuilds: the binding is stored (snapshot and event-source paths), survives restart, and every engine-rebuild path fails closed rather than falling back to the default engine. Fork/Clear preserve the binding; project memory is scoped to the session's own placement.
• mecatui: the /agent command for trying this end to end is in the stacked follow-up PR (see below).

Stack: this PR is the backend. The mecatui /agent <name> command and picker are a small stacked follow-up, #2055, based on this branch.

Tasks (all landed)

• A: agent_definition_name wire/domain/persistence plumbing (AC2.1, 2.2)
• B: core session-creation catalog ceiling, minted Authority (AC1.1-1.6, 1.9-1.11, 1.15-1.17)
• C: provider/model pair resolution, Limits/PermissionMode tighten (AC1.12-1.14)
• D: session.Authority.Ceiling domain mechanism (AC3.1, 3.2)
• E: guardrail contextual-review pinning tests (AC1.7, 1.8)
• F: fail-closed guards across engine-rebuild paths (AC3.3-3.6)
• G: Fork/Clear persistence, placement-aware project memory (AC2.3-2.6)

Integration fixes found after the tasks landed

The tasks were built in isolation and several defects only appeared when they were composed. Each has a mutation-verified regression test.

1. Ceiling never wired (4fed89362): Authority.Ceiling was never populated on the real mint path, so enforcement was dead code in production.
2. Deps.Role misread as "delegated child" (ec23650e9): the agent-bound root set a diagnostic Role, which engine/agent treats as the child signal. Contextual guardrail verdicts degraded to unresolved, which a headless engine denies. Fixed by not setting Role at all.
3. Restore without a Ceiling (b14f10f99): sessnap.Restore and eventsource.Fold could restore an agent-bound label with no Ceiling, which the grant paths treat as unrestricted. Both restores now set the label before binding authority, and BindAuthority rejects an agent-bound bind without a Ceiling.
4. Create idempotency (e114ac1c2): an explicit-ID retry did not compare the agent binding, and compared raw request limits to the persisted clamped limits. It now compares the binding and skips the raw-limits comparison for agent-bound requests.
5. Earlier: both persistence paths now carry the label, task api:update and the changelog entry are done, grpc-schema.md regenerated.

Items 3 and 4 came from an external review (hashes above are post-rebase); each claim was checked against the code before fixing.

Verification

• task test:race: passed before the latest rebase onto main. After the rebase I re-ran build, vet, and focused tests for the touched packages (engine/session, engine/adapter/*, internal/adapter/server, internal/app), and confirmed task generate / task api:update produce no drift. The full race suite is left to CI.

• task test (all modules) passed before the mecatui /agent commit. After that commit I re-ran only task lint and go test ./cmd/mecatui/..., both clean.

• /panel-review ran earlier with 0 ship-blockers, before items 3 and 4 were found. It has not been re-run since.

• go run ./cmd/mecademo: shows the tool call, the permission ask and approval, and the result.

Known gaps and open questions

• An external review also listed about a dozen test-coverage and documentation findings that I have not yet verified or addressed, including: debug_mcp_servers coverage for AC1.2, an end-to-end create-to-bound-Ceiling assertion, a more representative fake engine in the fork/clear test, full-composition catalog checks, context-propagation coverage for placement-scoped memory, grpc-api.md documentation of agent-bound semantics, a stale model_id-without-provider_id statement in grpc-schema.md, and whether the engine/CHANGELOG.md entry should be classified as Changed rather than Added for the two guard behaviours.
• A server older than ADR 0353 that advertises agent definitions would silently ignore agent_definition_name.

---

Fully or partially written by an AI agent.

🤖 Generated with Claude Code