How ClawTalk's Model Escalation Logic Determines When to Switch Between Different LLMs

ClawTalk's model escalation logic uses a confidence-based decision pipeline in src/agents/clawtalk/escalation.ts to determine whether to route prompts to a locally-configured model or escalate to a more powerful cloud-based LLM based on intent classification, confidence scores, and input complexity.

The closedclaw repository implements an intelligent routing system called ClawTalk that dynamically switches between language models based on prompt characteristics. Understanding how this model escalation logic works is crucial for optimizing performance and cost when deploying multi-tier LLM architectures.

Understanding the Core Escalation Algorithm

The escalation engine evaluates every user prompt through a multi-step decision pipeline defined in src/agents/clawtalk/escalation.ts. Each step checks specific conditions to determine if the current local model can handle the request or if it requires escalation to a more capable cloud model.

The Decision Pipeline Steps

The algorithm processes conditions in the following priority order:

1. Configuration Check: If config.escalationModel is not configured (falsy), escalation is disabled entirely (lines 50-57).

2. Simple Intent Fast Path: If the intent is classified as SIMPLE_INTENTS and confidence exceeds 0.4, the system retains the local model, assuming tool usage will handle complexity (lines 59-66).

3. Very Low Confidence: If confidence falls below threshold × 0.6, the system escalates immediately due to uncertainty (lines 68-76).

4. Complex Intent Threshold: For intents in COMPLEX_INTENTS, if confidence is below the configured threshold, escalation occurs (lines 78-86).

5. Long Input Handling: For inputs exceeding 500 characters with confidence below threshold × 1.2, the system escalates to ensure adequate reasoning capacity (lines 88-96).

6. General Threshold: If confidence is below the base threshold, escalation triggers (lines 98-106).

7. Default Case: If none of the above conditions match, the local model handles the request (lines 108-112).

Configuration and Thresholds

The escalation behavior is controlled through the ClawTalkConfig interface defined in src/agents/clawtalk/types.ts (lines 107-110). Two critical parameters govern the logic:

• escalationThreshold: A decimal value (default 0.5) representing the minimum confidence required to avoid escalation for most intents.
• escalationModel: The identifier for the cloud-based LLM to use when escalation triggers (e.g., "gpt-4o-mini").

Implementation Details

The shouldEscalate Function

The core logic resides in the shouldEscalate function within src/agents/clawtalk/escalation.ts. This function accepts a classification result (confidence score and intent category) along with the input length and configuration, returning an EscalationDecision object.

The decision object includes:

• escalate: Boolean indicating whether to switch models
• targetModel: The specific model to use if escalating
• reason: Human-readable explanation for the decision

Model Override in the Hook

The actual model switching occurs in src/agents/clawtalk/clawtalk-hook.ts (lines 46-48). The hook consumes the escalation decision and injects a modelOverride into the agent start flow:

const escalationDecision = shouldEscalate({ … });
…
modelOverride: escalationDecision.escalate
    ? (escalationDecision.targetModel ?? activeConfig.escalationModel)
    : undefined,

When modelOverride is defined, the system routes the request to the specified cloud model rather than the default local model.

Practical Example

The following example demonstrates how to use the escalation logic directly:

import { shouldEscalate } from "./escalation.js";
import { DEFAULT_CONFIG } from "./types.js";

const cfg = {
  ...DEFAULT_CONFIG,
  escalationModel: "gpt-4o-mini",   // cloud model
  escalationThreshold: 0.5,
};

const decision = shouldEscalate({
  confidence: 0.32,
  intent: "code_generate",
  inputLength: 120,
  config: cfg,
});

if (decision.escalate) {
  console.log(
    `Escalating to ${decision.targetModel} because: ${decision.reason}`
  );
}

Output:

Escalating to gpt-4o-mini because: Very low confidence (32% < 30%)

This mirrors the runtime behavior when processing user prompts, ensuring low-confidence requests automatically route to more capable models.

Summary

• ClawTalk's model escalation logic evaluates every prompt through a 7-step decision pipeline in src/agents/clawtalk/escalation.ts.
• The system uses confidence scores, intent classification, and input length to determine whether to retain the local model or escalate to a cloud-based LLM.
• Configuration parameters escalationThreshold (default 0.5) and escalationModel control the sensitivity and target of escalations.
• The actual model switch occurs in src/agents/clawtalk/clawtalk-hook.ts through the modelOverride mechanism.

Frequently Asked Questions

What triggers model escalation in ClawTalk?

Model escalation triggers when the shouldEscalate function detects conditions such as very low confidence (below 60% of the threshold), complex intents with insufficient confidence, long inputs over 500 characters, or general confidence below the configured threshold. These checks prioritize accuracy over latency for challenging requests.

How do I configure the escalation threshold?

Set the escalationThreshold field in your ClawTalkConfig (defined in src/agents/clawtalk/types.ts). The default value is 0.5, meaning any confidence score below 50% typically triggers escalation unless other conditions override it. Lower values make the system more tolerant of uncertainty, while higher values increase escalation frequency.

Can I disable model escalation entirely?

Yes. If the escalationModel configuration field is falsy or undefined, the escalation logic returns early and never switches models (see lines 50-57 in src/agents/clawtalk/escalation.ts). This effectively forces all requests to use the local model regardless of confidence scores or intent complexity.

Which file handles the actual model switching?

The actual model switching is implemented in src/agents/clawtalk/clawtalk-hook.ts. This file consumes the EscalationDecision from shouldEscalate and assigns the modelOverride field (lines 46-48), which instructs the agent runtime to route the request to the specified cloud model instead of the default local model.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}