@fitlab-ai/agent-infra 0.11.8 → 0.11.9

package/lib/agent-clients/custom-tool-invocations.ts

@@ -0,0 +1,129 @@
+type CustomToolInvocation = Readonly<{
+  name: string;
+  invocation: string;
+}>;
+
+type CustomToolInvocationDiagnosticCode =
+  | 'INVALID_CUSTOM_TOOL_CONFIG'
+  | 'INVALID_CUSTOM_TOOL_INVOCATION'
+  | 'INVALID_CUSTOM_TOOL_INVOCATION_PLACEHOLDER';
+
+type CustomToolInvocationDiagnostic = Readonly<{
+  code: CustomToolInvocationDiagnosticCode;
+  path: string;
+}>;
+
+type NormalizeCustomToolInvocationsResult = Readonly<{
+  items: readonly CustomToolInvocation[];
+  diagnostics: readonly CustomToolInvocationDiagnostic[];
+}>;
+
+const ALLOWED_PLACEHOLDERS = Object.freeze(['skillName', 'projectName']);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptySingleLine(value: unknown): value is string {
+  return typeof value === 'string'
+    && value.trim() !== ''
+    && !/[\r\n]/.test(value);
+}
+
+function hasValidPlaceholders(invocation: string): boolean {
+  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: unknown): NormalizeCustomToolInvocationsResult {
+  const items: CustomToolInvocation[] = [];
+  const diagnostics: CustomToolInvocationDiagnostic[] = [];
+
+  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' as const,
+          path: 'sandbox.tools.ids'
+        })
+      ])
+    });
+  }
+
+  if (!isRecord(definitions)) {
+    return Object.freeze({
+      items: Object.freeze([]),
+      diagnostics: Object.freeze([
+        Object.freeze({
+          code: 'INVALID_CUSTOM_TOOL_CONFIG' as const,
+          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 };
+export type {
+  CustomToolInvocation,
+  CustomToolInvocationDiagnostic,
+  CustomToolInvocationDiagnosticCode,
+  NormalizeCustomToolInvocationsResult
+};

package/lib/agent-clients/next-steps.ts

@@ -2,7 +2,7 @@ import { listEnabledAgentClientAdapters } from './registry.ts';
 import { renderAgentClientInvocation } from './invocation.ts';
 import semver from 'semver';
 import { isTaskScopeSkill } from '../task/skill-scope.ts';
-import type { CustomTUI } from './custom-tuis.ts';
+import type { CustomToolInvocation } from './custom-tool-invocations.ts';
 import type { AgentClientId, AgentClientState } from './types.ts';
 
 type NextStepCommand = Readonly<{
@@ -15,7 +15,7 @@ type NextStepCommand = Readonly<{
 type RenderNextStepsInput = Readonly<{
   projectName: string;
   state: AgentClientState;
-  customTUIs: readonly CustomTUI[];
+  customToolInvocations: readonly CustomToolInvocation[];
   skillName: string;
   taskRef?: string;
   version?: string;
@@ -69,7 +69,7 @@ function renderNextStepCommands(
       )
     })
   );
-  const custom = input.customTUIs.map(
+  const custom = input.customToolInvocations.map(
     (tool): NextStepCommand => Object.freeze({
       source: 'custom',
       displayName: tool.name,

package/lib/agent-clients/reconcile.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import defaults from '../defaults.json' with { type: 'json' };
 import { normalizeAgentClients, serializeAgentClients } from './config.ts';
-import { normalizeCustomTUIs } from './custom-tuis.ts';
+import { normalizeCustomToolInvocations } from './custom-tool-invocations.ts';
 import { renderNextStepCommands } from './next-steps.ts';
 import { planAgentClientProjectAssets } from './project-assets.ts';
 import {
@@ -216,11 +216,11 @@ function planAgentClientReconciliation(input: Readonly<{
     delete (nextConfig.files as Record<string, unknown>).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) =>

package/lib/agent-clients/schema.ts

@@ -43,16 +43,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/lib/init.ts

@@ -314,8 +314,8 @@ async function cmdInit(): Promise<void> {
   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 {
     console.log('  Next step: open this project in any AI TUI and run:');

package/lib/internal/agent-client.ts

@@ -5,7 +5,7 @@ import {
   AgentClientConfigError,
   normalizeAgentClients
 } from '../agent-clients/config.ts';
-import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
+import { normalizeCustomToolInvocations } from '../agent-clients/custom-tool-invocations.ts';
 import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
 import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
@@ -148,11 +148,11 @@ function agentClient(args: string[] = []): void {
 
   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/lib/sandbox/recovery.ts

@@ -8,12 +8,10 @@ import {
   containerNameCandidates,
   sandboxBranchLabel,
   sandboxLabel,
-  sandboxRuntimeCapabilityLabel,
   sandboxTaskIdLabel,
   sandboxWorkspaceModeLabel,
   worktreeDirCandidates
 } from './constants.ts';
-import { isAgentClientId } from '../agent-clients/types.ts';
 import {
   createSandboxCapabilityPlan
 } from './agent-client-reconciler.ts';
@@ -100,8 +98,6 @@ export type SandboxRecoverySnapshot = {
   workspaceTopology?: 'legacy-parent' | 'per-state' | 'unknown';
   taskView?: { path: string; readable: boolean };
   runtimeStoreOk?: boolean;
-  runtimeCapabilityOk?: boolean;
-  unexpectedCapabilityMounts?: string[];
   mounts: Array<{
     path: string;
     expectedType: string;
@@ -452,12 +448,6 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
         : `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',
@@ -482,14 +472,6 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
       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'
@@ -964,11 +946,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,
@@ -1035,8 +1012,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/lib/sandbox/tool-types.ts

@@ -10,6 +10,7 @@ type SandboxTool = {
   containerMount: string;
   versionCmd: string;
   setupHint: string;
+  invoke?: string;
   envVars?: Record<string, string>;
   hostPreSeedFiles?: Array<{ hostPath: string; sandboxName: string }>;
   hostPreSeedDirs?: Array<{ hostDir: string; sandboxSubdir: string }>;

package/lib/sandbox/tools.ts

@@ -231,6 +231,7 @@ export function parseCustomTool(
   if (!containerMount.startsWith('/')) {
     throw new Error(`${context}: field "containerMount" must be an absolute path`);
   }
+  const invoke = asOptionalNonEmptyString(entry.invoke, 'invoke', context);
 
   const tool: SandboxTool = {
     id,
@@ -241,6 +242,7 @@ export function parseCustomTool(
     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/lib/task/finalization.ts

@@ -795,9 +795,12 @@ function terminalResult(
   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,
@@ -808,7 +811,7 @@ function terminalResult(
     completedSteps: completedSteps(receipt),
     pendingSteps: pending,
     result: hardError
-      ? (error?.retryable ? 'blocked' : 'failed')
+      ? (resultError?.retryable ? 'blocked' : 'failed')
       : postLifecyclePending
         ? 'completed_with_warnings'
         : pending.length === 0
@@ -817,7 +820,7 @@ function terminalResult(
             ? 'blocked'
             : 'failed',
     warnings,
-    error: hardError ? error : postLifecyclePending ? null : error
+    error: hardError ? resultError : postLifecyclePending ? null : resultError
   };
 }
 
@@ -850,7 +853,6 @@ async function prepareUnderLock(
   const commentSync = options.commentSync ?? syncPlatformComment;
   const issueSync = options.issueSync ?? syncPlatformIssue;
   const issueInspect = options.issueInspect ?? inspectPlatformIssue;
-  const verify = options.verify ?? verifyTaskEvent;
   const consumedCapabilities = new Set<string>();
   let receipt: TaskFinalizationReceipt;
   try {
@@ -922,6 +924,7 @@ async function prepareUnderLock(
       const badOperation = issueOperations?.find((operation) =>
         ['requirements', 'issue-type', 'fields', ...(base ? ['labels:in'] : [])].includes(operation.name)
         && 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 ?? {
@@ -1080,84 +1083,9 @@ async function prepareUnderLock(
     })
     : undefined;
 
-  let verification: TaskFinalizationStep | null = 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: FinalizationError = {
-        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: TaskFinalizationStep = 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 })
@@ -1208,7 +1136,7 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
   const resolved = resolveTaskRef(request.taskRef, { repoRoot });
   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);
@@ -1255,7 +1183,7 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
       if (!receipt) 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) {
@@ -1291,7 +1219,7 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
           }
         }
       }
-      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) });
@@ -1302,6 +1230,7 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
         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 },
@@ -1312,8 +1241,82 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
         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: TaskVerificationResult;
+      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: TaskFinalizationReceipt;
+        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: TaskFinalizationStep = { 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: TaskFinalizationReceipt;
+        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: TaskFinalizationReceipt;
+      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) {
     const detail = error instanceof TaskExecutionLockError

package/lib/task/verification.ts

@@ -13,7 +13,7 @@ type VerificationEvent =
   | 'review-analysis.completed' | 'plan.completed' | 'review-plan.completed'
   | 'code.completed' | 'review-code.completed' | 'manual-validation.completed' | 'validation-run.completed'
   | 'block-task.completed' | 'cancel-task.completed' | 'commit.completed'
-  | 'complete-task.preflight' | 'complete-task.hard-preflight' | 'complete-task.prepared' | 'complete-task.completed'
+  | 'complete-task.preflight' | 'complete-task.hard-preflight' | 'complete-task.completed'
   | 'create-pr.completed' | 'create-task.completed'
   | 'import-codescan.completed' | 'import-dependabot.completed'
   | 'import-issue.completed' | 'watch-pr.completed'
@@ -68,7 +68,6 @@ const VERIFICATION_CATALOG: Readonly<Record<VerificationEvent, VerificationSpec>
   '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/lib/update.ts

@@ -27,7 +27,6 @@ type UpdateConfig = {
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
   agentClients?: unknown;
-  customTUIs?: unknown;
 };
 
 type Defaults = {
@@ -189,8 +188,8 @@ async function cmdSync(): Promise<void> {
   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 {
     console.log('  Next step: run the full update in your AI TUI:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.8",
+  "version": "0.11.9",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",