[Draft] agent_sys with agent config

.gitignore

@@ -62,3 +62,11 @@ mission.md
 .spur_job_*.sh
 .spur_ns_*.sh
 spur-*.out
+
+# serena writes `.serena/` into whatever directory it is given as `--project`,
+# and `examples/env_checker`'s capability-7 measurements point it at the agent
+# asset directory. Config and symbol cache, regenerated on demand, belonging to
+# no package. Ignored rather than remembered: `launch.sh` refuses to start a run
+# while the package tree is dirty, so an untracked by-product that everybody
+# knows to skip would block the gate and teach people to bypass it.
+.serena/

agent_sys/agent/backend.py

@@ -182,6 +182,21 @@ class Assignment(BaseModel):
     #: which is what every backend but `claude_sdk` does today.
     tools: tuple[Any, ...] = ()
 
+    #: **External MCP servers this agent's components declared**, keyed by the
+    #: name the model addresses them under. `env_mgr.Prepared.mcp_servers`,
+    #: straight through.
+    #:
+    #: Typed loosely for `tools`' reason and one more of its own: the values are
+    #: the *SDK's* server vocabulary — `{"type": "stdio", "command": …}` and the
+    #: rest — so a type here would be `agent` declaring a shape it does not own
+    #: and cannot check, on behalf of one of its backends.
+    #:
+    #: **A field and not prose in the readme**, for the reason spec §5.5 gives
+    #: `tools`: an agent told in English to start an MCP server will improvise.
+    #: A backend that cannot express external servers ignores this entirely,
+    #: which is every backend but `claude_sdk` today.
+    mcp_servers: dict[str, Any] = Field(default_factory=dict)
+
     #: `env_mgr.Confinement`, carried for an executor that wants to report what
     #: it will run under. Typed loosely because `agent` may not import `env_mgr`.
     #:

agent_sys/agent/backends/claude_sdk.py

@@ -357,6 +357,34 @@ def _options(self) -> dict[str, Any]:
             options.setdefault("permission_mode", "bypassPermissions")
         if self.assignment.environment:
             options.setdefault("env", dict(self.assignment.environment))
+        if self.assignment.mcp_servers:
+            # **The per-agent components' external servers, under the tool
+            # server's own collision policy.** Not a second policy: the reason a
+            # name may not be taken twice is that `mcp__<server>__<tool>` is what
+            # the model calls, and that is true of a component's server exactly
+            # as it is of `env_mgr`'s. So the refusal below is the same refusal,
+            # said about a different name.
+            #
+            # **Refused rather than merged, and the direction matters.** The
+            # caller's `options["mcp_servers"]` is an operator's configuration;
+            # `assignment.mcp_servers` is what a package declared. Letting either
+            # win silently means one of the two gets different tools than the
+            # ones they wrote, with nothing said — the defect the `env_mgr` key
+            # already carries a comment about, one collision wider.
+            servers = dict(options.get("mcp_servers") or {})
+            clash = sorted(set(servers) & set(self.assignment.mcp_servers))
+            if clash:
+                raise BackendUnsupported(
+                    self.key,
+                    "mcp_servers",
+                    f"this config and this agent's components both declare MCP "
+                    f"server(s) {clash}. The model addresses these as "
+                    f"mcp__<server>__<tool>, so two servers cannot share a name — "
+                    f"rename one side rather than letting the other's tools "
+                    f"disappear.",
+                )
+            servers.update(self.assignment.mcp_servers)
+            options["mcp_servers"] = servers
         if self.assignment.tools:
             # **Spec §5.5's remote surface, and the only place that knows the
             # SDK.** `env_mgr` may not import the SDK and `agent/backend.py` is

agent_sys/agent/docs/design.md

@@ -1297,7 +1297,7 @@ test the chain against nothing that can actually fail to be available.
 | **O1** | **Criterion 13 is not testable as written.** "Losslessly for what both support" requires knowing the intersection of two harnesses' feature sets, and no converter computes it — everyone hand-maintains a table. Both reference implementations' tables fail invisibly: **pandoc** classifies a dropped block as `INFO`, so `--fail-if-warnings` exits 0 with the content gone, and attribute-level loss (a link title) is logged at *no* level; **kompose**'s 25-entry unsupported-key table has **no production caller** — its only caller is its own unit test, and the exported sibling is invoked with an empty map, so eight declared-unsupported keys converted clean with exit 0. The only executable formulation found anywhere is `rulesync`'s per-(target, feature) fixtures asserting the *canonical* value. **The criterion needs to name the artefact that defines "what both support" and the test that keeps it honest** — and to separate *unsupported* (the target cannot express it) from *unknown* (the converter did not handle it), which GitHub Actions Importer does and which criterion 13 conflates |
 | **O2** | **Which `claude` CLI the backend runs is undecided, and it is `env_mgr`'s call.** The SDK prefers its bundled 328 MB executable; `env_mgr` installs plugins into whatever is on `PATH`. Unless `cli_path` is set from the prepared environment, an agent does not see the plugins its own recipe installed. §8.7 |
 | **O3** | **The backend's transcript lands outside the confinement zone.** `~/.claude/projects/<encoded-cwd>/*.jsonl`, containing prompts and reasoning, written by default. Criterion 16 is about the system's record and stays true, but "an agent reaches only its own zone" does not. Three levers exist (`CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_SKIP_PROMPT_HISTORY`, a `SessionStore`); choosing one is `env_mgr`'s, and its spec does not mention the directory |
-| **O4** | **§4.5's "Claude Code's format" is ambiguous.** The declarative `.claude/settings.json` surface and the SDK's `ClaudeAgentOptions(hooks={...})` callbacks are different execution models. Every surveyed converter targets the first; **nobody converts programmatic callbacks at all.** §4.5 must name which surface is canonical, and if it is the callbacks, criterion 13 has no prior art of any kind behind it |
+| **O4** | **ANSWERED — the declarative `settings.json` surface is canonical.** The question was whether *"Claude Code's format"* meant the `.claude/settings.json` tree or the SDK's `ClaudeAgentOptions(hooks={...})` callbacks; every surveyed converter targets the first and **nobody converts programmatic callbacks at all.** Per-agent components forced the ruling, because they had to be *stored* somewhere: L2 and L3 are `.claude/` trees, `env_mgr/agent_assets.py` writes `<zone>/config/settings.json` and points `CLAUDE_CONFIG_DIR` at it, and `spec.md` §4.5 now says so. The warned-of consequence is therefore not incurred — criterion 13 rests on the surface the prior art covers. The callback form stays legal in a backend `config` and is passed through; it is simply not the stored form. **What is still open is narrower and belongs to O1**: no converter exists, so "canonical" is currently a claim about one harness rather than a demonstrated N-to-1 |
 | **O5** | **Two objects hold "the agent spec table".** `AgentSpecRegistry` here, and `AgentMgr.register(spec, **config)` in `task_graph`, which copies its dict onto every minted `Agent.config`. This design assumes the loader feeds the second from the first and that nothing else writes either — but the direction is not stated in any spec, and `engineer_principle.md` §1 forbids two writers for one fact |
 | **O6** | **How each phase becomes separately attributable** — narrowed twice, and the question is now smaller than rev. 3 stated it. `validator` design §8.2 rev. 2 owns the **requirement**: a phase must carry an `agent_id`, because criterion 10 there is untestable otherwise, and the SDK's `agent_id` is *"absent on the main thread"*. This module owns the **mechanism**, and one candidate is ruled out: not one client with several `session_id`s, because `interrupt()` takes no `session_id` and acts on the whole connection (§8.4). `fork_session`, `resume`, a subagent per phase, and a second client remain, and none was tested. The stage-three consistency pass found this document and `validator`'s giving different answers to what turned out to be two different questions; splitting them is what made the residue this small |
 | **O7** | **Mid-run backend failure.** §3.3's "pins the whole run" implies no fallback after the chosen backend dies, and every surveyed project except LiteLLM agrees. LiteLLM's cost is on record — a depth bound, an attempted-targets set against looping graphs, a pin predicate, cooldown feedback and per-failure-class chains, threaded through a loosely-typed `kwargs` at four call sites. Worth knowing before anyone proposes it, and worth stating in the spec either way |

agent_sys/agent/docs/spec.md

@@ -104,6 +104,16 @@ spec** — the two are declared together in a closure.
 | `env` | Environment requirements, resolved by `env_mgr` |
 | `knowledge` | §3.4 |
 | `rules` / `hooks` / `skills` | Configuration, stored in canonical form. §4.5 |
+| `assets` | **Filled by `spec_loader`, not written.** This agent's own directory under the package's `assets/`, found by the same three folder spellings a body lookup uses — `X`, `X.agent`, `agent.X`. Two matching directories is `SpecInconsistent`; an explicit binding is legal and warns. §4.5a |
+| `recipes` | The **agent layer** of three recipe layers; `env_mgr` recipe YAMLs as `agent_sys:<name>` or `package:<relpath>` — a reference names its root. §4.5a |
+
+Nine keys became eleven, and both additions are one thing: **an agent may now
+carry components, not only files.** §4.5a is why that needed new keys instead of
+a longer `skills` list.
+
+**There was a third, `agent_plugins:`, and it is deleted** —
+`docs/spec.provisioning.md` §4: what this repository ships under
+`env_mgr/addons/` is installed by a recipe, and no declaration key reaches it.
 
 ### 3.2 Permissions are not here
 
@@ -377,6 +387,62 @@ Picking one canonical format matters more than which one is picked: with N
 harnesses, storing each in its own format needs N² converters, and storing one
 canonical form needs N.
 
+**Which Claude Code surface is canonical: the declarative one.** Design O4 asked,
+because *"Claude Code's format"* named two different execution models — the
+`.claude/settings.json` tree and the SDK's `ClaudeAgentOptions(hooks={...})`
+callbacks — and every surveyed converter targets the first while nobody converts
+programmatic callbacks at all. The answer is the first, and it is now what the
+code does: `env_mgr` writes `<zone>/config/settings.json` and points
+`CLAUDE_CONFIG_DIR` at it. The consequence O4 warned about is therefore not
+incurred — criterion 13 rests on the surface the prior art actually covers.
+
+The callback form is not forbidden; a backend config may still carry `hooks`, and
+`claude_sdk` passes it through. What it is not is the **stored** form, so nothing
+in a package or a component is written that way.
+
+### 4.5a A component is a tree, and that needed three keys
+
+§4.5's three lists are lists of *files*. A Claude Code component is a directory:
+a skill is a directory, a plugin marketplace is a directory of directories, and
+an MCP server is a process to register rather than a file to place. Naming every
+file would make a package author restate a layout the harness already fixes.
+
+**Two routes, and only one copies a tree.** `docs/spec.provisioning.md` is
+normative here and supersedes both the L1/L2/L3 numbering and the three-origins
+table that replaced it.
+
+| what | declared how |
+|---|---|
+| anything upstream ships, and anything `agent_sys` ships under `env_mgr/addons/` | `recipes: [...]`, or the package/default recipe layer; `tags: [internal]` marks an item as ours |
+| what one task package carries for one agent | **undeclared** — `<assets>/.claude/`, copied |
+
+**The copied tree is in Claude Code's canonical layout**:
+`settings.json`, `skills/<name>/`, `plugins/` (a local marketplace),
+`.mcp.json`, and `tools/*.mcp.py`. It is the harness's own layout rather than
+ours, so a file is placed and not converted. (A `tools/*.tooldef.py` was a fourth
+member until 2026-09-04, when the in-process route it used was deleted —
+`docs/spec.provisioning.md` §6.)
+
+**A package's own material is undeclared on purpose.** A declaration would be a
+second statement of what the directory already says, and the two would drift the
+first time somebody moved it without editing the YAML.
+
+`env_mgr/agent_assets.py` installs both; `env_mgr/docs/design.md` §11.5a is
+the mechanism, including the measured ordering constraint that decides when
+`settings.json` is written, the marketplace copy probe F forced, and why a
+recipe runs the shipped machinery as a subprocess. What reaches this package
+from a component is `Assignment.mcp_servers`. `Assignment.tools` also exists,
+but nothing a component ships arrives through it — it carries `env_mgr`'s own
+remote surface and nothing else (§5.5).
+
+**A component names a binary through `${VAR}`, never through `PATH`.** An
+`.mcp.json` entry is expanded against the zone environment before it becomes an
+`mcp_servers` entry, and an unresolved name is an error. That is not a
+convenience: `PATH` is derived from the granted policy at prepare step 2, and a
+directory a recipe installs into does not exist until step 6b — so
+`"${UV_TOOL_BIN_DIR}/serena"` is the only spelling that works, and it is the one
+measured working.
+
 ---
 
 ## 5. `claude-agent-sdk` as the first backend

agent_sys/agent/runner.py

@@ -761,6 +761,10 @@ def _deploy(self, spec: Any) -> Executor:
             # `Prepared` from before this field existed is still a valid one,
             # which is the same allowance every other optional field here gets.
             tools=tuple(getattr(prepared, "tools", ()) or ()),
+            # The per-agent components' external servers, same allowance and
+            # for the same reason: a `Prepared` built before this field existed
+            # is still a valid one.
+            mcp_servers=dict(getattr(prepared, "mcp_servers", None) or {}),
             confinement=getattr(prepared, "confinement", None),
             agent_cli=prepared.agent_cli,
             # **Read, not inferred**, and that is the field's whole reason.

agent_sys/agent/spec.py

@@ -106,6 +106,34 @@ class AgentSpec(_Model):
     hooks: list[str] = Field(default_factory=list)
     skills: list[str] = Field(default_factory=list)
 
+    #: This agent's own directory under the package's `assets/`, package-relative,
+    #: or `""` when it has none. **Filled by `spec_loader`, not written**, from the
+    #: same folder convention that scopes a task's body lookup.
+    #:
+    #: Spec §3.1 listed nine keys and this is a tenth, so it is a spec change and
+    #: not a model detail: what an agent carries turned out not to fit in `rules` /
+    #: `hooks` / `skills`, which are three lists of *paths to individual files*. A
+    #: Claude Code component is a **tree** — a skill is a directory, a plugin
+    #: marketplace is a directory of directories — and naming each file would make
+    #: the package author restate a layout the harness already fixes.
+    assets: str = ""
+
+    #: `env_mgr` recipe YAMLs run before the session, each written
+    #: ``<scheme>:<ref>`` — ``agent_sys:<name>`` for one this repository ships
+    #: under `env_mgr/recipes/`, ``package:<relpath>`` for one this task package
+    #: carries. **A reference names its root**: there is no bare form and no
+    #: fallback, because until 2026-09-04 the root was decided by which candidate
+    #: happened to exist. The
+    #: route by which an agent asks for components this repository does not ship
+    #: and should not vendor (serena, marketplace plugins, apt/pip tools) — and,
+    #: with an item carrying ``tags: [internal]``, for one that it does.
+    #:
+    #: **Also filled by convention** when the agent carries its own recipe:
+    #: `assets/env_recipe.<name>.yaml` and every other permutation of those
+    #: tokens (`spec_loader/assets.py`, `fill_agent_env_recipe`). Declaring it
+    #: by hand is legal, warns, and wins whole.
+    recipes: list[str] = Field(default_factory=list)
+
     @field_validator("backends", mode="before")
     @classmethod
     def _normalise(cls, value: Any) -> Any:

agent_sys/cli/main.py

@@ -21,6 +21,7 @@
 
 import argparse
 import logging
+import os
 import shutil
 import sys
 from collections.abc import Sequence
@@ -49,6 +50,7 @@
 from env_mgr.prepare import EnvManager, permissions_enforced
 from env_mgr.protocols import NoConfinement, PrepareRefused, UnresolvedGrant
 from env_mgr.remote.connection import sync_transport
+from env_mgr.servers import REGISTRY_ENV_VAR, owned_servers
 from env_mgr.sync import check_delete_scope
 from monitor import (
     NullUserSink,
@@ -209,7 +211,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         try:
             if args.verb == "show":
                 return _show(args, stream)
-            return _run(args, stream)
+            return _run(args, stream, stack)
         except package.PackageNotFound as exc:
             return _fail(stream, PRECONDITION, str(exc))
         except SpecInvalid as exc:
@@ -259,12 +261,16 @@ def _show(args: argparse.Namespace, stream: Stream) -> int:
 # run
 
 
-def _run(args: argparse.Namespace, stream: Stream) -> int:
+def _run(args: argparse.Namespace, stream: Stream, stack: ExitStack) -> int:
     if args.clean:
         return _clean(args, stream)
     if args.dry_run:
         return _dry_run(args, stream)
-    return _real_run(args, stream)
+    # `stack` reaches only `_real_run`: it is what stops the servers a run
+    # started, and the other two verbs start none. `clean` removes a directory;
+    # `dry-run` dispatches nothing, which its own body asserts rather than
+    # assumes.
+    return _real_run(args, stream, stack)
 
 
 def _clean(args: argparse.Namespace, stream: Stream) -> int:
@@ -326,7 +332,7 @@ def _layout(args: argparse.Namespace) -> Layout:
     return layout_for(root).create()
 
 
-def _real_run(args: argparse.Namespace, stream: Stream) -> int:
+def _real_run(args: argparse.Namespace, stream: Stream, stack: ExitStack) -> int:
     """Everything. Needs credentials, a sandbox, and a model.
 
     The order of the two preconditions is measured rather than aesthetic: the
@@ -351,6 +357,23 @@ def _real_run(args: argparse.Namespace, stream: Stream) -> int:
     promises = expectations.for_package(package.locate(args.package))
 
     layout = _layout(args)
+    # **The servers this run starts are stopped when this block unwinds.**
+    # `env_mgr` starts them, so `env_mgr` stops them: this is a call site, not a
+    # transfer of responsibility, and nothing below has to remember to clean up.
+    #
+    # The path is set on `os.environ` and not passed, because that is the only
+    # channel that reaches the installer: a recipe runs as a grandchild
+    # (`agent_assets._run_recipe` shells `python -m env_mgr`), and its
+    # environment is built from this process's. It is a **per-run** constant, so
+    # unlike `CLAUDE_CONFIG_DIR` -- which `agent_assets._child_env` refuses to
+    # set globally because it is per-attempt and the runner is threaded -- there
+    # is no value here for two threads to take from each other.
+    #
+    # What this does and does not promise is in `env_mgr/servers.py`: servers
+    # stop on normal and handled-error exit, and leak on SIGTERM and SIGKILL.
+    registry_file = layout.run / "servers.json"
+    os.environ[REGISTRY_ENV_VAR] = str(registry_file)
+    stack.enter_context(owned_servers(registry_file))
     root = package.locate(args.package)
     # **Read once, at start-up, and it is the run's fact rather than a task's.**
     # `env_mgr.prepare.permissions_enforced()` is the single reader of the