lynkr 9.4.6 → 9.6.0

package/src/orchestrator/index.js

@@ -18,6 +18,7 @@ const { createAuditLogger } = require("../logger/audit-logger");
 const { getResolvedIp, runWithDnsContext } = require("../clients/dns-logger");
 const { getShuttingDown } = require("../api/health");
 const { tryPreflight, buildSatisfiedResponse: buildPreflightResponse } = require("./preflight");
+const { detectBypass, buildBypassResponse } = require("./bypass");
 const crypto = require("crypto");
 const { asyncClone, asyncTransform, getPoolStats } = require("../workers/helpers");
 const { getSemanticCache, isSemanticCacheEnabled } = require("../cache/semantic");
@@ -1362,8 +1363,12 @@ function sanitizePayload(payload) {
     delete clean.tool_choice;
   }
 
-  // Smart tool selection (universal, applies to all providers)
-  if (config.smartToolSelection?.enabled && Array.isArray(clean.tools) && clean.tools.length > 0) {
+  // Smart tool selection (server mode only). In client/passthrough mode the
+  // client (e.g. Claude Code) owns tool execution, so stripping its tools would
+  // make the model emit calls for tools we removed — they then get dropped as
+  // "hallucinated" and the session makes no progress. Pass tools through intact.
+  const inClientMode = config.toolExecutionMode === "client" || config.toolExecutionMode === "passthrough";
+  if (!inClientMode && config.smartToolSelection?.enabled && Array.isArray(clean.tools) && clean.tools.length > 0) {
     const classification = classifyRequestType(clean);
     const selectedTools = selectToolsSmartly(clean.tools, classification, {
       provider: providerType,
@@ -1977,6 +1982,12 @@ IMPORTANT TOOL USAGE RULES:
     cleanPayload._tenantPolicy = options.tenantPolicy;
   }
 
+  // Thread session id for provider affinity — keeps a tool-bearing
+  // conversation on one provider so tool_call_id linkage doesn't break.
+  if (session?.id) {
+    cleanPayload._sessionId = session.id;
+  }
+
   // RTK-inspired tool result compression: compress large tool_results
   // before they reach the model (saves 60-90% on test/git/lint output)
   if (config.toolResultCompression?.enabled !== false) {
@@ -1985,6 +1996,18 @@ IMPORTANT TOOL USAGE RULES:
     compressToolResults(cleanPayload.messages, { tier });
   }
 
+  // MCP-aware tool dedup: drop built-in tools superseded by present MCP tools
+  // (e.g. WebSearch/WebFetch when Exa/Tavily MCP is available). Always on.
+  const { applyToolDedup } = require("../context/tool-dedup");
+  applyToolDedup(cleanPayload);
+
+  // Caveman terse-output injection (opt-in): nudge the model toward shorter
+  // responses to reduce output tokens.
+  if (config.caveman?.enabled === true) {
+    const { injectCaveman } = require("../context/caveman");
+    cleanPayload.system = injectCaveman(cleanPayload.system);
+  }
+
   if (agentTimer) agentTimer.mark("preInvokeModel");
   let databricksResponse;
   try {
@@ -3735,6 +3758,14 @@ async function processMessage({ payload, headers, session, cwd, options = {} })
     };
   }
 
+  // === REQUEST BYPASS ===
+  // Claude CLI housekeeping (Warmup pings, topic/title extraction) doesn't
+  // need a model call — return a canned response and skip the provider.
+  const bypass = detectBypass({ payload, headers });
+  if (bypass) {
+    return buildBypassResponse(bypass, requestedModel);
+  }
+
   // === PREFLIGHT CHECK ===
   // If the request supplied preflight_commands and they all pass in
   // the workspace, the work is already done — short-circuit with a

package/src/routing/index.js

@@ -138,7 +138,46 @@ function getBestLocalProvider() {
  * @param {Object} options - Routing options
  * @returns {Object} Routing decision with provider and metadata
  */
+const sessionAffinity = require('./session-affinity');
+
+/**
+ * Provider routing with session affinity.
+ *
+ * When a conversation already carries tool history, reuse the provider the
+ * session first routed to so tool-call IDs don't break across providers.
+ * Fresh turns route normally and refresh the session's pinned provider.
+ */
 async function determineProviderSmart(payload, options = {}) {
+  const sessionId = payload?._sessionId || null;
+
+  // Enforce affinity only for in-flight tool exchanges — the turns that 400
+  // if the provider changes. Fresh turns keep full per-turn tier routing.
+  if (sessionId && !options.forceProvider && sessionAffinity.payloadHasToolHistory(payload)) {
+    const pinned = sessionAffinity.getPinned(sessionId);
+    if (pinned) {
+      logger.debug({ sessionId, provider: pinned.provider, tier: pinned.tier },
+        '[Routing] Session affinity — reusing provider for tool-bearing turn');
+      return {
+        provider: pinned.provider,
+        model: pinned.model,
+        tier: pinned.tier,
+        method: 'session_affinity',
+        reason: 'tool_history_provider_pin',
+      };
+    }
+  }
+
+  const decision = await _determineProviderSmartInner(payload, options);
+
+  // Remember the chosen provider so later tool-bearing turns stay consistent.
+  if (sessionId && decision?.provider && !options.forceProvider) {
+    sessionAffinity.setPinned(sessionId, decision);
+  }
+
+  return decision;
+}
+
+async function _determineProviderSmartInner(payload, options = {}) {
   const primaryProvider = config.modelProvider?.type ?? 'databricks';
 
   // Risk analysis runs orthogonally to complexity. We compute it once
@@ -658,6 +697,14 @@ function getRoutingHeaders(decision) {
     headers['X-Lynkr-Cost-Optimized'] = 'true';
   }
 
+  // Tier-aware fallback surfacing (never silent).
+  if (decision.fallback) {
+    headers['X-Lynkr-Fallback'] = 'true';
+    if (decision.fromTier) headers['X-Lynkr-Fallback-From-Tier'] = decision.fromTier;
+    if (decision.servedTier) headers['X-Lynkr-Served-Tier'] = decision.servedTier;
+    if (decision.fallbackDirection) headers['X-Lynkr-Fallback-Direction'] = decision.fallbackDirection;
+  }
+
   if (decision.risk?.level) {
     headers['X-Lynkr-Risk'] = decision.risk.level;
     const hits = Array.from(new Set([

package/src/routing/model-registry.js

@@ -54,9 +54,41 @@ const DATABRICKS_FALLBACK = {
   'databricks-bge-large-en': { input: 0.02, output: 0, context: 512 },
 };
 
-// Default cost for unknown models
+// Default cost for unknown models. Returned with `unknown: true` so callers can
+// distinguish a real price from a fabricated guess.
 const DEFAULT_COST = { input: 1.0, output: 3.0, context: 128000 };
 
+// Curated name aliases (exact, one-directional). Maps a name a caller might use
+// to the canonical key likely present in the pricing data. Misses are harmless
+// (resolution simply continues down the ladder).
+const MODEL_ALIASES = {
+  'claude-sonnet-4-5': 'claude-sonnet-4-5-20250929',
+  'claude-opus-4-1': 'claude-opus-4-1-20250805',
+  'claude-3-5-sonnet': 'claude-3-5-sonnet-20241022',
+};
+
+/**
+ * Parse MODEL_PRICE_OVERRIDES env (JSON object of
+ * { "<model>": { "input": <usd/1M>, "output": <usd/1M>, "context"?: N } }).
+ * Lets operators pin correct prices for models the registry doesn't know.
+ */
+function _loadOverrides() {
+  const out = new Map();
+  const raw = process.env.MODEL_PRICE_OVERRIDES;
+  if (!raw) return out;
+  try {
+    const parsed = JSON.parse(raw);
+    for (const [name, info] of Object.entries(parsed)) {
+      if (info && typeof info.input === 'number' && typeof info.output === 'number') {
+        out.set(name.toLowerCase(), { context: 128000, ...info });
+      }
+    }
+  } catch (err) {
+    logger.warn({ err: err.message }, '[ModelRegistry] Failed to parse MODEL_PRICE_OVERRIDES');
+  }
+  return out;
+}
+
 class ModelRegistry {
   constructor() {
     this.litellmPrices = {};
@@ -64,6 +96,7 @@ class ModelRegistry {
     this.loaded = false;
     this.lastFetch = 0;
     this.modelIndex = new Map();
+    this.overrides = _loadOverrides();
   }
 
   /**
@@ -255,40 +288,70 @@ class ModelRegistry {
    * @returns {Object} Cost info { input, output, context, ... }
    */
   getCost(modelName) {
-    if (!modelName) return { ...DEFAULT_COST, source: 'default' };
+    if (!modelName) return { ...DEFAULT_COST, source: 'default', unknown: true };
 
-    const normalizedName = modelName.toLowerCase();
+    const name = String(modelName).toLowerCase().trim();
+    const hit = this._resolveCost(name);
+    if (hit) return hit;
 
-    // Direct lookup
-    if (this.modelIndex.has(normalizedName)) {
-      return this.modelIndex.get(normalizedName);
-    }
+    // Nothing matched — report unknown rather than silently fabricating a price.
+    logger.debug({ model: modelName }, '[ModelRegistry] Model not found — cost unknown');
+    return { ...DEFAULT_COST, source: 'default', unknown: true };
+  }
 
-    // Try common variations
-    const variations = [
-      normalizedName,
-      normalizedName.replace('databricks-', ''),
-      normalizedName.replace('azure/', ''),
-      normalizedName.replace('bedrock/', ''),
-      normalizedName.replace('anthropic.', ''),
-      normalizedName.split('/').pop(),
-    ];
-
-    for (const variant of variations) {
-      if (this.modelIndex.has(variant)) {
-        return this.modelIndex.get(variant);
-      }
+  /**
+   * Deterministic price resolution. Each step is exact (no bidirectional
+   * substring matching), and the only loose step (longest-prefix) is
+   * one-directional and length-bounded, so unrelated names can't false-match.
+   * Returns a cost object with a `resolution` tag, or null if nothing matched.
+   * @param {string} name - already lowercased/trimmed
+   */
+  _resolveCost(name) {
+    const tag = (value, resolution, matchedAs) => ({
+      ...value,
+      resolution,
+      ...(matchedAs && matchedAs !== name ? { matchedAs } : {}),
+    });
+
+    // 1. Operator overrides (exact) — ground truth.
+    if (this.overrides.has(name)) return tag({ ...this.overrides.get(name), source: 'override' }, 'override');
+
+    // 2. Exact registry hit.
+    if (this.modelIndex.has(name)) return tag(this.modelIndex.get(name), 'exact');
+
+    // 3. Provider-prefix strip (exact).
+    const stripped = [
+      name.replace(/^databricks-/, ''),
+      name.replace(/^azure\//, ''),
+      name.replace(/^bedrock\//, ''),
+      name.replace(/^anthropic\./, ''),
+      name.replace(/^openai\//, ''),
+      name.includes('/') ? name.split('/').pop() : null,
+    ].filter((v) => v && v !== name);
+    for (const v of stripped) {
+      if (this.overrides.has(v)) return tag({ ...this.overrides.get(v), source: 'override' }, 'prefix-strip', v);
+      if (this.modelIndex.has(v)) return tag(this.modelIndex.get(v), 'prefix-strip', v);
     }
 
-    // Fuzzy match for partial names
+    // 4. Curated alias (exact).
+    const alias = MODEL_ALIASES[name];
+    if (alias && this.modelIndex.has(alias)) return tag(this.modelIndex.get(alias), 'alias', alias);
+
+    // 5. Date/version-suffix normalization (e.g. -20250929, -2025-09-29, -v2).
+    const dateless = name.replace(/[-@](\d{8}|\d{4}-\d{2}-\d{2}|v\d+)$/, '');
+    if (dateless !== name && this.modelIndex.has(dateless)) return tag(this.modelIndex.get(dateless), 'date-normalize', dateless);
+
+    // 6. Longest registry key that is a prefix of the requested name. Bounded so
+    //    short keys can't grab unrelated names (e.g. "gpt-5.2-chat-2026" → "gpt-5.2-chat").
+    let best = null;
     for (const [key, value] of this.modelIndex.entries()) {
-      if (key.includes(normalizedName) || normalizedName.includes(key)) {
-        return value;
+      if (key.length >= 6 && name.startsWith(key) && (!best || key.length > best.key.length)) {
+        best = { key, value };
       }
     }
+    if (best) return tag(best.value, 'longest-prefix', best.key);
 
-    logger.debug({ model: modelName }, '[ModelRegistry] Model not found, using default');
-    return { ...DEFAULT_COST, source: 'default' };
+    return null;
   }
 
   /**

package/src/routing/risk-analyzer.js

@@ -13,13 +13,18 @@ const { extractContent } = require('./complexity-analyzer');
 // Substring keywords found in file paths or instruction text.
 // Matched case-insensitively as raw substrings, so "auth" hits
 // "src/auth/login.ts" and "authentication".
+// NOTE: keywords are matched as case-insensitive *substrings* against file
+// paths, so overly generic terms cause false positives. 'session' and 'token'
+// were removed because they match benign paths (src/sessions/*, tokenizer.js,
+// token-budget.js) and were force-escalating ordinary requests to COMPLEX —
+// real secrets/credentials are still covered by the keywords below.
 const PROTECTED_PATH_KEYWORDS = [
-  'auth', 'oauth', 'jwt', 'session', 'security', 'permission', 'rbac',
+  'auth', 'oauth', 'jwt', 'security', 'permission', 'rbac',
   'payment', 'payments', 'billing', 'invoice', 'subscription',
   'migration', 'migrations', 'schema',
   'infra', 'terraform', 'kustomize', 'helm', 'kubernetes',
   '.github/workflows', '.env', 'secret', 'credential',
-  'api-key', 'api_key', 'apikey', 'token',
+  'api-key', 'api_key', 'apikey',
   'webhook', 'admin',
 ];
 

package/src/routing/session-affinity.js

@@ -0,0 +1,96 @@
+/**
+ * Session → Provider Affinity
+ *
+ * A multi-turn agentic conversation builds up tool_use / tool_result history
+ * whose tool-call IDs are formatted for the provider that produced them. If a
+ * later turn re-routes to a *different* provider (because per-turn complexity
+ * or risk changed), that provider rejects the orphaned tool linkage:
+ *
+ *   Azure: 400 "No tool call found for function call output with call_id …"
+ *   Moonshot: 400 "Invalid request: tool_call_id is not found"
+ *
+ * To prevent that, once a session has chosen a provider we keep subsequent
+ * turns on it *while the payload carries tool history*. Fresh turns (no tool
+ * state) still route normally, so per-turn tier routing is preserved.
+ *
+ * @module routing/session-affinity
+ */
+
+const MAX_ENTRIES = 2000;
+const TTL_MS = 60 * 60 * 1000; // 1 hour
+
+/** @type {Map<string, {provider:string, model:string|null, tier:string|null, ts:number}>} */
+const pins = new Map();
+
+function _evictIfNeeded() {
+  if (pins.size <= MAX_ENTRIES) return;
+  // Map preserves insertion order — drop the oldest.
+  const oldest = pins.keys().next().value;
+  if (oldest !== undefined) pins.delete(oldest);
+}
+
+/**
+ * True when the payload contains an in-flight tool exchange — i.e. a prior
+ * assistant tool_use or a user tool_result. These are the turns whose
+ * tool-call IDs break if the provider changes.
+ * @param {object} payload
+ * @returns {boolean}
+ */
+function payloadHasToolHistory(payload) {
+  const messages = payload?.messages;
+  if (!Array.isArray(messages)) return false;
+  for (const msg of messages) {
+    const content = msg?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      const t = block?.type;
+      if (t === "tool_use" || t === "tool_result") return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Return the pinned routing decision for a session, or null if none / expired.
+ * @param {string} sessionId
+ */
+function getPinned(sessionId) {
+  if (!sessionId) return null;
+  const entry = pins.get(sessionId);
+  if (!entry) return null;
+  if (Date.now() - entry.ts > TTL_MS) {
+    pins.delete(sessionId);
+    return null;
+  }
+  return entry;
+}
+
+/**
+ * Record the provider a session routed to, for reuse on later tool-bearing turns.
+ * @param {string} sessionId
+ * @param {{provider:string, model?:string|null, tier?:string|null}} decision
+ */
+function setPinned(sessionId, decision) {
+  if (!sessionId || !decision?.provider) return;
+  // Refresh insertion order so active sessions aren't evicted.
+  pins.delete(sessionId);
+  pins.set(sessionId, {
+    provider: decision.provider,
+    model: decision.model ?? null,
+    tier: decision.tier ?? null,
+    ts: Date.now(),
+  });
+  _evictIfNeeded();
+}
+
+/** Test/maintenance helper. */
+function _clear() {
+  pins.clear();
+}
+
+module.exports = {
+  payloadHasToolHistory,
+  getPinned,
+  setPinned,
+  _clear,
+};

package/src/routing/telemetry.js

@@ -94,7 +94,9 @@ function init() {
         circuit_breaker_state TEXT,
         quality_score   REAL,
         tokens_per_second REAL,
-        cost_efficiency REAL
+        cost_efficiency REAL,
+        request_text    TEXT,
+        response_text   TEXT
       );
 
       CREATE INDEX IF NOT EXISTS idx_telemetry_provider
@@ -110,6 +112,15 @@ function init() {
         ON routing_telemetry(session_id, timestamp);
     `);
 
+    // Migration: add columns to pre-existing tables (CREATE TABLE IF NOT EXISTS
+    // won't add them to a DB created before these columns existed).
+    const existingCols = new Set(db.prepare("PRAGMA table_info(routing_telemetry)").all().map((c) => c.name));
+    for (const col of ["request_text", "response_text"]) {
+      if (!existingCols.has(col)) {
+        db.exec(`ALTER TABLE routing_telemetry ADD COLUMN ${col} TEXT`);
+      }
+    }
+
     logger.info({ dbPath }, "Routing telemetry database initialised");
     return true;
   } catch (err) {
@@ -163,14 +174,14 @@ function record(data) {
           provider, model, routing_method, was_fallback, output_tokens,
           latency_ms, status_code, error_type, cost_usd, tool_calls_made,
           retry_count, circuit_breaker_state, quality_score, tokens_per_second,
-          cost_efficiency
+          cost_efficiency, request_text, response_text
         ) VALUES (
           @request_id, @session_id, @timestamp, @complexity_score, @tier,
           @agentic_type, @tool_count, @input_tokens, @message_count, @request_type,
           @provider, @model, @routing_method, @was_fallback, @output_tokens,
           @latency_ms, @status_code, @error_type, @cost_usd, @tool_calls_made,
           @retry_count, @circuit_breaker_state, @quality_score, @tokens_per_second,
-          @cost_efficiency
+          @cost_efficiency, @request_text, @response_text
         )`
       );
       if (!insert) return;
@@ -201,6 +212,8 @@ function record(data) {
         quality_score: data.quality_score ?? null,
         tokens_per_second: data.tokens_per_second ?? null,
         cost_efficiency: data.cost_efficiency ?? null,
+        request_text: data.request_text ?? null,
+        response_text: data.response_text ?? null,
       });
     } catch (err) {
       logger.debug({ err: err.message }, "Telemetry record failed");

package/src/routing/tier-fallback.js

@@ -0,0 +1,91 @@
+/**
+ * Tier-aware fallback chain (escalate-then-demote).
+ *
+ * When a tier's provider fails, prefer a MORE capable tier first (climb toward
+ * REASONING), and only if every higher tier is also unavailable do we fall
+ * downward — all the way to the local SIMPLE tier as a last resort. This biases
+ * for correctness/availability over cost, matching a conservative routing policy.
+ *
+ * Example ladder: SIMPLE → MEDIUM → COMPLEX → REASONING
+ *   - COMPLEX fails  → [REASONING, MEDIUM, SIMPLE]
+ *   - REASONING fails → [COMPLEX, MEDIUM, SIMPLE]
+ *   - MEDIUM fails    → [COMPLEX, REASONING, SIMPLE]
+ *
+ * Pure and dependency-injectable so it can be unit-tested without real providers.
+ */
+
+const logger = require("../logger");
+
+const TIER_ORDER = ["SIMPLE", "MEDIUM", "COMPLEX", "REASONING"];
+
+/** Default availability check: a provider is unavailable if its circuit is OPEN. */
+function defaultIsProviderAvailable(provider) {
+  try {
+    const { getCircuitBreakerRegistry } = require("../clients/circuit-breaker");
+    const registry = getCircuitBreakerRegistry();
+    const all = typeof registry.getAll === "function" ? registry.getAll() : [];
+    const entry = Array.isArray(all) ? all.find((b) => b.name === provider) : null;
+    return !(entry && entry.state === "OPEN");
+  } catch {
+    return true; // fail open — never block fallback on a health-check error
+  }
+}
+
+/** Resolve a tier name to { tier, provider, model }, or null if not configured. */
+function resolveTier(tier, selector) {
+  try {
+    const sel = selector || require("./model-tiers").getModelTierSelector();
+    const r = sel.selectModel(tier);
+    if (!r || !r.provider || !r.model) return null;
+    return { tier, provider: r.provider, model: r.model };
+  } catch {
+    return null; // tier not configured (TIER_<X> unset) — skip it
+  }
+}
+
+/**
+ * Build the escalate-then-demote fallback chain for a failed tier.
+ *
+ * @param {string} currentTier - the tier whose provider just failed
+ * @param {Object} [opts]
+ * @param {Object} [opts.selector] - model-tiers selector (injected for tests)
+ * @param {Function} [opts.isProviderAvailable] - (provider) => boolean (injected for tests)
+ * @returns {Array<{tier,provider,model,demotedFrom,direction}>} ordered candidates
+ */
+function getFallbackChain(currentTier, opts = {}) {
+  const isAvailable = opts.isProviderAvailable || defaultIsProviderAvailable;
+  const idx = TIER_ORDER.indexOf(currentTier);
+  if (idx === -1) return [];
+
+  const higher = TIER_ORDER.slice(idx + 1); // ascending toward REASONING
+  const lower = TIER_ORDER.slice(0, idx).reverse(); // descending toward SIMPLE
+  const ordered = [...higher, ...lower];
+
+  const seen = new Set();
+  // Never re-attempt the exact provider:model that just failed.
+  const current = resolveTier(currentTier, opts.selector);
+  if (current) seen.add(`${current.provider}:${current.model}`);
+
+  const chain = [];
+  for (const tier of ordered) {
+    const resolved = resolveTier(tier, opts.selector);
+    if (!resolved) continue;
+    const key = `${resolved.provider}:${resolved.model}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (!isAvailable(resolved.provider)) continue;
+    chain.push({
+      ...resolved,
+      demotedFrom: currentTier,
+      direction: TIER_ORDER.indexOf(tier) > idx ? "up" : "down",
+    });
+  }
+
+  logger.debug(
+    { currentTier, chain: chain.map((c) => `${c.tier}:${c.provider}`) },
+    "[TierFallback] Built fallback chain"
+  );
+  return chain;
+}
+
+module.exports = { getFallbackChain, resolveTier, TIER_ORDER };

package/src/server.js

@@ -29,6 +29,7 @@ const { registerTaskTools } = require("./tools/tasks");
 const { registerTestTools } = require("./tools/tests");
 const { registerMcpTools } = require("./tools/mcp");
 const { registerAgentTaskTool } = require("./tools/agent-task");
+const { registerDecomposeTool } = require("./tools/decompose");
 const { initConfigWatcher, getConfigWatcher } = require("./config/watcher");
 const { initializeHeadroom, shutdownHeadroom, getHeadroomManager } = require("./headroom");
 const { getWorkerPool, isWorkerPoolReady } = require("./workers/pool");
@@ -62,6 +63,7 @@ if (LAZY_TOOLS_ENABLED) {
   registerTestTools();
   registerMcpTools();
   registerAgentTaskTool();
+  registerDecomposeTool();
   logger.info({ mode: "eager" }, "All tools loaded at startup");
 }
 

package/src/tools/decompose.js

@@ -0,0 +1,91 @@
+const { registerTool } = require(".");
+const { runDecomposedTask } = require("../agents/decomposition");
+const logger = require("../logger");
+
+/**
+ * DecomposeTask tool — breaks a complex task into focused subtasks with isolated
+ * context, runs them (parallel where independent), and synthesizes the result.
+ *
+ * Opt-in: requires TASK_DECOMPOSITION_ENABLED=true and AGENTS_ENABLED=true.
+ * Degrades gracefully — if the gate decides decomposition isn't worth it (or
+ * planning fails), it returns ok:true with decomposed:false and a reason so the
+ * caller can solve the task monolithically.
+ */
+function registerDecomposeTool() {
+  registerTool(
+    "DecomposeTask",
+    async ({ args = {} }, context = {}) => {
+      const task = args.task || args.prompt || args.description;
+
+      if (!task || typeof task !== "string") {
+        return {
+          ok: false,
+          status: 400,
+          content: JSON.stringify({ error: "task is required" }, null, 2),
+        };
+      }
+
+      logger.info(
+        { task: task.slice(0, 100), sessionId: context.sessionId },
+        "DecomposeTask: evaluating task for decomposition"
+      );
+
+      try {
+        const result = await runDecomposedTask(task, {
+          sessionId: context.sessionId,
+          cwd: context.cwd,
+          riskLevel: args.riskLevel || context.riskLevel,
+        });
+
+        if (result.decomposed) {
+          return {
+            ok: true,
+            status: 200,
+            content: result.result,
+            metadata: {
+              decomposed: true,
+              subtasks: result.plan?.subtasks?.length,
+              levels: result.stats?.levels,
+              strategy: result.plan?.strategy,
+              confidence: result.quality?.confidence,
+              recommendFallback: result.recommendFallback,
+              savedTokens: result.savings?.savedTokens,
+            },
+          };
+        }
+
+        // Not decomposed — signal the caller to solve monolithically.
+        return {
+          ok: true,
+          status: 200,
+          content: JSON.stringify(
+            {
+              decomposed: false,
+              reason: result.reason,
+              guidance: "Solve this task directly without decomposition.",
+            },
+            null,
+            2
+          ),
+          metadata: { decomposed: false, reason: result.reason },
+        };
+      } catch (error) {
+        logger.error({ error: error.message }, "DecomposeTask: error");
+        return {
+          ok: false,
+          status: 500,
+          content: JSON.stringify(
+            { error: "Decomposition error", message: error.message },
+            null,
+            2
+          ),
+        };
+      }
+    },
+    { category: "decompose" }
+  );
+
+  logger.info("DecomposeTask tool registered");
+}
+
+module.exports = { registerDecomposeTool };

package/src/tools/lazy-loader.js

@@ -77,6 +77,11 @@ const TOOL_CATEGORIES = {
     loader: () => require('./agent-task').registerAgentTaskTool,
     priority: 2,
   },
+  decompose: {
+    keywords: ['decompose', 'subtask', 'break down', 'break into', 'split task', 'plan and execute'],
+    loader: () => require('./decompose').registerDecomposeTool,
+    priority: 2,
+  },
   'code-mode': {
     keywords: ['mcp', 'execute', 'server', 'tool', 'code mode'],
     loader: () => require('./code-mode').registerCodeModeTools,
@@ -296,6 +301,9 @@ function loadCategoryForTool(toolName) {
     // TinyFish (web agent)
     'web_agent': 'tinyfish',
     'agent_task': 'agentTask',
+
+    // Task decomposition
+    'decomposetask': 'decompose',
   };
 
   // Direct mapping