@peopl-health/nexus 5.68.8 → 5.68.10

package/lib/clinical/config/cohortConfig.js

@@ -65,4 +65,4 @@ function clearCohortCache() {
   inFlightRead = null;
 }
 
-module.exports = { isInCohort, clearCohortCache };
+module.exports = { isInCohort, isCohortEnabled, clearCohortCache };

package/lib/clinical/context/ToolRuntimeContext.js

@@ -56,6 +56,7 @@ class ToolRuntimeContext {
     this.skillActivationIteration = new Map();
     this.currentIteration = null;
     this.toolHistory = [];
+    this.toolRejections = [];
     this.safetyArtifact = null;
     this.palliativeAssessment = null;
     this.careplan = null;
@@ -93,9 +94,11 @@ class ToolRuntimeContext {
     this.trace.addStep({ iteration, ...toolData });
     if (toolData.success) this.toolHistory.push(toolData);
     if (!toolData.success || isToolFailure(toolData.tool_output)) {
+      const code = refusalCode(toolData.tool_output);
+      this.toolRejections.push({ tool: toolData.tool_name, code, iteration: iteration ?? null });
       logger.warn('[toolRuntime] tool call rejected', {
         tool: toolData.tool_name,
-        reason: refusalCode(toolData.tool_output),
+        reason: code,
         iteration: iteration ?? null,
         turnId: this.turnId || null,
       });
@@ -108,7 +111,7 @@ class ToolRuntimeContext {
   }
 
   async store({ outbound = null, completed = false, predictionTimeMs = null, error = null } = {}) {
-    this.trace.setSignals({ activatedSkills: [...this.activatedSkills].sort() });
+    this.trace.setSignals({ activatedSkills: [...this.activatedSkills].sort(), toolRejections: [...this.toolRejections] });
     this.trace.setOutbound(outbound || this.trace.outbound || null);
     const hasError = error !== null && error !== undefined;
     const isSuperseded = hasError ? false : !this.isLive();

package/lib/clinical/flags/flagSnapshot.js

@@ -0,0 +1,59 @@
+const { isCohortEnabled } = require('../config/cohortConfig');
+const { isBridgeEnabled } = require('./bridgeConfig');
+const { contextReadLive, contextMirrorLive, contextVerifierLive } = require('./clinicalContextFlags');
+const { clinicalPatternFloorLive } = require('./clinicalPatternFloorFlags');
+const { isComposerEnabled, isAgentSelfRenderEnabled } = require('./composerFlags');
+const { isContingencyCancelOnReplyLive, isArmOnOpenCeilingLive, isContingencyRuleBlockLive } = require('./contingencyFlags');
+const { escalationAssessmentLive, escalationUpdateModeLive } = require('./escalationFlags');
+const { inboundRecoveryLive, coldInboundMode } = require('./inboundRecoveryFlags');
+const { isLlmAuditEnabled } = require('./llmAuditConfig');
+const { isLlmMonitorEnabled } = require('./llmMonitorConfig');
+const { patternConsultLive } = require('./patternConsultFlags');
+const { recommendationRetryLive } = require('./recommendationRecoveryFlags');
+const { isShadowEnabled } = require('./shadowConfig');
+const { supportLightFromChatLive } = require('./supportLightFlags');
+const { triageGateFloorLive } = require('./triageGateFloorFlags');
+const { triageRecommendationLive, rankComparatorLive } = require('./triageRecommendationFlags');
+const { isConversationalDeclarationLive, isConversationalDraftReuseLive, isDeclarationModelCheckLive } = require('./turnEfficiencyFlags');
+
+const FLAG_READERS = {
+  cohort: isCohortEnabled,
+  bridge: isBridgeEnabled,
+  contextRead: contextReadLive,
+  contextMirror: contextMirrorLive,
+  contextVerifier: contextVerifierLive,
+  clinicalPatternFloor: clinicalPatternFloorLive,
+  composer: isComposerEnabled,
+  agentSelfRender: isAgentSelfRenderEnabled,
+  contingencyCancelOnReply: isContingencyCancelOnReplyLive,
+  armOnOpenCeiling: isArmOnOpenCeilingLive,
+  contingencyRuleBlock: isContingencyRuleBlockLive,
+  escalationAssessment: escalationAssessmentLive,
+  escalationUpdateMode: escalationUpdateModeLive,
+  inboundRecovery: inboundRecoveryLive,
+  coldInboundMode,
+  llmAudit: isLlmAuditEnabled,
+  llmMonitor: isLlmMonitorEnabled,
+  patternConsult: patternConsultLive,
+  recommendationRetry: recommendationRetryLive,
+  shadow: isShadowEnabled,
+  supportLightFromChat: supportLightFromChatLive,
+  triageGateFloor: triageGateFloorLive,
+  triageRecommendation: triageRecommendationLive,
+  rankComparator: rankComparatorLive,
+  conversationalDeclaration: isConversationalDeclarationLive,
+  conversationalDraftReuse: isConversationalDraftReuseLive,
+  declarationModelCheck: isDeclarationModelCheckLive,
+};
+
+function snapshotClinicalFlags() {
+  return Object.fromEntries(Object.entries(FLAG_READERS).map(([name, read]) => {
+    try {
+      return [name, read()];
+    } catch (error) {
+      return [name, null];
+    }
+  }));
+}
+
+module.exports = { snapshotClinicalFlags };

package/lib/clinical/helpers/clinicalWorkflowGuard.js

@@ -60,7 +60,7 @@ function routingSkillStep(trace, { enabledSkills = [], skillActivationIteration
 
   return {
     instruction: activatedAt != null
-      ? `read the ${ROUTING_SKILL} body returned to you (it was requested in this same response, so its content did not reach you)`
+      ? `read the ${ROUTING_SKILL} body returned to you (it was returned in this same response, so its content did not reach you yet)`
       : `call Skill with skill="${ROUTING_SKILL}" and read what it returns`,
     toolIds: [SKILL_TOOL],
   };
@@ -154,7 +154,7 @@ function validateClinicalDelivery(trace, { enabledSkills = [], skillActivationIt
   return {
     error: REFUSAL.skillBeforeDelivery,
     recovery: activatedAt != null
-      ? `The ${downstream} body was requested in this same response, so its content did not reach you. Read it, then compose the patient message from the rules it defines.`
+      ? `The ${downstream} body was returned in this same response, so its content did not reach you yet. Read it, then compose the patient message from the rules it defines.`
       : `The plan you committed routes to ${downstream}. Call Skill with skill="${downstream}", read the body it returns, then compose the patient message from the rules it defines.`,
     requiredToolIds: [SKILL_TOOL],
   };
@@ -166,6 +166,7 @@ module.exports = {
   ROUTING_SKILL,
   SKILL_TOOL,
   clinicalIntakeRequiresRisk,
+  hasAlternateTerminalCommit,
   hasUsableRiskContext,
   isPurelyConversational,
   validateClinicalDelivery,

package/lib/clinical/helpers/skillActivationHelper.js

@@ -0,0 +1,53 @@
+const { loadSkillBody } = require('../services/skillService');
+const { logger } = require('../../utils/logger');
+
+const { SKILL_TOOL } = require('./clinicalWorkflowGuard');
+
+function markSkillActivated(runtime, name) {
+  runtime?.activatedSkills?.add(name);
+  if (runtime?.skillActivationIteration && !runtime.skillActivationIteration.has(name)) {
+    runtime.skillActivationIteration.set(name, runtime.currentIteration ?? null);
+  }
+}
+
+// Hands the model a skill the workflow guard is about to require, inside the result of the tool that made it
+// required, so the turn does not spend an iteration being refused and then asking for it. The guard stays the net.
+async function attachRequiredSkill(runtime, name) {
+  if (!runtime || !name) return null;
+  if (!(runtime.enabledSkills || []).includes(name)) return null;
+  if (!(runtime.trace?.signals?.offeredToolIds || []).includes(SKILL_TOOL)) return null;
+  if (runtime.activatedSkills?.has(name)) return null;
+
+  try {
+    const { skill } = await loadSkillBody(name);
+    if (!skill) return null;
+    markSkillActivated(runtime, skill.name);
+    runtime.trace?.setSignals?.({ attachedSkills: [...(runtime.trace.signals?.attachedSkills || []), skill.name] });
+    return { name: skill.name, version: skill.version, body: skill.body };
+  } catch (error) {
+    logger.warn('[skillActivation] required skill could not be attached; the guard will ask for it', {
+      skill: name, turnId: runtime.turnId || null, error: error?.message,
+    });
+    return null;
+  }
+}
+
+// A skill body governs only the turn it was handed over in. Outside that turn (history replay, monitor evidence)
+// the attachment is dropped, as for a Skill call, whose output is never replayed.
+function withoutAttachedSkillBodies(output) {
+  let parsed = output;
+  if (typeof output === 'string') {
+    try { parsed = JSON.parse(output); } catch (error) { return output; }
+  }
+  const skills = parsed?.data?.activated_skills;
+  if (!Array.isArray(skills)) return output;
+  const { activated_skills: _attached, ...data } = parsed.data;
+  const stripped = { ...parsed, data };
+  return typeof output === 'string' ? JSON.stringify(stripped) : stripped;
+}
+
+module.exports = {
+  attachRequiredSkill,
+  markSkillActivated,
+  withoutAttachedSkillBodies,
+};

package/lib/clinical/monitoring/contingencyMonitorSpec.js

@@ -1,5 +1,6 @@
 const { patientMessageFromTrace } = require('../helpers/evidenceAnchorHelper');
 const { parseGradeEstimate, projectGradeEstimate } = require('../helpers/gradeEstimateHelper');
+const { withoutAttachedSkillBodies } = require('../helpers/skillActivationHelper');
 const { redactDirectIdentifiers } = require('../../utils/sanitizerUtils');
 const { logger } = require('../../utils/logger');
 
@@ -256,7 +257,7 @@ function compactStep(step) {
   return {
     tool_name: step.tool_name,
     arguments: minimized(step.tool_arguments || null),
-    output: minimized(step.tool_output || null),
+    output: minimized(withoutAttachedSkillBodies(step.tool_output) || null),
     success: step.success !== false,
     iteration: step.iteration ?? null,
   };

package/lib/clinical/providers/AnthropicProvider.js

@@ -240,7 +240,7 @@ class AnthropicProvider extends BaseLLMProvider {
           if (lastUserTurn?.role === 'user') {
             deliveryNudges++;
             previousRoundTools = [];
-            trace?.setSignals?.({ deliveryNudges });
+            trace?.setSignals?.({ deliveryNudges, nudgeKind: canDecide ? 'outreach' : 'delivery' });
             logger.warn('[AnthropicProvider] Turn will not close — nudging', { tool: canDecide ? OUTREACH_DECISION_TOOL : 'DeliverPatientMessage', deliveryNudges, hasEnded, isBudgetSpent });
             const turnContent = Array.isArray(lastUserTurn.content)
               ? lastUserTurn.content

package/lib/clinical/providers/BaseLLMProvider.js

@@ -10,6 +10,7 @@ const { resolveSkillCatalog } = require('../services/skillService');
 const { RISK_HEADLINE_MARKER } = require('../services/riskHeadlineService');
 const { resolveClinicalContext } = require('../services/clinicalContextReadService');
 const { isContingencyRuleBlockLive } = require('../flags/contingencyFlags');
+const { snapshotClinicalFlags } = require('../flags/flagSnapshot');
 const { TURN_KIND } = require('../context/turnContext');
 const { extractPatientMessage } = require('../../helpers/patientMessageHelper');
 const runtimeConfig = require('../../config/runtimeConfig');
@@ -102,7 +103,7 @@ class BaseLLMProvider {
       presetId: resolvedPresetId, presetVersion: resolvedPresetVersion, modelConfig,
     } = await composePrompt({ presetId, presetVersion, promptId: assistantId, variables: promptVariables });
 
-    const { toolIds, filtered, descriptions: toolDescriptions } = await resolveTools({
+    const { toolIds, filtered, descriptions: toolDescriptions, unregisteredToolIds = [] } = await resolveTools({
       promptId: resolvedPromptId || assistantId, assistant, presetToolIds,
     });
     const requestedAdditionalToolIds = Array.isArray(prePromptResult?.additionalToolIds)
@@ -200,7 +201,12 @@ class BaseLLMProvider {
     }
 
     trace?.setPrompt({ resolvedPresetId, resolvedPresetVersion });
-    trace?.setSignals?.({ offeredToolIds: effectiveToolIds, enabledSkills });
+    trace?.setSignals?.({
+      offeredToolIds: effectiveToolIds,
+      enabledSkills,
+      flags: snapshotClinicalFlags(),
+      ...(unregisteredToolIds.length > 0 && { unregisteredToolIds }),
+    });
 
     const { response, toolsExecuted, retries, usage } = await this._invokeModel({
       instructions: instructions || devContent || '',
@@ -619,6 +625,11 @@ class BaseLLMProvider {
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
       try {
         logger.info('[runConversation] Attempt', { attempt, maxRetries, threadId, assistantId });
+        // A retry starts from the original input, so a skill body handed over in an earlier attempt is not in context.
+        if (attempt > 1) {
+          config?.assistant?.toolRuntimeContext?.activatedSkills?.clear();
+          config?.assistant?.toolRuntimeContext?.skillActivationIteration?.clear();
+        }
 
         const result = await this._executeConversation(config);
         // DeliverPatientMessage is the curated patient reply; prefer it over any model narration in the final response.

package/lib/clinical/services/promptComposerService.js

@@ -191,6 +191,7 @@ async function fetchToolsByRecordIds(recordIds) {
   return tools;
 }
 
+const BLANK_TOOL_ID = '(blank tool_id)';
 const warnedUnlinked = new Set();
 
 function warnUnlinkedRegisteredTools(linkedToolIds, promptId) {
@@ -228,6 +229,7 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
   const activeTools = mappedTools.filter(t => !t.status || t.status === 'prod' || (!isProd && t.status === 'dev'));
 
   const validToolIds = [];
+  const unregisteredToolIds = [];
   const descriptions = {};
 
   for (const tool of activeTools) {
@@ -237,6 +239,7 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
       // An Airtable column retyped away from long text would otherwise reach the model as [object Object].
       if (typeof tool.description === 'string' && tool.description) descriptions[id] = tool.description;
     } else {
+      unregisteredToolIds.push(id || BLANK_TOOL_ID);
       logger.error('[promptComposer] Tool mapped in Airtable but not registered in code', { toolId: id, promptId });
     }
   }
@@ -252,7 +255,7 @@ async function resolveTools({ promptId, assistant, presetToolIds = null, status
 
   logger.debug('[promptComposer] Tools resolved', { promptId, mapped: activeTools.length, valid: validToolIds.length, filtered: true });
 
-  return { toolIds: validToolIds, filtered: true, descriptions };
+  return { toolIds: validToolIds, filtered: true, descriptions, unregisteredToolIds };
 }
 
 function clearCache() {

package/lib/clinical/tools/extractClinicalInfoTool.js

@@ -1,8 +1,9 @@
 const { requireGatewayProvider } = require('../config/llmConfig');
 const { getSafetyFlagPatterns } = require('../config/divergenceConfig');
-const { isPurelyConversational } = require('../helpers/clinicalWorkflowGuard');
+const { ROUTING_SKILL, isPurelyConversational } = require('../helpers/clinicalWorkflowGuard');
 const { detectSafetyFlags } = require('../helpers/safetyFlagsHelper');
 const { projectClinicalFacts, renderClinicalIntakeSummary } = require('../helpers/clinicalFactsHelper');
+const { attachRequiredSkill } = require('../helpers/skillActivationHelper');
 const { extractClinicalMentions, getConversationalTokens } = require('../services/clinicalExtractionService');
 const { recordClinicalIntake } = require('../services/clinicalAirtableService');
 const { getCtcaeCatalog } = require('../stores/CtcaeCatalog');
@@ -40,7 +41,7 @@ const MAX_CONTEXT_TURNS = 6;
 
 const definition = {
   name: 'extractClinicalInfo',
-  description: '**Does:** Extracts ALL structured clinical facts from the current patient message — symptoms, labs, medications, diagnoses, appointments, treatments — and returns them as a discriminated-union `clinical_facts[]` list keyed by `kind`. Call ONCE per turn with ALL detected tags in a single call — one call covers every category.\n\n**Required inputs:** `raw_message` (the patient\'s current turn text, VERBATIM — the full contents of `<patient_message>`, every line of it when the turn carries more than one), `detected_tags` (list, at least one of: `symptom`, `indication`, `treatment`, `adherence`, `medication`, `appointment`, `emotion`, `lab_value`, `diagnosis`, `allergy`, `comorbidity`, `performance_status`; empty only for a purely conversational message or when declaring `non_clinical_request`), `intake_source` (`self` | `caregiver` | `team_relay`).\n\n**When to call:** at the start of any turn where the patient message mentions, explicitly or implicitly, any of the 12 supported categories. The result drives every downstream router-side read (landscape / history / risk / patterns).\n\n**When NOT to call:**\n- When the patient SHARED raw numeric results / lab values / files — use `reportResultsReceived` instead (it both logs the share AND emits FHIR Observations directly).\n- More than once per turn — a single call covers every category.\n\n**Returns:** `data.clinical_facts[]` — a discriminated-union list where each record has `kind` (observation | medication | condition | procedure | appointment | allergy) plus common fields `{id, code, effective, notes}` (null/default fields are OMITTED — e.g. `interpretation` appears only when non-default) and kind-specific fields:\n- `kind=observation`: `code_ctcae`, `value`, `grade_scale`,   `episode_id`, `trend`. Read `grade_scale` to anchor the   grade assigned in `recordClinicalImpression`. It is present   whenever the term has a curated CTCAE ladder, and ABSENT   when it does not — an absent `grade_scale` means there is no   rubric for this term, not that one was withheld. An absent   `grade_scale` means the term has no curated rubric, not   that one was withheld — so there is nothing to grade   against from memory. Call `lookupCtcaeEntry` when you   suspect the term itself is wrong; otherwise say where the   grade came from in `grade_estimate.source`.\n- `kind=medication`: `adherence_status` (`started` |   `ongoing` | `non_adherent` | …).\n- `kind=condition`: `clinical_status` (`active` | `resolved`   | …) — patient self-report of an existing diagnosis   (distinct from `openCondition` which commits a new   agent-tracked case).\n- `kind=procedure`: patient-reported procedure done   elsewhere (distinct from `recordIntervention` which is   agent-authored); `venue`/`outcome` may be null in the   current extraction phase.\n- `kind=appointment`: `scheduled_for`, `purpose` (may be   null in the current extraction phase).\nThe system writes the matching FHIR resource (Observation / MedicationStatement / Condition / Procedure / Appointment) + `Provenance` per fact on the audit lane; `allergy`, `comorbidity`, and `performance_status` are captured in a dedicated aggregate, not as a per-fact resource.\n\n**When the result asks you to confirm:** `data.pending_confirmation[]` means the patient reported a REAL clinical event but named it only generically («me suspendieron el tratamiento»), so it was deliberately NOT recorded. Each entry carries `{term, category, missing, quote}`; the list holds EVERY fact withheld this turn, but ask about the FIRST one only. Ask the patient for exactly what its `missing` names, in ONE short natural question, and never state or imply that anything was recorded. When they answer, call `extractClinicalInfo` again on their reply and it will be recorded then. `data.context_gaps[]` — only ever sent when there is nothing to confirm — names ONE stored variable that is stale or incomplete; raise it only if the conversation allows it naturally. Both lists are empty whenever the turn carries a safety flag: never ask housekeeping questions during a safety event.\n\n**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated). Facts listed in `pending_confirmation` are NOT recorded as facts — they never reach the clinical intake or the patient\'s chart; FHIR keeps them only as unconfirmed drafts until the patient confirms them.',
+  description: '**Does:** Extracts ALL structured clinical facts from the current patient message — symptoms, labs, medications, diagnoses, appointments, treatments — and returns them as a discriminated-union `clinical_facts[]` list keyed by `kind`. Call ONCE per turn with ALL detected tags in a single call — one call covers every category.\n\n**Required inputs:** `raw_message` (the patient\'s current turn text, VERBATIM — the full contents of `<patient_message>`, every line of it when the turn carries more than one), `detected_tags` (list, at least one of: `symptom`, `indication`, `treatment`, `adherence`, `medication`, `appointment`, `emotion`, `lab_value`, `diagnosis`, `allergy`, `comorbidity`, `performance_status`; empty only for a purely conversational message or when declaring `non_clinical_request`), `intake_source` (`self` | `caregiver` | `team_relay`).\n\n**When to call:** at the start of any turn where the patient message mentions, explicitly or implicitly, any of the 12 supported categories. The result drives every downstream router-side read (landscape / history / risk / patterns).\n\n**When NOT to call:**\n- When the patient SHARED raw numeric results / lab values / files — use `reportResultsReceived` instead (it both logs the share AND emits FHIR Observations directly).\n- More than once per turn — a single call covers every category.\n\n**Returns:** `data.clinical_facts[]` — a discriminated-union list where each record has `kind` (observation | medication | condition | procedure | appointment | allergy) plus common fields `{id, code, effective, notes}` (null/default fields are OMITTED — e.g. `interpretation` appears only when non-default) and kind-specific fields:\n- `kind=observation`: `code_ctcae`, `value`, `grade_scale`,   `episode_id`, `trend`. Read `grade_scale` to anchor the   grade assigned in `recordClinicalImpression`. It is present   whenever the term has a curated CTCAE ladder, and ABSENT   when it does not — an absent `grade_scale` means there is no   rubric for this term, not that one was withheld. An absent   `grade_scale` means the term has no curated rubric, not   that one was withheld — so there is nothing to grade   against from memory. Call `lookupCtcaeEntry` when you   suspect the term itself is wrong; otherwise say where the   grade came from in `grade_estimate.source`.\n- `kind=medication`: `adherence_status` (`started` |   `ongoing` | `non_adherent` | …).\n- `kind=condition`: `clinical_status` (`active` | `resolved`   | …) — patient self-report of an existing diagnosis   (distinct from `openCondition` which commits a new   agent-tracked case).\n- `kind=procedure`: patient-reported procedure done   elsewhere (distinct from `recordIntervention` which is   agent-authored); `venue`/`outcome` may be null in the   current extraction phase.\n- `kind=appointment`: `scheduled_for`, `purpose` (may be   null in the current extraction phase).\nThe system writes the matching FHIR resource (Observation / MedicationStatement / Condition / Procedure / Appointment) + `Provenance` per fact on the audit lane; `allergy`, `comorbidity`, and `performance_status` are captured in a dedicated aggregate, not as a per-fact resource.\n\n`data.activated_skills[]` — present when clinical facts were extracted and `clinical_routing` is enabled but not yet loaded this turn: its `body` is the routing protocol. Read it before `submitRoutingDecision`; no `Skill` call needed.\n\n**When the result asks you to confirm:** `data.pending_confirmation[]` means the patient reported a REAL clinical event but named it only generically («me suspendieron el tratamiento»), so it was deliberately NOT recorded. Each entry carries `{term, category, missing, quote}`; the list holds EVERY fact withheld this turn, but ask about the FIRST one only. Ask the patient for exactly what its `missing` names, in ONE short natural question, and never state or imply that anything was recorded. When they answer, call `extractClinicalInfo` again on their reply and it will be recorded then. `data.context_gaps[]` — only ever sent when there is nothing to confirm — names ONE stored variable that is stale or incomplete; raise it only if the conversation allows it naturally. Both lists are empty whenever the turn carries a safety flag: never ask housekeeping questions during a safety event.\n\n**Side effects:** System emits a FHIR resource + `Provenance` per fact on the audit lane, except `allergy`/`comorbidity`/`performance_status` (aggregated). Facts listed in `pending_confirmation` are NOT recorded as facts — they never reach the clinical intake or the patient\'s chart; FHIR keeps them only as unconfirmed drafts until the patient confirms them.',
   strict: true,
   parameters: {
     type: 'object',
@@ -265,6 +266,10 @@ async function handler(args, context = {}) {
   const gradeScales = {};
   for (const term of terms) gradeScales[term] = catalog.getGradeScale(term);
   const envelope = projectClinicalFacts({ clinicalMentions, safetyFlags, gradeScales, askAgenda });
+  const routingSkill = clinicalMentions.length || pendingMentions.length
+    ? await attachRequiredSkill(runtime, ROUTING_SKILL)
+    : null;
+  if (routingSkill) envelope.data.activated_skills = [routingSkill];
   return JSON.stringify(envelope);
 }
 

package/lib/clinical/tools/skillTool.js

@@ -1,9 +1,10 @@
 const { MEDICATION_NAMING_RULE } = require('../helpers/medicationNamingRule');
+const { markSkillActivated } = require('../helpers/skillActivationHelper');
 const { loadSkillBody } = require('../services/skillService');
 
 const definition = {
   name: 'Skill',
-  description: '**Does:** Activates an enabled skill by name and returns its `SKILL.md` body inline; the body then governs the rest of the turn.\n\n**Required inputs:** `skill` (enabled skill name, no leading slash, e.g. `emergency`), `args` (context string the skill body can interpret — pass `null` when there is no additional context).\n\n**When to call:** the turn matches a protocol the operator has enabled for this run (e.g. an emergency/red-flag turn) and you need its full body to proceed correctly.\n\n**When NOT to call:** the skill is not enabled for this run; a plain reply covers the turn without a protocol.\n\n**Returns:** `activated_skills[]` — `{name, version, body}`; read `body` and follow it verbatim. A skill not enabled for this run returns the enabled skill names, and an unknown name returns the available skill names, in the error payload for self-correction. Read-only.',
+  description: '**Does:** Activates an enabled skill by name and returns its `SKILL.md` body inline; the body then governs the rest of the turn.\n\n**Required inputs:** `skill` (enabled skill name, no leading slash, e.g. `emergency`), `args` (context string the skill body can interpret — pass `null` when there is no additional context).\n\n**When to call:** the turn matches a protocol the operator has enabled for this run (e.g. an emergency/red-flag turn) and you need its full body to proceed correctly.\n\n**When NOT to call:** the skill is not enabled for this run; a plain reply covers the turn without a protocol.\n\n**Returns:** `activated_skills[]` — `{name, version, body}`; read `body` and follow it verbatim. A skill already returned this turn (by `Skill` or inside another tool\'s `activated_skills`) returns `already_active` instead of the body again. A skill not enabled for this run returns the enabled skill names, and an unknown name returns the available skill names, in the error payload for self-correction. Read-only.',
   strict: true,
   replayScope: 'turn',
   parameters: {
@@ -46,6 +47,14 @@ async function handler(args, context) {
       });
     }
 
+    const runtime = context?.toolRuntimeContext;
+    if (runtime?.activatedSkills?.has(name)) {
+      return JSON.stringify({
+        success: true,
+        data: { already_active: name, note: `The ${name} body was already returned to you in this turn; follow it from there.` },
+      });
+    }
+
     const { skill, availableSkills } = await loadSkillBody(name);
     if (!skill) {
       return JSON.stringify({
@@ -58,11 +67,7 @@ async function handler(args, context) {
     const fragment = { name: skill.name, version: skill.version, body: skill.body };
     if (args?.args) fragment.args_received = args.args;
 
-    const runtime = context?.toolRuntimeContext;
-    runtime?.activatedSkills?.add(skill.name);
-    if (runtime?.skillActivationIteration && !runtime.skillActivationIteration.has(skill.name)) {
-      runtime.skillActivationIteration.set(skill.name, runtime.currentIteration ?? null);
-    }
+    markSkillActivated(runtime, skill.name);
 
     return JSON.stringify({ success: true, data: { activated_skills: [fragment] } });
   } catch (err) {

package/lib/clinical/tools/submitRoutingDecisionTool.js

@@ -1,7 +1,8 @@
 const crypto = require('node:crypto');
 
-const { validateRoutingPrerequisites } = require('../helpers/clinicalWorkflowGuard');
+const { clinicalIntakeRequiresRisk, hasAlternateTerminalCommit, validateRoutingPrerequisites } = require('../helpers/clinicalWorkflowGuard');
 const { MEDICATION_NAMING_RULE } = require('../helpers/medicationNamingRule');
+const { attachRequiredSkill } = require('../helpers/skillActivationHelper');
 const { storeRoutingDecision, readRoutingDecisions, readSymptomCases } = require('../../fhir');
 const { RoutingDecision } = require('../../shared/dtos/RoutingDecision');
 const { foldAccents } = require('../../utils/formatUtils');
@@ -92,7 +93,7 @@ const _CASE_IMPLYING_ACTIONS = new Set([
 
 const definition = {
   name: 'submitRoutingDecision',
-  description: '**Does:** The terminal routing checkpoint — call ONCE per turn to commit the turn plan. Decomposes `trace` (the per-mention evaluation record) and `turn_plan` (the primary action + optional secondary/deferred) into a persisted RoutingDecision (assessment + disposition + provenance), sets the turn\'s outbound signals, and hands the agent the next skill to invoke.\n\n**Required inputs:** `trace.mentions_evaluated[]` — one entry per clinical mention: `clinical_reasoning`, `decision.action`, `case_id_opened_or_updated` — REQUIRED whenever `decision.action` acts on a symptom (`emergency_escalation`, `team_escalation`, `symptom_recommendation`, `symptom_probe`, `acknowledge_improvement_on_case`, `follow_up_on_open_case`, `revisit_neglected_case`, `educate_about_symptom`, `weekly_triage_recommendations`, `generate_recommendations`), null only for a genuinely caseless mention (a medication, an appointment, a mood), plus `safety_flag_disposition` (string or object) when `safety_flags_received` is non-empty. `turn_plan.primary` — exactly one `{action, reason, case_id?}`; `turn_plan.secondary[]` — up to 2 `{action, compose_as}`; `turn_plan.deferred[]` — optional `{item?, defer_reason}`.\n\n**Routing-skill prerequisite:** when `clinical_routing` is among your enabled skills and `Skill` is offered to you this turn, this checkpoint fails until that body has been read in an EARLIER iteration. Presets without either proceed straight to routing. Requesting it in the same response does not count — its content never reached you. Call `Skill` with `skill=clinical_routing`, read what it returns, then commit here. This is the most common reason a first attempt is rejected.\n\n**Risk prerequisite:** after a clinical intake with extracted mentions, this checkpoint fails until the turn trace records a successful, processed risk read with status `final`, `no_signal`, or `not_generated`. Normally call `getRouterContextBundle` first and use its `risk.turn_focus`; if `sections_returned` lacks `risk` or reports `_diagnostics.risk_error`, call `getPatientRiskAssessment`, then retry this checkpoint.\n\n**Enum coercion:** primary/secondary `action` and secondary `compose_as` are folded (case/accent/separator) and synonym-mapped to canonical values; each repair is disclosed via `auto_repairs`. A genuinely unknown action is rejected.\n\n**Returns:** `decision_id`, `downstream_skill_to_invoke` (emergency | accompaniment | symptom_management | patient_education | null, derived from `primary.action`), and `auto_repairs` (only when non-empty). Fails hard with `risk_assessment_required_before_routing` when clinical intake ran without a processed risk disposition, with `decision_already_committed_for_turn` if called twice in one turn, when a symptom-acting mention carries no `case_id_opened_or_updated`, and when a named `case_id` does not exist for this patient. A clinical `DeliverPatientMessage` remains blocked until this commit succeeds.\n\n**Side effects:** persists the RoutingDecision; sets `branch_taken=ai_agent` on the turn trace.',
+  description: '**Does:** The terminal routing checkpoint — call ONCE per turn to commit the turn plan. Decomposes `trace` (the per-mention evaluation record) and `turn_plan` (the primary action + optional secondary/deferred) into a persisted RoutingDecision (assessment + disposition + provenance), sets the turn\'s outbound signals, and returns the body of the skill that governs the reply.\n\n**Required inputs:** `trace.mentions_evaluated[]` — one entry per clinical mention: `clinical_reasoning`, `decision.action`, `case_id_opened_or_updated` — REQUIRED whenever `decision.action` acts on a symptom (`emergency_escalation`, `team_escalation`, `symptom_recommendation`, `symptom_probe`, `acknowledge_improvement_on_case`, `follow_up_on_open_case`, `revisit_neglected_case`, `educate_about_symptom`, `weekly_triage_recommendations`, `generate_recommendations`), null only for a genuinely caseless mention (a medication, an appointment, a mood), plus `safety_flag_disposition` (string or object) when `safety_flags_received` is non-empty. `turn_plan.primary` — exactly one `{action, reason, case_id?}`; `turn_plan.secondary[]` — up to 2 `{action, compose_as}`; `turn_plan.deferred[]` — optional `{item?, defer_reason}`.\n\n**Routing-skill prerequisite:** when `clinical_routing` is among your enabled skills and `Skill` is offered to you this turn, this checkpoint fails until that body has been read in an EARLIER iteration. Presets without either proceed straight to routing. `extractClinicalInfo` returns that body in its `activated_skills` when it extracts clinical mentions: read it there and commit here in a LATER response, not in the same one as the intake. If no body was returned, call `Skill` with `skill=clinical_routing` first.\n\n**Risk prerequisite:** after a clinical intake with extracted mentions, this checkpoint fails until the turn trace records a successful, processed risk read with status `final`, `no_signal`, or `not_generated`. Normally call `getRouterContextBundle` first and use its `risk.turn_focus`; if `sections_returned` lacks `risk` or reports `_diagnostics.risk_error`, call `getPatientRiskAssessment`, then retry this checkpoint.\n\n**Enum coercion:** primary/secondary `action` and secondary `compose_as` are folded (case/accent/separator) and synonym-mapped to canonical values; each repair is disclosed via `auto_repairs`. A genuinely unknown action is rejected.\n\n**Returns:** `decision_id`, `downstream_skill_to_invoke` (emergency | accompaniment | symptom_management | patient_education | null, derived from `primary.action`), `activated_skills` (that skill\'s body, when it is enabled and not yet loaded this turn — read it and compose the reply from it; no `Skill` call needed), and `auto_repairs` (only when non-empty). Fails hard with `risk_assessment_required_before_routing` when clinical intake ran without a processed risk disposition, with `decision_already_committed_for_turn` if called twice in one turn, when a symptom-acting mention carries no `case_id_opened_or_updated`, and when a named `case_id` does not exist for this patient. A clinical `DeliverPatientMessage` remains blocked until this commit succeeds.\n\n**Side effects:** persists the RoutingDecision; sets `branch_taken=ai_agent` on the turn trace.',
   strict: false,
   parameters: {
     type: 'object',
@@ -431,6 +432,9 @@ async function handler(args = {}, context = {}) {
     const downstream = derivedDownstreamSkill(plan.primaryAction);
     runtime.trace.setSignals({ downstreamSkill: downstream || null });
     const data = { decision_id: decision.decisionId, downstream_skill_to_invoke: downstream };
+    const deliveryNeedsSkill = clinicalIntakeRequiresRisk(runtime.trace) && !hasAlternateTerminalCommit(runtime.trace);
+    const downstreamSkill = deliveryNeedsSkill ? await attachRequiredSkill(runtime, downstream) : null;
+    if (downstreamSkill) data.activated_skills = [downstreamSkill];
     if (repairs.length) data.auto_repairs = repairs;
     return JSON.stringify({ success: true, data });
   } catch (err) {

package/lib/helpers/messageHelper.js

@@ -3,6 +3,8 @@ const moment = require('moment-timezone');
 const { logger } = require('../utils/logger');
 const { isPlainObject } = require('../utils/jsonUtils');
 
+const { withoutAttachedSkillBodies } = require('../clinical/helpers/skillActivationHelper');
+
 function formatMessage(reply) {
   try {
     if (!reply.createdAt) return [];
@@ -62,9 +64,8 @@ function getMessageTools(reply, { skipTools, replayArgs } = {}) {
       const argsStr = JSON.stringify(args);
       let outputStr;
       if (t.tool_output != null && !keepArgs) {
-        outputStr = typeof t.tool_output === 'string'
-          ? t.tool_output
-          : JSON.stringify(t.tool_output);
+        const output = withoutAttachedSkillBodies(t.tool_output);
+        outputStr = typeof output === 'string' ? output : JSON.stringify(output);
       } else {
         outputStr = JSON.stringify({ success: t.success !== false });
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "5.68.8",
+  "version": "5.68.10",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",