start_handoff
Destructive
Begin a sequential delegation handoff from an intent plan that has been approved for delegation. This passes control to the next delegate in the chain to continue execution.
Instructions
Start a sequential delegation handoff from a delegation-eligible intent plan
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| intentId | Yes | ||
| context | No | ||
| mcpProfile | No | ||
| bundleId | No | ||
| partnerProfile | No | ||
| approved | No | ||
| repoPath | No | ||
| delegateProfile | No | ||
| plannedChecks | No |
Implementation Reference
- scripts/delegation-runtime.js:526-631 (handler)The startHandoff function implements the core tool logic: evaluates delegation eligibility, validates MCP profile constraints (dispatch/locked), checks delegate profile consistency, scores reliability, persists a 'started' event, and returns the handoffId, taskKey, status, delegateProfile, and handoffContract.
function startHandoff(params = {}) { const evaluation = evaluateDelegation({ delegationMode: 'sequential', plan: params.plan, mcpProfile: params.mcpProfile, context: params.context, repoPath: params.repoPath, plannedChecks: params.plannedChecks, }); if (String(params.mcpProfile || '').trim() === 'dispatch') { persistRejectedStart({ taskKey: evaluation.taskKey, intentId: params.plan && params.plan.intent ? params.plan.intent.id : null, delegateProfile: null, mcpProfile: params.mcpProfile, partnerProfile: params.partnerProfile, reasonCode: 'dispatch_profile', reason: 'Dispatch MCP profile may not start handoffs.', context: params.context, repoPath: params.repoPath, }); throw createDelegationError('Dispatch MCP profile may not start handoffs.', 403); } if (String(params.mcpProfile || '').trim() === 'locked') { persistRejectedStart({ taskKey: evaluation.taskKey, intentId: params.plan && params.plan.intent ? params.plan.intent.id : null, delegateProfile: null, mcpProfile: params.mcpProfile, partnerProfile: params.partnerProfile, reasonCode: 'locked_profile', reason: 'Locked MCP profile may not start handoffs.', context: params.context, repoPath: params.repoPath, }); throw createDelegationError('Locked MCP profile may not start handoffs.', 403); } if (!evaluation.delegationEligible || evaluation.executionMode !== 'sequential_delegate') { persistRejectedStart({ taskKey: evaluation.taskKey, intentId: params.plan && params.plan.intent ? params.plan.intent.id : null, delegateProfile: evaluation.delegateProfile, mcpProfile: params.mcpProfile, partnerProfile: params.partnerProfile, reasonCode: evaluation.reasonCode, reason: evaluation.delegationReason, context: params.context, repoPath: params.repoPath, }); throw createDelegationError(evaluation.delegationReason, evaluation.reasonCode === 'unresolved_handoff_exists' ? 409 : 422, { reasonCode: evaluation.reasonCode, }); } if (params.delegateProfile && params.delegateProfile !== evaluation.delegateProfile) { persistRejectedStart({ taskKey: evaluation.taskKey, intentId: params.plan && params.plan.intent ? params.plan.intent.id : null, delegateProfile: params.delegateProfile, mcpProfile: params.mcpProfile, partnerProfile: params.partnerProfile, reasonCode: 'delegate_profile_mismatch', reason: 'Requested delegateProfile does not match the planner-selected profile.', context: params.context, repoPath: params.repoPath, }); throw createDelegationError('Requested delegateProfile does not match the planner-selected profile.', 400); } const { DELEGATION_LOG_PATH } = getDelegationPaths(); const handoffId = `handoff_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`; const event = { eventType: 'started', handoffId, taskKey: evaluation.taskKey, intentId: params.plan.intent.id, delegateProfile: evaluation.delegateProfile, mcpProfile: params.mcpProfile, partnerProfile: params.partnerProfile || null, context: normalizeText(params.context || params.plan.context || ''), repoPath: params.repoPath || null, plannedChecks: unique([ ...(Array.isArray(params.plannedChecks) ? params.plannedChecks : []), ...(evaluation.handoffContract && Array.isArray(evaluation.handoffContract.requiredChecks) ? evaluation.handoffContract.requiredChecks : []), ]), contract: evaluation.handoffContract, delegationScore: evaluation.delegationScore, timestamp: new Date().toISOString(), }; appendJSONL(DELEGATION_LOG_PATH, event); return { handoffId, taskKey: event.taskKey, status: 'started', executionMode: 'sequential_delegate', delegateProfile: event.delegateProfile, handoffContract: event.contract, }; } - adapters/mcp/server-stdio.js:679-702 (registration)MCP server handler for 'start_handoff': loads the intentRouter and delegationRuntime modules, plans the intent, then calls delegationRuntime.startHandoff() with plan, context, mcpProfile, partnerProfile, repoPath, delegateProfile, and plannedChecks.
case 'start_handoff': { const intentRouter = loadPrivateMcpModule('intentRouter'); const delegationRuntime = loadPrivateMcpModule('delegationRuntime'); if (!intentRouter || !delegationRuntime) return unavailablePrivateMcpFeature('start_handoff'); return toTextResult(delegationRuntime.startHandoff({ plan: intentRouter.planIntent({ intentId: args.intentId, context: args.context || '', mcpProfile: args.mcpProfile, bundleId: args.bundleId, partnerProfile: args.partnerProfile, delegationMode: 'sequential', approved: args.approved === true, repoPath: args.repoPath, }), context: args.context || '', mcpProfile: args.mcpProfile || getActiveMcpProfile(), partnerProfile: args.partnerProfile || null, repoPath: args.repoPath, delegateProfile: args.delegateProfile || null, plannedChecks: Array.isArray(args.plannedChecks) ? args.plannedChecks : [], })); } - evaluateDelegation function evaluates whether a handoff is eligible based on delegationMode, semantic phases, delegate profile compatibility, context budget, active handoffs, recent failures, and reliability score threshold (>=0.6). Returns delegationEligible, executionMode, delegateProfile, handoffContract, score, and reasonCode.
function evaluateDelegation(params = {}) { const delegationMode = normalizeDelegationMode(params.delegationMode); const plan = params.plan || {}; const mcpProfile = String(params.mcpProfile || plan.mcpProfile || 'default').trim(); const context = String(params.context || plan.context || ''); const repoPath = params.repoPath || null; const taskKey = buildTaskKey({ intentId: plan.intent && plan.intent.id, repoPath, context, }); const semanticPhases = deriveSemanticPhases(plan.actions); const hasEvidence = semanticPhases.some((phase) => phase.kind === 'evidence'); const hasMutation = semanticPhases.some((phase) => phase.kind === 'mutation'); const contextDigest = buildContextDigest(plan, context); const contextChars = contextDigest.length; const selection = selectDelegateProfile({ mcpProfile, plan, contextChars }); const { DELEGATION_MODEL_PATH } = getDelegationPaths(); const model = loadDelegationModel(DELEGATION_MODEL_PATH); const events = readDelegationEvents(); const activeHandoffs = deriveActiveHandoffs(events); const activeHandoff = activeHandoffs.byTaskKey.get(taskKey) || null; const reliabilityBias = selection.delegateProfile ? getReliabilityBias(model, [ 'delegation_global', `intent_${plan.intent && plan.intent.id}`, `profile_${selection.delegateProfile}`, ]) : 0; const recentFailure = selection.delegateProfile ? hasRecentSimilarFailure(events, plan.intent && plan.intent.id, selection.delegateProfile) : false; let score = 0; if (semanticPhases.length >= 2) score += 0.25; else score -= 0.30; if (hasEvidence && hasMutation) score += 0.15; if (selection.delegateProfile) score += 0.15; if (plan.codegraphImpact && plan.codegraphImpact.enabled && Array.isArray(plan.codegraphImpact.verificationHints) && plan.codegraphImpact.verificationHints.length > 0) { score += 0.10; } if (selection.contextFits) score += 0.10; else if (selection.delegateProfile) score -= 0.20; score += reliabilityBias; if (recentFailure) score -= 0.25; score = Number(Math.max(0, Math.min(1, score)).toFixed(3)); let reasonCode = 'delegation_disabled'; let delegationReason = 'Delegation is disabled for this plan.'; let delegationEligible = false; let executionMode = 'single_agent'; let delegateProfile = null; let handoffContract = null; if (delegationMode !== 'off') { if (plan.status !== 'ready') { reasonCode = 'checkpoint_required'; delegationReason = 'Delegation is blocked until the required approval checkpoint is cleared.'; } else if (mcpProfile === 'dispatch') { reasonCode = 'dispatch_profile'; delegationReason = 'Dispatch MCP profile may inspect plans and metrics, but remote handoffs stay disabled.'; } else if (mcpProfile === 'locked') { reasonCode = 'locked_profile'; delegationReason = 'Locked MCP profile may inspect the plan but cannot start a handoff.'; } else if (semanticPhases.length < 2) { reasonCode = 'single_phase_task'; delegationReason = 'Delegation was skipped because the task collapses into a single semantic phase.'; } else if ((plan.actions || []).length < 3) { reasonCode = 'insufficient_actions'; delegationReason = 'Delegation was skipped because the task does not have enough action surface to justify a handoff.'; } else if (!selection.delegateProfile) { reasonCode = 'no_compatible_delegate'; delegationReason = 'Delegation was skipped because no existing delegate profile can execute the required actions within policy.'; } else if (!selection.contextFits) { reasonCode = 'budget_exceeded'; delegationReason = 'Delegation was skipped because the context exceeds the selected delegate profile budget.'; } else if (activeHandoff) { reasonCode = 'unresolved_handoff_exists'; delegationReason = 'Delegation is blocked because an unresolved handoff already exists for this task.'; } else if (recentFailure) { reasonCode = 'recent_failure'; delegationReason = 'Delegation confidence was reduced by a recent similar failure, so the planner kept the task single-agent.'; } else if (score < 0.6) { reasonCode = 'low_score'; delegationReason = 'Delegation was considered but the reliability score did not clear the handoff threshold.'; } else { reasonCode = 'delegation_selected'; delegationReason = 'Delegation cleared the structural, budget, and reliability checks.'; delegationEligible = true; executionMode = 'sequential_delegate'; delegateProfile = selection.delegateProfile; handoffContract = buildHandoffContract({ plan, delegateProfile, plannedChecks: params.plannedChecks, }); } } return { delegationMode, executionMode, delegationEligible, delegationScore: executionMode === 'sequential_delegate' ? score : 0, delegationReason, delegateProfile, handoffContract, reasonCode, rawDelegationScore: score, taskKey, activeHandoffId: activeHandoff ? activeHandoff.handoffId : null, semanticPhases, contextChars, }; } - buildHandoffContract is called within evaluateDelegation to construct the handoff contract including required checks.
plannedChecks: params.plannedChecks, }); } - adapters/mcp/server-stdio.js:161-173 (helper)PRIVATE_MCP_MODULES mapping that resolves 'delegationRuntime' to scripts/delegation-runtime.js, loaded dynamically in the start_handoff handler.
const PRIVATE_MCP_MODULES = Object.freeze({ intentRouter: path.resolve(__dirname, '../../scripts/intent-router.js'), delegationRuntime: path.resolve(__dirname, '../../scripts/delegation-runtime.js'), orgDashboard: path.resolve(__dirname, '../../scripts/org-dashboard.js'), reflectorAgent: path.resolve(__dirname, '../../scripts/reflector-agent.js'), swarmCoordinator: path.resolve(__dirname, '../../scripts/swarm-coordinator.js'), sessionReport: path.resolve(__dirname, '../../scripts/session-report.js'), operatorArtifacts: path.resolve(__dirname, '../../scripts/operator-artifacts.js'), managedLessonAgent: path.resolve(__dirname, '../../scripts/managed-lesson-agent.js'), semanticLayer: path.resolve(__dirname, '../../scripts/semantic-layer.js'), lessonInference: path.resolve(__dirname, '../../scripts/lesson-inference.js'), lessonSearch: path.resolve(__dirname, '../../scripts/lesson-search.js'), });