@jc_stack/ez-agents 0.1.0-beta.42 → 0.1.0-beta.44

package/src/ai.ts

@@ -5,7 +5,7 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { homedir } from 'node:os'
 import { join, delimiter } from 'node:path'
-import { executorEnvironment, executorKey, resolveExecutor } from './executor.js'
+import { executorEnvironment, executorInvocation, executorKey, resolveExecutor } from './executor.js'
 import { desktopCodexPath } from './desktop-bridge.js'
 
 export type AiPreset = { id: string; name: string; cli: string; provider?: string; model?: string; effort?: string }
@@ -27,6 +27,8 @@ export const isExecutionChoice = (v: unknown): v is ExecutionChoice => {
   return Boolean(c && /^[0-9a-f-]{36}$/i.test(c.sessionId) && isPreset(c.preset))
 }
 export const presetLabel = (p: AiPreset) => `${p.cli}${p.provider ? ` (${p.provider})` : ''} · ${p.model || 'client default'} · ${p.effort || 'default effort'}`
+// OpenCode encodes its provider in the native provider/model identifier.
+export const presetProvider = (p: AiPreset) => p.cli === 'opencode' ? p.model?.split('/')[0] : p.provider
 // The seed delegates model selection to the native client. Project its resolved
 // settings for status without pinning future conversations to that snapshot.
 export const statusPreset = (preset: AiPreset, discovered: AiPreset[]): AiPreset =>
@@ -53,8 +55,10 @@ export const installed = async (cli: string): Promise<boolean> => {
 // The optional runner injects `opencode models` output in tests; production
 // spawns the installed CLI with the whitelisted executor environment.
 export const readOpencodeModels = async (run?: (args: string[]) => Promise<string>, dataHome?: string): Promise<ModelChoice[]> => {
-  const exec = run ?? (async (args: string[]) =>
-    (await promisify(execFile)('opencode', args, { env: { ...executorEnvironment(), ...(dataHome ? { XDG_DATA_HOME: dataHome } : {}) }, timeout: 8000, maxBuffer: 4 * 1024 * 1024 })).stdout)
+  const exec = run ?? (async (args: string[]) => {
+    const invocation = executorInvocation('opencode', args)
+    return (await promisify(execFile)(invocation.command, invocation.args, { env: { ...executorEnvironment(), ...(dataHome ? { XDG_DATA_HOME: dataHome } : {}) }, timeout: 8000, maxBuffer: 4 * 1024 * 1024 })).stdout
+  })
   const record = (value: unknown): Record<string, unknown> =>
     value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
   try {

package/src/audio.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process'
 import { readRequest } from './read-request.js'
+import { executorEnvironment, executorInvocation } from './executor.js'
 
 export type AudioOptions = {
   geminiApiKey?: string
@@ -33,7 +34,7 @@ export const pcmToWav = (pcm: Buffer, sampleRate = 24000, channels = 1): Buffer
 
 export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Promise<Buffer> => {
   return new Promise((resolve, reject) => {
-    const child = spawn(
+    const invocation = executorInvocation(
       'ffmpeg',
       [
         '-f',
@@ -52,8 +53,9 @@ export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Pr
         'ogg',
         '-',
       ],
-      { stdio: ['pipe', 'pipe', 'pipe'] },
     )
+    const child = spawn(invocation.command, invocation.args,
+      { env: executorEnvironment(), stdio: ['pipe', 'pipe', 'pipe'] })
 
     const output: Buffer[] = []
     let error = ''

package/src/client-defaults.ts

@@ -6,14 +6,16 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { createHash } from 'node:crypto'
 import { installed, type AiPreset } from './ai.js'
-import { executorEnvironment } from './executor.js'
+import { executorEnvironment, executorInvocation } from './executor.js'
 
 const record = (v: unknown): Record<string, unknown> =>
   v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {}
 const value = (v: unknown): string | undefined =>
   typeof v === 'string' && /^[a-zA-Z0-9_./:-]{1,160}$/.test(v) ? v : undefined
-const command = async (cli: string, args: string[], cwd: string): Promise<string> =>
-  (await promisify(execFile)(cli, args, { cwd, env: executorEnvironment(), timeout: 8000, maxBuffer: 2 * 1024 * 1024 })).stdout
+const command = async (cli: string, args: string[], cwd: string): Promise<string> => {
+  const invocation = executorInvocation(cli, args)
+  return (await promisify(execFile)(invocation.command, invocation.args, { cwd, env: executorEnvironment(), timeout: 8000, maxBuffer: 2 * 1024 * 1024 })).stdout
+}
 
 export const resolvedCodexDefaults = (configValue: unknown, catalogValue: unknown): Record<string, unknown> => {
   const config = record(configValue)
@@ -32,7 +34,8 @@ export const resolvedCodexDefaults = (configValue: unknown, catalogValue: unknow
 
 // Native config/read resolves Codex's layers; do not reimplement TOML or start a turn.
 export const codexDefaults = (cwd: string, codexHome?: string, nativeFallback = false): Promise<Record<string, unknown>> => new Promise((resolve) => {
-  const child = spawn('codex', ['app-server'], { cwd,
+  const invocation = executorInvocation('codex', ['app-server'])
+  const child = spawn(invocation.command, invocation.args, { cwd,
     env: { ...executorEnvironment(), ...(codexHome ? { CODEX_HOME: codexHome } : {}) }, stdio: ['pipe', 'pipe', 'ignore'] })
   const lines = createInterface({ input: child.stdout })
   let done = false

package/src/control-state.ts

@@ -2,7 +2,7 @@ import { assertEffort } from './model-policy.js'
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
 import { mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { isPreset, persistedPreset, type AiPreset, type ExecutionChoice, type ModelChoice } from './ai.js'
+import { isPreset, persistedPreset, presetProvider, type AiPreset, type ExecutionChoice, type ModelChoice } from './ai.js'
 
 export type Owner = {
   id?: string
@@ -615,7 +615,7 @@ export class ControlStore {
     // Hot path (every inbound message and every source tick): when the pinned
     // session already matches the selected preset, return it with zero
     // control/ writes and without taking the lock. Any divergence (missing
-    // session, CLI/provider/model change, untitled fresh session) falls
+    // session, choice change, untitled fresh session) falls
     // through to the serializing slow path. A concurrent control edit inside
     // the microsecond unlocked window fails closed downstream (the execution
     // session lookup rejects a stale pin; the batch can be retried).
@@ -625,7 +625,7 @@ export class ControlStore {
     const session = settled.activeSession
     if (settledPreset && session && (session.cli || session.hasStarted) &&
       !(session.cli === settledPreset.cli && session.hasStarted && session.preset &&
-        (session.preset.provider !== settledPreset.provider || session.preset.model !== settledPreset.model)) &&
+        presetProvider(session.preset) !== presetProvider(settledPreset)) &&
       (session.cli !== settledPreset.cli || JSON.stringify(session.preset) === JSON.stringify(settledPreset)) &&
       Boolean(session.title || session.hasStarted || !title?.trim()))
       return { sessionId: session.sessionId, preset: settledPreset }
@@ -637,10 +637,10 @@ export class ControlStore {
       if (!state.activeSession.cli && !state.activeSession.hasStarted) state.activeSession.cli = preset.cli
       if (state.activeSession.cli === preset.cli) {
         const previous = state.activeSession.preset
-        // Same CLI, different provider/model: web/Telegram must not resume the old native thread.
-        // Undefined is the native client default and is a distinct selection.
+        // A provider change starts a separate native context. Model and effort
+        // changes are native turn settings within the existing conversation.
         if (state.activeSession.hasStarted && previous &&
-            (previous.provider !== preset.provider || previous.model !== preset.model)) {
+            presetProvider(previous) !== presetProvider(preset)) {
           ;(state.sessions ??= []).push(state.activeSession)
           state.activeSession = { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli, preset }
         } else {
@@ -772,13 +772,17 @@ export class ControlStore {
       assertEffort(preset.effort, preset.model, preset.cli)
       if ((state.activeSession?.sessionId ?? null) !== expectedSession) throw new Error('Menu expired. Open Choose AI again.')
       const current = ai.presets.find((p) => p.id === ai.selectedId)!
-      if (state.activeSession && (current.cli !== preset.cli || !state.activeSession.cli) && !fresh) return false
+      if (state.activeSession && (current.cli !== preset.cli || presetProvider(current) !== presetProvider(preset) || !state.activeSession.cli) && !fresh) return false
       if (fresh || !state.activeSession) {
         rememberPreset(state)
         if (state.activeSession) (state.sessions ??= []).push(state.activeSession)
-        state.activeSession = { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli }
+        state.activeSession = { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli, preset: persistedPreset(preset) }
       }
       ai.selectedId = id
+      // Persist the conversation's choice now, even if the owner switches chats
+      // or restarts before sending another message. Queued choices are snapshots.
+      if (state.activeSession.cli === preset.cli && (!state.activeSession.preset || presetProvider(state.activeSession.preset) === presetProvider(preset)))
+        state.activeSession.preset = persistedPreset(preset)
       ai.recentIds = [id, ...(ai.recentIds ?? []).filter((recentId) => recentId !== id)].slice(0, 3)
       await this.writeState(state)
       return true

package/src/conversation-menu.ts

@@ -1,5 +1,6 @@
 import { InlineKeyboard, type Context } from 'grammy'
 import { ControlStore, sessionTitle } from './control-state.js'
+import { presetLabel } from './ai.js'
 
 // IDs identify existing relay bindings only; the engine still owns all context.
 // Titles come from owner renames; no run text or delivery history is read here.
@@ -61,13 +62,15 @@ export const createConversationMenu = (control: ControlStore) => {
         } else {
           const keyboard = new InlineKeyboard().text('Archive this conversation', `chat:archive:${id}`).row()
             .text('Back to conversations', 'chat:list:0:0')
-          try { await control.switchSession(id) }
+          let selected
+          try { selected = await control.switchSession(id) }
           catch (error) {
             // Even an older session that cannot resume can still be archived.
             await render(ctx, `${sessionTitle(session)}\n${error instanceof Error ? error.message : 'Unable to continue.'}`, keyboard)
             return true
           }
-          await render(ctx, `Current conversation: ${sessionTitle(session)}\nSend a message to continue. To rename it, use /rename followed by a name.`, keyboard)
+          keyboard.inline_keyboard.unshift([{ text: 'Choose AI', callback_data: 'menu:ai' }])
+          await render(ctx, `Current conversation: ${sessionTitle(selected)}\nAI: ${selected.preset ? presetLabel(selected.preset) : 'Not saved; open Choose AI.'}\nSend a message to continue. To rename it, use /rename followed by a name.`, keyboard)
         }
       } catch (error) {
         await ctx.reply(error instanceof Error ? error.message : 'Conversation selection failed.')

package/src/executor.ts

@@ -2,7 +2,7 @@ import { executionDefaults } from './model-policy.js'
 import { startTaskExecutor } from './task-executor.js'
 import { deliverySocketPath } from './delivery-socket.js'
 import { mkdtemp, rm, writeFile, mkdir, symlink, readFile } from 'node:fs/promises'
-import { accessSync, constants as fsConstants } from 'node:fs'
+import { accessSync, openSync, closeSync, constants as fsConstants } from 'node:fs'
 import { tmpdir, homedir } from 'node:os'
 import path from 'node:path'
 import { spawn, type ChildProcess } from 'node:child_process'
@@ -210,7 +210,7 @@ export const EXECUTOR_REGISTRY: Record<string, CliAdapter> = {
       // Loaded by path, never by prompt text, so the model cannot miss it.
       try {
         const skill = path.join(opts.controlDir, 'cli', 'pi', 'skills', 'ez-delivery', 'SKILL.md')
-        accessSync(skill, fsConstants.R_OK)
+        closeSync(openSync(skill, 'r'))
         args.push('--skill', path.dirname(skill))
       } catch { /* runs without the skill exactly as before */ }
       // Bind Pi to this conversation, not the most recently used session in
@@ -280,7 +280,7 @@ export const resolveExecutor = (name?: string): CliAdapter => EXECUTOR_REGISTRY[
 // secret.
 export const opencodeDataHome = (controlDir: string): string | undefined => {
   try {
-    accessSync(path.join(controlDir, 'cli', 'opencode', 'auth.json'), fsConstants.R_OK)
+    closeSync(openSync(path.join(controlDir, 'cli', 'opencode', 'auth.json'), 'r'))
     return path.join(controlDir, 'cli')
   } catch { return undefined }
 }
@@ -289,7 +289,7 @@ export const opencodeDataHome = (controlDir: string): string | undefined => {
 // auth.json). Only a path is ever returned, never a secret.
 export const piAgentDir = (controlDir: string): string | undefined => {
   try {
-    accessSync(path.join(controlDir, 'cli', 'pi', 'agent', 'auth.json'), fsConstants.R_OK)
+    closeSync(openSync(path.join(controlDir, 'cli', 'pi', 'agent', 'auth.json'), 'r'))
     return path.join(controlDir, 'cli', 'pi', 'agent')
   } catch { return undefined }
 }
@@ -315,7 +315,7 @@ export const opencodeInvocation = (
 export const executorInvocation = (command: string, args: string[]) => {
   const uid = process.geteuid?.()
   return process.platform === 'linux' && uid !== undefined && process.getuid?.() !== uid
-    ? { command: 'setpriv', args: [`--ruid=${uid}`, `--euid=${uid}`, '--', command, ...args] }
+    ? { command: 'setpriv', args: [`--ruid=${uid}`, `--euid=${uid}`, '--no-new-privs', '--', command, ...args] }
     : { command, args }
 }
 

package/src/menu.ts

@@ -4,7 +4,7 @@ import path from 'node:path'
 import { randomBytes } from 'node:crypto'
 import { InlineKeyboard, type Context } from 'grammy'
 import { ControlStore, type ControlGuard } from './control-state.js'
-import { chatPreset, installed, persistedPreset, presetLabel, readModels, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
+import { chatPreset, installed, persistedPreset, presetLabel, presetProvider, readModels, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
 
 export const mainCommands = [
@@ -64,7 +64,7 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     const state = (await control.status()).ai
     if (!state) throw new Error('AI settings not initialized')
     const current = state.presets.find((p) => p.id === state.selectedId)!
-    const fresh = current.cli !== preset.cli || current.provider !== preset.provider || Boolean(session && !session.cli)
+    const fresh = current.cli !== preset.cli || presetProvider(current) !== presetProvider(preset) || Boolean(session && !session.cli)
     if (!await control.selectPreset(preset.id, expectedSession, fresh, guard)) throw new Error('AI binding changed. Refresh available AIs before trying again.')
     return { preset, fresh }
   }
@@ -72,12 +72,13 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     const session = await control.getActiveSession()
     const { fresh } = await select(preset, session?.sessionId ?? null)
     await ctx.reply(`${preset.name}\n${presetLabel(preset)}\n${fresh
-      ? 'CLI changed: fresh conversation. Files kept; queued work unchanged.'
-      : 'Selected for this conversation. Queued work unchanged.'}`)
+      ? 'Client or provider changed: fresh conversation. Files kept; queued work unchanged.'
+      : 'Saved for this conversation. History kept; queued work unchanged.'}`)
   }
   const list = async (ctx: Context) => {
     const models = await catalog()
     const state = await control.aiState(initial)
+    const selected = state.presets.find((preset) => preset.id === state.selectedId)!
     const keyboard = new InlineKeyboard()
     if (models.length) {
       const recent = (state.recentIds ?? [])
@@ -99,8 +100,8 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
       await list(next)
     })
     await ctx.reply(models.length
-      ? 'Choose AI\nUse a recent choice or select an installed client, then choose its model and reasoning level.'
-      : 'Choose AI\nNo client catalog available. Showing the current client setup only.', { reply_markup: keyboard })
+      ? `Choose AI\nCurrent: ${presetLabel(selected)}\nSaved per conversation. Select a client, model and reasoning level; changing client or provider starts a new conversation.`
+      : `Choose AI\nCurrent: ${presetLabel(selected)}\nNo client catalog available. Showing the current client setup only.`, { reply_markup: keyboard })
   }
   const available = async (ctx: Context, cli: string, page = 0, listed?: ModelChoice[]) => {
     const models = (listed ?? await catalog()).filter((model) => model.cli === cli)
@@ -129,7 +130,8 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     const existing = state.presets.find((preset) => preset.cli === stored.cli && preset.provider === stored.provider && preset.model === stored.model && preset.effort === stored.effort)
     const preset = existing ?? candidate
     await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : isInstalled)
-    await control.savePreset(preset, guard)
+    // Private scopes persist their selection on the session, not the owner menu.
+    if (!guard?.applicationScope) await control.savePreset(preset, guard)
     return preset
   }
   const save = async (ctx: Context, model: ModelChoice, effort?: string) => {

package/src/plugin-broker.mjs

@@ -59,6 +59,7 @@ const validateManagerArgs = async (value, workspace) => {
   if (!args.length) throw Error('Missing broker management command');
   const [group, action, name, extra, ...tail] = args;
   if (group === 'tools' && action === 'list' && (args.length === 2 || args.length === 3 && name === '--details')) return args;
+  if (group === 'tools' && action === 'skill' && IDENTIFIER.test(name) && args.length === 4) return args;
   if (group === 'tools' && action === 'exposure' && args.length === 2) return args;
   if (group === 'plugins' && action === 'available' && args.length === 2) return args;
   if (group === 'plugins' && action === 'list' && args.length === 2) return args;
@@ -90,6 +91,7 @@ const validateManagerArgs = async (value, workspace) => {
         (args.length === 3 || ['stable', 'beta', 'manual'].includes(extra))) return args;
     if (action === 'prepare' && args.length === 5 && IDENTIFIER.test(name) && extra === '--file' &&
         typeof tail[0] === 'string' && path.isAbsolute(tail[0])) {
+      if (name === 'main') throw Error('Main runtime candidates require operator preparation outside the agent');
       let resolved;
       try { resolved = await fs.realpath(tail[0]); } catch { throw Error('Upgrade candidate must be an existing file inside the agent workspace'); }
       if (!childOf(resolved, workspace)) throw Error('Upgrade candidate must stay inside the agent workspace');

package/src/plugins/manager.mjs

@@ -1,5 +1,6 @@
 import { sharedService, attachShared } from './shared.mjs';
 import { exposure, commandExposure } from './exposure.mjs';
+import { installedNativeHelp } from './native-tasks.mjs';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,7 +18,16 @@ const emit = value => console.log(JSON.stringify(value));
 const keys = (object, allowed) => { if(!object || typeof object !== 'object' || Array.isArray(object) || Object.keys(object).some(k=>!allowed.includes(k))) throw Error('Invalid or unknown descriptor fields'); };
 const strings = value => { if(!Array.isArray(value) || value.some(x=>typeof x!=='string' || x.includes('\0'))) throw Error('Expected literal string arguments'); return value; };
 const containerPath = value => { if(typeof value!=='string' || !value.startsWith('/') || value.includes('..') || /[\0\n\r:$]/.test(value) || value.startsWith('/var/run') || value.startsWith('/proc') || value.startsWith('/sys')) throw Error('Invalid container path'); return value; };
-const privateDir = async dir => fs.mkdir(dir,{recursive:true,mode:0o700});
+export async function privateDir(dir) {
+  const created=await fs.mkdir(dir,{recursive:true,mode:0o700});
+  if(!created)return;
+  // A root broker must leave new private directories with the installer's
+  // ownership, just as atomic files are. Do not change existing directories.
+  let current=created;await stewardOwned(current);
+  for(const part of path.relative(created,dir).split(path.sep).filter(Boolean)) {
+    current=path.join(current,part);await stewardOwned(current);
+  }
+}
 export async function atomic(file, value) {
   const tmp = `${file}.${randomUUID()}.tmp`;
   await fs.writeFile(tmp,JSON.stringify(value,null,2)+'\n',{mode:0o600,flag:'wx'});
@@ -280,11 +290,12 @@ export async function hostNetworkBindings(config, record, home) {
     throw Error('Invalid host network bindings');
   const route = configured?.[record.manifest?.id];
   if (route === undefined) return [];
-  if (process.env.EZ_DOCKER_COMPOSE === 'standalone') {
-    throw Error('Isolated broker cannot use host network bindings');
-  }
-  if (realpathSync(path.join(deployment, 'mind')) !== config.workspace ||
-      realpathSync(path.join(deployment, 'control')) !== realpathSync(agent.controlDir))
+  const isolated = process.env.EZ_DOCKER_COMPOSE === 'standalone';
+  if (isolated && host.isolation !== 'isolated') throw Error('Isolated broker requires an isolated host binding');
+  // Like folder grants, network grants use the exact mounted identities. The
+  // broker does not receive the host deployment's convenience symlinks.
+  if (!isolated && (realpathSync(path.join(deployment, 'mind')) !== config.workspace ||
+      realpathSync(path.join(deployment, 'control')) !== realpathSync(agent.controlDir)))
     throw Error('Invalid host network binding deployment');
   keys(route, ['revisions', 'bindings']);
   const trusted = await snapshot(record.source);
@@ -519,7 +530,14 @@ export async function init(home,workspace,catalogFile,hostConfig,standalone=fals
         await fs.access(target,fs.constants.X_OK);
         await fs.symlink(target,path.join(bin,name));
       }
-      for(const file of await fs.readdir(agent.binDir)) {if(file==='ez') throw Error('Existing ez binding collision');if(Object.hasOwn(manifest.bin,file))continue;await fs.symlink(path.join(agent.binDir,file),path.join(bin,file));}
+      for(const file of await fs.readdir(agent.binDir)) {
+        if(file==='ez') {
+          if(await fs.realpath(path.join(agent.binDir,file))!==await fs.realpath(new URL('../../bin/ez',import.meta.url)))throw Error('Existing ez binding collision');
+          continue;
+        }
+        if(Object.hasOwn(manifest.bin,file))continue;
+        await fs.symlink(path.join(agent.binDir,file),path.join(bin,file));
+      }
       agent.binDir=bin;agent.toolsHome=home;await atomic(hostConfig,host);
     }
   });
@@ -540,7 +558,6 @@ export async function install(home,config,name,source,revision) {
     const stage=path.join(base,`.stage-${randomUUID()}`);await privateDir(stage);
     try {
       for(const [relative,file] of p.files) {const dest=path.join(stage,relative);await fs.mkdir(path.dirname(dest),{recursive:true,mode:0o755});await fs.writeFile(dest,file.data,{mode:file.mode,flag:'wx'});}
-      await fs.chmod(stage,0o755);
       // A previously interrupted install may leave a snapshot. Never silently replace it.
       try { await fs.rename(stage,target); } catch(error) {
         if(!['EEXIST','ENOTEMPTY'].includes(error.code)) throw error;
@@ -583,17 +600,34 @@ export async function main(args) {
     return (await import('./connection.mjs')).connect(home,rest[0],rest.slice(1),{publish:port,serve:true});
   }
   if(group==='tools'&&action==='connect')return (await import('./connection.mjs')).connect(home,rest[0],rest.slice(1));
-  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list [--details]|exposure|connect <alias> <args...>|serve <host-port:container-port> <alias> <args...>','<registered CLI> ...'],foreignWorkspace:'Relay-bound registries run only from their owning agent workspace',scope:home});
+  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list [--details]|skill <plugin> <declared-path>|exposure|connect <alias> <args...>|serve <host-port:container-port> <alias> <args...>','<registered CLI> ...'],native:await installedNativeHelp(path.join(home,'bin')),foreignWorkspace:'Relay-bound registries run only from their owning agent workspace',scope:home});
   if(group==='plugins'&&(!action||args.includes('--help'))) return emit({commands:['available','list','inspect <id>','install <id>','start <id>','stop <id>','status <id>','logs <id>','uninstall <id>','catalog-add <id> --source PATH --revision HASH','export <id> <artifact> --output PATH','folder-bind <id> --service NAME --source PATH --target PATH [--writable]','folder-unbind <id> --service NAME --target PATH','folders <id>','shared-enable <id> <service>','shared-disable <id> <service>','shared-status <id> <service>'],uninstall:'Stops and removes containers/network and unregisters aliases; retains all volumes and secrets. No data deletion flag.',scope:home});
   if(group==='plugins'||group==='tools') {
     args=rest;args=args.filter(a=>a!=='--json');
     if(action==='available'&&group==='plugins') return emit(config.catalog);
     const r=await registry(home);
+    if(group==='tools' && action==='skill') {
+      if(args.length!==2)throw Error('Use tools skill <plugin> <declared-path>');
+      const [name,skill]=args,record=r.plugins[id(name)];
+      if(!record || !record.manifest.skills.includes(skill))throw Error('Unknown installed plugin skill');
+      if(path.isAbsolute(skill) || skill.split('/').some(part=>!part || part==='.' || part==='..') || /[\0\r\n]/.test(skill))throw Error('Unsafe skill path');
+      const source=await fs.realpath(record.source);
+      if(source!==record.source || !childOf(source,home))throw Error('Skill source must stay inside installed packages');
+      let file=source;
+      for(const part of skill.split('/')) {
+        file=path.join(file,part);
+        if((await fs.lstat(file)).isSymbolicLink())throw Error('Skill symlinks are not supported');
+      }
+      const stat=await fs.stat(file);
+      if(!stat.isFile() || stat.size>64*1024)throw Error('Skill must be a regular file of at most 64 KiB');
+      return emit({plugin:name,revision:record.revision,path:skill,content:await fs.readFile(file,'utf8')});
+    }
     if(action==='list') {
       if(group==='tools' && args.length===1 && args[0]==='--details')return emit(Object.fromEntries(Object.entries(r.plugins).map(([name,p])=>[name,{
         description:typeof p.manifest.description==='string'?p.manifest.description.replace(/\s+/g,' ').trim().slice(0,200):'',
         commands:Object.keys(p.manifest.commands).map(alias=>`ez ${alias} --help`),
         skills:p.manifest.skills.map(skill=>path.join(p.source,skill)),
+        skillReads:p.manifest.skills.map(skill=>['ez','tools','skill',name,skill]),
       }])));
       if(args.length)throw Error('Use tools list [--details] or plugins list');
       return emit(group==='tools'?r.commands:r.plugins);

package/src/plugins/native-tasks.d.mts

@@ -1,4 +1,5 @@
 export function nativeTaskBinding(home:string, environment?:NodeJS.ProcessEnv):Promise<{cwd:string;env:NodeJS.ProcessEnv}>;
 import type {DeliveryContext} from '../delivery-context.mjs';
 export function nativeCommands():{command:string;description:string;limitations?:string[]}[];
+export function installedNativeHelp(binDirectory:string):Promise<{description:string;argv:string[]}[]>;
 export function nativeTasks(home:string,args:string[],options?:{signal?:AbortSignal;command?:string;deliveryContext?:DeliveryContext}):Promise<{code:number;stdout:string;stderr:string}>;

package/src/plugins/native-tasks.mjs

@@ -9,6 +9,19 @@ export const nativeCommands=()=>[
   {command:'message',description:"Send text, voice or a workspace document to the paired owner's Telegram chat and wait for its Telegram delivery receipt. Read --help.",limitations:['History requires a native run; inline text only.']},
 ];
 
+export async function installedNativeHelp(binDirectory) {
+  const commands=[];
+  for(const {command,description} of nativeCommands()) {
+    const executable=path.join(binDirectory,`ezenciel-agents-${command}`);
+    try {await fs.access(executable,fs.constants.X_OK);} catch(error) {
+      if(['ENOENT','EACCES'].includes(error.code))continue;
+      throw error;
+    }
+    commands.push({description,argv:[executable,'--help']});
+  }
+  return commands;
+}
+
 export async function nativeTaskBinding(home,environment=process.env) {
   home=await fs.realpath(home);
   const config=JSON.parse(await fs.readFile(path.join(home,'config.json'),'utf8'));

package/src/task-cli.ts

@@ -6,7 +6,7 @@ const { values, positionals } = parseArgs({ allowPositionals: true, options: {
   'context-file': { type: 'string' }, 'capability-file': { type: 'string' }, hours: { type: 'string' }, id: { type: 'string' }, help: { type: 'boolean' },
   'incoming-only': { type: 'boolean' }, 'until-revoked': { type: 'boolean' }, 'any-conversation': { type: 'boolean' },
 } })
-if (values.help) { console.log('ezenciel-agents-task propose --source NAME (--contact EXACT_ID | --any-conversation) --purpose TEXT --context-file FILE [--capability-file FILE] --hours 24 [--incoming-only [--until-revoked]] | list | revoke --id TASK_ID'); console.log(await readFile(new URL('../docs/selective-monitoring.md', import.meta.url), 'utf8')) }
+if (values.help) { console.log('ezenciel-agents-task start|propose --source NAME (--contact EXACT_ID | --any-conversation) --purpose TEXT --context-file FILE [--capability-file FILE] --hours 24 [--incoming-only [--until-revoked]] | list | revoke --id TASK_ID'); console.log(await readFile(new URL('../docs/selective-monitoring.md', import.meta.url), 'utf8')) }
 else {
   if (!process.env.EZ_CONTROL_DIR || !process.env.EZ_RUN_ID) throw new Error('Run from the current owner turn')
   const anyConversation = values['any-conversation'] === true

package/src/task-executor.ts

@@ -7,7 +7,7 @@ import { spawn, execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { readRun } from './delivery-socket.js'
 import { Tasks } from './tasks.js'
-import { executorEnvironment, terminateJob, type ExecutorOptions } from './executor.js'
+import { executorEnvironment, executorInvocation, terminateJob, type ExecutorOptions } from './executor.js'
 
 // This adapter is deliberately version-pinned: a new native tool default needs
 // a fresh tool-inventory audit before external correspondence can use it.
@@ -45,13 +45,15 @@ export async function startTaskExecutor(options: ExecutorOptions) {
   const toolNames = [...(task.anyConversation ? ['context','send'] : ['context','send','note','report','complete']),...capabilityNames]
   if (capabilityNames.length && !options.toolsHome) throw new Error('Channel capabilities require an installed tool registry')
   const environment = executorEnvironment()
-  const version = await promisify(execFile)('codex', ['--version'], { env: environment })
+  const versionInvocation = executorInvocation('codex', ['--version'])
+  const version = await promisify(execFile)(versionInvocation.command, versionInvocation.args, { env: environment })
   if (version.stdout.trim() !== `codex-cli ${TASK_CODEX_VERSION}`) throw new Error(`Restricted tasks require audited Codex ${TASK_CODEX_VERSION}`)
   const temporary = await mkdtemp(join(tmpdir(), 'ez-task-'))
   try {
     const directory = join(temporary, 'workspace'), home = join(temporary, 'home')
     await mkdir(directory, { mode: 0o700 }); await mkdir(home, { mode: 0o700 })
-    const catalog = await promisify(execFile)('codex', ['debug', 'models', '--bundled'], { env: environment, maxBuffer: 4 * 1024 * 1024 })
+    const catalogInvocation = executorInvocation('codex', ['debug', 'models', '--bundled'])
+    const catalog = await promisify(execFile)(catalogInvocation.command, catalogInvocation.args, { env: environment, maxBuffer: 4 * 1024 * 1024 })
     await writeFile(join(temporary, 'models.json'), JSON.stringify(taskModelCatalog(JSON.parse(catalog.stdout))), { mode: 0o600 })
     const auth = process.env.EZ_ISOLATION === 'isolated'
       ? join(options.controlDir, 'cli', 'codex', 'auth.json')
@@ -60,7 +62,8 @@ export async function startTaskExecutor(options: ExecutorOptions) {
     const broker = [process.execPath, '--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)),
       fileURLToPath(new URL('./task-mcp.ts', import.meta.url)), options.controlDir, options.runId, options.toolsHome ?? '', JSON.stringify(task.capabilities ?? [])]
     const prompt = JSON.stringify({event: run.external ? 'correspondence_received' : 'task_activated', taskId: run.taskId})
-    const child = spawn('codex', taskArguments(directory, broker, prompt, toolNames, options), {
+    const invocation = executorInvocation('codex', taskArguments(directory, broker, prompt, toolNames, options))
+    const child = spawn(invocation.command, invocation.args, {
       cwd: directory, env: { ...environment, HOME: home, CODEX_HOME: home }, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32',
     })
     await new Promise<void>((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject) })

package/src/tasks.ts

@@ -22,6 +22,7 @@ export type Task = {
   sourceId: string; bindingId: string; accountId: string; conversationId: string
   purpose: string; context: string; createdAt: number; expiresAt: number
   state: 'pending' | 'active' | 'revoked' | 'completed'
+  grant?: string; initialRunDispatched?: true
   notes: string[]; operations: Record<string, { text: string; attachmentId?:string; state: 'uncertain' | 'accepted'; receipt?: unknown }>
   capabilityOperations?: Record<string, { capabilityId: string; inputHash: string; lease: string; attachment?:TaskAttachment; state: 'authorized' | 'completed' }>
   publicBudget?: PublicBudget
@@ -59,6 +60,8 @@ export class Tasks {
         !bounded(task.accountId, 200) || !bounded(task.conversationId, 200) || !bounded(task.purpose, 1000) ||
         !bounded(task.context, 6000) || !Number.isFinite(task.createdAt) || !Number.isFinite(task.expiresAt) ||
         !['pending', 'active', 'revoked', 'completed'].includes(task.state) || !Array.isArray(task.notes) ||
+        (task.grant !== undefined && (typeof task.grant !== 'string' || !/^[a-f0-9]{64}$/.test(task.grant))) ||
+        (task.initialRunDispatched !== undefined && task.initialRunDispatched !== true) ||
         !task.operations || typeof task.operations !== 'object' || (task.capabilityOperations !== undefined && (!task.capabilityOperations || typeof task.capabilityOperations !== 'object')) ||
         (task.anyConversation && !validPublicBudget(task.publicBudget)) || !task.owner) throw new Error('Invalid task record')
       return task
@@ -91,11 +94,7 @@ export class Tasks {
       !ownsRun(task.owner, run))
       throw new Error('Task is inactive or expired')
     const owner = (await new ControlStore(this.controlDir, 900000).status()).owner
-    const approval = await new ApprovalStore(this.controlDir).getDecision(task.id)
-    const approvedByOwner = approval?.version === 2
-      ? approval.decidedOwnerId === ownerId(task.owner) && approval.decidedOwnerEpoch === ownerEpoch(task.owner)
-      : !!owner && ownsRun(owner,{telegramUserId:approval?.decidedBy!,chatId:task.owner.telegramChatId})
-    if (!sameOwner(task.owner, owner) || approval?.decision !== 'approved' || !approvedByOwner || approval.runId !== task.runId || approval.prompt !== this.prompt(task))
+    if (!sameOwner(task.owner, owner) || (task.grant ? task.grant !== this.scopeHash(task) : !await this.approved(task)))
       throw new Error('Task approval is no longer valid')
     if (checkProvider) await this.source(task)
     if (run.external && checkProvider) {
@@ -107,6 +106,34 @@ export class Tasks {
     }
     return task
   }
+  // Persist only the bounded grant, not transient approval/outbox state. Bind every
+  // immutable authority field so later scope changes cannot reuse an old grant.
+  private scopeHash(task: Task) {
+    return createHash('sha256').update(JSON.stringify([
+      task.id, task.runId, task.owner, task.sourceId, task.bindingId, task.accountId,
+      task.conversationId, task.purpose, task.context, task.createdAt, task.expiresAt,
+      task.waitForIncoming, task.untilRevoked, task.anyConversation, task.capabilities,
+    ])).digest('hex')
+  }
+  private async approved(task: Task) {
+    const approval = await new ApprovalStore(this.controlDir).getDecision(task.id)
+    const approvedByOwner = approval?.version === 2
+      ? approval.decidedOwnerId === ownerId(task.owner) && approval.decidedOwnerEpoch === ownerEpoch(task.owner)
+      : ownsRun(task.owner,{telegramUserId:approval?.decidedBy!,chatId:task.owner.telegramChatId})
+    return approval?.decision === 'approved' && approvedByOwner && approval.runId === task.runId && approval.prompt === this.prompt(task)
+  }
+  private async dispatchInitial(task: Task) {
+    if (task.waitForIncoming || task.initialRunDispatched) return
+    // Runs are intentionally memory-only. Do not replay an opener after restart,
+    // when its delivery may be unknown; subsequent inbound events still resume.
+    task.initialRunDispatched = true
+    await this.save(task)
+    await new RunStore(this.controlDir).create({
+      id: `event_${createHash('sha256').update(task.id).digest('hex')}`, taskId: task.id,
+      ownerId: ownerId(task.owner), ownerEpoch: ownerEpoch(task.owner),
+      chatId: task.owner.telegramChatId, telegramUserId: task.owner.telegramUserId, texts: [],
+    })
+  }
   async match(sourceId: string, bindingId: string, events: SourceEvent[]) {
     if (!events.length || new Set(events.map(event => event.conversationId)).size !== 1) return
     const matches = (await this.list()).filter(t => t.state === 'active' && t.expiresAt > Date.now() &&
@@ -137,19 +164,23 @@ export class Tasks {
       const task = await this.get(id)
       if (!task) return false
       if (task.state === 'revoked' && task.unwatchPending) { await this.unwatch(task); return true }
-      const approval = await new ApprovalStore(this.controlDir).getDecision(id)
-      if (!approval || approval.runId !== task.runId || approval.prompt !== this.prompt(task)) throw new Error('Task approval mismatch')
-      if (task.state === 'pending' && approval.decision !== 'pending') {
-        task.state = approval.decision === 'approved' ? 'active' : 'revoked'
-        if (task.state === 'active') {
-          const source = await this.source(task)
-          await sourceCall(source.socketPath, 'task-watch', { accountId: task.accountId, conversationId: task.conversationId, expiresAt: task.expiresAt })
+      if (!['pending', 'active'].includes(task.state) || task.expiresAt <= Date.now()) return false
+      if (!task.grant) {
+        const approval = await new ApprovalStore(this.controlDir).getDecision(id)
+        if (!approval || approval.runId !== task.runId || approval.prompt !== this.prompt(task)) throw new Error('Task approval mismatch')
+        if (approval.decision === 'pending') return true
+        if (approval.decision === 'denied') {
+          task.state = 'revoked'; await this.save(task); return true
         }
+        if (!await this.approved(task)) throw new Error('Task approval is no longer valid')
+        const source = await this.source(task)
+        await sourceCall(source.socketPath, 'task-watch', { accountId: task.accountId, conversationId: task.conversationId, expiresAt: task.expiresAt })
+        if (task.state === 'active' && !task.waitForIncoming) task.initialRunDispatched = true
+        task.state = 'active'; task.grant = this.scopeHash(task)
         await this.save(task)
       }
-      if (task.state === 'active' && !task.waitForIncoming && task.expiresAt > Date.now()) await new RunStore(this.controlDir).create({
-        id: `event_${createHash('sha256').update(task.id).digest('hex')}`, taskId: task.id, chatId: task.owner.telegramChatId, telegramUserId: task.owner.telegramUserId, texts: [],
-      })
+      if (task.grant !== this.scopeHash(task)) throw new Error('Task grant scope changed')
+      await this.dispatchInitial(task)
       return true
     })
   }
@@ -182,7 +213,7 @@ export class Tasks {
         if(task.unwatchPending) await this.unwatch(task)
         return { id: task.id, state: task.state }
       }
-      if (command !== 'propose') throw new Error('Unknown owner task command')
+      if (command !== 'start' && command !== 'propose') throw new Error('Unknown owner task command')
       if (args.waitForIncoming !== undefined && typeof args.waitForIncoming !== 'boolean') throw new Error('Invalid incoming-only option')
       if (args.untilRevoked !== undefined && (typeof args.untilRevoked !== 'boolean' || (args.untilRevoked && args.waitForIncoming !== true))) throw new Error('Persistent permission requires incoming-only mode')
       if (args.anyConversation !== undefined && typeof args.anyConversation !== 'boolean') throw new Error('Invalid any-conversation option')
@@ -207,6 +238,13 @@ export class Tasks {
       const task: Task = { version: args.anyConversation ? 4 : args.untilRevoked ? 3 : args.waitForIncoming ? 2 : 1, ...(args.untilRevoked ? {untilRevoked:true as const} : {}), ...(args.waitForIncoming ? { waitForIncoming: true as const } : {}), ...(args.anyConversation ? {anyConversation:true as const,publicBudget:{windowStartedAt:Date.now(),runs:0,responses:0,totalRuns:0,totalResponses:0}} : {}), ...(capabilities ? {capabilities} : {}), id: `task_${randomUUID().replaceAll('-', '')}`, runId, owner, sourceId: source.id,
         bindingId: source.bindingId, accountId: head.accountId, conversationId: args.conversationId, purpose: args.purpose,
         context: args.context, createdAt: Date.now(), expiresAt: args.untilRevoked ? 8640000000000000 : Date.now() + args.hours * 3600000, state: 'pending', notes: [], operations: {} }
+      if (command === 'start') {
+        await sourceCall(source.socketPath, 'task-watch', { accountId: task.accountId, conversationId: task.conversationId, expiresAt: task.expiresAt })
+        task.state = 'active'; task.grant = this.scopeHash(task)
+        await this.save(task)
+        await this.dispatchInitial(task)
+        return { id: task.id, state: task.state }
+      }
       if (this.prompt(task).length > 3500) throw new Error('Proposal is too long for owner review; shorten the shared context')
       await this.save(task)
       await new ApprovalStore(this.controlDir).requestApproval(task.id, this.prompt(task), runId)