Implement session-scoped Agent Definitions

[kantord]

Summary and stack

Implements session roots bound to named agent definitions: a definition-specific tool catalog and nonwidenable authority ceiling, with ordinary root-session guardrails and approval handling. Motivated by #1053.

Backend PR: main → this PR → #2055, the TUI command and picker. This PR contains the server, engine, persistence, protocol, SDK feature vocabulary, documentation, and backend tests—not the /agent UI.

Previously agreed design; implementation review remains necessary

This is the implementation of the design and acceptance criteria reviewed under the former ADR/acceptance-plan process, not a new proposal for the feature:

• #1783 merged the design-only ADR on September 23, including Jakub's approval. No implementation was approved by that PR.
• #1812 resolved the numbering collision, leaving this decision as ADR 0353.
• #1815 reviewed and merged the Plan / Interface checkpoint on September 29. See the review against the then-current code, the merged acceptance criteria and resolved human decisions, and the ADR snapshot at that merge. The merged files, rather than the original draft wording in the PR bodies, record the settled decisions.
• #2105 subsequently removed that documentation/process scaffolding. The immutable links above retain the design provenance without restoring retired process requirements.

Main has moved. Those approvals establish design intent, not that old implementation recipes or an old review still prove today's code correct. This implementation adapts that intent to current owner-scoped sources, placement and MCP-runtime lifecycles, provider-aware aliases (#2019), and contextual guardrail composition. Historical task letters are not the readiness checklist.

Implemented behavior

• Optional agent_definition_name on gRPC and HTTP creation, with resolved_agent_definition_name echoed back. Unknown names and incompatible debug/client-MCP combinations are rejected.
• The root catalog comes from the definition's bounded tool set and selected MCP servers. Authority is minted from that catalog; later grants cannot exceed its ceiling. The engine retains root approval and guardrail behavior rather than delegated-child behavior.
• Definition model aliases retain their provider/model pairing. A root does not inherit the generic subagent default or invoke automatic delegation routing. Request overrides follow the agreed five-case pair resolution; wire model_id remains literal. An unavailable explicitly pinned provider still fails creation—this PR does not introduce a different fallback policy.
• Requested limits and permission mode only tighten the definition. Fork/Clear retain the binding and inherited authority, apply the current definition catalog, and enforce tighter returned mode/limits. Unsafe runtime rebuilds fail closed.
• Owner/execution-scoped sources, remote/no-FS policy and prompt configuration, provider effort/capability reconstruction, and operation-pinned MCP assets use the existing composition mechanisms. Failed construction/publication releases acquired resources.
• Effective identity persists separately from original explicit-ID create intent. Identical retries survive clamping; changed requests are rejected. Snapshot and event-source restore reject bound records without valid authority, while learning-evidence reconstruction retains the required metadata.
• Project memory follows the session placement and its trust decision. No-FS sessions do not receive project-memory content. Enrollment checks ownership before revealing whether a session is agent-bound.

API compatibility

Additive wire change; API major remains 1. Omitted binding fields preserve ordinary-session behavior. The stable session_agent_definitions feature reports protocol support on both transports, independent of whether definitions are configured. Clients relying on binding must require this feature and verify the exact response echo before sending a prompt; an older gRPC server can silently ignore the new field. Existing clients do not need changes. Upgrade the server before relying on binding; no wire-breaking change or major-bump approval is requested.

Go and stored-data compatibility are separate: new engine identifiers are classified as Added and authority-enforcement behavior as Changed (pre-v1 minor) in the engine changelog. Ordinary legacy sessions need no migration. Valid legacy agent-bound records without the new retry fingerprint remain readable but cannot prove explicit-ID retry equality. Malformed bound authority is rejected, not reconstructed from today's definition. Metadata readability does not imply permission to resume execution after restart.

Additional due diligence — October 15, 2026

The extra pass checked the implemented behavior again rather than relying on the historical approvals or an earlier end-to-end run.

Automated verification and targeted regression review

Passed locally on the completed implementation and cleanup tree:

• task lint
• task --concurrency 1 test — complete offline suite, including standalone module checks
• task --concurrency 1 test:race — complete race suite
• go run ./cmd/mecademo — observed tool call, permission ask, approval, and result
• task docs; SDK typecheck and focused discovery tests; generated contract/API updates and checks; site build

The full suites were serialized and used a short temporary root plus isolated loopback networking to avoid occupied host OAuth ports and Unix-socket path limits. Namespace setup capabilities were dropped before the final gate run. Initial environment/timing failures were investigated; tests were not disabled to obtain the passing runs.

Verification ran on the integrated backend-plus-TUI working tree before the stack was separated. After committing the backend changes and updating the TUI stack, the final TUI head c704ae874 was checked to be tree-identical to that tested tree. This is not a claim that the backend-only SHA was separately put through every gate, or that a future merge with newer main has already been validated. CI remains an independent gate.

Agent-assisted spec, standards, test-adequacy, architecture, security, and reuse review was followed by fixes and focused closure checks. Useful committed evidence includes:

Boundary checked	Regression evidence
Settings aliases, distinct root/child providers, actual model requests, owner isolation, remote/no-FS posture, runtime publication, effort/capabilities	Root composition tests and healed-default test
Failed-create retry and failed-successor source/lease cleanup	Real-composition lifecycle tests
Factory acknowledgment, tightened successors, fixed runtime configuration, ownership-safe enrollment, durable retry intent	Factory acknowledgment, lifecycle persistence, and retry tests
Placement-specific project memory through real successor requests	Memory integration tests
gRPC/HTTP mapping, rejection behavior, and effective identity	Wire parity tests

The bloat review consolidated repeated catalog/broker setup and trimmed redundant integration permutations while retaining the unit matrices and distinct lifecycle/transport tests. It did not replace integration coverage with helper-only assertions.

Separate manual end-to-end smoke pass

The operator supplied an additional agent-assisted manual-run report from today's working tree. It used locally built mecated/mecatui, the offline --mock-script provider, temporary HOME/XDG directories and workspace, HTTP/SSE via curl, and a small gRPC client built from generated contracts. It exercised both in-memory and persistent stores, including killing and restarting the persistent server. Authentication was disabled on loopback. No operator credentials, paid providers, or operator state were used. This report was not pinned to an immutable final commit and should not be read as a rerun after every subsequent edit.

Journey	Reported observation
Discovery	/v1/compatibility advertised session_agent_definitions.
Create and echo	HTTP returned 201 and gRPC succeeded with the bound-name echo; ordinary creation omitted the binding. Bound sessions reported no built-in shell; the ordinary session reported shell availability.
Mode and limit attenuation	acceptEdits against reviewer's plan ceiling resolved to plan on both transports. A requested 100-turn limit resolved to 3, confirmed with gRPC GetSession.
Runtime budget	A mock script requesting six Read calls stopped after exactly three turns with max_turns.
Tool scope and permission flow	A Write call against Read-only reviewer returned unknown tool. The same call against writer (Read/Write) produced permission.ask; this observation alone does not claim that the write was approved and completed.
Validation	Unknown definition: HTTP 400 / gRPC InvalidArgument. Camel-case agentDefinitionName: HTTP 400. Binding plus debug target: HTTP 400. SetMode on a bound session: InvalidArgument.
Client MCP rejection	HTTP 501 / gRPC Unimplemented on the TCP deployment. This exercised the deployment guard, which runs before the agent-bound guard—not a manual proof of that inner guard.
Provider/model	Alias fast resolved to mock/mock-fast; an unavailable openai definition pin returned InvalidArgument; a bound model-only request retained its literal model ID.
Fork/Clear	Both returned HTTP 201; successors retained plan mode and no-shell capabilities.
Persistent restart	Metadata retained plan mode and clamped limits. Prompting the old bound session failed closed on rehydration; SetMode remained rejected. Fork/Clear after restart worked and their successors retained plan/no-shell behavior. An ordinary session ran normally after restart.

The picker/filter and /agent smoke observations belong to #2055, not this backend diff.

Limits of that evidence and remaining merge work

Not exercised by the manual smoke pass: real LLM behavior with restricted catalogs; authenticated multi-owner transport/deployment behavior (covered at the isolated composition-test layer); the inner agent-bound client-MCP guard on a Unix-socket-only listener; deployed mecak8s/Redis/Kubernetes leases; remote store/definition drivers; TLS/mTLS deployment; microVM/execution-template deployment; or a live TypeScript SDK journey. Mock/fixture coverage and SDK type/discovery checks are not substitutes for those deployment runs. These checks can be done before merge with the appropriate environment; they are not inherently impossible until deployment.

Intentional v1 scope: no delegation from an agent-bound root, no new per-caller definition-name ACL, and no execution resume of a bound session after restart/client-MCP rehydration. Fail-closed restart was an explicit accepted decision; continuation support remains #1796.

Main integration completed after the review. The initial review fetched main at 7cd9bb0f9. This branch now includes main at ce0f816e0, merged in c4b5b1fe0. The only textual conflict was in engine/CHANGELOG.md; both the agent-authority and scheduling-contract entries were retained unchanged. Local task lint, task docs, the complete offline and race suites, and the offline demo passed again on the merged backend. The TUI branch was then updated, with its package race suite and scoped lint passing; its diff remains the original 15 TUI files. GitHub reports both branches conflict-free at this update. The earlier manual smoke report was not rerun as part of this conflict resolution. Latest CI and implementation review remain required; these results do not certify future main changes.

[JAORMX]

So, I think the direction makes sense. Asking an agent to “be a reviewer” is easy. Making sure it stays within its permissions when someone forks the session or tries to attach more tools is the useful part here.

I’d keep a clear distinction between what this PR enforces inside Mecatl and what we’re proposing in #2121. This PR gives us a session bound to a definition, with an authority ceiling that cannot grow. The broker work would independently enforce the MCP portion of that authority and attribute calls to a particular agent acting for a particular user. I wouldn’t make this PR wait for that whole architecture.

My main question is how definition changes interact with session continuity. This PR rebuilds fork/clear successors using the current definition while retaining inherited authority. The identity proposal pins a definition revision to an instance. Those can fit together, but we should be explicit: a successor is a new instance; restoring an existing instance must not silently replace its definition or widen its authority. And an administrator still needs to be able to revoke access.

I’m fine with failing closed on restart for this first version. It’s a real usability limitation, especially during rolling upgrades, but I’d rather have an honest limitation than accidentally restore a broader session. We should make the recovery path clear and keep safe continuation as a separate follow-up.

For the identity integration, I’d propose treating agent_definition_name as a selector, rather than an identity. The user asks for reviewer; trusted server-side code resolves which definition that means in the applicable source scope. The external identity should come from registering a particular instance against that resolved definition, not from trusting the string the client supplied.

Concretely, I’d want the integration contract to separate:

• The display/selection name, such as reviewer.
• An admitted definition reference identifying its source and revision. Two definitions with the same name must not become interchangeable.
• The durable instance identifier, associated with the owning user/session and its effective authority ceiling.

When we add the broker, Mecatl would register the instance using a definition reference the broker recognizes. The broker would validate that registration and establish the instance’s permitted MCP operations from admitted definition records. The client or model shouldn’t be able to establish authority by supplying a name, a tool list, or even a digest. A digest identifies content; it doesn’t prove we trust it.

That also leaves a separate admission question: is this caller allowed to start a session using this definition? We don’t need to add definition-specific ACLs here, but selecting a known name must not later become an implicit privilege grant.

For this PR, I’m suggesting we document that boundary and the successor/restoration rules, not add credentials or a registration API. Then the follow-up in 2121 has a concrete job: define the admitted definition reference, bind it to an instance and owner, and enforce the resulting ceiling at the broker.

[JAORMX]

I think the overall approach makes sense, but there’s a definition-scope enforcement issue we should fix before merging: the root authority is minted from a catalog that can include explicitly disallowed tools. I’ve kept the inline comment focused on the implementation and repair, rather than an exploit walkthrough.

The other actionable findings are the child-only Shell trust gate leaking into root construction, explicit auto reasoning effort changing meaning during reconstruction, and a missing exactness assertion on the production-minted ceiling. Those have inline comments with the relevant paths and suggested regression coverage.

This was an eight-reviewer panel covering the agreed spec, Go conventions, test adequacy, security, lifecycle/composition, API compatibility, duplication, and library reuse. Disputed findings received a separate verification pass. No local tests or linters were run; this is static review backed by the existing CI results. I didn’t find a useful duplication or dependency refactor to ask for. The root/child differences mostly deserve to stay explicit.

A few nonblocking follow-ups, rather than requests to expand this PR:

• Clarify that bound-session limit tightening covers turns and tool calls; the requested consecutive-failure limit currently keeps the inherited value. That matches the accepted scope, but the API documentation says “limits” more broadly.
• Add high-level TypeScript binding support as a coordinated follow-up: the typed option, feature requirement, and exact response-echo check should arrive together. Accidental JavaScript forwarding of the currently undeclared option isn’t a supported safe workflow.
• Clarify whether explicit-ID Service retries compare raw omitted mode or mode after deployment defaulting. The fingerprint currently uses the latter. This is the embedding seam, not a public HTTP/gRPC explicit-ID retry issue.
• Consider making definition selection and governance-root inputs explicit in a future factory API cleanup. I don’t think a context-to-request refactor needs to block this PR.

CI is a separate concern: Go race, lint, build, API compatibility, and SDK checks passed. The Studio route-count failure is inherited from the base: the skills-files route added a sixteenth operation without updating the count or declaring the expected transport errors. The execution-provider production-profile check was still running when checked. I’m not requesting changes because of that inherited CI failure.

The intentional exclusions (bound-root delegation, new definition-name ACLs, and direct restart execution) aren’t review blockers, and I’m not pulling the broker or TUI follow-ups into this PR.

[kantord]

Thank you for the careful review, and for being explicit about scope. Summary of what changed in 1ef3e92:

• The four inline findings are fixed with regression tests (see the replies on each thread).
• Documented in user-docs/reference/grpc-api.md: agent_definition_name selects a definition by name and is not an authenticated identity, and no source or revision is recorded. Fork and Clear create new sessions, and resuming an existing bound session after restart is refused, so it is never restored from a different definition. The authority ceiling bounds what a session can be granted and is not an access-control or revocation mechanism. The doc also states that this feature adds no definition-specific access controls, credentialed instance registration, or broker-side enforcement, which stay with docs: describe agent authority, broker trust boundaries, and implementation gaps #2121 and follow-ups.
• Limit wording: the doc now says definition tightening covers turns and tool calls, and that the consecutive-failure limit keeps the inherited value.

Follow-ups:

• TypeScript SDK support, as a coordinated typed option, feature check, and response-echo validation: TypeScript SDK: high-level support for session-scoped agent definitions #2383.
• mecatui integration, tracked against the draft mecatui: /agent command and picker for session-scoped agent definitions #2055: mecatui: finish /agent integration for session-scoped agent definitions #2384.
• Explicit factory inputs instead of context-carried selection: deferred as a future cleanup.

Still open: whether explicit-ID retries fingerprint the omitted mode before or after deployment defaulting. I have not verified this yet and don't want to document a guess, so I'll trace it and update the docs.

Fully or partially written by an AI agent.

[JAORMX]

Thanks for addressing the review. I rechecked the changes at 7fff6936b, including the main merge and broker-provenance fixture correction. The four original findings are addressed: late tool exclusions now survive catalog and authority construction, root Shell availability follows the main runner, stored explicit-auto effort survives reconstruction, and the new tests assert exact granted and ceiling sets.

The resource caveat doesn’t reopen the blocker. mcp_resource__<server> is a separate opaque capability, not a catalog tool; mcp__<server>__resources would be a normal MCP tool and is covered by the exclusion check. I wouldn’t expand the denylist contract in this PR.

One nonblocking test suggestion remains: the new effort lifecycle tests use a simulated factory. A real app-factory case with operator default high and explicit auto, checking the reminted provider effort, would give us additional confidence. The existing tests do catch the original selector-reconstruction regression.

The documented scope and tracked SDK/TUI follow-ups look reasonable. The omitted-mode retry semantics can remain a follow-up clarification. Approving the code; CI still needs to finish successfully before merge. No local tests or linters were run during this review.