docs(plugins): explain saved configuration and launch-only MCP servers

plugin-examples/agent-configuration/README.md

@@ -1,14 +1,19 @@
 # Agent configuration
 
-Changes new Codex agents through `server.before("agent.create", ...)`:
+Sets saved Codex options through `server.before("agent.create", ...)`:
 
 - Sets `config.providerOptions.sandbox_mode` to `workspace-write`.
 - Sets `config.providerOptions.approval_policy` to `on-request`.
-- Adds the `company` server to `config.mcpServers`.
-- Preserves other configuration, provider options, MCP servers, and environment overrides.
+- Preserves other configuration and provider options.
+
+Adds the `company` MCP server to Codex launches through
+`server.before("agent.session_open", ...)`. The server is never saved in the agent's configuration;
+existing saved MCP servers are preserved. Existing agents receive the server through the
+[session reopen behavior](../../public-docs/plugins/reference.md#attach-tools-to-agents).
 
 Replace `https://tools.example.com/mcp` in `index.server.ts` with your MCP server URL before using
-this example. The URL is a placeholder. The `company` entry replaces an existing server with that name.
+this example. A `company` name collision with a saved server or another
+plugin fails the session open and names both sources.
 
 Install on a daemon with plugins enabled:
 
@@ -16,11 +21,13 @@ Install on a daemon with plugins enabled:
 paseo plugin install /absolute/path/to/plugin-examples/agent-configuration
 ```
 
-The callback receives the request after earlier plugins have transformed it. The nested spreads
-preserve their settings; the explicit values replace only the named fields. Paseo validates and saves
-the resulting configuration before starting the agent. Existing agents are unchanged.
+Each session-open callback receives only this plugin's MCP servers. The nested spreads preserve
+entries added by this plugin's earlier callbacks. The create callback receives configuration after
+earlier plugins have transformed it; its explicit Codex options replace the named fields in the
+saved configuration of new agents and remain after this plugin is disabled.
 
-See the [lifecycle reference](../../public-docs/plugins/reference.md#lifecycle-hooks) for ordering
-and callback shapes. [Lifecycle actions](../lifecycle-actions) demonstrates provider switching and
-environment injection. Its provider-switch callback clears provider options when changing Codex to
-Claude, so use these examples separately when trying the Codex-specific settings.
+See [Inject MCP servers](../../public-docs/plugins/reference.md#inject-mcp-servers) for choosing
+between saved configuration and plugin-owned servers. [Lifecycle actions](../lifecycle-actions)
+demonstrates provider switching and environment injection. Its provider-switch callback clears
+provider options when changing Codex to Claude, so use these examples separately when trying the
+Codex-specific settings.

plugin-examples/agent-configuration/index.server.ts

@@ -15,12 +15,22 @@ export default function contribute(server: PluginServerContext) {
           sandbox_mode: "workspace-write",
           approval_policy: "on-request",
         },
-        mcpServers: {
-          ...request.config.mcpServers,
-          company: {
-            type: "http",
-            url: "https://tools.example.com/mcp",
-          },
+      },
+    };
+  });
+
+  server.before("agent.session_open", ({ request }) => {
+    if (request.provider !== "codex") {
+      return;
+    }
+
+    return {
+      ...request,
+      mcpServers: {
+        ...request.mcpServers,
+        company: {
+          type: "http",
+          url: "https://tools.example.com/mcp",
         },
       },
     };

plugin-examples/agent-configuration/paseo-plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "agent-configuration",
   "requirements": {
-    "paseo": ">=0.8.0"
+    "paseo": ">=0.13.2"
   }
 }