evolcore 0.0.23 → 0.0.25

package/dist/index.js

@@ -100,6 +100,7 @@ import { MAIN_PACKAGE_NAME } from './product.js';
 import fs from 'fs';
 import crypto from 'crypto';
 import { fileURLToPath } from 'url';
+import * as platform from './utils/cross-platform.js';
 const controlMenuDeduper = new MenuRequestDeduper();
 /** 出站 payload 摘要（用于 channel-out.log） */
 function summarizeOutboundPayload(payload) {
@@ -134,6 +135,7 @@ function summarizeOutboundPayload(payload) {
             break;
         case 'status.started':
         case 'status.progress':
+        case 'status.notice':
         case 'status.requires_action':
         case 'status.queued':
         case 'status.completed':
@@ -326,102 +328,158 @@ function seedUpgradeCheckTrigger(manager, owner) {
     const cliPath = path.join(packageRoot, 'dist', 'cli', 'index.js');
     const packageJsonPath = path.join(packageRoot, 'package.json');
     const devMode = fs.existsSync(path.join(packageRoot, 'src', 'index.ts'));
-    fs.writeFileSync(scriptPath, `#!/usr/bin/env node
-const { existsSync, readFileSync } = require('node:fs');
-const { spawn } = require('node:child_process');
-
-const CLI_PATH = ${JSON.stringify(cliPath)};
-const PACKAGE_JSON = ${JSON.stringify(packageJsonPath)};
-const PACKAGE_NAME = ${JSON.stringify(MAIN_PACKAGE_NAME)};
-const DEV_MODE = ${devMode ? 'true' : 'false'};
-
-function emit(outcome, text) {
-  process.stdout.write(JSON.stringify({ outcome, text, files: [] }));
-}
-
-function compareVersions(a, b) {
-  const pa = a.split('-')[0].split('.').map(Number);
-  const pb = b.split('-')[0].split('.').map(Number);
-  const count = Math.max(pa.length, pb.length);
-  for (let i = 0; i < count; i += 1) {
-    const av = Number.isFinite(pa[i]) ? pa[i] : 0;
-    const bv = Number.isFinite(pb[i]) ? pb[i] : 0;
-    if (av < bv) return -1;
-    if (av > bv) return 1;
-  }
-  return 0;
-}
-
-async function latestVersion() {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 10_000);
-  try {
-    const response = await fetch('https://registry.npmjs.org/' + encodeURIComponent(PACKAGE_NAME) + '/latest', {
-      signal: controller.signal,
-      headers: { Accept: 'application/json' },
-    });
-    if (!response.ok) return null;
-    const data = await response.json();
-    return typeof data.version === 'string' ? data.version : null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-async function main() {
-  if (DEV_MODE) {
-    emit('noop', 'upgrade check skipped in dev mode');
-    return;
-  }
-
-  let localVersion;
-  try {
-    localVersion = JSON.parse(readFileSync(PACKAGE_JSON, 'utf8')).version;
-  } catch {
-    emit('error', 'failed to read local ec version');
-    return;
-  }
-  if (typeof localVersion !== 'string' || !localVersion) {
-    emit('error', 'failed to read local ec version');
-    return;
-  }
-
-  let remoteVersion;
-  try {
-    remoteVersion = await latestVersion();
-  } catch {
-    remoteVersion = null;
-  }
-  if (!remoteVersion) {
-    emit('error', 'failed to check evolcore latest version');
-    return;
-  }
-  if (compareVersions(localVersion, remoteVersion) >= 0) {
-    emit('noop', 'evolcore is already up to date (' + localVersion + '; latest ' + remoteVersion + ')');
-    return;
-  }
-  if (!existsSync(CLI_PATH)) {
-    emit('error', 'restart-monitor entry not found: ' + CLI_PATH);
-    return;
-  }
-
-  try {
-    const child = spawn(process.execPath, [CLI_PATH, 'restart-monitor'], {
-      detached: true,
-      stdio: 'ignore',
-      windowsHide: process.platform === 'win32',
-      env: { ...process.env },
-    });
-    child.unref();
-    emit('success', 'evolcore upgrade available: ' + localVersion + ' -> ' + remoteVersion + '; restart-monitor started');
-  } catch (error) {
-    emit('error', 'failed to start restart-monitor: ' + (error && error.message ? error.message : String(error)));
-  }
-}
-
-main().catch((error) => {
-  emit('error', 'upgrade check failed: ' + (error && error.message ? error.message : String(error)));
-});
+    // Resolve the launch argv at generation time: in a checkout this points the
+    // monitor at src/ through tsx, so a `npm run build` that wipes dist/ cannot
+    // take the watchdog down with it.
+    const monitorEntry = platform.resolveCliEntry(packageRoot);
+    const stageParent = path.join(resolvePaths().root, 'data', 'monitor-stage');
+    fs.writeFileSync(scriptPath, `#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+const { existsSync, readFileSync } = fs;
+const { spawn } = require('node:child_process');
+
+const CLI_PATH = ${JSON.stringify(monitorEntry.entry)};
+const CLI_ARGS = ${JSON.stringify(monitorEntry.args)};
+const PACKAGE_ROOT = ${JSON.stringify(packageRoot)};
+const STAGE_PARENT = ${JSON.stringify(stageParent)};
+const PACKAGE_JSON = ${JSON.stringify(packageJsonPath)};
+const PACKAGE_NAME = ${JSON.stringify(MAIN_PACKAGE_NAME)};
+const DEV_MODE = ${devMode ? 'true' : 'false'};
+
+function emit(outcome, text) {
+  process.stdout.write(JSON.stringify({ outcome, text, files: [] }));
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('-')[0].split('.').map(Number);
+  const pb = b.split('-')[0].split('.').map(Number);
+  const count = Math.max(pa.length, pb.length);
+  for (let i = 0; i < count; i += 1) {
+    const av = Number.isFinite(pa[i]) ? pa[i] : 0;
+    const bv = Number.isFinite(pb[i]) ? pb[i] : 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+async function latestVersion() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 10_000);
+  try {
+    const response = await fetch('https://registry.npmjs.org/' + encodeURIComponent(PACKAGE_NAME) + '/latest', {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return typeof data.version === 'string' ? data.version : null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  if (DEV_MODE) {
+    emit('noop', 'upgrade check skipped in dev mode');
+    return;
+  }
+
+  let localVersion;
+  try {
+    localVersion = JSON.parse(readFileSync(PACKAGE_JSON, 'utf8')).version;
+  } catch {
+    emit('error', 'failed to read local ec version');
+    return;
+  }
+  if (typeof localVersion !== 'string' || !localVersion) {
+    emit('error', 'failed to read local ec version');
+    return;
+  }
+
+  let remoteVersion;
+  try {
+    remoteVersion = await latestVersion();
+  } catch {
+    remoteVersion = null;
+  }
+  if (!remoteVersion) {
+    emit('error', 'failed to check evolcore latest version');
+    return;
+  }
+  if (compareVersions(localVersion, remoteVersion) >= 0) {
+    emit('noop', 'evolcore is already up to date (' + localVersion + '; latest ' + remoteVersion + ')');
+    return;
+  }
+  if (!existsSync(CLI_PATH)) {
+    emit('error', 'restart-monitor entry not found: ' + CLI_PATH);
+    return;
+  }
+
+  // Installed mode: copy the monitor out of the package before it upgrades that
+  // same package. Mirrors prepareMonitorStage(); kept inline because this file
+  // is generated standalone CJS. Any failure degrades to launching in place —
+  // losing upgrade isolation beats losing the upgrade.
+  let launchArgs = CLI_ARGS;
+  const launchEnv = { ...process.env };
+  if (!DEV_MODE && STAGE_PARENT) {
+    try {
+      const stageDir = path.join(STAGE_PARENT, 'upgrade-' + process.pid + '-' + Date.now());
+      fs.mkdirSync(stageDir, { recursive: true });
+      fs.cpSync(path.join(PACKAGE_ROOT, 'dist'), path.join(stageDir, 'dist'), { recursive: true });
+      if (existsSync(PACKAGE_JSON)) fs.copyFileSync(PACKAGE_JSON, path.join(stageDir, 'package.json'));
+      const modulesSource = path.join(PACKAGE_ROOT, 'node_modules');
+      if (existsSync(modulesSource)) {
+        const staged = path.join(stageDir, 'node_modules');
+        try {
+          // junction works unelevated on Windows; dir symlink elsewhere.
+          fs.symlinkSync(modulesSource, staged, process.platform === 'win32' ? 'junction' : 'dir');
+          fs.readdirSync(staged);
+        } catch (linkError) {
+          fs.rmSync(staged, { recursive: true, force: true });
+          fs.cpSync(modulesSource, staged, { recursive: true });
+        }
+      }
+      const stagedEntry = path.join(stageDir, 'dist', 'cli', 'index.js');
+      if (existsSync(stagedEntry)) {
+        launchArgs = [stagedEntry];
+        launchEnv.EVOLCORE_TARGET_PACKAGE_ROOT = PACKAGE_ROOT;
+        launchEnv.EVOLCORE_MONITOR_STAGE = stageDir;
+      }
+    } catch (stageError) {
+      // Fall through with the in-place entry.
+    }
+  }
+
+  try {
+    const child = spawn(process.execPath, [...launchArgs, 'restart-monitor'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: process.platform === 'win32',
+      env: launchEnv,
+    });
+    child.unref();
+    const pid = child.pid;
+    // The daemon is still running here — the monitor is what stops it. So a
+    // monitor that dies on load costs the upgrade, not the service; still,
+    // report it accurately instead of claiming success.
+    await new Promise(resolve => setTimeout(resolve, 3000));
+    let alive = false;
+    try { process.kill(pid, 0); alive = true; } catch (e) { alive = false; }
+    if (!alive) {
+      emit('error', 'restart-monitor exited during startup; upgrade to ' + remoteVersion + ' not applied');
+      return;
+    }
+    emit('success', 'evolcore upgrade available: ' + localVersion + ' -> ' + remoteVersion + '; restart-monitor started');
+  } catch (error) {
+    emit('error', 'failed to start restart-monitor: ' + (error && error.message ? error.message : String(error)));
+  }
+}
+
+main().catch((error) => {
+  emit('error', 'upgrade check failed: ' + (error && error.message ? error.message : String(error)));
+});
 `);
     // Remove the pre-Node script left by older installations so it cannot be
     // selected by a stale trigger definition or run manually by accident.
@@ -1066,7 +1124,7 @@ async function main() {
     agentLoader.register(new GeminiAgentPlugin());
     agentLoader.register(new EcagentAgentPlugin());
     const creationErrors = [];
-    const agentInstances = agentLoader.createAll(agentRegistry, {
+    const agentInstances = await agentLoader.createAll(agentRegistry, {
         onSessionIdUpdate: async (sessionId, agentSessionId, context) => {
             return await sessionManager.updateAgentSessionIdBySessionId(sessionId, agentSessionId, context?.turn);
         },
@@ -1493,8 +1551,9 @@ async function main() {
         }
         if (definition.execution.effort && !actor.daemonPrivileged) {
             const baseagent = definition.execution.baseagent
-                ?? agentRegistry.get(definition.agentAid)?.baseagent
-                ?? 'claude';
+                ?? agentRegistry.get(definition.agentAid)?.baseagent;
+            if (!baseagent)
+                throw new Error('cannot determine Trigger baseagent');
             const effortDecision = validateRuntimeStringFieldOverride({
                 selfAid: definition.agentAid,
                 role: actor.role,
@@ -2154,6 +2213,7 @@ async function main() {
             const pendingRouteContext = restartDelivery.delivery ? { delivery: restartDelivery.delivery } : {};
             const replyContext = {
                 ...(pendingRouteContext ?? {}),
+                ...(pending.threadId ? { threadId: pending.threadId } : {}),
                 ...(pending.rootId ? { replyToMessageId: pending.rootId, replyInThread: !!pending.threadId } : {}),
             };
             const owningAgent = agentRegistry.resolveByChannel(adapter.channelKey);
@@ -2165,10 +2225,23 @@ async function main() {
                 ...(restartDelivery.delivery ? { delivery: restartDelivery.delivery } : {}),
                 replyContext: Object.keys(replyContext).length > 0 ? replyContext : undefined,
             });
+            // restart-monitor 会在回滚/升级时写入 outcome：必须如实告诉发起方这次跑的是
+            // 哪个版本，否则 agent 会以为自己的改动或升级已经生效。
+            const restartNotice = pending.outcome === 'rolled-back'
+                ? {
+                    text: `⚠️ 服务已重启，但运行的是上一个版本。${pending.outcomeReason ? `原因：${pending.outcomeReason}。` : ''}本次改动未生效，请检查后重试。`,
+                    subtype: 'restarted-rolled-back',
+                }
+                : pending.outcome === 'upgraded'
+                    ? {
+                        text: `✅ 服务重启成功！${pending.outcomeReason ? `${pending.outcomeReason}` : ''}`,
+                        subtype: 'restarted-upgraded',
+                    }
+                    : { text: '✅ 服务重启成功！', subtype: 'restarted' };
             await sendSystemPayload(adapter, envelope, {
                 kind: 'system.notice',
-                text: '✅ 服务重启成功！',
-                subtype: 'restarted',
+                text: restartNotice.text,
+                subtype: restartNotice.subtype,
             });
             pendingRestartNoticeSent = true;
             fs.rmSync(pendingFile, { force: true });
@@ -2658,9 +2731,18 @@ async function main() {
                 continue;
             }
             const evolName = owningAgent.aid;
-            const baseagentName = session.baseagent || primaryBaseagent;
-            const agent = agentMap.get(`${evolName}::${baseagentName}`) || agentMap.get(primaryRunnerKey);
+            const baseagentName = typeof session.baseagent === 'string' ? session.baseagent.trim() : '';
+            if (!baseagentName) {
+                logger.error(`[Resume] session ${session.id}: missing baseagent binding, refusing implicit runner fallback`);
+                sessionManager.clearProcessing(session.id);
+                continue;
+            }
+            // Recovery must resume on the exact Agent × baseagent runner recorded by
+            // the Session. Never fall back to the primary runner: doing so can bind
+            // an in-flight session to a different backend.
+            const agent = agentMap.get(`${evolName}::${baseagentName}`);
             if (!agent) {
+                logger.error(`[Resume] session ${session.id}: runner unavailable for ${evolName}::${baseagentName}; refusing fallback`);
                 sessionManager.clearProcessing(session.id);
                 continue;
             }
@@ -2727,11 +2809,12 @@ async function main() {
                 return owner?.aid === aid;
             });
             const welcome = aunInstance?.channel;
-            const ownerAid = getFirstStaticAgentOwner(aid);
             const owningAgent = agentRegistry.get(aid);
-            const sessions = aunInstance && ownerAid && owningAgent
+            const firstOwnerAid = getFirstStaticAgentOwner(aid);
+            const sessions = aunInstance && firstOwnerAid && owningAgent
                 ? {
-                    ensurePostBootstrapMainSession: async () => {
+                    ensurePostBootstrapMainSession: async (owner) => {
+                        const ownerAid = owner || firstOwnerAid;
                         const channel = aunInstance.adapter.channelName;
                         const active = await sessionManager.getActiveSession(channel, ownerAid);
                         const ensured = await sessionManager.ensureNewMainSessionForOperation({
@@ -2739,7 +2822,7 @@ async function main() {
                             channelId: ownerAid,
                             projectPath: active?.projectPath || owningAgent.projectPath || defaultProjectPath,
                             baseagent: owningAgent.baseagent || active?.baseagent || primaryBaseagent,
-                            operationId: postBootstrapWelcomeOperationId(aid),
+                            operationId: postBootstrapWelcomeOperationId(aid, ownerAid),
                             identityMetadata: {
                                 ...(active?.metadata ?? {}),
                                 channelKey: aunInstance.adapter.channelKey,
@@ -2851,15 +2934,18 @@ async function main() {
             for (const runner of new Set(agentMap.values())) {
                 if (typeof runner?.evaluatePreToolUse !== 'function')
                     continue;
-                const result = await runner.evaluatePreToolUse(params.threadId, params.toolName, params.toolInput, params.signal, params.callId);
+                const result = await runner.evaluatePreToolUse(params.threadId, params.toolName, params.toolInput, params.signal, params.callId, params.sessionToken);
                 if (result.applicable)
                     return result;
             }
+            // A credential that no runner issued is forged or belongs to a thread
+            // whose rollout is gone. Never allow it; uncredentialed calls were
+            // already allowed by the IPC layer before reaching this executor.
             return {
                 ok: false,
                 applicable: true,
                 decision: 'deny',
-                reason: 'No active EvolCore Codex runner accepted this managed hook request',
+                reason: 'No active EvolCore Codex runner accepted this managed hook credential',
             };
         });
         const resolveManagedHandoffScope = async (params, operation) => {
@@ -3192,7 +3278,7 @@ async function main() {
                 const creationErrors = [];
                 const staged = candidate.config.enabled === false
                     ? []
-                    : agentLoader.createForAgent(candidate, {
+                    : await agentLoader.createForAgent(candidate, {
                         onSessionIdUpdate: async (sessionId, agentSessionId, context) => {
                             return await sessionManager.updateAgentSessionIdBySessionId(sessionId, agentSessionId, context?.turn);
                         },
@@ -3292,7 +3378,7 @@ async function main() {
                     throw new Error(agentRuntimeError);
                 }
                 const creationErrors = [];
-                const newAgentInstances = agentLoader.createForAgent(agent, {
+                const newAgentInstances = await agentLoader.createForAgent(agent, {
                     onSessionIdUpdate: async (sessionId, agentSessionId, context) => {
                         return await sessionManager.updateAgentSessionIdBySessionId(sessionId, agentSessionId, context?.turn);
                     },
@@ -3483,7 +3569,7 @@ async function main() {
             hotLoad: coreHotLoadAgent,
             resync: coreResyncAgents,
             create: async (options) => {
-                const { agentCreateNonInteractive } = await import('./cli/agent.js');
+                const { agentCreateNonInteractive } = await import('./cli/agent-create.js');
                 return await agentCreateNonInteractive(options, { hotLoadAgent: coreHotLoadAgent });
             },
             aunAids: () => channelInstances.flatMap((inst) => {
@@ -3577,7 +3663,8 @@ async function main() {
             });
             if (params.targetAid
                 && params.targetAid !== delegation.grant.selfAid
-                && subject.dataScope !== 'daemon') {
+                && subject.dataScope !== 'daemon'
+                && !(operation === 'agent.show' && isManagementRole(subject.role))) {
                 return { ok: false, code: 'SCOPE_MISMATCH', error: 'only the current Agent can be targeted' };
             }
             const decision = authorizeOperation({
@@ -3624,18 +3711,21 @@ async function main() {
             const taskAid = delegation.grant.selfAid;
             const targetAid = sub === 'list'
                 ? undefined
-                : sub === 'show'
-                    ? (argv[2] && !argv[2].startsWith('--') ? argv[2] : taskAid)
-                    : sub === 'reload'
-                        ? (argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined)
-                        : (argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined);
+                : sub === 'persona'
+                    ? taskAid
+                    : sub === 'show'
+                        ? (argv[2] && !argv[2].startsWith('--') ? argv[2] : taskAid)
+                        : sub === 'reload'
+                            ? (argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined)
+                            : (argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined);
             const operation = sub === 'list' ? 'agent.list'
                 : sub === 'show' ? 'agent.show'
-                    : sub === 'new' ? 'agent.create'
-                        : sub === 'enable' ? 'agent.enable'
-                            : sub === 'disable' ? 'agent.disable'
-                                : sub === 'reload' ? 'agent.reload'
-                                    : sub === 'delete' ? 'agent.delete' : undefined;
+                    : sub === 'persona' ? 'agent.persona'
+                        : sub === 'new' ? 'agent.create'
+                            : sub === 'enable' ? 'agent.enable'
+                                : sub === 'disable' ? 'agent.disable'
+                                    : sub === 'reload' ? 'agent.reload'
+                                        : sub === 'delete' ? 'agent.delete' : undefined;
             if (!operation)
                 return fail('INVALID_ARGS', `unsupported managed agent command: ${sub}`);
             if (sub === 'new' && !argv.includes('--non-interactive')) {
@@ -3667,7 +3757,7 @@ async function main() {
                 subject,
                 intent: {
                     operation,
-                    scope: operation === 'agent.show'
+                    scope: operation === 'agent.show' || operation === 'agent.persona'
                         ? 'agent'
                         : operation === 'agent.reload' && targetAid
                             ? 'agent'
@@ -3723,45 +3813,148 @@ async function main() {
                         },
                         connection: agent.connection ?? null,
                         sessions: agent.sessions ?? { active: 0, last_activity: null },
-                        paths: { config: null, agent_md: null, project: null, data: null },
-                        redacted: true,
+                        paths: subject.dataScope === 'daemon'
+                            ? (agent.paths ?? { config: null, agent_md: null, project: null, data: null })
+                            : { config: null, agent_md: null, project: null, data: null },
+                        ...(subject.dataScope === 'daemon' ? {} : { redacted: true }),
                         ...(agent.createProgress ? { createProgress: agent.createProgress } : {}),
                     } };
             }
+            if (operation === 'agent.persona') {
+                const rawPersonaArgs = argv.slice(2);
+                const hasFormatSuffix = rawPersonaArgs.length >= 2
+                    && rawPersonaArgs.at(-2) === '--format'
+                    && rawPersonaArgs.at(-1) === 'json';
+                const personaArgs = hasFormatSuffix ? rawPersonaArgs.slice(0, -2) : rawPersonaArgs;
+                if (!hasFormatSuffix && rawPersonaArgs.includes('--format')) {
+                    return fail('INVALID_ARGS', 'persona 仅支持末尾的 --format json');
+                }
+                if (personaArgs.length === 2 && personaArgs[0] === '--file') {
+                    return fail('INVALID_ARGS', '托管 persona --file 必须由 CLI 读取后作为文本提交');
+                }
+                const wantsShow = personaArgs.length === 1 && personaArgs[0] === 'show';
+                const text = personaArgs.length === 2 && personaArgs[0] === '--text'
+                    ? personaArgs[1]
+                    : undefined;
+                if (!wantsShow && !(personaArgs.length === 2 && personaArgs[0] === '--text')) {
+                    return fail('INVALID_ARGS', '用法: ec agent persona show | --text <text>');
+                }
+                if (text === undefined && !wantsShow)
+                    return fail('INVALID_ARGS', 'persona --text 缺少参数');
+                const { agentPersona } = await import('./cli/agent.js');
+                const result = await agentPersona(taskAid, wantsShow ? { trustedLocal: true } : { text, trustedLocal: true });
+                if (!result.ok)
+                    return fail(result.code ?? 'INTERNAL', result.error);
+                return { ok: true, result: {
+                        ok: true,
+                        aid: taskAid,
+                        content: result.content,
+                        ...(result.saved ? { saved: true } : {}),
+                    } };
+            }
             if (operation === 'agent.create') {
                 const aid = argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined;
                 if (!aid)
                     return fail('INVALID_ARGS', 'ec agent new requires an AID');
-                const { agentCreateNonInteractive, resolveAgentCreatePlan, validateAgentCreatePlan } = await import('./cli/agent.js');
+                const { agentCreateNonInteractive, resolveAgentCreatePlan, validateAgentCreatePlan, parseAgentOwnerArgs, parseAgentTags } = await import('./cli/agent-create.js');
+                let ownerOptions;
+                try {
+                    ownerOptions = parseAgentOwnerArgs(argv);
+                }
+                catch (error) {
+                    return fail('INVALID_ARGS', error instanceof Error ? error.message : String(error));
+                }
+                let tags;
+                try {
+                    tags = parseAgentTags(value('--tags'));
+                }
+                catch (error) {
+                    return fail('INVALID_ARGS', error instanceof Error ? error.message : String(error));
+                }
                 const plan = resolveAgentCreatePlan({
                     aid,
                     project: value('--project'),
                     baseagent: value('--baseagent'),
-                    owner: value('--owner'),
+                    ...ownerOptions,
+                    handoff: value('--handoff'),
                     name: value('--name'),
                     description: value('--description'),
+                    tags,
                     force: argv.includes('--force'),
                 });
                 const validationError = validateAgentCreatePlan(plan);
                 if (validationError)
                     return fail('INVALID_ARGS', validationError);
+                if (argv.includes('--handoff')) {
+                    if (!delegation.grant.messageId)
+                        return fail('INVALID_ARGS', '--handoff requires an originating message');
+                    if (!plan.handoff?.trim())
+                        return fail('INVALID_ARGS', '--handoff requires non-empty context');
+                    if ((plan.owners?.[0] ?? plan.owner) !== taskAid) {
+                        return fail('INVALID_ARGS', '--handoff requires the creating Agent to be the first Owner');
+                    }
+                    if (plan.configExists)
+                        return fail('INVALID_ARGS', '--handoff requires a new Agent');
+                }
                 if (argv.includes('--dry-run'))
                     return { ok: true, result: { ok: true, dryRun: true, plan } };
+                let handoffId;
+                if (plan.handoff) {
+                    try {
+                        const created = await handoffRuntime.createOutbound({
+                            selfAid: taskAid,
+                            to: aid,
+                            originSessionId: sessionId,
+                            originMessageId: delegation.grant.messageId,
+                            payload: { type: 'text', text: plan.handoff },
+                            encrypt: true,
+                            targetChatType: 'private',
+                            explicitReturnPolicy: 'required',
+                            contextOnly: true,
+                            originAuthorization: {
+                                actorId: delegation.grant.actorId,
+                                channelKey: delegation.grant.channel,
+                                channelType: delegation.grant.channelType,
+                                chatType: delegation.grant.chatType,
+                                peerKey: delegation.grant.peerKey,
+                            },
+                            causation: responseEngine.getTaskRuntimeContext(sessionId)?.causation,
+                        });
+                        handoffId = created.handoff?.handoff_id;
+                        if (!handoffId)
+                            return fail('INVALID_ARGS', '--handoff requires a different target session');
+                    }
+                    catch (error) {
+                        return fail('HANDOFF_PREPARE_FAILED', error instanceof Error ? error.message : String(error));
+                    }
+                }
                 const createOptions = {
                     aid: plan.aid,
                     project: plan.project,
                     baseagent: plan.baseagent,
                     owner: plan.owner,
+                    owners: plan.owners,
                     name: plan.name,
                     description: plan.description,
+                    tags: plan.tags,
                     force: argv.includes('--force'),
                 };
-                const result = agentApplicationService
-                    ? await agentApplicationService.create(createOptions)
-                    : await agentCreateNonInteractive(createOptions);
-                return !result.ok
-                    ? fail(result.code ?? 'INTERNAL', result.error)
-                    : { ok: true, result: { ...result, configPath: '[redacted]' } };
+                try {
+                    const result = agentApplicationService
+                        ? await agentApplicationService.create(createOptions)
+                        : await agentCreateNonInteractive(createOptions);
+                    if (!result.ok) {
+                        if (handoffId)
+                            handoffRuntime.store.discard(taskAid, handoffId, 'operation_failed');
+                        return fail(result.code ?? 'INTERNAL', result.error);
+                    }
+                    return { ok: true, result: { ...result, configPath: '[redacted]', ...(handoffId ? { handoff_id: handoffId } : {}) } };
+                }
+                catch (error) {
+                    if (handoffId)
+                        handoffRuntime.store.discard(taskAid, handoffId, 'operation_failed');
+                    return fail('INTERNAL', error instanceof Error ? error.message : String(error));
+                }
             }
             if (operation === 'agent.delete') {
                 const result = agentApplicationService