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.

[JAORMX]

Blocking: can we apply the definition’s exclusions to the final assembled catalog before minting authority here? scopedToolNamesMode filters core names, but resolvedAgentDefCatalog subsequently adds MCP tools at agentdefs.go:1142–1151 and automatically adds ShellStatus at 1130–1133, without applying DisallowedTools again. This root then copies those entries into both its grant and ceiling. The delegated path’s separate agentDefinitionAuthorityCeiling filtering does not protect this root path.

Please make the final advertised catalog and minted authority respect the same exclusions, including MCP and automatically added tools, and add negative regression coverage through the real root factory. Normal permission approval must not override an explicit definition exclusion.

[JAORMX]

This base set still carries the read-only child’s Shell trust gate. baseSubagentTools adds Shell through buildSandboxedCommandRunner, which requires TrustProject; the main runner created above does not have that same restriction. An explicitly admitted operator definition requesting Shell therefore loses it on an untrusted checkout, even when an ordinary root has Shell available through its normal permission flow. allowShell=true later cannot put a missing tool back into the base.

Could we derive root Shell availability from the main runner before applying the definition scope, while preserving no-FS and deployment restrictions? A regression using an explicit definition, TrustProject=false, and a configured Ask would pin the distinction between project-content trust and root tool permissions.

[JAORMX]

Persisting effective reasoning effort here loses the distinction between explicit auto and an omitted selector when this configuration is reconstructed. With operator effort high, create-time auto correctly resolves to an empty effective value. The runtime-rebuild selector at service.go:6521 later passes that empty value back to resolveSessionEffort, where it means inherit the operator default. It becomes high, and the fixed-configuration check at 6815–6830 rejects the rebuild. This is reachable after a same-process MCP runtime revision change; it does not depend on the intentionally unsupported restart path.

Fork/Clear reconstruct the same empty selector at placement_successor.go:382, but accept and persist the changed effort instead.

When reconstructing an already-bound session’s effective configuration, could we encode stored empty effort as explicit auto, while retaining explicit successor overrides? Please cover both a runtime revision rebuild and Fork/Clear with operator default high and initial request auto.

[JAORMX]

Could we assert the production-minted ceiling’s exact contents against an independently specified fixture here? Checking expected tools are present and Ceiling.Contains(CapabilitySet) still passes if an undeclared tool is added only to the ceiling. The aggregate grant-rejection tests construct their own ceilings, so they wouldn’t catch that factory regression either.

An exact expected capability/ceiling assertion, followed by an out-of-definition grant attempt that must fail without mutation, would pin the nonwidenable-ceiling contract through the actual construction path. Explicitly denied MCP and automatically added tools would make useful negative controls alongside it.