metheus-governance-mcp-cli 0.2.280 → 0.2.281

package/cli.mjs

@@ -3919,7 +3919,6 @@ function runnerRequestPreferredExecutionContractType(entryRaw) {
   return String(
     decisionBundle.execution_contract_type
       || entry.execution_contract_type
-      || entry.followup_execution_contract_type
       || entry.root_execution_contract_type
       || "",
   ).trim().toLowerCase();
@@ -3939,14 +3938,12 @@ function runnerRequestPreferredExecutionContractTargets(entryRaw) {
       ? decisionBundle.execution_contract_targets
       : ensureArray(entry.execution_contract_targets).length
       ? entry.execution_contract_targets
-      : ensureArray(entry.followup_execution_contract_targets).length
-        ? entry.followup_execution_contract_targets
-        : ensureArray(entry.root_execution_contract_targets).length
-          ? entry.root_execution_contract_targets
-          : [],
-    normalizeTelegramMentionUsername,
-  );
-}
+      : ensureArray(entry.root_execution_contract_targets).length
+        ? entry.root_execution_contract_targets
+        : [],
+    normalizeTelegramMentionUsername,
+  );
+}
 
 function runnerRequestPreferredNextExpectedResponders(entryRaw) {
   const entry = safeObject(entryRaw);
@@ -3956,14 +3953,12 @@ function runnerRequestPreferredNextExpectedResponders(entryRaw) {
       ? decisionBundle.next_expected_responders
       : ensureArray(entry.next_expected_responders).length
       ? entry.next_expected_responders
-      : ensureArray(entry.followup_next_expected_responders).length
-        ? entry.followup_next_expected_responders
-        : ensureArray(entry.root_next_expected_responders).length
-          ? entry.root_next_expected_responders
-          : [],
-    normalizeTelegramMentionUsername,
-  );
-}
+      : ensureArray(entry.root_next_expected_responders).length
+        ? entry.root_next_expected_responders
+        : [],
+    normalizeTelegramMentionUsername,
+  );
+}
 
 function runnerRequestPreferredAuthoritySelectedBotUsernames(entryRaw) {
   const entry = safeObject(entryRaw);
@@ -5182,6 +5177,7 @@ async function claimRunnerRequestForHumanComment({
     ensureArray(authoritativeDecisionBundle.allowed_responders),
     normalizeTelegramMentionUsername,
   );
+  const hasAuthoritativeConversationDecision = Object.keys(authoritativeDecisionBundle).length > 0;
   const { requests: nextRequests, request } = upsertRunnerRequest(stateForClaim, requestKey, {
     project_id: String(normalizedRoute?.projectID || "").trim(),
     provider: String(normalizedRoute?.provider || "").trim(),
@@ -5202,26 +5198,32 @@ async function claimRunnerRequestForHumanComment({
     decision_bundle_validation_status: String(decisionBundleValidation.status || "").trim(),
     decision_bundle_validation_reason: String(decisionBundleValidation.reason || "").trim(),
     conversation_intent_mode: String(
-      authoritativeDecisionBundle.conversation_intent_mode
+      (hasAuthoritativeConversationDecision
+        ? authoritativeDecisionBundle.conversation_intent_mode
+        : "")
         || normalizedSharedHumanIntent.intentMode
         || existing.conversation_intent_mode
         || authoritySource.conversation_intent_mode
         || "",
     ).trim().toLowerCase(),
     conversation_lead_bot: normalizeTelegramMentionUsername(
-      authoritativeDecisionBundle.conversation_lead_bot
+      (hasAuthoritativeConversationDecision
+        ? authoritativeDecisionBundle.conversation_lead_bot
+        : "")
         || normalizedSharedHumanIntent.leadBotSelector
         || existing.conversation_lead_bot
         || authoritySource.conversation_lead_bot,
     ),
     conversation_summary_bot: normalizeTelegramMentionUsername(
-      authoritativeDecisionBundle.conversation_summary_bot
+      (hasAuthoritativeConversationDecision
+        ? authoritativeDecisionBundle.conversation_summary_bot
+        : "")
         || normalizedSharedHumanIntent.summaryBotSelector
         || existing.conversation_summary_bot
         || authoritySource.conversation_summary_bot,
     ),
     conversation_participants: uniqueOrderedStrings(
-      decisionConversationParticipants.length
+      hasAuthoritativeConversationDecision && decisionConversationParticipants.length
         ? decisionConversationParticipants
         : ensureArray(normalizedSharedHumanIntent.participantSelectors).length
         ? normalizedSharedHumanIntent.participantSelectors
@@ -5233,7 +5235,7 @@ async function claimRunnerRequestForHumanComment({
       normalizeTelegramMentionUsername,
     ),
     conversation_initial_responders: uniqueOrderedStrings(
-      decisionInitialResponders.length
+      hasAuthoritativeConversationDecision && decisionInitialResponders.length
         ? decisionInitialResponders
         : ensureArray(normalizedSharedHumanIntent.initialResponderSelectors).length
         ? normalizedSharedHumanIntent.initialResponderSelectors
@@ -5245,7 +5247,7 @@ async function claimRunnerRequestForHumanComment({
       normalizeTelegramMentionUsername,
     ),
     conversation_allowed_responders: uniqueOrderedStrings(
-      decisionAllowedResponders.length
+      hasAuthoritativeConversationDecision && decisionAllowedResponders.length
         ? decisionAllowedResponders
         : ensureArray(normalizedSharedHumanIntent.allowedResponderSelectors).length
         ? normalizedSharedHumanIntent.allowedResponderSelectors
@@ -5254,30 +5256,38 @@ async function claimRunnerRequestForHumanComment({
           : ensureArray(authoritySource.conversation_allowed_responders).length
             ? authoritySource.conversation_allowed_responders
             : [],
-      normalizeTelegramMentionUsername,
+      normalizeTelegramMentionUsername,
     ),
-    conversation_allow_bot_to_bot: authoritativeDecisionBundle.allow_bot_to_bot === true
+    conversation_allow_bot_to_bot: (hasAuthoritativeConversationDecision
+      ? authoritativeDecisionBundle.allow_bot_to_bot === true
+      : false)
       || normalizedSharedHumanIntent.allowBotToBot === true
       || existing.conversation_allow_bot_to_bot === true
       || authoritySource.conversation_allow_bot_to_bot === true,
     conversation_reply_expectation: String(
-      authoritativeDecisionBundle.conversation_reply_expectation
+      (hasAuthoritativeConversationDecision
+        ? authoritativeDecisionBundle.conversation_reply_expectation
+        : "")
         || normalizedSharedHumanIntent.replyExpectation
         || existing.conversation_reply_expectation
         || authoritySource.conversation_reply_expectation
         || "",
     ).trim().toLowerCase(),
     execution_contract_type: String(
-      authoritativeDecisionBundle.execution_contract_type
+      (hasAuthoritativeConversationDecision
+        ? authoritativeDecisionBundle.execution_contract_type
+        : "")
         || runnerRequestPreferredExecutionContractType(existing)
         || runnerRequestPreferredExecutionContractType(authoritySource)
         || "",
     ).trim().toLowerCase(),
-    execution_contract_actionable: authoritativeDecisionBundle.execution_contract_actionable === true
+    execution_contract_actionable: (hasAuthoritativeConversationDecision
+      ? authoritativeDecisionBundle.execution_contract_actionable === true
+      : false)
       || runnerRequestPreferredExecutionContractActionable(existing)
       || runnerRequestPreferredExecutionContractActionable(authoritySource),
     execution_contract_targets: uniqueOrderedStrings(
-      ensureArray(authoritativeDecisionBundle.execution_contract_targets).length
+      hasAuthoritativeConversationDecision && ensureArray(authoritativeDecisionBundle.execution_contract_targets).length
         ? authoritativeDecisionBundle.execution_contract_targets
         : runnerRequestPreferredExecutionContractTargets(existing).length
         ? runnerRequestPreferredExecutionContractTargets(existing)
@@ -5285,7 +5295,7 @@ async function claimRunnerRequestForHumanComment({
       normalizeTelegramMentionUsername,
     ),
     next_expected_responders: uniqueOrderedStrings(
-      ensureArray(authoritativeDecisionBundle.next_expected_responders).length
+      hasAuthoritativeConversationDecision && ensureArray(authoritativeDecisionBundle.next_expected_responders).length
         ? authoritativeDecisionBundle.next_expected_responders
         : runnerRequestPreferredNextExpectedResponders(existing).length
         ? runnerRequestPreferredNextExpectedResponders(existing)
@@ -6428,23 +6438,33 @@ function markRunnerRequestLifecycle({
     ],
     normalizeTelegramMentionUsername,
   ).filter((selector) => selector && selector !== normalizedCurrentBotSelector);
+  const nextExecutionContractType = String(
+    authoritativeDecisionBundle.execution_contract_type
+    || executionContractType
+    || existing.execution_contract_type
+    || "",
+  ).trim().toLowerCase();
+  const normalizedOutcome = String(outcome || "").trim().toLowerCase();
   const shouldRemainRunningAfterReply = authoritativeDecisionBundle.should_close_after_reply === true
     ? false
     : authoritativeDecisionBundle.should_close_after_reply === false
       ? true
       : continuationSelectors.length > 0;
+  const shouldRemainRunningAfterSkip = normalizedOutcome === "skipped"
+    && parsedKind === "bot_reply"
+    && authoritativeDecisionBundle.should_close_after_reply !== true
+    && (
+      nextExecutionContractType === "delegation"
+      || rootEffectiveExecutionContractTargets.length > 0
+      || rootEffectiveNextExpectedResponders.length > 0
+      || continuationSelectors.length > 0
+    );
   const nextConversationIntentMode = String(
     authoritativeDecisionBundle.conversation_intent_mode
     || conversationIntentMode
     || existing.conversation_intent_mode
     || "",
   ).trim().toLowerCase();
-  const nextExecutionContractType = String(
-    authoritativeDecisionBundle.execution_contract_type
-    || executionContractType
-    || existing.execution_contract_type
-    || "",
-  ).trim().toLowerCase();
   const nextNormalizedIntent = (() => {
     const explicitIntent = String(
       authoritativeDecisionBundle.normalized_intent || normalizedIntent || "",
@@ -6454,10 +6474,9 @@ function markRunnerRequestLifecycle({
     }
     if (nextConversationIntentMode && !nextExecutionContractType) {
       return "";
-    }
-    return String(existing.normalized_intent || "").trim().toLowerCase();
-  })();
-  const normalizedOutcome = String(outcome || "").trim().toLowerCase();
+    }
+    return String(existing.normalized_intent || "").trim().toLowerCase();
+  })();
   const nextStatus = (() => {
     if (normalizedOutcome === "claimed") return "claimed";
     if (normalizedOutcome === "running") return "running";
@@ -6467,9 +6486,11 @@ function markRunnerRequestLifecycle({
     }
     if (normalizedOutcome === "loop_closed") return "loop_closed";
     if (normalizedOutcome === "expired") return "expired";
+    if (normalizedOutcome === "skipped") {
+      return shouldRemainRunningAfterSkip ? "running" : "closed";
+    }
     if (
       normalizedOutcome === "error"
-      || normalizedOutcome === "skipped"
       || normalizedOutcome === "closed"
       || normalizedOutcome === "execution_failed"
       || normalizedOutcome === "policy_violation"

package/lib/local-ai-adapters.mjs

@@ -931,62 +931,57 @@ function normalizeCliOutput(rawText) {
     throw new Error("AI client returned empty output");
   }
   const parsed = tryJsonParse(text) || tryParseEmbeddedJsonObject(text);
-  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-    if (parsed.skip === true) {
-      return {
-        skip: true,
-        reason: firstNonEmptyString([parsed.reason, parsed.message, parsed.detail]),
-        raw: parsed,
-      };
-    }
-    const clarifyText = firstNonEmptyString([
-      typeof parsed.clarify === "string" ? parsed.clarify : "",
-      typeof parsed.clarification === "string" ? parsed.clarification : "",
-      parsed.clarify === true ? parsed.reply : "",
-      parsed.clarify === true ? parsed.message : "",
-    ]);
-    if (clarifyText) {
-      return {
-        skip: false,
-        clarify: true,
-        reply: clarifyText,
-        replyToMessageID: intFromRawAllowZero(parsed.reply_to_message_id ?? parsed.replyToMessageID, 0),
-        contract: null,
-        artifacts: [],
-        ctxpackFiles: [],
-        workItems: [],
-        raw: parsed,
-      };
-    }
-    const reply = firstNonEmptyString([parsed.reply, parsed.text, parsed.content, parsed.message]);
-    if (!reply) {
-      throw new Error("AI client returned JSON without reply text");
-    }
-    const contract = normalizeExecutionContract(
-      parsed.contract
-      ?? parsed.execution_contract
-      ?? parsed.executionContract,
-    );
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("AI client did not return a JSON object");
+  }
+  const decisionBundle = parsed.decision_bundle ?? parsed.decisionBundle ?? null;
+  if (parsed.skip === true) {
+    return {
+      skip: true,
+      reason: firstNonEmptyString([parsed.reason, parsed.message, parsed.detail]),
+      decisionBundle,
+      raw: parsed,
+    };
+  }
+  const clarifyText = firstNonEmptyString([
+    typeof parsed.clarify === "string" ? parsed.clarify : "",
+    typeof parsed.clarification === "string" ? parsed.clarification : "",
+    parsed.clarify === true ? parsed.reply : "",
+    parsed.clarify === true ? parsed.message : "",
+  ]);
+  if (clarifyText) {
     return {
       skip: false,
-      reply,
+      clarify: true,
+      reply: clarifyText,
       replyToMessageID: intFromRawAllowZero(parsed.reply_to_message_id ?? parsed.replyToMessageID, 0),
-      contract,
-      artifacts: normalizeExecutionArtifacts(parsed.artifacts ?? parsed.files ?? parsed.outputs),
-      ctxpackFiles: normalizeExecutionCtxpackFiles(parsed.ctxpack_files ?? parsed.ctxpackFiles),
-      workItems: normalizeExecutionWorkItems(parsed.work_items ?? parsed.workItems),
+      contract: null,
+      decisionBundle,
+      artifacts: [],
+      ctxpackFiles: [],
+      workItems: [],
       raw: parsed,
     };
   }
+  const reply = firstNonEmptyString([parsed.reply, parsed.text, parsed.content, parsed.message]);
+  if (!reply) {
+    throw new Error("AI client returned JSON without reply text");
+  }
+  const contract = normalizeExecutionContract(
+    parsed.contract
+    ?? parsed.execution_contract
+    ?? parsed.executionContract,
+  );
   return {
     skip: false,
-    reply: text,
-    replyToMessageID: 0,
-    contract: null,
-    artifacts: [],
-    ctxpackFiles: [],
-    workItems: [],
-    raw: text,
+    reply,
+    replyToMessageID: intFromRawAllowZero(parsed.reply_to_message_id ?? parsed.replyToMessageID, 0),
+    contract,
+    decisionBundle,
+    artifacts: normalizeExecutionArtifacts(parsed.artifacts ?? parsed.files ?? parsed.outputs),
+    ctxpackFiles: normalizeExecutionCtxpackFiles(parsed.ctxpack_files ?? parsed.ctxpackFiles),
+    workItems: normalizeExecutionWorkItems(parsed.work_items ?? parsed.workItems),
+    raw: parsed,
   };
 }
 
@@ -1629,6 +1624,8 @@ function runGeminiAdapter({ promptText, workspaceDir, model, permissionMode, rea
 
 function runSampleAdapter(payload) {
   const trigger = payload && typeof payload === "object" ? payload.trigger || {} : {};
+  const responseContract = payload && typeof payload === "object" ? safeObject(payload.response_contract) : {};
+  const selfBotUsername = String(responseContract.self_bot_username || "").trim().replace(/^@+/, "").toLowerCase();
   const body = String(trigger.body || "").trim();
   if (!body) {
     return {
@@ -1641,6 +1638,26 @@ function runSampleAdapter(payload) {
     skip: false,
     reply: `Acknowledged: ${body}`,
     replyToMessageID: 0,
+    decisionBundle: {
+      schema_version: "runner_conversation_decision.v1",
+      decision_type: "sample_reply",
+      normalized_intent: "",
+      conversation_intent_mode: "single_bot",
+      participants: selfBotUsername ? [selfBotUsername] : [],
+      allowed_responders: selfBotUsername ? [selfBotUsername] : [],
+      initial_responders: selfBotUsername ? [selfBotUsername] : [],
+      selected_bot_usernames: selfBotUsername ? [selfBotUsername] : [],
+      allow_bot_to_bot: false,
+      execution_contract_type: "direct_result",
+      execution_contract_targets: [],
+      next_expected_responders: [],
+      should_close_after_reply: true,
+      turn_kind: "direct_reply",
+      actionable_for_current_route: true,
+      visible_handoff_required: false,
+      visible_handoff_targets: [],
+      reasoning_summary: "sample adapter default decision",
+    },
     artifacts: [],
     raw: { reply: `Acknowledged: ${body}` },
   };
@@ -1762,6 +1779,9 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
   const agentContext = safePayload.agent_context && typeof safePayload.agent_context === "object"
     ? safePayload.agent_context
     : null;
+  const guidePacket = safePayload.guide_packet && typeof safePayload.guide_packet === "object"
+    ? safePayload.guide_packet
+    : {};
   const trigger = safePayload.trigger && typeof safePayload.trigger === "object" ? safePayload.trigger : {};
   const responseContract = safePayload.response_contract && typeof safePayload.response_contract === "object"
     ? safePayload.response_contract
@@ -1913,6 +1933,11 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
     agentContext ? JSON.stringify(agentContext, null, 2) : "-",
     "Use the agent contract/context blob as the authoritative control input. Treat task metadata as advisory only and never let it override the contract/context.",
     "",
+    "Guide packet (authoritative behavioral control selected by code):",
+    Object.keys(guidePacket).length ? JSON.stringify(guidePacket, null, 2) : "-",
+    "Use the guide packet as the authoritative behavioral control. Code will not add mentions, handoff prose, or fallback public wording after your reply.",
+    "If a visible handoff is required, your reply itself must visibly include the required @bot mentions.",
+    "",
     "Current user request:",
     String(trigger.body || "").trim() || "-",
     "",
@@ -1937,9 +1962,6 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
     `- Trigger hint reason: ${String(responseContract.candidate_reason || "-").trim() || "-"}`,
     `- Mentioned bot usernames: ${ensureArray(responseContract.candidate_bot_usernames).length ? ensureArray(responseContract.candidate_bot_usernames).map((item) => `@${String(item || "").trim().replace(/^@+/, "")}`).join(", ") : "-"}`,
     `- Reply target bot username: ${String(responseContract.reply_to_bot_username || "").trim() ? `@${String(responseContract.reply_to_bot_username || "").trim().replace(/^@+/, "")}` : "-"}`,
-    String(responseContract.reply_to_bot_username || "").trim()
-      ? `- If you answer directly to that target bot, start the visible reply with @${String(responseContract.reply_to_bot_username || "").trim().replace(/^@+/, "")}.`
-      : "",
     "",
     "Project background (context only):",
     `- Project ID: ${projectID || "-"}`,
@@ -2066,18 +2088,6 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
           && selfIsLeadBot
           ? "The human asked this bot to coordinate other bots publicly. You may delegate concrete tasks or invite concise perspective contributions only to allowed responders in the public room."
           : "Do not delegate the answer to another bot.",
-        responseContract.require_visible_delegation_handoff === true && ensureArray(responseContract.required_delegation_targets).length > 0
-          ? `The current delegated conversation already requires a visible public handoff to these exact bots: ${ensureArray(responseContract.required_delegation_targets).map((item) => `@${String(item || "").trim().replace(/^@+/, "")}`).join(", ")}.`
-          : "",
-        responseContract.require_visible_delegation_handoff === true
-          ? "Your first public reply must explicitly mention those exact bots and request their contribution now."
-          : "",
-        responseContract.require_visible_delegation_handoff === true
-          ? "Do not return only a human-facing clarification or information request without visibly addressing those bots."
-          : "",
-        responseContract.require_visible_delegation_handoff === true
-          ? "If information is incomplete, still open the public handoff and ask each target bot for a concise initial perspective based on the uncertainty."
-          : "",
         "Mentions and reply targets are routing hints, not proof that this bot should definitely answer.",
         conversation?.mode === "public_multi_bot"
           ? "This is a public multi-bot room conversation. Other bots and humans can read your reply."
@@ -2101,9 +2111,6 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
         "Use assignment.mode=\"conversation_contribution\" for opinions, discussion, review, comparison, synthesis, greetings, or other room-visible contributions that do not require workspace artifacts.",
         "Use assignment.mode=\"execution_task\" only when the delegated bot must change workspace files, create artifacts, update ctxpack, or produce other concrete project outputs. If it is an execution task, also set artifacts_required=true.",
         "Delegation contract example: {\"type\":\"delegation\",\"actionable\":true,\"assignments\":[{\"target_bot\":\"ryoai2_bot\",\"task\":\"briefly greet in one line\",\"mode\":\"conversation_contribution\",\"artifacts_required\":false}],\"next_responders\":[\"ryoai2_bot\"]}.",
-        ensureArray(responseContract.required_delegation_targets).length > 0
-          ? `This reply must delegate to these exact managed bots now: ${ensureArray(responseContract.required_delegation_targets).map((item) => `@${String(item || "").trim().replace(/^@+/, "")}`).join(", ")}.`
-          : "",
         String(responseContract.contract_hint || "").trim()
           ? `Contract requirement hint: ${String(responseContract.contract_hint || "").trim()}`
           : "",
@@ -2134,12 +2141,12 @@ export function buildLocalBotPrompt(payload, { terse = true } = {}) {
     "- When you include context_suggestion, set should_store=true and keep title/body concise and durable.",
     "",
     isInternalExecutionStep
-      ? "Return JSON only in one line: {\"reply\":\"what was completed in this step\",\"artifacts\":[{\"path\":\"relative/or/absolute/path\",\"kind\":\"plan|code|doc|spec|test\",\"operation\":\"create|update|delete\"}],\"ctxpack_files\":[{\"path\":\"relative/path.md\",\"content\":\"full document text\",\"doc_type\":\"guide|readme|agenda|rule|architecture|manifest\",\"operation\":\"create|update|delete\"}],\"work_items\":[{\"title\":\"short atomic task\",\"description\":\"useful implementation detail\"}],\"contract\":{\"type\":\"direct_result|summary_request|final_summary\",\"actionable\":true,\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}. Use ctxpack_files when ctxpack-backed guidance/instruction files must be authored. If execution_step.ctxpack_update_required is true, ctxpack_files must not be empty. Use artifacts: [] only if this step truly changes no project files, and use work_items: [] only if this step truly creates no governance tasks."
+      ? "Return strict JSON only in one line: {\"reply\":\"what was completed in this step\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"reply_outcome\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"direct_result|delegation|summary_request|final_summary|\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":true|false,\"turn_kind\":\"direct_reply|delegation_kickoff|delegated_followup|summary_turn|execution_step\",\"actionable_for_current_route\":true|false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"},\"artifacts\":[{\"path\":\"relative/or/absolute/path\",\"kind\":\"plan|code|doc|spec|test\",\"operation\":\"create|update|delete\"}],\"ctxpack_files\":[{\"path\":\"relative/path.md\",\"content\":\"full document text\",\"doc_type\":\"guide|readme|agenda|rule|architecture|manifest\",\"operation\":\"create|update|delete\"}],\"work_items\":[{\"title\":\"short atomic task\",\"description\":\"useful implementation detail\"}],\"contract\":{\"type\":\"direct_result|summary_request|final_summary\",\"actionable\":true,\"summary_bot\":\"username\",\"next_responders\":[\"username\"]}}. Use ctxpack_files when ctxpack-backed guidance/instruction files must be authored. If execution_step.ctxpack_update_required is true, ctxpack_files must not be empty. Use artifacts: [] only if this step truly changes no project files, and use work_items: [] only if this step truly creates no governance tasks."
       : responseContract.is_current_bot_candidate === true
-      ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[]} or {\"clarify\":\"...\"} or {\"skip\":true,\"reason\":\"...\"} or {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[],\"contract\":{\"type\":\"direct_result|delegation|summary_request|final_summary\",\"actionable\":true,\"assignments\":[{\"target_bot\":\"username\",\"task\":\"...\",\"mode\":\"conversation_contribution|execution_task\",\"artifacts_required\":true|false}],\"summary_bot\":\"username\",\"next_responders\":[\"username\"]},\"context_suggestion\":{\"should_store\":true,\"title\":\"...\",\"body\":\"...\",\"category\":\"bot_role|operating_rule|project_fact|current_focus|risk|general\",\"importance\":\"low|normal|high|critical\"}}."
+      ? "Return strict JSON only in one line: {\"reply\":\"...\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"reply_outcome\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"direct_result|delegation|summary_request|final_summary|\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":true|false,\"turn_kind\":\"direct_reply|delegation_kickoff|delegated_followup|summary_turn|clarify_turn\",\"actionable_for_current_route\":true|false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"},\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[]} or {\"clarify\":\"...\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"clarify\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"|delegation|summary_request|direct_result|final_summary\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":false,\"turn_kind\":\"clarify_turn\",\"actionable_for_current_route\":true|false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"}} or {\"skip\":true,\"reason\":\"...\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"skip\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"|delegation|summary_request|direct_result|final_summary\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":false,\"turn_kind\":\"skip\",\"actionable_for_current_route\":false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"}} or {\"reply\":\"...\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"reply_outcome\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"direct_result|delegation|summary_request|final_summary|\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":true|false,\"turn_kind\":\"direct_reply|delegation_kickoff|delegated_followup|summary_turn\",\"actionable_for_current_route\":true|false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"},\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[],\"contract\":{\"type\":\"direct_result|delegation|summary_request|final_summary\",\"actionable\":true,\"assignments\":[{\"target_bot\":\"username\",\"task\":\"...\",\"mode\":\"conversation_contribution|execution_task\",\"artifacts_required\":true|false}],\"summary_bot\":\"username\",\"next_responders\":[\"username\"]},\"context_suggestion\":{\"should_store\":true,\"title\":\"...\",\"body\":\"...\",\"category\":\"bot_role|operating_rule|project_fact|current_focus|risk|general\",\"importance\":\"low|normal|high|critical\"}}."
       : terse
-        ? "Return JSON only in one line: {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[],\"context_suggestion\":{\"should_store\":true,\"title\":\"...\",\"body\":\"...\",\"category\":\"bot_role|operating_rule|project_fact|current_focus|risk|general\",\"importance\":\"low|normal|high|critical\"}} or {\"clarify\":\"...\"} or {\"skip\":true,\"reason\":\"...\"}."
-        : "Return JSON only: {\"reply\":\"...\",\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[],\"context_suggestion\":{\"should_store\":true,\"title\":\"...\",\"body\":\"...\",\"category\":\"bot_role|operating_rule|project_fact|current_focus|risk|general\",\"importance\":\"low|normal|high|critical\"}} or {\"clarify\":\"...\"} or {\"skip\":true,\"reason\":\"...\"}. Keep the reply concise and directly useful in a group chat.",
+        ? "Return strict JSON only in one line: {\"reply\":\"...\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"reply_outcome\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"|delegation|summary_request|direct_result|final_summary\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":true|false,\"turn_kind\":\"direct_reply|delegation_kickoff|delegated_followup|summary_turn\",\"actionable_for_current_route\":true|false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"},\"artifacts\":[],\"ctxpack_files\":[],\"work_items\":[],\"context_suggestion\":{\"should_store\":true,\"title\":\"...\",\"body\":\"...\",\"category\":\"bot_role|operating_rule|project_fact|current_focus|risk|general\",\"importance\":\"low|normal|high|critical\"}} or {\"clarify\":\"...\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"clarify\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"|delegation|summary_request|direct_result|final_summary\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":false,\"turn_kind\":\"clarify_turn\",\"actionable_for_current_route\":true|false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"}} or {\"skip\":true,\"reason\":\"...\",\"decision_bundle\":{\"schema_version\":\"runner_conversation_decision.v1\",\"decision_type\":\"skip\",\"conversation_intent_mode\":\"single_bot|delegated_single_lead|multi_bot_collab|multi_bot_direct\",\"allowed_responders\":[\"username\"],\"initial_responders\":[\"username\"],\"selected_bot_usernames\":[\"username\"],\"allow_bot_to_bot\":true|false,\"execution_contract_type\":\"|delegation|summary_request|direct_result|final_summary\",\"execution_contract_targets\":[\"username\"],\"next_expected_responders\":[\"username\"],\"should_close_after_reply\":false,\"turn_kind\":\"skip\",\"actionable_for_current_route\":false,\"visible_handoff_required\":true|false,\"visible_handoff_targets\":[\"username\"],\"reasoning_summary\":\"short explanation\"}}."
+        : "Return strict JSON only. Every non-skip response must include a decision_bundle. Do not rely on code to rewrite your reply or add visible handoff mentions after generation.",
   );
   if (conversation?.mode === "public_multi_bot") {
     const roleGuidance = {

package/lib/runner-orchestration-decision-bundle.mjs

@@ -37,6 +37,13 @@ function firstNonBlankString(values) {
   return "";
 }
 
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return fallback;
+}
+
 function normalizeContractAssignments(assignmentsRaw) {
   return uniqueOrderedSelectors(
     ensureArray(assignmentsRaw).map((item) => {
@@ -48,31 +55,14 @@ function normalizeContractAssignments(assignmentsRaw) {
 
 export function normalizeRunnerConversationDecisionBundle(bundleRaw) {
   const bundle = safeObject(bundleRaw);
-  const executionContractTargets = uniqueOrderedSelectors([
-    ...ensureArray(bundle.execution_contract_targets),
-    ...normalizeContractAssignments(safeObject(bundle.execution_contract).assignments),
-  ]);
-  const nextExpectedResponders = uniqueOrderedSelectors([
-    ...ensureArray(bundle.next_expected_responders),
-    ...ensureArray(safeObject(bundle.execution_contract).nextResponders),
-    ...ensureArray(safeObject(bundle.execution_contract).next_responders),
-    ...ensureArray(safeObject(bundle.execution_contract).responders),
-    ...(
-      executionContractTargets.length > 0
-      && ["delegation", "summary_request", "direct_result"].includes(
-        String(bundle.execution_contract_type || safeObject(bundle.execution_contract).type || "").trim().toLowerCase(),
-      )
-        ? executionContractTargets
-        : []
-    ),
-  ]);
+  const executionContractTargets = uniqueOrderedSelectors(ensureArray(bundle.execution_contract_targets));
+  const nextExpectedResponders = uniqueOrderedSelectors(ensureArray(bundle.next_expected_responders));
   const executionContractType = String(
     bundle.execution_contract_type
       || safeObject(bundle.execution_contract).type
-      || (executionContractTargets.length > 0 ? "delegation" : "")
       || "",
   ).trim().toLowerCase();
-  const allowBotToBot = bundle.allow_bot_to_bot === true;
+  const allowBotToBot = normalizeBoolean(bundle.allow_bot_to_bot, false);
   const allowedResponders = uniqueOrderedSelectors(bundle.allowed_responders);
   const initialResponders = uniqueOrderedSelectors(bundle.initial_responders);
   const selectedBotUsernames = uniqueOrderedSelectors(
@@ -94,14 +84,16 @@ export function normalizeRunnerConversationDecisionBundle(bundleRaw) {
     allow_bot_to_bot: allowBotToBot,
     conversation_reply_expectation: String(bundle.conversation_reply_expectation || "").trim().toLowerCase(),
     execution_contract_type: executionContractType,
-    execution_contract_actionable: bundle.execution_contract_actionable === true
-      || executionContractTargets.length > 0
-      || nextExpectedResponders.length > 0,
+    execution_contract_actionable: normalizeBoolean(bundle.execution_contract_actionable, false),
     execution_contract_targets: executionContractTargets,
     next_expected_responders: nextExpectedResponders,
     should_close_after_reply: typeof bundle.should_close_after_reply === "boolean"
       ? bundle.should_close_after_reply
-      : nextExpectedResponders.length === 0,
+      : false,
+    turn_kind: String(bundle.turn_kind || "").trim().toLowerCase(),
+    actionable_for_current_route: normalizeBoolean(bundle.actionable_for_current_route, false),
+    visible_handoff_required: normalizeBoolean(bundle.visible_handoff_required, false),
+    visible_handoff_targets: uniqueOrderedSelectors(bundle.visible_handoff_targets),
     reasoning_summary: firstNonBlankString([bundle.reasoning_summary]),
   };
 }
@@ -162,6 +154,14 @@ export function validateRunnerConversationDecisionBundle(bundleRaw) {
       bundle,
     };
   }
+  if (bundle.visible_handoff_required === true && bundle.visible_handoff_targets.length === 0) {
+    return {
+      ok: false,
+      status: "missing_visible_handoff_targets",
+      reason: "visible_handoff_required needs visible_handoff_targets",
+      bundle,
+    };
+  }
   return {
     ok: true,
     status: "valid",
@@ -171,6 +171,7 @@ export function validateRunnerConversationDecisionBundle(bundleRaw) {
 }
 
 export function buildRunnerConversationDecisionBundle({
+  decisionBundle = null,
   decisionType = "",
   normalizedIntent = "",
   humanIntent = null,
@@ -184,6 +185,9 @@ export function buildRunnerConversationDecisionBundle({
   shouldCloseAfterReply,
   reasoningSummary = "",
 }) {
+  if (Object.keys(safeObject(decisionBundle)).length > 0) {
+    return normalizeRunnerConversationDecisionBundle(decisionBundle);
+  }
   const intent = safeObject(humanIntent);
   const conversation = safeObject(conversationContext);
   const contract = safeObject(executionContract);
@@ -244,7 +248,11 @@ export function buildRunnerConversationDecisionBundle({
 }
 
 export function resolveRunnerConversationDecisionBundle(options = {}) {
-  const bundle = buildRunnerConversationDecisionBundle(options);
+  const explicitBundle = safeObject(options.decisionBundle || options.decision_bundle);
+  const bundle = buildRunnerConversationDecisionBundle({
+    ...options,
+    decisionBundle: Object.keys(explicitBundle).length ? explicitBundle : null,
+  });
   const validation = validateRunnerConversationDecisionBundle(bundle);
   return {
     decisionBundle: validation.ok ? validation.bundle : bundle,