elenchus_escalate_tier

Instructions

Implementation Reference

• src/tools/pipeline-tools.ts:60-93 (handler)

  The handler function for the elenchus_escalate_tier tool. Gets pipeline state, calls escalateTier() from the pipeline module, and returns success/failure with previous and new tier information.

  export async function escalateTierTool(
    args: z.infer<typeof EscalateTierSchema>
  ): Promise<{
    success: boolean;
    previousTier?: VerificationTier;
    newTier?: VerificationTier;
    message: string;
  }> {
    const state = getPipelineState(args.sessionId);
    if (!state) {
      return {
        success: false,
        message: 'No pipeline found for this session'
      };
    }
  
    const previousTier = state.currentTier;
    const success = escalateTier(args.sessionId, args.targetTier, args.reason, args.scope);
  
    if (!success) {
      return {
        success: false,
        previousTier,
        message: `Cannot escalate from ${previousTier} to ${args.targetTier}`
      };
    }
  
    return {
      success: true,
      previousTier,
      newTier: args.targetTier,
      message: `Escalated from ${previousTier} to ${args.targetTier}: ${args.reason}`
    };
  }

• src/pipeline/index.ts:293-317 (helper)

  The core escalateTier() function that performs the actual state mutation: validates the target tier is higher than current, records the escalation, and updates currentTier.

  export function escalateTier(
    sessionId: string,
    targetTier: VerificationTier,
    reason: string,
    scope: string[] = []
  ): boolean {
    const state = pipelineStates.get(sessionId);
    if (!state) return false;
  
    // Using TIER_ORDER constant
    const currentIndex = TIER_ORDER.indexOf(state.currentTier);
    const targetIndex = TIER_ORDER.indexOf(targetTier);
  
    if (targetIndex <= currentIndex) return false;
  
    state.escalations.push({
      fromTier: state.currentTier,
      toTier: targetTier,
      reason,
      files: scope
    });
    state.currentTier = targetTier;
  
    return true;
  }

• src/tools/schemas.ts:269-274 (schema)

  Zod schema for elenchus_escalate_tier input validation: sessionId (string), targetTier (enum: 'focused' | 'exhaustive'), reason (string), and optional scope (array of strings).

  export const EscalateTierSchema = z.object({
    sessionId: z.string().describe('Session ID'),
    targetTier: EscalateTierEnum.describe('Target tier to escalate to: "focused" or "exhaustive"'),
    reason: z.string().describe('Reason for escalation'),
    scope: z.array(z.string()).optional().describe('Files to focus on (if any)')
  });

• src/tools/pipeline-tools.ts:149-165 (registration)

  Registration of elenchus_escalate_tier in the pipelineTools object with description, schema, and handler.

  export const pipelineTools = {
    elenchus_get_pipeline_status: {
      description: 'Get current tier pipeline status including completed tiers, escalations, and token usage.',
      schema: GetPipelineStatusSchema,
      handler: getPipelineStatusTool
    },
    elenchus_escalate_tier: {
      description: 'Manually escalate to a higher verification tier (screen → focused → exhaustive).',
      schema: EscalateTierSchema,
      handler: escalateTierTool
    },
    elenchus_complete_tier: {
      description: 'Mark the current tier as complete and check for auto-escalation based on issues found.',
      schema: CompleteTierSchema,
      handler: completeTierTool
    }
  };

• src/tools/index.ts:41-54 (registration)

  Tools composition: pipelineTools is spread into the master 'tools' object which is the final MCP tool registry.

  export const tools = {
    ...sessionLifecycleTools,
    ...issueManagementTools,
    ...mediatorTools,
    ...roleTools,
    ...reverifyTools,
    ...diffTools,
    ...cacheTools,
    ...pipelineTools,
    ...safeguardsTools,
    ...optimizationTools,
    ...dynamicRoleTools,
    ...llmEvalTools,
  };