@jc_stack/ez-agents 0.1.0-beta.33 → 0.1.0-beta.34

package/.env.example

@@ -48,6 +48,10 @@ EZ_REPAIR_ENABLED=true
 # Optional native application-only runtime: no Telegram bot or token.
 # Requires EZ_APPLICATION_PORT; administrator bootstrap uses the real operator ID.
 # EZ_TELEGRAM_ENABLED=false
+# Isolation class from agent creation (default isolated).
+# EZ_ISOLATION=isolated
+# EZ_EXECUTOR_TRANSPORT=local
+# Host-capable: EZ_ISOLATION=host-capable and EZ_EXECUTOR_TRANSPORT=host
 # Private application-only local container isolation (optional; default workspace-write).
 # EZ_CODEX_SANDBOX=external
 

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.1.0-beta.34
+
+- Correct setup guidance for host-capable custom Codex providers and replace
+  stale pinned-beta installation guidance with current release records.
+
+- Record an isolation class at agent creation. The default is `isolated`: the
+  native CLI runs in the relay (`EZ_EXECUTOR_TRANSPORT=local`). Pass
+  `--isolation host-capable` to reuse the installer UID and host CLI login.
+  Mismatched class and transport fail closed. Isolated Codex sets
+  `EZ_CODEX_SANDBOX=external`. Host transport is not started for isolated
+  agents. Unlabeled existing host transports stay host-capable.
+- Install pinned Codex CLI `0.153.4` in the relay runtime image so isolated
+  agents resolve `codex` on PATH. Isolated jobs keep auth in
+  `control/cli/codex` and do not link the operator `~/.codex`.
+
+- Confine macOS host jobs to their bound workspace and prevent cross-agent
+  plugin registry access.
+- Support agent-scoped OpenRouter models through the native Codex engine and
+  start a new native session when the provider or model changes.
+- Resolve native CLIs from the host PATH, expose captured presets in application
+  run receipts, and seed one purpose-scoped AGENTS.md for new agents.
+
 ## 0.1.0-beta.33
 
 - Allow compatible plugin updates to add commands to existing services, registering
@@ -21,6 +43,9 @@
   host CLI configuration needed for restricted read-only plugin commands.
 - Clarify domain-agent positioning while preserving native engine ownership.
 
+- Prevent accidental cross-agent plugin access by rejecting relay-bound registry
+  calls outside the owning workspace, and restrict its host-folder bindings to
+  workspace roots explicitly granted by the host.
 - Answer native app-server requests with their current protocol shapes. Scheduled
   `codex-gui` browser work now surfaces approval requests and grants only its
   active turn session-scoped HTTPS browser-origin and Chrome app elicitations,

package/Dockerfile

@@ -9,6 +9,10 @@ COPY . .
 FROM dependencies AS test
 RUN pnpm verify
 FROM dependencies AS runtime
+# Keep this pin aligned with TASK_CODEX_VERSION. Isolated agents run this CLI
+# in the relay; do not bind-mount the operator's ~/.codex.
+ARG CODEX_CLI_VERSION=0.153.4
+RUN npm install -g @openai/codex@${CODEX_CLI_VERSION} && command -v codex
 RUN chmod +x docker/entrypoint.sh bin/ezenciel-agents* && mkdir -p /state/control /state/home /workspace && chown node:node /state/control /state/home /workspace
 RUN node -e 'for (const [name, target] of Object.entries(require("./package.json").bin)) require("node:fs").symlinkSync("/app/" + target, "/usr/local/bin/" + name)'
 ENV HOME=/state/home EZ_AGENT_WORKSPACE=/workspace EZ_CONTROL_DIR=/state/control EZ_EXECUTOR_CLI=grok PATH=/app/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

package/README.md

@@ -148,15 +148,19 @@ the user's request and preserve its scope.
 
 ## Package and runtime
 
-**Beta 0.1.0-beta.12 — for testing on a trusted machine.** Offline and Docker
-fixtures are verified. Live account onboarding and reboot acceptance for this
-release are deferred; this is not a production-readiness claim. The source branch
-may contain changes newer than the published beta; inspect the supplied artifact's
-documentation when installing a pinned release.
-
-The npm package is `@jc_stack/ez-agents` (channel `beta`). Download a pinned
-release with `npm pack @jc_stack/ez-agents@0.1.0-beta.12`, or get the tarball and SHA256SUMS from
-[GitHub prereleases](https://github.com/jdorado/ez-agents/releases/tag/v0.1.0-beta.12).
+**Published beta releases are for testing on a trusted machine.** Offline and
+Docker fixtures are verified for the selected release. Live account onboarding
+and reboot acceptance remain beta gates; this is not a production-readiness
+claim. The source branch may contain changes newer than the published beta, so
+inspect the supplied artifact's documentation when installing a pinned release.
+
+The npm package is `@jc_stack/ez-agents`. Approved beta publications use npm's
+`latest` distribution tag while their versions and GitHub releases remain
+prereleases. For a reproducible download, choose an exact version from
+[GitHub prereleases](https://github.com/jdorado/ez-agents/releases) and substitute
+it for `VERSION` in `npm pack @jc_stack/ez-agents@VERSION`.
+You can also download the release's candidate tarball and verify its SHA-256
+against the attached release receipt or release notes.
 GitHub remains under `jdorado`; npm uses `jc_stack`. Do not install the unrelated
 unscoped `ez-whatsapp` package.
 
@@ -242,28 +246,32 @@ credentials, startup, and verified pairing; never present this as human homework
 | `ezenciel-agents-install build` | Build once per artifact, with a private log and duplicate-build detection |
 | `ezenciel-agents-install status --deployment <path>` | Distinguish runtime/configuration, pairing and Telegram reply evidence |
 | `ezenciel-agents-create --register-cli <current-cli>` | Record the CLI that installs the initial package |
-| `ezenciel-agents-create --name <name> --purpose <purpose>` | Create an agent inheriting the installation CLI; token via stdin |
+| `ezenciel-agents-create --name <name> --purpose <agent-brief>` | Create an agent from the installing LLM's compact brief; packaged Codex defaults isolated, other CLIs stay host-capable; token via stdin |
+| `ezenciel-agents-create --name <name> --purpose <agent-brief> --isolation host-capable` | Explicitly reuse the host CLI and installer UID |
 | `ezenciel-agents-host` | Invoke the existing shared host CLI for this deployment |
-| `ezenciel-agents-setup configure <executor>` | Private configuration and missing starter files; preserves personal files |
-| `ezenciel-agents-setup configure <executor> --token-stdin` | Same, with the BotFather token supplied privately through stdin |
+| `ezenciel-agents-setup configure <executor> --purpose-file <path>` | Private configuration and missing starter files; fresh workspaces require installer-scoped purpose; preserves personal files |
+| `ezenciel-agents-setup configure <executor> --purpose-file <path> --token-stdin` | Same, with the BotFather token supplied privately through stdin |
 | `ezenciel-agents-setup service` | Start only the Docker relay bound by `docker.env` in the current directory; register the [host service](docs/host-service.md) separately |
 | `ezenciel-agents-owner status` | Inspect the owner and pending pairing requests |
 | `ezenciel-agents-owner approve <telegram-user-id>` | Approve the verified owner; never an arbitrary first sender |
 | `ezenciel-agents-setup status` | Inspect installed executor choices |
-| `ezenciel-agents-setup init` | Seed only missing workspace guidance |
+| `ezenciel-agents-setup init --purpose-file <path>` | Seed missing workspace guidance; purpose is optional only when AGENTS.md already exists |
 
 Run runtime tools through `ezenciel-agents-docker run --rm relay <command>`
 as shown in the Docker guide. Keep the Docker engine available; Compose owns
-restart and shutdown. The installing agent registers the small host CLI transport with the native service manager.
+restart and shutdown. Host-capable agents register the small host CLI transport with the native service manager. Isolated agents do not.
 
 ## Runtime and development reference
 
 The selected host CLI runs in this agent's persistent workspace and owns its
 Markdown/work files. New conversations and AI changes preserve those files.
-`AGENTS.md`, `SOUL.md`, and `USER.md` are seeded; `MEMORY.md` is
-optional. Installed plugin snippets and skill paths come from `ez tools list --details`; no tool inventory file needs maintenance. Received files go in `inbox/`, tasks and deliverables in `work/`.
-Credentials and control state stay outside the mind. File separation is not
-OS isolation against a process running as the same user.
+One compact, purpose-scoped `AGENTS.md` is seeded; `MEMORY.md` is optional.
+The installing LLM authors the initial brief from the owner's request and known
+application context; Ez stores it without trying to infer the product itself.
+Installed plugin snippets and skill paths come from `ez tools list --details`; no tool inventory file needs maintenance. Received files go in `inbox/`, tasks and deliverables in `work/`.
+Credentials and control state stay outside the mind. Isolated agents use relay
+mounts as the filesystem boundary. Host-capable file separation is not OS
+isolation against a process running as the same user.
 
 In Telegram, **Conversations** (or `/chats`) lists this agent's saved Ez
 conversations by name. Tap a name to continue its native engine session and

package/THIRD_PARTY_NOTICES.md

@@ -8,7 +8,7 @@ The container is built locally; no bundled third-party binary image is promised.
 
 Direct runtime dependencies: grammy (MIT), tsx (MIT). Development dependencies
 include TypeScript (Apache-2.0) and Node type definitions (MIT). The runtime
-image installs ffmpeg and Debian packages: redistributing that image requires
-review of its exact package build, notices and corresponding-source obligations.
-Docker and the selected host AI CLI are separately installed products, not covered
-by this repository's MIT license.
+image installs ffmpeg, Debian packages, and pinned `@openai/codex` (Apache-2.0):
+redistributing that image requires review of its exact package build, notices and
+corresponding-source obligations. Docker and a host-capable AI CLI remain
+separately installed products, not covered by this repository's MIT license.

package/compose.yaml

@@ -17,6 +17,7 @@ services:
       EZ_RELAY_UID: ${EZ_RELAY_UID:-1001}
       EZ_REPAIR_ENABLED: ${EZ_REPAIR_ENABLED:-true}
       EZ_AGENT_PURPOSE_FILE: /run/agent-purpose.md
+      EZ_ISOLATION: ${EZ_ISOLATION:-}
       EZ_EXECUTOR_TRANSPORT: ${EZ_EXECUTOR_TRANSPORT:-host}
       EZ_CHANNEL_BACKEND_URL: ${EZ_CHANNEL_BACKEND_URL:-}
       EZ_TELEGRAM_WEB_APP: ${EZ_TELEGRAM_WEB_APP:-}
@@ -50,7 +51,7 @@ services:
       retries: 3
 configs:
   agent_purpose:
-    file: ${EZ_AGENT_PURPOSE_FILE:-./templates/agent/SOUL.md}
+    file: ${EZ_AGENT_PURPOSE_FILE:-./templates/agent-purpose.md}
 secrets:
   relay_env:
     file: ${EZ_RELAY_ENV_FILE:?Set EZ_RELAY_ENV_FILE to the private relay env file}

package/docker/smoke.mjs

@@ -10,6 +10,7 @@ const volume = `${holder}-control`;
 const application = `${holder}-application`;
 const marker = 'qa-private-secret-never-in-executor';
 writeFileSync(join(dir, 'relay.env'), `TELEGRAM_BOT_TOKEN=${marker}\n`, { mode: 0o600 });
+writeFileSync(join(dir, 'purpose.md'), 'Verify the packaged Ez runtime.\n', { mode: 0o644 });
 writeFileSync(join(dir, 'node'), `#!/bin/sh\nIFS= read -r value <&3\n[ "$value" = "TELEGRAM_BOT_TOKEN=${marker}" ] || exit 91\nexec /usr/local/bin/node "$@"\n`, { mode: 0o555 });
 const run = (args) => spawnSync('docker', args, { encoding: 'utf8', timeout: 60000 });
 try {
@@ -17,17 +18,19 @@ try {
     '--mount',`type=bind,src=${join(dir,'node')},dst=/qa/node,readonly`,'-e','PATH=/qa:/usr/local/bin:/usr/bin:/bin',image,'application','--help']);
   assert.equal(inherited.status,0,inherited.stderr);
   const nonroot = ['--user','20000:20000','--read-only','--cap-drop','ALL','--security-opt','no-new-privileges',
+    '--mount',`type=bind,src=${join(dir,'purpose.md')},dst=/run/agent-purpose.md,readonly`,'-e','EZ_AGENT_PURPOSE_FILE=/run/agent-purpose.md',
     '--tmpfs','/tmp:mode=1777','--tmpfs','/state/control:uid=20000,gid=20000,mode=700',
     '--tmpfs','/state/home:uid=20000,gid=20000,mode=700','--tmpfs','/workspace:uid=20000,gid=20000,mode=700',
-    '-e','EZ_TELEGRAM_ENABLED=false','-e','EZ_APPLICATION_PORT=8110','-e','EZ_EXECUTOR_TRANSPORT=local','-e','EZ_EXECUTOR_CLI=codex'];
+    '-e','EZ_TELEGRAM_ENABLED=false','-e','EZ_APPLICATION_PORT=8110','-e','EZ_ISOLATION=isolated','-e','EZ_EXECUTOR_TRANSPORT=local','-e','EZ_EXECUTOR_CLI=codex'];
   const help = run(['run','--rm',...nonroot,image,'application','--help']);
   assert.equal(help.status,0,help.stderr);
   assert.match(help.stdout,/ezenciel-agents-application/);
   const login = run(['run','--rm',...nonroot,'--entrypoint','/bin/bash',image,'-lc',
-    'command -v ezenciel-agents-application && command -v ezenciel-agents-message && ezenciel-agents-message --help']);
+    'command -v ezenciel-agents-application && command -v ezenciel-agents-message && command -v codex && ezenciel-agents-message --help && codex --version']);
   assert.equal(login.status,0,login.stderr);
   assert.match(login.stdout,/\/usr\/local\/bin\/ezenciel-agents-application/);
   assert.match(login.stdout,/\/usr\/local\/bin\/ezenciel-agents-message/);
+  assert.match(login.stdout,/codex-cli 0\.153\.4/);
   const started = run(['run','-d','--name',application,...nonroot,image,'start']);
   assert.equal(started.status,0,started.stderr);
   let ready = false;
@@ -82,5 +85,5 @@ try {
   assert.equal(run(['kill',holder]).status,0);
   const recovered=run(['run','--rm','-v',`${volume}:/state/control`,image,'exec','node','-e','process.exit(0)']);
   assert.equal(recovered.status,0,recovered.stderr);
-  console.log('Docker smoke passed: direct non-root application help/start/health/stop, inherited private descriptor, non-root executor, private secret isolation, literal argv, exit code, no Docker socket, duplicate writer rejection and crash lock release.');
+  console.log('Docker smoke passed: direct non-root application help/start/health/stop, inherited private descriptor, non-root executor, isolated Codex on PATH, private secret isolation, literal argv, exit code, no Docker socket, duplicate writer rejection and crash lock release.');
 } finally { run(['rm','-f',holder,application]); run(['volume','rm',volume]); rmSync(dir, {recursive:true, force:true}); }

package/docs/application-channel.md

@@ -6,6 +6,10 @@ outbox. The application supplies domain tools and keeps its UI/content API; it
 can remove its own model runner, continuation loop and engine authentication.
 This is separate from the older outbound channel-backend integration.
 
+Run admission, status and inbox receipts include the immutable `preset` captured
+for that run so an application can label delivered messages with the engine choice
+that actually produced them.
+
 ## Shared runtime controls
 
 Register with `--share-owner` (the existing `--share-telegram` spelling is an
@@ -267,6 +271,8 @@ separate CLI histories. A retry cannot change an admitted turn's AI choice.
 
 Register owner-chat channels with `--share-owner` and submit `followOwner:true`.
 Web, phone and Telegram then use the same selected native conversation and AI.
+A later same-client provider or model change starts a new native conversation for the next
+admitted turn; already-queued work keeps its original engine.
 This works without Telegram and requires no transcript replay or new runner.
 Scoped application conversations remain separate when the flag is omitted.
 Owner identity does not automatically merge histories or grant learner access.

package/docs/architecture/ai-selection.md

@@ -8,7 +8,9 @@ At intake each journal entry receives an immutable preset and conversation ID.
 Batches cannot cross that boundary. The run copies that choice and invokes the
 native adapter with its exact model/effort. A later menu change cannot reroute it.
 Old conversation metadata is retained only so accepted work can finish; selecting
-a different CLI never restores that CLI's old history.
+a different CLI never restores that CLI's old history. Selecting a different provider
+or model on the same client does not resume the previous selection's native thread; the next
+admitted turn starts a new native conversation.
 
 Grok/Claude accept caller-selected native UUIDs. Codex/OpenCode generate IDs, so
 the adapter reads only their typed JSONL session metadata; stdout never becomes a

package/docs/docker-runtime.md

@@ -1,9 +1,9 @@
 # Docker runtime and shared host CLI
 
-Docker Compose owns each relay and executable plugin. The CLI the user installs
-Ez from stays on the host, with its existing authentication. All agents in that
-installation use that CLI; there is no second CLI installation or agent-specific
-CLI login. The relay image contains Node, relay dependencies and ffmpeg.
+Docker Compose owns each relay and executable plugin. Isolated agents run the
+native CLI from the relay image (pinned Codex). Host-capable agents reuse the
+CLI the user installed Ez from, with its existing authentication. The relay
+image contains Node, relay dependencies, ffmpeg and that pinned Codex CLI.
 The runtime image exposes Ez commands through the wrappers in `/app/bin`, including
 `ezenciel-agents-application`; application images do not need to link Ez themselves.
 The image also installs package-manifest commands in `/usr/local/bin`, so native
@@ -13,26 +13,33 @@ belongs to Ez packaging, not an application image or an engine-specific prompt.
 ## Agent binding
 
 Use [agent-led setup](setup.md). `ezenciel-agents-create` accepts a name, purpose,
+optional `--isolation isolated|host-capable` (default `isolated`),
 a bot token through stdin; the CLI defaults to the one recorded at package
 installation by `--register-cli <current-cli>`. It creates a private deployment
 with a unique Compose project, mind, control directory and secret file. Names
 cannot overwrite existing agents. `installation.json` keeps subsequent agents
 on the same CLI. Each agent gets its own purpose and native conversation IDs.
+`isolated` sets `EZ_EXECUTOR_TRANSPORT=local` and runs the native CLI in the
+relay. `host-capable` sets `host` and reuses the installer UID; unlabeled
+existing host transports stay host-capable so they are not flipped.
 
 `docker.env` contains explicit absolute paths, never token values:
 
 ```dotenv
 COMPOSE_PROJECT_NAME=ez-agent-family
 EZ_EXECUTOR_CLI=grok
+EZ_ISOLATION=isolated
+EZ_EXECUTOR_TRANSPORT=local
 EZ_AGENT_WORKSPACE=/absolute/private/agents/family/mind
 EZ_CONTROL_DIR=/absolute/private/agents/family/control
 EZ_RELAY_ENV_FILE=/absolute/private/agents/family/relay.env
 EZ_AGENT_PURPOSE_FILE=/absolute/private/agents/family/purpose.md
 ```
 
-The installing agent runs `ezenciel-agents-host` under the host's service manager
+Host-capable agents run `ezenciel-agents-host` under the host's service manager
 with `EZ_DEPLOYMENT_DIR` bound to that deployment. This small transport invokes
-the existing CLI; it is not a second relay or model loop. It reads requests from
+the existing CLI; it is not a second relay or model loop. Isolated agents do not
+start it. It reads requests from
 the agent's control directory, fixes cwd/control/tool paths from its installation
 binding, strips environment secrets, forwards native output and exit status, and
 propagates cancellation. Requests cannot select another executable. No network
@@ -41,9 +48,10 @@ is required. Host Node 22+ and the package dependencies run this transport.
 
 Mount mind and control at identical absolute paths in Docker and on the host,
 so incoming files, message attachments and CLI outputs need no path translation.
-Only that agent's directories are mounted into its relay. The host CLI reuses the existing login. Codex receives a private per-agent
+Only that agent's directories are mounted into its relay. Host-capable CLI reuses the existing login. Codex receives a private per-agent
 state home with linked authentication; global memory/configuration is excluded.
-This is not an OS security boundary between agents running as the same user.
+Host-capable is not an OS security boundary between agents running as the same user.
+Isolated agents use the relay mounts; sibling host paths are not present.
 Plugin setup also binds `toolsHome` in the host configuration. Codex receives
 write access to that registry and network access for the Docker client; the host
 rejects registries belonging to a different workspace. Restart the host worker
@@ -146,13 +154,22 @@ default. Existing queued jobs retain their captured execution choice.
 
 ## Codex context isolation
 
-The host Codex binary and existing login are reused, but each agent has its own
-`control/cli/codex` state directory. Only authentication is linked to the host
+Isolated agents run the image Codex with `EZ_CODEX_SANDBOX=external`. Auth is a
+real file at that agent's `control/cli/codex/auth.json`. Do not bind-mount the
+operator `~/.codex` or `$HOME` into an isolated relay. Host-capable agents reuse
+the host Codex binary and login, with a
+`control/cli/codex` state directory. The native CLI is resolved from the host
+PATH, not the package `binDir`, so a shared runtime or one agent's wrapper cannot
+retarget another agent's `CODEX_HOME`. Only authentication is linked to the host
 login; global configuration, sessions and memories are not imported. Global
 memory and host skill discovery are disabled for relay jobs. A conversation
 that already received unrelated global context must be replaced with a fresh
 native conversation; disabling injection does not remove prior turn content.
 This prevents automatic context sharing, not adversarial access by the host user.
+On macOS host jobs, Seatbelt also denies sibling directories of the bound
+workspace (a tenant farm), while allowing explicitly shared and additional
+workspace grants and leaving `$HOME` readable for the host CLI.
+Codex then uses `danger-full-access` so it does not apply a nested Seatbelt.
 
 ## Chat latency
 

package/docs/host-service.md

@@ -1,7 +1,8 @@
 # Host transport startup
 
-Register one service per deployment after initializing its tools. Substitute the
-exact absolute paths below. Use the existing authenticated host user and include
+Register one service per **host-capable** deployment after initializing its tools.
+Isolated agents run the native CLI in the relay and must not start this service.
+Substitute the exact absolute paths below. Use the existing authenticated host user and include
 its Node 22+, pnpm (or Corepack), Docker and CLI directories in PATH. Resolve the
 actual installed launchers first; shell aliases and interactive shell startup
 files are not available to services. No bot token goes in these service files.
@@ -21,6 +22,7 @@ Description=Ez family host CLI transport
 Type=simple
 Environment=EZ_DEPLOYMENT_DIR=/absolute/private/agents/family
 Environment=PATH=/absolute/node/bin:/absolute/package-manager/bin:/absolute/cli/bin:/usr/local/bin:/usr/bin:/bin
+EnvironmentFile=-%h/.config/ez/family-provider.env
 ExecStart=/absolute/ez-package/package/bin/ezenciel-agents-host
 Restart=on-failure
 RestartSec=5
@@ -29,6 +31,13 @@ RestartSec=5
 WantedBy=default.target
 ```
 
+When the installation declares a custom Codex provider, create that private
+environment file with mode `0600` and only the referenced key, for example
+`OPENROUTER_API_KEY=...`. Provider and model selection do not belong in the
+environment; they remain agent runtime state. The supervisor forwards only keys
+explicitly named by the agent's provider binding, and the Codex subprocess still
+receives none of the relay or plugin secrets.
+
 ```sh
 systemctl --user daemon-reload
 systemctl --user enable --now ez-family.service
@@ -81,10 +90,12 @@ main/plugin replacement. See [upgrade setup, tools and recovery](upgrades.md). E
 
 ## Shared application workspace
 
-Codex tasks inherit the agent's `control/cli/codex/auth.json` binding. Its default
-is a link to the host user's existing login. An operator may provision a private
-agent credential there during migration; new task homes link to that binding,
-preserving it rather than reverting to a different or expired host login.
+Codex tasks inherit the agent's `control/cli/codex/auth.json` binding. Host-capable
+default is a link to the host user's existing login. Isolated agents use a real
+file in that directory and the image Codex; they do not link `~/.codex`. An
+operator may provision a private agent credential there during migration; new
+task homes link to that binding, preserving it rather than reverting to a
+different or expired host login.
 
 An agent binding may set `sharedWorkspace` to an absolute canonical application
 repository. The host resolves its canonical path, adds that directory to Codex

package/docs/plugins.md

@@ -291,6 +291,21 @@ already exist on the host. Keep indexes and writable metadata in the plugin's
 normal volume. This uses Docker bind mounts; it copies no source bytes and
 starts no provider sync. Read-only is the default.
 
+For a relay-bound agent, the source must be inside its workspace/shared workspace
+or under a plugin-specific root granted in the agent's external host configuration:
+
+```json
+{
+  "pluginFolderRoots": {
+    "library": ["/absolute/existing/notes"]
+  }
+}
+```
+
+The agent cannot add this grant through its registry. A missing grant fails before
+Compose or registry state changes. Standalone registries remain operator-owned and
+do not use a relay host allowlist.
+
 Stop the plugin before changing a binding:
 
 ```sh

package/docs/repair.md

@@ -30,7 +30,7 @@ True makes the capability available; it does not itself grant a repair mandate.
 The setting does not change filesystem/GitHub permissions and does
 not cancel an already running task. Explicitly stop active repair work when needed.
 An owner can also disable repairs globally or for a repository in the agent's
-saved USER.md preferences; carry those restrictions into background task context.
+saved AGENTS.md preferences; carry those restrictions into background task context.
 
 ## Setup boundary
 

package/docs/setup.md

@@ -67,8 +67,23 @@ not imported into restricted sessions. No workflow prompt is added to input.
 Use the existing owner's host account. Unless a layout was supplied, use
 `${XDG_DATA_HOME:-$HOME/.local/share}/ez/packages/<version>/` for extracted main
 packages and `${XDG_DATA_HOME:-$HOME/.local/share}/ez/agents/` for private deployments.
-Never overwrite an existing package/deployment or extract over its state. Infer
-the agent name and purpose from the owner's request; ask only when missing.
+Never overwrite an existing package/deployment or extract over its state.
+
+Before creation, use your own reasoning and the context already available from
+the owner to write the agent's initial brief. This is not a label or a copy of
+the request. Describe, in concrete language, who the agent serves, what product
+or environment it works in, the outcomes it should help produce, the capabilities
+currently available to it, and important scope boundaries. Include material facts
+you already know about the application; do not invent unknown facts. Omit generic
+personality prose and sections irrelevant to this agent. Keep the result compact
+enough to read on every turn. Ask the owner only when a missing fact would
+materially change the agent being installed.
+
+Pass that generated brief as the purpose. For example, a request to create a
+personal assistant should produce a brief tailored to that person's stated work,
+preferences and connected capabilities—not merely `Personal assistant`. A product
+agent should identify the product, user, current product scope and available
+actions without embedding product-specific behavior in Ez Core.
 
 Before running Node commands, check `command -v node` and `node --version`.
 If Node 22+ or this package's pinned pnpm is missing, provision it using the
@@ -163,20 +178,72 @@ so later service starts use the same build without depending on shell environmen
 
 ```sh
 export EZ_AGENTS_HOME=/absolute/private/agents
-bin/ezenciel-agents-create --name family-shopper --purpose 'Help my family plan shopping.' < /private/bot-token
+bin/ezenciel-agents-create --name family-shopper --purpose 'You are the shopping assistant for the owner and their family. Help plan shared shopping, organize confirmed requests, and use only the installed shopping and messaging capabilities. Do not purchase, message others, or infer household preferences without owner authority.' < /private/bot-token
 export EZ_DEPLOYMENT_DIR="$EZ_AGENTS_HOME/family-shopper"
 ```
 
+Creation records an isolation class. Packaged Codex defaults to `isolated`: the
+native CLI runs inside the relay, which only has that agent's workspace and control mounts.
+Sibling host paths are absent (`ENOENT`), not merely unreadable. Pass
+`--isolation host-capable` only when the owner needs the installer UID (host
+browser, local git, host files). Other installed CLIs default to `host-capable`
+because they are not packaged in the relay; requesting isolated execution for
+them fails closed. Host-capable reuses the host CLI login and is not an OS tenant
+boundary. The class cannot be changed later by flipping Compose; recreate the agent.
+
+Isolated Codex uses the pinned CLI in the relay image and
+`EZ_CODEX_SANDBOX=external` so Codex does not nest a sandbox inside the
+container. Provision that agent's `control/cli/codex/auth.json`; do not bind-mount
+the operator `~/.codex`. The host LaunchAgent is not started. Host-capable agents
+still need [host startup](host-service.md).
+
 Agent creation defaults to the CLI recorded when the initial package was
 installed. It needs no `--cli` argument. A later shell or different available CLI
 does not change that saved default. No installed-binary ranking or Grok fallback
 is used.
+
+Custom Codex providers such as OpenRouter currently require an explicitly
+host-capable agent: their keys are supplied by the private host-service
+environment. The isolated relay has no custom-provider key injection path.
+Register the provider and initial model set as non-secret installation metadata;
+repeat `--codex-model` for every model the agent may select:
+
+```sh
+bin/ezenciel-agents-create \
+  --name family-shopper \
+  --purpose 'Help my family plan shopping.' \
+  --isolation host-capable \
+  --codex-provider openrouter \
+  --codex-provider-name OpenRouter \
+  --codex-base-url https://openrouter.ai/api/v1 \
+  --codex-env-key OPENROUTER_API_KEY \
+  --codex-model google/gemini-3.8-flash \
+  --codex-model deepseek/deepseek-v4.1-flash \
+  < /private/bot-token
+```
+
+This stores provider configuration and model IDs in `host-executor.json`, never
+the API key. The key belongs only in the private host-service environment. The
+agent or owner can later change the active provider/model through the existing
+runtime control without reinstalling or editing an environment file:
+
+```sh
+ezenciel-agents-ai list
+ezenciel-agents-ai select --cli codex --provider openrouter \
+  --model google/gemini-3.8-flash
+```
+
+Changing provider starts a fresh native session so a session is never resumed
+against a different backend. Queued work retains the provider/model captured
+when it was admitted.
 The creator writes `host-executor.json`, private secrets, mind/control paths,
 purpose and unique plugin volume names. Duplicate names fail without overwriting.
 `ezenciel-agents-create --list` lists deployments without secrets.
 
-Before starting that host transport, initialize the main package’s built-in plugin manager. It runs on the host
+Before starting a host-capable transport, initialize the main package’s built-in plugin manager. It runs on the host
 for Docker access and adds no separate package or provider library. The packaged catalog is empty so the relay installs independently.
+Isolated agents still initialize this registry for plugin discovery; they do not
+start `ezenciel-agents-host`.
 Use its empty default catalog. Plugin preparation follows the verified Telegram
 handoff, not this step. Run:
 
@@ -202,16 +269,21 @@ the plugin skill through onboarding and verified use under that same request.
    Registry initialization itself does not connect accounts or start plugins.
 Never silently reuse a global `ez` from the old sandbox runtime.
 
-4. Follow [host startup templates](host-service.md). Register `bin/ezenciel-agents-host` with the host's native service manager,
-   binding `EZ_DEPLOYMENT_DIR` and the user's existing CLI PATH/HOME. On macOS use
-   a LaunchAgent; on Linux use a user service. Use the absolute Node/package
+4. Isolated agents skip host transport. Run `bin/ezenciel-agents-docker up -d --wait`
+   from the deployment directory. Do not register `ezenciel-agents-host` for them;
+   starting it fails closed.
+
+   Host-capable agents follow [host startup templates](host-service.md). Register
+   `bin/ezenciel-agents-host` with the host's native service manager, binding
+   `EZ_DEPLOYMENT_DIR` and the user's existing CLI PATH/HOME. On macOS use a
+   LaunchAgent; on Linux use a user service. Use the absolute Node/package
    paths. This generic transport is the only host execution bridge. Do not start
    another host relay or install another CLI. Verify its heartbeat, then run
    `bin/ezenciel-agents-docker up -d --wait`.
 
    `ezenciel-agents-setup service` is Docker-only startup: run it from the
    deployment directory containing `docker.env`. It starts the relay and does
-   not install or start the host-executor user service. Complete the host
+   not install or start the host-executor user service. Complete host-capable
    registration above separately.
 
 5. Ask the owner to message the exact bot. Verify the pending numeric identity,
@@ -224,8 +296,8 @@ Never silently reuse a global `ez` from the old sandbox runtime.
    stopped to verify repairs, then restore the poller; never replay uncertain
    user actions merely to test delivery.
 
-The main runtime is fully installer-owned: build it, register its host
-transport, bring its Compose project up, and verify restart persistence. Plugins
+The main runtime is fully installer-owned: build it, register host transport
+only for host-capable agents, bring its Compose project up, and verify restart persistence. Plugins
 are installed by the working Telegram agent when the owner requests their
 capability there; account onboarding and provider confirmation follow that request.
 Never use a missing plugin as a reason
@@ -238,9 +310,11 @@ current heartbeats and owner-bound completed-run delivery receipts without sendi
 messages or exposing tokens. Receipt evidence is historical: separately verify
 the current conversation and restart persistence before declaring setup complete.
 
-Purpose seeds SOUL.md once; future customization survives restart. Conversations,
-pairing, files and plugin accounts are separate. The existing host CLI login is
-shared, so this is not a security sandbox against other agents under that user.
+Purpose scopes AGENTS.md once; future customization survives restart. Conversations,
+pairing, files and plugin accounts are separate. Isolated agents use the relay
+mount namespace as the filesystem boundary. Host-capable agents share the
+installer UID and CLI login; that class is not a security sandbox against other
+agents under that user.
 Plugins run in their own containers and own their authentication. Install and
 register them only for the requested agent. Never clone another agent's plugin
 credentials. See [runtime, migration and QA](docker-runtime.md).
@@ -256,7 +330,7 @@ default. Existing queued jobs retain their captured execution choice.
 | Symptom | Inspect and recover |
 |---|---|
 | Docker unavailable | Check engine and Compose, start the supported installation; complete any required OS consent. |
-| Bot stays silent | Check pending owner identity, relay health, host heartbeat and outbox; approve only the verified owner. |
+| Bot stays silent | Check pending owner identity, relay health, host heartbeat (host-capable only) and outbox; approve only the verified owner. |
 | CLI exits without reply | Inspect the actual tool result and delivery receipt; stdout is not Telegram output. |
 | Exit 73 | An existing writer holds this deployment; stop the exact duplicate, never delete the kernel lock. |
 | Plugin absent | Check the bound catalog and install/start the reviewed package explicitly; no plugin ships by default. |

package/docs/standalone-cli.md

@@ -32,8 +32,9 @@ Use `ez tools list --details` for generated installed-plugin descriptions, help
 Add that instruction to its existing project instructions without replacing them.
 Use the absolute launcher, or prepend its bin directory to that session's PATH.
 Never overwrite another global `ez`; it may belong to a different installation.
-A company registry remains explicit even when invoked from a different directory.
-Other projects/accounts should use separate registries and private plugin state.
+A standalone company registry remains explicit even when invoked from a different
+directory. A relay-bound registry rejects calls from outside its workspace. Other
+projects/accounts must use separate registries and private plugin state.
 
 ## Install and verify a capability
 
@@ -54,9 +55,9 @@ Native client plugins/connectors are not converted into Ez plugins automatically
 
 A relay can coexist with CLI-only registries on the same machine. It retains its
 own pairing, single-writer queue, mind and plugin registry. Calling its existing
-bound launcher explicitly reuses that registry and its accounts; never initialize
-over it or silently select it from another workspace. Coordinate writes with its
-active jobs. Separate registries do not automatically share credentials or data.
+bound launcher must be run from the owning agent workspace. Never initialize over
+it or select it from another workspace. Coordinate writes with its active jobs.
+Separate registries do not automatically share credentials or data.
 
 Continuous monitoring requires a configured event consumer/relay and the plugin's
 supported watcher. CLI-only installation does not create background agent turns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.33",
+  "version": "0.1.0-beta.34",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/scripts/smoke-scheduler.ts

@@ -15,7 +15,8 @@ const duration=Number(process.argv[2] || 1860),cli=process.argv[3] || 'codex'
 const nativeGoal=process.argv[4]==='goal'
 if(!Number.isSafeInteger(duration) || duration<30)throw new Error('Duration must be at least 30 seconds')
 const root=await mkdtemp(join(tmpdir(),'ez-scheduler-smoke-')),workspace=join(root,'agent'),controlDir=join(root,'control')
-await initializeWorkspace(workspace)
+const purpose=join(root,'purpose.md');await writeFile(purpose,'Verify native scheduled work and responsive owner chat.\n')
+await initializeWorkspace(workspace,purpose)
 const control=new ControlStore(controlDir,1000),scheduler=new Scheduler(controlDir),runs=new RunStore(controlDir)
 await control.requestPairing(101,101);await control.approveOwner(101)
 const owner=(await control.status()).owner!,execution=await control.captureChoice(initialPreset(cli))