@fitlab-ai/agent-infra 0.11.8 → 0.11.9

package/README.md

@@ -240,7 +240,7 @@ In-depth guides live under [`docs/en/`](./docs/en/README.md):
 - [Feishu Bridge](./docs/en/feishu-bridge.md) — configure the Feishu long-connection adapter, command routing, permissions, and TUI selection
 - [Built-in AI Skills](./docs/en/skills.md) — the full skill catalog by use case
 - [Custom Skills](./docs/en/custom-skills.md) — create and sync project-specific skills
-- [Custom TUI Configuration](./docs/en/custom-tui.md) — adapt agent-infra to non-built-in AI TUIs
+- [Custom Tool Invocations](./docs/en/custom-tool-invocations.md) — configure custom-tool next-step commands
 - [Prebuilt Workflows](./docs/en/workflows.md) — the gated delivery lifecycle and example flow
 - [Configuration Reference](./docs/en/configuration.md) — `.agents/.airc.json`, external sources, version management
 - [File Management Strategies](./docs/en/file-management.md) — managed / merged / ejected update strategies

package/README.zh-CN.md

@@ -239,7 +239,7 @@ my-project/
 - [飞书桥接](./docs/zh-CN/feishu-bridge.md) — 配置飞书长连接 adapter、命令路由、权限和 TUI 选择
 - [内置 AI Skills](./docs/zh-CN/skills.md) — 按使用场景分组的完整 skill 清单
 - [自定义 Skills](./docs/zh-CN/custom-skills.md) — 创建并同步项目专属 skill
-- [自定义 TUI 配置](./docs/zh-CN/custom-tui.md) — 适配非内置的 AI TUI
+- [自定义工具调用](./docs/zh-CN/custom-tool-invocations.md) — 配置自定义工具的下一步命令
 - [预置工作流](./docs/zh-CN/workflows.md) — 分阶段交付链路与示例流程
 - [配置参考](./docs/zh-CN/configuration.md) — `.agents/.airc.json`、外部源、版本管理
 - [文件管理策略](./docs/zh-CN/file-management.md) — managed / merged / ejected 更新策略

package/dist/lib/agent-clients/custom-tool-invocations.js

@@ -0,0 +1,92 @@
+const ALLOWED_PLACEHOLDERS = Object.freeze(['skillName', 'projectName']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptySingleLine(value) {
+    return typeof value === 'string'
+        && value.trim() !== ''
+        && !/[\r\n]/.test(value);
+}
+function hasValidPlaceholders(invocation) {
+    const placeholders = [
+        ...invocation.matchAll(/\$\{([^}]+)\}/g)
+    ].map((match) => match[1]);
+    return placeholders.includes('skillName')
+        && placeholders.every((placeholder) => ALLOWED_PLACEHOLDERS.includes(placeholder))
+        && !invocation
+            .replaceAll('${skillName}', '')
+            .replaceAll('${projectName}', '')
+            .includes('${');
+}
+function normalizeCustomToolInvocations(config) {
+    const items = [];
+    const diagnostics = [];
+    const root = isRecord(config) ? config : {};
+    const sandbox = isRecord(root.sandbox) ? root.sandbox : {};
+    const sandboxTools = isRecord(sandbox.tools) ? sandbox.tools : { ids: ['agent-infra'] };
+    const definitions = sandboxTools.definitions ?? {};
+    const selectedIds = sandboxTools.ids;
+    if (!Array.isArray(selectedIds)) {
+        return Object.freeze({
+            items: Object.freeze([]),
+            diagnostics: Object.freeze([
+                Object.freeze({
+                    code: 'INVALID_CUSTOM_TOOL_CONFIG',
+                    path: 'sandbox.tools.ids'
+                })
+            ])
+        });
+    }
+    if (!isRecord(definitions)) {
+        return Object.freeze({
+            items: Object.freeze([]),
+            diagnostics: Object.freeze([
+                Object.freeze({
+                    code: 'INVALID_CUSTOM_TOOL_CONFIG',
+                    path: 'sandbox.tools.definitions'
+                })
+            ])
+        });
+    }
+    for (const [index, id] of selectedIds.entries()) {
+        if (typeof id !== 'string') {
+            diagnostics.push({
+                code: 'INVALID_CUSTOM_TOOL_INVOCATION',
+                path: `sandbox.tools.ids[${index}]`
+            });
+            continue;
+        }
+        const candidate = definitions[id];
+        if (!isRecord(candidate))
+            continue;
+        if (candidate.invoke === undefined)
+            continue;
+        const base = `sandbox.tools.definitions.${id}`;
+        const name = candidate.name === undefined ? id : candidate.name;
+        if (!isNonEmptySingleLine(name)) {
+            diagnostics.push({ code: 'INVALID_CUSTOM_TOOL_INVOCATION', path: `${base}.name` });
+            continue;
+        }
+        if (!isNonEmptySingleLine(candidate.invoke)) {
+            diagnostics.push({ code: 'INVALID_CUSTOM_TOOL_INVOCATION', path: `${base}.invoke` });
+            continue;
+        }
+        if (!hasValidPlaceholders(candidate.invoke)) {
+            diagnostics.push({
+                code: 'INVALID_CUSTOM_TOOL_INVOCATION_PLACEHOLDER',
+                path: `${base}.invoke`
+            });
+            continue;
+        }
+        items.push(Object.freeze({
+            name,
+            invocation: candidate.invoke
+        }));
+    }
+    return Object.freeze({
+        items: Object.freeze(items),
+        diagnostics: Object.freeze(diagnostics.map((diagnostic) => Object.freeze(diagnostic)))
+    });
+}
+export { normalizeCustomToolInvocations };
+//# sourceMappingURL=custom-tool-invocations.js.map

package/dist/lib/agent-clients/next-steps.js

@@ -37,7 +37,7 @@ function renderNextStepCommands(input) {
             args
         })
     }));
-    const custom = input.customTUIs.map((tool) => Object.freeze({
+    const custom = input.customToolInvocations.map((tool) => Object.freeze({
         source: 'custom',
         displayName: tool.name,
         command: renderAgentClientInvocation(tool.invocation, {

package/dist/lib/agent-clients/reconcile.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import defaults from '../defaults.json' with { type: 'json' };
 import { normalizeAgentClients, serializeAgentClients } from './config.js';
-import { normalizeCustomTUIs } from './custom-tuis.js';
+import { normalizeCustomToolInvocations } from './custom-tool-invocations.js';
 import { renderNextStepCommands } from './next-steps.js';
 import { planAgentClientProjectAssets } from './project-assets.js';
 import { listAgentClientAdapters, listEnabledAgentClientAdapters } from './registry.js';
@@ -141,11 +141,11 @@ function planAgentClientReconciliation(input) {
     if (Object.keys(baselines).length === 0) {
         delete nextConfig.files.managedBaselines;
     }
-    const custom = normalizeCustomTUIs(input.projectRoot, input.config.customTUIs ?? []);
+    const custom = normalizeCustomToolInvocations(input.config);
     const nextSteps = renderNextStepCommands({
         projectName,
         state: desired,
-        customTUIs: custom.items,
+        customToolInvocations: custom.items,
         skillName: 'update-agent-infra'
     });
     const actionableSeed = seedOperations.some((operation) => operation.kind === 'write' || operation.kind === 'remove');

package/dist/lib/agent-clients/schema.js

@@ -38,16 +38,24 @@ const AGENT_CLIENTS_SCHEMA = {
                 }
             }))
         },
-        customTUIs: {
-            type: 'array',
-            items: {
-                type: 'object',
-                additionalProperties: true,
-                required: ['name', 'dir', 'invoke'],
-                properties: {
-                    name: { type: 'string' },
-                    dir: { type: 'string' },
-                    invoke: { type: 'string' }
+        sandbox: {
+            type: 'object',
+            properties: {
+                tools: {
+                    type: 'object',
+                    properties: {
+                        ids: { type: 'array', items: { type: 'string' } },
+                        definitions: {
+                            type: 'object',
+                            additionalProperties: {
+                                type: 'object',
+                                properties: {
+                                    name: { type: 'string' },
+                                    invoke: { type: 'string' }
+                                }
+                            }
+                        }
+                    }
                 }
             }
         }

package/dist/lib/init.js

@@ -228,8 +228,8 @@ async function cmdInit() {
     console.log('    npm install -g @fitlab-ai/agent-infra');
     console.log('');
     if (workflowPlan.nextSteps.length === 0) {
-        console.log('  No Agent Client project integration enabled.');
-        console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);
+        console.log('  No Agent Client or sandbox custom tool integration enabled.');
+        console.log(`  Configure a custom tool in "sandbox.tools.definitions" and select it in "sandbox.tools.ids" in ${configPath}.`);
         console.log('');
     }
     else {

package/dist/lib/internal/agent-client.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { AgentClientConfigError, normalizeAgentClients } from '../agent-clients/config.js';
-import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.js';
+import { normalizeCustomToolInvocations } from '../agent-clients/custom-tool-invocations.js';
 import { renderNextStepCommands } from '../agent-clients/next-steps.js';
 import { getAgentClientModelSelection } from '../agent-clients/registry.js';
 import { isAgentClientId } from '../agent-clients/types.js';
@@ -139,11 +139,11 @@ function agentClient(args = []) {
     }
     try {
         const clients = normalizeAgentClients(config);
-        const custom = normalizeCustomTUIs(process.cwd(), config.customTUIs ?? []);
+        const custom = normalizeCustomToolInvocations(config);
         const commands = renderNextStepCommands({
             projectName: String(config.project ?? ''),
             state: clients.state,
-            customTUIs: custom.items,
+            customToolInvocations: custom.items,
             skillName: parsed.skillName,
             ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
             ...(parsed.version ? { version: parsed.version } : {})

package/dist/lib/sandbox/recovery.js

@@ -4,8 +4,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { nodeEntryArgs } from './control/executor.js';
-import { containerNameCandidates, sandboxBranchLabel, sandboxLabel, sandboxRuntimeCapabilityLabel, sandboxTaskIdLabel, sandboxWorkspaceModeLabel, worktreeDirCandidates } from './constants.js';
-import { isAgentClientId } from '../agent-clients/types.js';
+import { containerNameCandidates, sandboxBranchLabel, sandboxLabel, sandboxTaskIdLabel, sandboxWorkspaceModeLabel, worktreeDirCandidates } from './constants.js';
 import { createSandboxCapabilityPlan } from './agent-client-reconciler.js';
 import { toEnginePath } from './engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from './mounts.js';
@@ -277,12 +276,6 @@ export function classifySandboxRecovery(snapshot) {
                 : `Container identity ${actualIdentity} on branch ${snapshot.actualBranch ?? 'unknown'} does not match requested ${expectedIdentity} on branch ${snapshot.expectedBranch}.`
         });
     }
-    if (snapshot.runtimeCapabilityOk === false) {
-        findings.push({
-            repairKind: 'hard-failure',
-            message: 'Container runtime capability signature does not match the current sandbox plan.'
-        });
-    }
     if (snapshot.workspaceTopology === 'legacy-parent') {
         findings.push({
             repairKind: 'hard-failure',
@@ -307,13 +300,6 @@ export function classifySandboxRecovery(snapshot) {
             path: '/run/agent-infra/runtime'
         });
     }
-    for (const mountPath of snapshot.unexpectedCapabilityMounts ?? []) {
-        findings.push({
-            repairKind: 'hard-failure',
-            message: `Disabled Agent Client capability remains mounted at ${mountPath}.`,
-            path: mountPath
-        });
-    }
     for (const mount of snapshot.mounts) {
         if (snapshot.workspaceTopology === 'legacy-parent'
             && mount.path.startsWith('/workspace/.agents/workspace'))
@@ -679,11 +665,6 @@ export function collectSandboxRecoverySnapshot(params) {
         mode: sandboxWorkspaceModeLabel(params.config),
         taskId: sandboxTaskIdLabel(params.config)
     });
-    const selectedToolIds = new Set(tools.map((tool) => tool.id));
-    const unexpectedCapabilityMounts = capabilityPlan.cleanupInventory
-        .filter((tool) => isAgentClientId(tool.id) && !selectedToolIds.has(tool.id))
-        .map((tool) => tool.containerMount)
-        .filter((mountPath) => mountsByDestination.has(mountPath));
     const mountSnapshots = expectedMounts({
         config: params.config,
         branch: params.branch,
@@ -736,8 +717,6 @@ export function collectSandboxRecoverySnapshot(params) {
         identityOk: typeof inspection.Id === 'string' && inspection.Id.length > 0
             && branchLabel === params.branch
             && sameSandboxWorkspaceIdentity(containerWorkspace, workspace),
-        runtimeCapabilityOk: labels[sandboxRuntimeCapabilityLabel(params.config)] === capabilityPlan.runtimeSignature,
-        unexpectedCapabilityMounts,
         mounts: mountSnapshots,
         tmpfs,
         seeds,

package/dist/lib/sandbox/tools.js

@@ -187,6 +187,7 @@ export function parseCustomTool(entry, index, options, context = `customTools[${
     if (!containerMount.startsWith('/')) {
         throw new Error(`${context}: field "containerMount" must be an absolute path`);
     }
+    const invoke = asOptionalNonEmptyString(entry.invoke, 'invoke', context);
     const tool = {
         id,
         name: asOptionalNonEmptyString(entry.name, 'name', context) ?? id,
@@ -196,6 +197,7 @@ export function parseCustomTool(entry, index, options, context = `customTools[${
         versionCmd: asOptionalNonEmptyString(entry.versionCmd, 'versionCmd', context) ?? `which ${id}`,
         setupHint: asOptionalNonEmptyString(entry.setupHint, 'setupHint', context)
             ?? `Run \`${id}\` inside the container to set up.`,
+        ...(invoke === undefined ? {} : { invoke }),
         envVars: asStringRecord(entry.envVars, 'envVars', context),
         hostPreSeedFiles: parseHostPreSeedFiles(entry.hostPreSeedFiles, context),
         hostPreSeedDirs: parseHostPreSeedDirs(entry.hostPreSeedDirs, context),

package/dist/lib/task/finalization.js

@@ -619,9 +619,12 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
     const blocked = [steps.backfill, steps.lifecycle, steps.taskComment, steps.verification, steps.summary].some((step) => step?.status === 'blocked');
     const warnings = openWarnings(receipt);
     const postLifecyclePending = receipt.lifecycle === 'done' && (pending.some((step) => step !== 'lifecycle') || receipt.warningProjection === 'pending');
-    const hardError = error?.code.startsWith('FINALIZATION_') || error?.code === 'TASK_FINALIZATION_RECEIPT_INVALID';
+    const terminalVerificationPending = receipt.lifecycle === 'done' && receipt.verification === 'pending';
+    const resultError = error ?? (terminalVerificationPending ? steps.verification?.error : null) ?? null;
+    const hardError = error?.code.startsWith('FINALIZATION_') || error?.code === 'TASK_FINALIZATION_RECEIPT_INVALID'
+        || terminalVerificationPending;
     return {
-        status: hardError ? (error?.retryable ? 'blocked' : 'failed') : pending.length === 0 ? 'completed' : postLifecyclePending ? 'completed' : blocked ? 'blocked' : 'failed',
+        status: hardError ? (resultError?.retryable ? 'blocked' : 'failed') : pending.length === 0 ? 'completed' : postLifecyclePending ? 'completed' : blocked ? 'blocked' : 'failed',
         changed,
         taskId,
         backfill: steps.backfill ?? null,
@@ -632,7 +635,7 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
         completedSteps: completedSteps(receipt),
         pendingSteps: pending,
         result: hardError
-            ? (error?.retryable ? 'blocked' : 'failed')
+            ? (resultError?.retryable ? 'blocked' : 'failed')
             : postLifecyclePending
                 ? 'completed_with_warnings'
                 : pending.length === 0
@@ -641,7 +644,7 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
                         ? 'blocked'
                         : 'failed',
         warnings,
-        error: hardError ? error : postLifecyclePending ? null : error
+        error: hardError ? resultError : postLifecyclePending ? null : resultError
     };
 }
 function preparedResult(taskId, receipt, steps, changed) {
@@ -663,7 +666,6 @@ async function prepareUnderLock(request, taskId, options) {
     const commentSync = options.commentSync ?? syncPlatformComment;
     const issueSync = options.issueSync ?? syncPlatformIssue;
     const issueInspect = options.issueInspect ?? inspectPlatformIssue;
-    const verify = options.verify ?? verifyTaskEvent;
     const consumedCapabilities = new Set();
     let receipt;
     try {
@@ -732,7 +734,8 @@ async function prepareUnderLock(request, taskId, options) {
             }
             const issueOperations = synced.operations;
             const badOperation = issueOperations?.find((operation) => ['requirements', 'issue-type', 'fields', ...(base ? ['labels:in'] : [])].includes(operation.name)
-                && operation.status !== 'applied' && operation.status !== 'no-op');
+                && operation.status !== 'applied' && operation.status !== 'no-op'
+                && !(operation.name === 'requirements' && operation.status === 'skipped' && operation.reasonCode === 'NO_REQUIREMENTS_ANCHOR'));
             if ((synced.status !== 'applied' && synced.status !== 'no-op') || synced.error || badOperation) {
                 const error = synced.error ?? {
                     code: badOperation?.reasonCode || 'FINALIZATION_ISSUE_METADATA_UNCONFIRMED',
@@ -907,88 +910,9 @@ async function prepareUnderLock(request, taskId, options) {
             metadataProvider: () => ({ timestamp: projection.timestamp, agentInfraVersion: projection.agentInfraVersion })
         })
         : undefined;
-    let verification = null;
-    if (receipt.verification !== 'pending') {
-        verification = { status: receipt.verification === 'skipped' ? 'skipped' : 'no-op', changed: false, error: null };
-    }
-    else {
-        try {
-            receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-            const verificationState = resolveTaskRef(taskId, { repoRoot });
-            const verificationEvent = verificationState.ok && verificationState.state === 'completed'
-                ? 'complete-task.completed'
-                : 'complete-task.prepared';
-            const result = await verify({ taskRef: taskId, event: verificationEvent }, { repoRoot });
-            verification = verificationStep(result);
-            if (result.status === 'pass') {
-                const resolvedTaskWarning = receipt.warnings.some((warning) => warning.step === 'verification' && warning.status === 'open');
-                const warnings = applyVerificationWarnings(receipt, result);
-                receipt = updateReceipt(repoRoot, receipt, {
-                    verification: 'done', taskComment: resolvedTaskWarning ? 'pending' : receipt.taskComment,
-                    warningProjection: warnings.length > 0 ? 'pending' : 'done', warnings, lastError: null
-                });
-                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-                const finalComment = await syncPendingTaskComment({
-                    repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities
-                });
-                receipt = finalComment.receipt;
-                if (finalComment.step.status !== 'no-op')
-                    taskComment = finalComment.step;
-                changed = changed || finalComment.changed;
-                if (finalComment.error) {
-                    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, finalComment.error);
-                }
-            }
-            else {
-                const detail = verification.error ?? { code: 'VERIFY_FAILED', message: 'verification failed', retryable: true };
-                const warnings = applyVerificationWarnings(receipt, result);
-                receipt = updateReceipt(repoRoot, receipt, {
-                    verification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: detail
-                });
-                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-                const warningComment = await syncPendingTaskComment({
-                    repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities
-                });
-                receipt = warningComment.receipt;
-                taskComment = warningComment.step;
-                changed = changed || warningComment.changed;
-                if (warningComment.error) {
-                    return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, warningComment.error);
-                }
-                return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification }, changed, detail);
-            }
-        }
-        catch (error) {
-            const detail = errorOf(error, 'VERIFY_FAILED', true);
-            try {
-                const warnings = replaceWarning(receipt, warningFromError('verification', detail), 'open');
-                receipt = updateReceipt(repoRoot, receipt, {
-                    verification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: detail
-                });
-                receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-            }
-            catch (writeError) {
-                const persistence = errorOf(writeError, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
-                const hardError = {
-                    code: 'FINALIZATION_RECEIPT_WRITE_FAILED',
-                    message: `Unable to persist verification failure (${detail.code}: ${detail.message}): ${persistence.message}`,
-                    retryable: true
-                };
-                return terminalResult(taskId, receipt, {
-                    backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail }
-                }, changed, hardError);
-            }
-            try {
-                const warningComment = await syncPendingTaskComment({ repoRoot, taskId, agent: request.agent, receipt, projection: currentProjection(), refreshProjection: currentProjection, commentSync, consumedCapabilities });
-                receipt = warningComment.receipt;
-                if (warningComment.step.status !== 'no-op')
-                    taskComment = warningComment.step;
-                changed = changed || warningComment.changed;
-            }
-            catch { /* preserve the primary error */ }
-            return terminalResult(taskId, receipt, { backfill: backfillResult, lifecycle: lifecycleResult, taskComment, verification: { status: 'blocked', changed: false, error: detail } }, changed, detail);
-        }
-    }
+    const verification = receipt.verification === 'done'
+        ? { status: 'no-op', changed: false, error: null }
+        : { status: 'skipped', changed: false, error: null };
     let summary = receipt.summary === 'pending'
         ? await syncPendingSummary({ repoRoot, taskId, agent: request.agent, receipt, commentSync })
         : { receipt, step: { status: 'no-op', changed: false, error: null }, changed: false, error: null };
@@ -1039,7 +963,7 @@ async function commitPreparedTaskFinalization(request, options) {
     if (!resolved.ok)
         return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
     try {
-        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.commit', () => {
+        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.commit', async () => {
             if (options.controlBinding && options.manifestPath) {
                 try {
                     const manifest = readSandboxControlManifest(options.manifestPath);
@@ -1091,7 +1015,7 @@ async function commitPreparedTaskFinalization(request, options) {
                 return failed(resolved.taskId, {
                     code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation receipt is unavailable', retryable: true
                 });
-            if (receipt.lifecycle === 'done' && resolved.state === 'completed') {
+            if (receipt.lifecycle === 'done' && receipt.verification !== 'pending' && resolved.state === 'completed') {
                 return terminalResult(resolved.taskId, receipt, { lifecycle: { status: 'no-op', changed: false, error: null } }, false);
             }
             if (options.controlBinding) {
@@ -1130,7 +1054,7 @@ async function commitPreparedTaskFinalization(request, options) {
                     }
                 }
             }
-            if (receipt.taskComment === 'pending' || receipt.verification === 'pending' || receipt.summary === 'pending' || receipt.warningProjection === 'pending') {
+            if (receipt.taskComment === 'pending' || receipt.summary === 'pending' || receipt.warningProjection === 'pending') {
                 return failed(resolved.taskId, {
                     code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation has pending external steps', retryable: true
                 }, { completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt) });
@@ -1142,6 +1066,7 @@ async function commitPreparedTaskFinalization(request, options) {
                     message: `cannot verify canonical short-id registry: ${registry.error.code}: ${registry.error.message}`,
                     retryable: false
                 });
+            receipt = updateReceipt(repoRoot, receipt, { verification: 'pending' });
             const lifecycle = options.lifecycle ?? applyTaskLifecycle;
             const result = lifecycle({ taskRef: resolved.taskId, intent: 'complete', agent: request.agent }, { repoRoot, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) });
             const step = lifecycleStep(result);
@@ -1149,8 +1074,80 @@ async function commitPreparedTaskFinalization(request, options) {
                 const updated = updateReceipt(repoRoot, receipt, { lifecycle: 'pending', lastError: step.error });
                 return terminalResult(resolved.taskId, updated, { lifecycle: step }, result.changed, step.error);
             }
-            const updated = updateReceipt(repoRoot, receipt, { lifecycle: 'done', lastError: null });
-            return terminalResult(resolved.taskId, updated, { lifecycle: step }, result.changed);
+            let verificationResult;
+            try {
+                verificationResult = await (options.verify ?? verifyTaskEvent)({ taskRef: resolved.taskId, event: 'complete-task.completed' }, { repoRoot });
+            }
+            catch (error) {
+                const detail = errorOf(error, 'VERIFY_FAILED', true);
+                const warnings = replaceWarning(receipt, warningFromError('verification', detail), 'open');
+                let updated;
+                try {
+                    updated = updateReceipt(repoRoot, receipt, {
+                        lifecycle: 'done', verification: 'pending', taskComment: 'pending', warningProjection: 'pending',
+                        warnings, lastError: detail
+                    });
+                }
+                catch (persistCause) {
+                    const persistError = errorOf(persistCause, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
+                    persistError.code = 'FINALIZATION_RECEIPT_WRITE_FAILED';
+                    persistError.message = `${persistError.message}; verification also failed: ${detail.code}: ${detail.message}`;
+                    return failed(resolved.taskId, persistError, {
+                        changed: result.changed,
+                        lifecycle: step,
+                        verification: { status: 'blocked', changed: false, error: persistError },
+                        completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+                    });
+                }
+                const verification = { status: detail.retryable ? 'blocked' : 'failed', changed: false, error: detail };
+                return terminalResult(resolved.taskId, updated, { lifecycle: step, verification }, result.changed, detail);
+            }
+            const verification = verificationStep(verificationResult);
+            if (verificationResult.status === 'pass') {
+                const resolvedVerificationWarning = receipt.warnings.some((warning) => warning.step === 'verification' && warning.status === 'open');
+                const warnings = applyVerificationWarnings(receipt, verificationResult);
+                const hasOpenWarnings = warnings.some((warning) => warning.status === 'open');
+                let updated;
+                try {
+                    updated = updateReceipt(repoRoot, receipt, {
+                        lifecycle: 'done', verification: 'done',
+                        taskComment: resolvedVerificationWarning ? 'pending' : receipt.taskComment,
+                        warningProjection: hasOpenWarnings ? 'pending' : 'done', warnings, lastError: null
+                    });
+                }
+                catch (persistCause) {
+                    const persistError = errorOf(persistCause, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
+                    persistError.code = 'FINALIZATION_RECEIPT_WRITE_FAILED';
+                    return failed(resolved.taskId, persistError, {
+                        changed: result.changed,
+                        lifecycle: step,
+                        verification,
+                        completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+                    });
+                }
+                return terminalResult(resolved.taskId, updated, { lifecycle: step, verification }, result.changed);
+            }
+            const detail = verification.error ?? { code: 'VERIFY_FAILED', message: 'verification failed', retryable: true };
+            const warnings = applyVerificationWarnings(receipt, verificationResult);
+            let updated;
+            try {
+                updated = updateReceipt(repoRoot, receipt, {
+                    lifecycle: 'done', verification: 'pending', taskComment: 'pending', warningProjection: 'pending',
+                    warnings, lastError: detail
+                });
+            }
+            catch (persistCause) {
+                const persistError = errorOf(persistCause, 'FINALIZATION_RECEIPT_WRITE_FAILED', true);
+                persistError.code = 'FINALIZATION_RECEIPT_WRITE_FAILED';
+                persistError.message = `${persistError.message}; verification also failed: ${detail.code}: ${detail.message}`;
+                return failed(resolved.taskId, persistError, {
+                    changed: result.changed,
+                    lifecycle: step,
+                    verification: { status: 'blocked', changed: false, error: persistError },
+                    completedSteps: completedSteps(receipt), pendingSteps: pendingSteps(receipt), warnings: openWarnings(receipt)
+                });
+            }
+            return terminalResult(resolved.taskId, updated, { lifecycle: step, verification }, result.changed, detail);
         });
     }
     catch (error) {

package/dist/lib/task/verification.js

@@ -22,7 +22,6 @@ const VERIFICATION_CATALOG = {
     'commit.completed': gate('commit', 'active'),
     'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
     'complete-task.hard-preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
-    'complete-task.prepared': gate('complete-task', 'active'),
     'complete-task.completed': gate('complete-task', 'completed'),
     'create-pr.completed': gate('create-pr', 'active'),
     'create-task.completed': gate('create-task', 'active'),

package/dist/lib/update.js

@@ -132,8 +132,8 @@ async function cmdSync() {
     ok('Seed files synced successfully!');
     console.log('');
     if (workflowPlan.nextSteps.length === 0) {
-        console.log('  No Agent Client project integration enabled.');
-        console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
+        console.log('  No Agent Client or sandbox custom tool integration enabled.');
+        console.log(`  Configure a custom tool in "sandbox.tools.definitions" and select it in "sandbox.tools.ids" in ${CONFIG_PATH}.`);
         console.log('');
     }
     else {

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.8",
-  "sourceInputHash": "6ddb72f8b50137d5148a47172bd7eb2628b17a937ae647ac38350e582ba08124",
-  "internalExecutableBuildHash": "c886e015506879620bb490f1ea5977d9952f2bbb4515d3a0b49e0ec184b48028"
+  "packageVersion": "0.11.9",
+  "sourceInputHash": "17fe6c91408c93e3aa5185e816025d590ded7db7e6a305fdce00751e78723abc",
+  "internalExecutableBuildHash": "8de9870e4ece1050564d7a3e77ee211a789dd975e3f94593300b7362ed815a00"
 }