@manny-est/node-red-flowpilot 0.5.2 → 0.6.0

package/flowpilot.js

@@ -1,5 +1,7 @@
 const http = require("http");
+const https = require("https");
 const path = require("path");
+const PACKAGE_VERSION = require("./package.json").version;
 const createStorage = require("./lib/storage");
 const openaiProvider = require("./lib/provider-openai-compatible");
 const anthropicProvider = require("./lib/provider-anthropic");
@@ -72,8 +74,120 @@ const modifySystemPrompt = require("./lib/modify-system-prompt");
 const buildSystemPrompt = require("./lib/build-system-prompt");
 const personaPrompt = require("./lib/persona-prompt");
 const { buildCoreScript } = require("./lib/build-core-script");
+const {
+  createChatDataStreamSplitter,
+  findChatDataMarker,
+  splitChatDataBlock
+} = require("./lib/chat-data");
 const { extractJsonObject } = require("./lib/envelope");
 const { repairEnvelope } = require("./lib/validator");
+const { enforceAgentContract } = require("./lib/agent-contract");
+const { isProviderShapedResponse } = require("./lib/provider-shape-check");
+const API_KEY_UNCHANGED = createStorage.API_KEY_UNCHANGED;
+const UPDATE_CHECK_URL = "https://registry.npmjs.org/-/package/@manny-est/node-red-flowpilot/dist-tags";
+const UPDATE_CHECK_SUCCESS_TTL_MS = 6 * 60 * 60 * 1000;
+const UPDATE_CHECK_FAILURE_TTL_MS = 15 * 60 * 1000;
+const RUN_EVENTS_MAX_STORED = 50;
+const runEventsStore = new Map();
+let updateCheckCache = null;
+
+function parseVersion(v) {
+  var parts = String(v).split("-");
+  var core = parts[0].split(".").map(Number);
+  var pre = parts.length > 1 ? parts.slice(1).join("-").split(".") : null;
+  return { core: core, pre: pre };
+}
+
+function isNewer(remoteVersion, localVersion) {
+  var r = parseVersion(remoteVersion), l = parseVersion(localVersion);
+  for (var i = 0; i < 3; i++) {
+    var rv = r.core[i] || 0, lv = l.core[i] || 0;
+    if (rv !== lv) { return rv > lv; }
+  }
+  // core version numbers are equal
+  if (!r.pre && l.pre) { return true; }   // remote is a full release, local is a prerelease of the same core
+  if (r.pre && !l.pre) { return false; }  // remote is a prerelease, local is already past it
+  if (!r.pre && !l.pre) { return false; } // identical plain releases
+  // both are prereleases of the same core version — compare the last dot segment numerically if possible
+  var rn = Number(r.pre[r.pre.length - 1]);
+  var ln = Number(l.pre[l.pre.length - 1]);
+  if (!isNaN(rn) && !isNaN(ln)) { return rn > ln; }
+  return r.pre.join(".") !== l.pre.join(".") && r.pre.join(".") > l.pre.join(".");
+}
+
+function updateCheckFallbackResponse() {
+  return { enabled: true, updateAvailable: false };
+}
+
+function fetchUpdateDistTags() {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(UPDATE_CHECK_URL);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+
+    const req = https.request({
+      method: "GET",
+      hostname: url.hostname,
+      port: url.port || 443,
+      path: url.pathname + url.search,
+      headers: { Accept: "application/json" }
+    }, (res) => {
+      let data = "";
+      res.setEncoding("utf8");
+      res.on("data", chunk => { data += chunk; });
+      res.on("end", () => {
+        let parsed = null;
+        try {
+          parsed = data ? JSON.parse(data) : null;
+        } catch (err) {
+          reject(err);
+          return;
+        }
+        if (res.statusCode !== 200 || !parsed || typeof parsed !== "object") {
+          reject(new Error("Update check failed."));
+          return;
+        }
+        resolve(parsed);
+      });
+    });
+
+    req.on("error", reject);
+    req.setTimeout(5000, () => {
+      req.destroy(new Error("Timeout"));
+    });
+    req.end();
+  });
+}
+
+async function performUpdateCheck() {
+  try {
+    const distTags = await fetchUpdateDistTags();
+    const tag = PACKAGE_VERSION.indexOf("-") !== -1 ? "beta" : "latest";
+    const tagVersion = distTags && distTags[tag];
+    if (typeof tagVersion !== "string" || !tagVersion) {
+      throw new Error("Missing dist-tag.");
+    }
+    return {
+      succeeded: true,
+      result: {
+        enabled: true,
+        updateAvailable: isNewer(tagVersion, PACKAGE_VERSION),
+        latestVersion: tagVersion,
+        currentVersion: PACKAGE_VERSION,
+        tag: tag
+      }
+    };
+  } catch (err) {
+    return {
+      succeeded: false,
+      result: updateCheckFallbackResponse()
+    };
+  }
+}
 
 module.exports = function flowPilotRuntime(RED) {
   const storage = createStorage(RED.settings.userDir);
@@ -91,12 +205,11 @@ module.exports = function flowPilotRuntime(RED) {
     "that may have been said earlier, ask the user.";
 
   // ---------------------------------------------------------------------
-  // Tier-1 READ tools the model may call autonomously during
-  // a chat turn. Their data (RED.nodes, live selection, debug buffer) lives
-  // only in the editor, so each call is executed CLIENT-SIDE and its result
-  // passed back through the same sanitizer as selection context — a tool
-  // result can never carry a raw secret. WRITE actions are never exposed as
-  // tools; they stay on the existing diff/review/apply envelope.
+  // Tier-1 READ tools the model may call autonomously. Their data
+  // (RED.nodes, live selection, debug buffer) lives only in the editor, so
+  // each call is executed CLIENT-SIDE and its result passed back through the
+  // same sanitizer as selection context — a tool result can never carry a
+  // raw secret.
   // ---------------------------------------------------------------------
   const AGENT_READ_TOOLS = [
     {
@@ -205,6 +318,250 @@ module.exports = function flowPilotRuntime(RED) {
     }
   ];
 
+  // W7 Round 1 WRITE tools. One call represents one plan/todo item: a small
+  // coherent bundle, never one call per field. `tier` is FlowPilot metadata,
+  // not part of either provider's tool schema; providerToolDefinitions()
+  // strips it before the request leaves the server. The client combines this
+  // registry tier with classifyFlowNodes-equivalent per-call node safety so a
+  // write-gated call only prompts when it actually touches an unsafe type.
+  const WRITE_TOOLS = [
+    {
+      tier: "write-gated",
+      type: "function",
+      function: {
+        name: "apply_step",
+        description: "Apply ONE plan item as a small bundle of sparse " +
+          "property patches, at most one new node, and its immediate wires. " +
+          "Use one call for the whole item, not one call per field. Existing " +
+          "wire removal/replacement is expressed as a sparse " +
+          "changes[].set.wires final value.",
+        parameters: {
+          type: "object",
+          properties: {
+            summary: {
+              type: "string",
+              description: "Short todo-item description of this step."
+            },
+            changes: {
+              type: "array",
+              description: "Sparse patches for existing nodes.",
+              items: {
+                type: "object",
+                properties: {
+                  id: { type: "string" },
+                  set: { type: "object", additionalProperties: true }
+                },
+                required: ["id", "set"],
+                additionalProperties: false
+              }
+            },
+            newNodes: {
+              type: "array",
+              description: "At most one new node for this step, using a temporary id.",
+              items: {
+                type: "object",
+                properties: {
+                  id: { type: "string" },
+                  type: { type: "string" }
+                },
+                required: ["id", "type"],
+                additionalProperties: true
+              }
+            },
+            newWires: {
+              type: "array",
+              description: "Immediate wires for this step; ids may refer to " +
+                "existing nodes or newNodes temporary ids.",
+              items: {
+                type: "object",
+                properties: {
+                  from: { type: "string" },
+                  fromPort: { type: "integer", minimum: 0 },
+                  to: { type: "string" }
+                },
+                required: ["from", "fromPort", "to"],
+                additionalProperties: false
+              }
+            }
+          },
+          required: ["summary"],
+          additionalProperties: false
+        }
+      }
+    },
+    {
+      tier: "write-gated",
+      type: "function",
+      function: {
+        name: "remove_step",
+        description: "Remove one node as ONE plan item. Its connected wires " +
+          "are removed with it by the existing editor apply path.",
+        parameters: {
+          type: "object",
+          properties: {
+            summary: {
+              type: "string",
+              description: "Short todo-item description of this removal."
+            },
+            nodeId: { type: "string", description: "Existing node id to remove." }
+          },
+          required: ["summary", "nodeId"],
+          additionalProperties: false
+        }
+      }
+    },
+    {
+      tier: "write-gated",
+      type: "function",
+      function: {
+        name: "rename_node",
+        description: "Rename one existing node as ONE plan item.",
+        parameters: {
+          type: "object",
+          properties: {
+            summary: {
+              type: "string",
+              description: "Short todo-item description of this rename."
+            },
+            nodeId: { type: "string", description: "Existing node id to rename." },
+            name: { type: "string", description: "Exact final node name." }
+          },
+          required: ["summary", "nodeId", "name"],
+          additionalProperties: false
+        }
+      }
+    },
+    {
+      // ADR-003 R3a: grouping is visual-only, classified safe (auto-apply)
+      // regardless of which node types are grouped — "write-safe" here means
+      // "never eligible for consent-gating" (the mechanism
+      // writeToolCallNeedsConsent actually keys on), not "non-mutating" —
+      // this call does mutate (creates a group, pushes history), unlike
+      // ask_user, the tier's other current member.
+      tier: "write-safe",
+      type: "function",
+      function: {
+        name: "group_nodes",
+        description: "Create a new named group from existing, already-verified " +
+          "node ids. No nested groups (a group id among nodeIds) and no " +
+          "editing an existing group's membership — both are reported as an " +
+          "unsupported_operation instead of attempted.",
+        parameters: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Name for the new group." },
+            nodeIds: {
+              type: "array",
+              description: "Existing node ids to include in the new group.",
+              items: { type: "string" },
+              minItems: 1
+            }
+          },
+          required: ["name", "nodeIds"],
+          additionalProperties: false
+        }
+      }
+    },
+    {
+      tier: "write-safe",
+      type: "function",
+      function: {
+        name: "redirect_mode",
+        description: "End this Modify agent turn without mutating anything " +
+          "and redirect the user to Generate, Document, or Chat instead.",
+        parameters: {
+          type: "object",
+          properties: {
+            mode: {
+              type: "string",
+              enum: ["generate", "document", "chat"],
+              description: "The mode this request actually belongs in."
+            },
+            prompt: {
+              type: "string",
+              description: "Ready-to-send prompt to prefill after switching modes."
+            },
+            explanation: {
+              type: "string",
+              description: "Visible reply shown to the user before the redirect chip."
+            },
+            selectionHint: {
+              type: "string",
+              description: "Optional selection guidance for Document redirects."
+            },
+            targetNodeIds: {
+              oneOf: [
+                { type: "string", enum: ["all", "instance"] },
+                {
+                  type: "array",
+                  items: { type: "string" },
+                  minItems: 1
+                }
+              ],
+              description: "Optional resolved node target for Document redirects. " +
+                "\"all\" is the entire active flow/tab; \"instance\" is every flow " +
+                "tab in the whole Node-RED instance. Omit when the scope genuinely " +
+                "can't be resolved from context."
+            }
+          },
+          required: ["mode", "prompt", "explanation"],
+          additionalProperties: false
+        }
+      }
+    },
+    {
+      tier: "write-safe",
+      type: "function",
+      function: {
+        name: "ask_user",
+        description: "Ask the user a clarifying question, pause this loop, " +
+          "and resume with their answer. This does not mutate the flow.",
+        parameters: {
+          type: "object",
+          properties: {
+            question: { type: "string" },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional short answer choices."
+            }
+          },
+          required: ["question"],
+          additionalProperties: false
+        }
+      }
+    }
+  ];
+
+  function providerToolDefinitions(tools) {
+    return tools.map(function (tool) {
+      return { type: tool.type, function: tool.function };
+    });
+  }
+
+  function agentToolsFor(settings, activeProvider, mode, writesAllowed) {
+    const writesEnabled = settings.enableAgentWrite === true &&
+      (mode === "modify" || mode === "generate") && writesAllowed !== false &&
+      activeProvider && activeProvider.supportsTools === true;
+    return providerToolDefinitions(AGENT_READ_TOOLS.concat(writesEnabled ? WRITE_TOOLS : []));
+  }
+
+  function toolTierMap(toolCalls) {
+    if (!Array.isArray(toolCalls) || !toolCalls.length) { return null; }
+    const tiersByName = {};
+    WRITE_TOOLS.forEach(function (tool) {
+      tiersByName[tool.function.name] = tool.tier;
+    });
+    const byCallId = {};
+    toolCalls.forEach(function (call) {
+      const name = call && call.function && call.function.name;
+      if (call && call.id && tiersByName[name]) {
+        byCallId[call.id] = tiersByName[name];
+      }
+    });
+    return Object.keys(byCallId).length ? byCallId : null;
+  }
+
   // Keep only well-formed { role: "user"|"assistant", content: <string> }
   // entries. Anything else (bad shapes, empty content, other roles) is
   // dropped rather than rejected outright — the history is advisory context,
@@ -548,27 +905,22 @@ module.exports = function flowPilotRuntime(RED) {
     return clean;
   }
 
-  // W0.4: when logAssembledPrompts is enabled, append one JSON-lines entry to
-  // assembled-prompts.log. Called after each provider round-trip with both
-  // the outgoing messages and the raw response content. Auth keys are never
-  // included — only baseUrl + model from the provider profile.
-  function maybeLogAssembledPrompt(mode, messages, responseContent, parseOutcome, activeProvider) {
+  // Append a provider-turn event to debug.log when debugLogging is enabled.
+  // Callers pass only post-redaction messages/content and non-secret provider
+  // metadata; auth keys and headers must never be included.
+  function maybeLogDebugEvent(type, fields) {
     const settings = storage.getSettings();
-    if (!settings.logAssembledPrompts) { return; }
+    if (!settings.debugLogging) { return; }
+    fields = fields || {};
+    const messages = fields.messages || [];
     const promptChars = (messages || []).reduce(function (sum, m) {
       return sum + (m && typeof m.content === "string" ? m.content.length : 0);
     }, 0);
-    storage.appendAssembledPromptLog({
-      mode: mode,
-      providerBaseUrl: activeProvider && activeProvider.baseUrl,
-      model: activeProvider && activeProvider.model,
+    storage.appendDebugLog(Object.assign({
+      type: type,
       promptTokenEst: Math.round(promptChars / 4),
-      messageCount: (messages || []).length,
-      messages: messages,
-      responseChars: typeof responseContent === "string" ? responseContent.length : 0,
-      responseContent: responseContent,
-      parseOutcome: parseOutcome
-    });
+      messageCount: messages.length
+    }, fields));
   }
 
   // W0.1: warn when estimated prompt token count approaches the provider's
@@ -595,10 +947,78 @@ module.exports = function flowPilotRuntime(RED) {
   // Returns null when there's no selection — used by both /chat and
   // /generate so the two describe context identically and never drift.
   // ---------------------------------------------------------------------
-  function describeSelectionContext(context, redactionEnabled) {
+  function maxSelectionContextChars(settings) {
+    const configured = Number(settings && settings.maxContextChars);
+    return Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : 12000;
+  }
+
+  function joinSelectionContextSections(sections) {
+    return sections
+      .filter(function (section) { return !!section && typeof section.content === "string" && section.content.length > 0; })
+      .map(function (section) { return section.content; })
+      .join("\n\n");
+  }
+
+  function selectionContextTruncationNote(maxChars, omittedSections, hardCutoff) {
+    let note = "\n\n[FlowPilot truncated selection context to fit maxContextChars=" + maxChars + ".";
+    if (omittedSections.length) {
+      note += " Omitted sections: " + omittedSections.join(", ") + ".";
+    }
+    if (hardCutoff) {
+      note += " Remaining content was hard-cut and may end mid-JSON.";
+    }
+    return note + "]";
+  }
+
+  function truncateSelectionContext(sections, maxChars) {
+    let activeSections = (sections || []).filter(function (section) { return !!section; });
+    let content = joinSelectionContextSections(activeSections);
+    if (!maxChars || maxChars <= 0 || content.length <= maxChars) {
+      return { content: content, truncated: false };
+    }
+
+    const omittedSections = [];
+    ["debug", "config", "perNode", "edges", "subflows"].forEach(function (key) {
+      if (content.length <= maxChars) { return; }
+      const nextSections = [];
+      let removed = false;
+      activeSections.forEach(function (section) {
+        if (!removed && section.key === key && section.required !== true) {
+          removed = true;
+          omittedSections.push(section.label);
+          return;
+        }
+        nextSections.push(section);
+      });
+      if (removed) {
+        activeSections = nextSections;
+        content = joinSelectionContextSections(activeSections);
+      }
+    });
+
+    if (content.length <= maxChars) {
+      const note = selectionContextTruncationNote(maxChars, omittedSections, false);
+      if (content.length + note.length <= maxChars) {
+        content += note;
+      }
+      return { content: content, truncated: true };
+    }
+
+    const hardCutNote = selectionContextTruncationNote(maxChars, omittedSections, true);
+    if (hardCutNote.length >= maxChars) {
+      return { content: content.slice(0, maxChars), truncated: true };
+    }
+    return {
+      content: content.slice(0, maxChars - hardCutNote.length) + hardCutNote,
+      truncated: true
+    };
+  }
+
+  function describeSelectionContext(context, settings) {
     const nodes = context && Array.isArray(context.nodes) ? context.nodes : [];
     const debugMessages = context && Array.isArray(context.debugMessages) ? context.debugMessages : [];
     if (nodes.length === 0 && debugMessages.length === 0) { return null; }
+    settings = settings || {};
 
     const connections = (context && context.connections) ? context.connections : {};
     const edges = Array.isArray(connections.edges) ? connections.edges : [];
@@ -610,7 +1030,7 @@ module.exports = function flowPilotRuntime(RED) {
     // changes. redactionEnabled only controls the SEPARATE secret-shaped-value
     // scrubbing (password/token/apiKey-looking fields elsewhere in a node's
     // config) — tell the model the truth about which protection is active.
-    const credentialNote = redactionEnabled === false
+    const credentialNote = settings.redactionEnabled === false
       ? "Redaction is OFF for this session — context may contain sensitive " +
         "values the user chose to share (e.g. embedded API keys or tokens); " +
         "handle carefully and never volunteer them. Node-RED's separate " +
@@ -621,47 +1041,104 @@ module.exports = function flowPilotRuntime(RED) {
         "(it requires re-confirming a type-to-confirm phrase, by design)."
       : "This is sanitized configuration; credentials are redacted.";
 
-    let content = "";
+    const sections = [];
     if (nodes.length > 0) {
-      content += "The user has selected the following Node-RED nodes as context. " +
-                credentialNote + "\n\n" +
-                "Nodes:\n```json\n" + JSON.stringify(nodes) + "\n```";
+      sections.push({
+        key: "nodes",
+        label: "selected nodes",
+        required: true,
+        content: "The user has selected the following Node-RED nodes as context. " +
+          credentialNote + "\n\n" +
+          "Nodes:\n```json\n" + JSON.stringify(nodes) + "\n```"
+      });
       if (edges.length > 0) {
-        content += "\n\nConnections — directed edges by node id (a node's wires " +
-               "describe its OUTPUTS; one edge per output port; fromId/toId refer " +
-               "to the \"id\" fields in Nodes above):\n```json\n" +
-               JSON.stringify(edges) + "\n```";
-        content += "\n\nPer-node wiring summary, with readable \"Name [type]\" " +
-               "labels (inputs are reconstructed, since Node-RED nodes do not " +
-               "store their own inputs; subFlow groups nodes into connected " +
-               "sub-flows):\n```json\n" +
-               JSON.stringify(perNode) + "\n```";
+        sections.push({
+          key: "edges",
+          label: "connection edges",
+          content: "Connections — directed edges by node id (a node's wires " +
+            "describe its OUTPUTS; one edge per output port; fromId/toId refer " +
+            "to the \"id\" fields in Nodes above):\n```json\n" +
+            JSON.stringify(edges) + "\n```"
+        });
+        sections.push({
+          key: "perNode",
+          label: "per-node wiring summary",
+          content: "Per-node wiring summary, with readable \"Name [type]\" " +
+            "labels (inputs are reconstructed, since Node-RED nodes do not " +
+            "store their own inputs; subFlow groups nodes into connected " +
+            "sub-flows):\n```json\n" +
+            JSON.stringify(perNode) + "\n```"
+        });
       }
       if (subFlowCount > 1) {
-        content += "\n\nNote: the selection contains " + subFlowCount + " separate, " +
-               "unconnected sub-flows (see each node's subFlow number). Treat " +
-               "them as distinct unless the user says otherwise.";
+        sections.push({
+          key: "subflows",
+          label: "sub-flow note",
+          content: "Note: the selection contains " + subFlowCount + " separate, " +
+            "unconnected sub-flows (see each node's subFlow number). Treat " +
+            "them as distinct unless the user says otherwise."
+        });
       }
     }
 
-    const configNodes = (context && Array.isArray(context.configNodes)) ? context.configNodes : [];
+    const configNodes = settings.allowConfigContext === true &&
+      context && Array.isArray(context.configNodes) ? context.configNodes : [];
     if (configNodes.length > 0) {
-      content += (content ? "\n\n" : "") +
-             "Config nodes referenced by the selection (shared configuration " +
-             "objects not shown on the canvas; credentials are redacted). " +
-             "Use a config node's \"id\" to point an existing node at it via " +
-             "a \"changes\" patch, or create a new one via \"newNodes\":\n```json\n" +
-             JSON.stringify(configNodes) + "\n```";
+      sections.push({
+        key: "config",
+        label: "config nodes",
+        required: sections.length === 0,
+        content: "Config nodes referenced by the selection (shared configuration " +
+          "objects not shown on the canvas; credentials are redacted). " +
+          "Use a config node's \"id\" to point an existing node at it via " +
+          "a \"changes\" patch, or create a new one via \"newNodes\":\n```json\n" +
+          JSON.stringify(configNodes) + "\n```"
+      });
     }
 
     if (debugMessages.length > 0) {
-      content += (content ? "\n\n" : "") +
-             "The user attached recent Node-RED Debug sidebar output for " +
-             "troubleshooting (runtime data, may be truncated):\n```json\n" +
-             JSON.stringify(debugMessages) + "\n```";
+      sections.push({
+        key: "debug",
+        label: "debug messages",
+        required: sections.length === 0,
+        content: "The user attached recent Node-RED Debug sidebar output for " +
+          "troubleshooting (runtime data, may be truncated):\n```json\n" +
+          JSON.stringify(debugMessages) + "\n```"
+      });
     }
 
-    return { content: content, nodeCount: nodes.length, connectionCount: edges.length, debugMessageCount: debugMessages.length };
+    const limited = truncateSelectionContext(sections, maxSelectionContextChars(settings));
+    return {
+      content: limited.content,
+      nodeCount: nodes.length,
+      connectionCount: edges.length,
+      debugMessageCount: debugMessages.length,
+      truncated: limited.truncated
+    };
+  }
+
+  const AGENT_TRUNCATION_NUDGE =
+    "your last reply was cut off — emit ONLY the tool call";
+
+  function agentTurnOptions(settings, options) {
+    const configured = Number(settings.agentTurnMaxTokens);
+    return Object.assign({}, options || {}, {
+      maxTokens: Number.isInteger(configured) && configured > 0 ? configured : 4096
+    });
+  }
+
+  async function chatWithAgentCap(provider, activeProvider, messages, options) {
+    const first = await provider.chat(activeProvider, messages, options);
+    if (first.finishReason !== "length") { return first; }
+
+    const retryMessages = messages.concat([
+      { role: "system", content: AGENT_TRUNCATION_NUDGE }
+    ]);
+    const retry = await provider.chat(activeProvider, retryMessages, options);
+    if (retry.finishReason === "length") {
+      retry.fallbackToClassic = true;
+    }
+    return retry;
   }
 
   // ---------------------------------------------------------------------
@@ -669,28 +1146,56 @@ module.exports = function flowPilotRuntime(RED) {
   // log it, and return the result. Used by both /chat and /test so the two
   // never drift apart. contextMode is recorded for the audit trail.
   // ---------------------------------------------------------------------
-  // useTools: when true, the request offers AGENT_READ_TOOLS
+  // useTools: when true and the active provider supports native tools, the
+  // request offers the mode-appropriate agent tools
   // with tool_choice "auto". If the provider responds with tool_calls instead
   // of a final message, we return early with `toolCalls` + the `messages`
   // array built so far (so the caller/frontend can append the tool results
   // and continue via /flowpilot/agent-step) — nothing is recorded to the
   // transcript yet, since this isn't the final answer for the turn.
-  async function runChat(prompt, contextMode, context, history, historyTruncated, conversationId, useTools) {
+  async function runChat(prompt, contextMode, context, history, historyTruncated, conversationId, useTools, strategy) {
     const settings = storage.getSettings();
     const activeProvider = storage.getActiveProvider(settings);
 
-    const described = describeSelectionContext(context, settings.redactionEnabled);
+    // Shared with /flowpilot/test (contextMode === "connectivity-test"),
+    // which IS the confirming check itself and is exempt — every other
+    // caller (/flowpilot/chat) is a real operational request and gated.
+    if (contextMode !== "connectivity-test" && !isProviderConfirmed(activeProvider)) {
+      throw providerUnconfirmedError();
+    }
+
+    const described = describeSelectionContext(context, settings);
     const messages = buildMessages(
       buildChatSystemPrompt(settings),
       history, historyTruncated, described, prompt
     );
     warnNumCtxOverflow(messages, activeProvider, "chat");
 
-    const chatOptions = useTools ? { tools: AGENT_READ_TOOLS, toolChoice: "auto" } : undefined;
-    const result = await getProvider(activeProvider).chat(activeProvider, messages, chatOptions);
+    const toolsEnabled = !!useTools && activeProvider.supportsTools === true;
+    let chatOptions = toolsEnabled
+      ? { tools: agentToolsFor(settings, activeProvider, "chat"), toolChoice: "auto" }
+      : undefined;
+    const provider = getProvider(activeProvider);
+    let result;
+    if (strategy === "agent") {
+      chatOptions = agentTurnOptions(settings, chatOptions);
+      result = await chatWithAgentCap(provider, activeProvider, messages, chatOptions);
+    } else {
+      result = await provider.chat(activeProvider, messages, chatOptions);
+    }
 
-    if (result.toolCalls) {
+    if (result.toolCalls || result.fallbackToClassic) {
       const perf = performanceAuditFields(messages, result.content, result);
+      if (result.toolCalls) {
+        maybeLogDebugEvent("tool_call", {
+          mode: "chat",
+          providerBaseUrl: activeProvider.baseUrl,
+          model: activeProvider.model,
+          messages: messages,
+          toolCalls: result.toolCalls,
+          responseContent: result.content || null
+        });
+      }
       return { settings, activeProvider, result, perf, messages, toolCalls: result.toolCalls };
     }
 
@@ -700,6 +1205,15 @@ module.exports = function flowPilotRuntime(RED) {
     const split = splitChatDataBlock(result.content || "");
 
     recordTranscriptTurn(conversationId, "chat", prompt, split.message);
+    maybeLogDebugEvent("assistant_reply", {
+      mode: "chat",
+      providerBaseUrl: activeProvider.baseUrl,
+      model: activeProvider.model,
+      messages: messages,
+      responseChars: typeof result.content === "string" ? result.content.length : 0,
+      responseContent: result.content || "",
+      parseOutcome: "received"
+    });
 
     const perf = performanceAuditFields(messages, result.content, result);
 
@@ -717,7 +1231,13 @@ module.exports = function flowPilotRuntime(RED) {
     const settings = storage.getSettings();
     const activeProvider = storage.getActiveProvider(settings);
 
-    const described = describeSelectionContext(context, settings.redactionEnabled);
+    // Checked before any SSE headers are written, so the caller's catch
+    // block can still send a normal JSON 409 (res.headersSent is false).
+    if (!isProviderConfirmed(activeProvider)) {
+      throw providerUnconfirmedError();
+    }
+
+    const described = describeSelectionContext(context, settings);
     const messages = buildMessages(
       buildChatSystemPrompt(settings),
       history, historyTruncated, described, prompt
@@ -788,18 +1308,77 @@ module.exports = function flowPilotRuntime(RED) {
     }, performanceAuditFields(messages, full, streamResult)));
 
     recordTranscriptTurn(conversationId, "chat", prompt, visibleText);
+    maybeLogDebugEvent("assistant_reply", {
+      mode: "chat-stream",
+      providerBaseUrl: activeProvider.baseUrl,
+      model: activeProvider.model,
+      messages: messages,
+      responseChars: typeof full === "string" ? full.length : 0,
+      responseContent: full || "",
+      parseOutcome: "received"
+    });
   }
 
   // ---- Settings: read --------------------------------------------------
 
+  // Never let a real provider apiKey reach an HTTP response — storage's own
+  // getSettings()/saveSettings() still return the real key internally
+  // (getActiveProvider -> provider.chat depends on it), this masks ONLY the
+  // two client-facing routes below. hasApiKey lets the UI show "a key is
+  // saved" without ever receiving it; API_KEY_UNCHANGED is what the client
+  // echoes back on save to mean "leave it alone" (see
+  // reconcileProviderSecrets in lib/storage.js, the other half of this).
+  function maskProviderSecrets(settings) {
+    const masked = Object.assign({}, settings);
+    masked.providers = (Array.isArray(settings.providers) ? settings.providers : []).map(function (p) {
+      const hasApiKey = !!(p && p.apiKey && String(p.apiKey).trim());
+      const next = Object.assign({}, p);
+      next.apiKey = hasApiKey ? API_KEY_UNCHANGED : "";
+      next.hasApiKey = hasApiKey;
+      return next;
+    });
+    return masked;
+  }
+
   RED.httpAdmin.get("/flowpilot/settings", RED.auth.needsPermission("settings.read"), function (req, res) {
     try {
-      res.json(storage.getSettings());
+      const responseBody = maskProviderSecrets(storage.getSettings());
+      responseBody.flowpilotVersion = PACKAGE_VERSION;
+      res.json(responseBody);
     } catch (err) {
       res.status(500).json({ error: err.message });
     }
   });
 
+  RED.httpAdmin.get("/flowpilot/update-check", RED.auth.needsPermission("settings.read"), async function (req, res) {
+    const settings = storage.getSettings();
+    if (settings.checkForUpdates === false) {
+      res.json({ enabled: false });
+      return;
+    }
+
+    const now = Date.now();
+    if (updateCheckCache) {
+      const ageMs = now - updateCheckCache.checkedAt;
+      if (updateCheckCache.succeeded && ageMs < UPDATE_CHECK_SUCCESS_TTL_MS) {
+        res.json(updateCheckCache.result);
+        return;
+      }
+      if (!updateCheckCache.succeeded && ageMs < UPDATE_CHECK_FAILURE_TTL_MS) {
+        res.json(updateCheckFallbackResponse());
+        return;
+      }
+    }
+
+    const check = await performUpdateCheck();
+    updateCheckCache = {
+      checkedAt: now,
+      succeeded: check.succeeded,
+      result: check.result
+    };
+    res.json(check.result);
+  });
+
   // ---- Settings: default system prompt (for "Reset to default") -------
 
   RED.httpAdmin.get("/flowpilot/default-system-prompt", RED.auth.needsPermission("settings.read"), function (req, res) {
@@ -810,6 +1389,11 @@ module.exports = function flowPilotRuntime(RED) {
     }
   });
 
+  RED.httpAdmin.get("/flowpilot/run-events/:runId", RED.auth.needsPermission("settings.read"), function (req, res) {
+    const runId = req.params.runId;
+    res.json({ runId: runId, events: runEventsStore.get(runId) || [] });
+  });
+
   // ---- Pop-out window (Phase 8.5 C1, v1 review-only) -------------------
   // Serves the shared renderer (flowpilot-core.js, the same script
   // flowpilot.html loads for the sidebar) plus its stylesheet and the
@@ -848,18 +1432,118 @@ module.exports = function flowPilotRuntime(RED) {
     res.sendFile(path.join(__dirname, "lib", "popout", "view.html"));
   });
 
+  // Scoped to /flowpilot/* specifically — RED.httpAdmin is Node-RED's own
+  // shared admin app, so an unscoped .use() here would also intercept
+  // malformed-JSON errors on core Node-RED admin routes (flow deploy, node
+  // install, etc.), well beyond this ticket's intent to harden FlowPilot's
+  // own endpoints.
+  // CODEX-027 follow-up: a scoped RED.httpAdmin.use(errorHandler) here
+  // (tried both with and without a "/flowpilot" path prefix) never actually
+  // intercepted a malformed-JSON body-parse error live — Express's own
+  // default HTML error page still won, for every /flowpilot/* route tested,
+  // meaning Node-RED's core httpAdmin setup already fully resolves that
+  // error (parser -> its own handler -> response sent) before a route
+  // registered by a loaded plugin ever gets a chance to react, regardless
+  // of where among the plugin's own routes it's positioned. Reverted rather
+  // than ship a handler that silently never fires. The two higher-value
+  // parts of this ticket (empty-body validation, 404s for missing
+  // conversations) are real and verified working; malformed-JSON responses
+  // still return Express's default HTML page, not clean JSON — flagged as
+  // a known limitation, not fixed by this ticket.
+
+  // ---- Provider confirmation gate (ADR-007, SSRF mitigation) -----------
+  // No operational request (chat/generate/modify/document/build/agent-step)
+  // touches a provider's baseUrl until that exact URL has passed a real
+  // FlowPilot provider check — see isProviderShapedResponse
+  // (lib/provider-shape-check.js) below
+  // and /flowpilot/test, /flowpilot/probe, /flowpilot/models — the only
+  // three routes allowed to contact an unconfirmed URL. The first two
+  // WRITE confirmedBaseUrl/confirmedAt on a passing check (the deliberate
+  // confirming action); /flowpilot/models never does — it's read-only
+  // reconnaissance (listing available models), safe to allow pre-confirmation
+  // the same way /probe is, but not itself a confirmation. All three stay
+  // safe against an unconfirmed/malicious target the same way: a strict
+  // shape check on any "success" response (isProviderShapedResponse for
+  // chat-shaped, isModelsListShaped for a models list) and a generic,
+  // never-reflects-the-body error on failure (enforced at the shared HTTP
+  // client layer in lib/provider-*.js). lib/storage.js's
+  // reconcileProviderSecrets is the other half — it strips any
+  // client-supplied confirmedBaseUrl/confirmedAt on save and clears
+  // confirmation whenever baseUrl or apiKey actually changes, so
+  // confirmation can never be forged or silently carried over to a
+  // different URL.
+
+  function isProviderConfirmed(provider) {
+    // typeof check, not truthiness: baseUrl "" is a real, documented,
+    // supported value (Anthropic's "leave blank for api.anthropic.com"
+    // convention) — a provider CAN be legitimately confirmed with an empty
+    // confirmedBaseUrl, and `"" && ...` would silently evaluate false,
+    // locking that configuration out of confirmation forever. Only an
+    // actually-absent (never confirmed) field should fail this check.
+    return !!provider && typeof provider.confirmedBaseUrl === "string" &&
+      provider.confirmedBaseUrl === provider.baseUrl;
+  }
+
+  const PROVIDER_UNCONFIRMED_MESSAGE = "This provider hasn't passed a connection test yet — run Test Provider first.";
+
+  // For routes that resolve activeProvider themselves and can respond
+  // directly (models, agent-step, chat, chat-stream) — matches the
+  // {error:"code", message:"text"} shape requireExecutionContract already
+  // uses elsewhere in this file.
+  function requireConfirmedProvider(res, activeProvider) {
+    if (isProviderConfirmed(activeProvider)) { return true; }
+    res.status(409).json({ error: "provider_unconfirmed", message: PROVIDER_UNCONFIRMED_MESSAGE });
+    return false;
+  }
+
+  // For the generation-family helpers (runFlowGeneration/
+  // runFlowGenerationStream), which don't have direct access to `res` — they
+  // throw, and the route's existing sendGenerationError/stream-error path
+  // turns .status/.code into the actual response.
+  function providerUnconfirmedError() {
+    const err = new Error(PROVIDER_UNCONFIRMED_MESSAGE);
+    err.status = 409;
+    err.code = "provider_unconfirmed";
+    return err;
+  }
+
+  // The confirming check's own pass/fail criterion (B3) — extracted to its
+  // own module (lib/provider-shape-check.js) so it has a real, re-executable
+  // unit test rather than only code-review-level evidence.
+
+  function hasRequestBody(body) {
+    return !!body && typeof body === "object" && !Array.isArray(body) && Object.keys(body).length > 0;
+  }
+
+  function validateSettingsSaveBody(body) {
+    if (!hasRequestBody(body)) {
+      return "Settings payload is required.";
+    }
+    if (!Array.isArray(body.providers) || body.providers.length === 0) {
+      return "Settings payload must include at least one provider.";
+    }
+    if (!body.activeProviderId || !String(body.activeProviderId).trim()) {
+      return "Settings payload must include an activeProviderId.";
+    }
+    return null;
+  }
+
   // ---- Settings: write -------------------------------------------------
 
   RED.httpAdmin.post("/flowpilot/settings", RED.auth.needsPermission("settings.write"), function (req, res) {
+    const validationError = validateSettingsSaveBody(req.body);
+    if (validationError) {
+      return res.status(400).json({ error: validationError });
+    }
     try {
-      const saved = storage.saveSettings(req.body || {});
+      const saved = storage.saveSettings(req.body);
       storage.appendAudit({
         action: "settings_saved",
         providerName: saved.providerName,
         baseUrl: saved.baseUrl,
         model: saved.model
       });
-      res.json(saved);
+      res.json(maskProviderSecrets(saved));
     } catch (err) {
       res.status(500).json({ error: err.message });
     }
@@ -868,7 +1552,17 @@ module.exports = function flowPilotRuntime(RED) {
   // ---- Models: list models via the active provider's /v1/models -------
   // Always acts on the SAVED active provider (the frontend saves the form
   // first, mirroring Pre-flight check), and never errors out for a provider
-  // that doesn't support /v1/models — see listModels().
+  // that doesn't support /v1/models — see listModels(). No request body is
+  // read here, so no body-presence check applies (unlike /flowpilot/settings,
+  // which does act on its body).
+  //
+  // This is the THIRD route allowed to touch an unconfirmed baseUrl (ADR-007)
+  // — users need to see a model list before ever running Pre-flight check,
+  // and the confirmation gate would otherwise block that. Kept safe the same
+  // way /flowpilot/test and /flowpilot/probe are: listModels() only trusts a
+  // genuinely provider-shaped response (isModelsListShaped) and never
+  // reflects a raw failure body. Does not itself write confirmedBaseUrl/
+  // confirmedAt — only the deliberate /flowpilot/test action confirms.
 
   RED.httpAdmin.post("/flowpilot/models", RED.auth.needsPermission("settings.write"), async function (req, res) {
     try {
@@ -906,6 +1600,11 @@ module.exports = function flowPilotRuntime(RED) {
       try {
         await runChatStream(req, res, prompt, req.body.context, history, historyTruncated, req.body.conversationId);
       } catch (err) {
+        if (!res.headersSent && err && err.status) {
+          const errBody = { error: err.code || err.message };
+          if (err.code) { errBody.message = err.message; }
+          return res.status(err.status).json(errBody);
+        }
         storage.appendAudit({ action: "chat_stream_error", error: err.message });
         if (!res.headersSent) {
           res.status(500).json({ error: err.message });
@@ -919,7 +1618,8 @@ module.exports = function flowPilotRuntime(RED) {
     try {
       const useTools = !!req.body.tools;
       const { activeProvider, result, perf, chatMessage, chatData, messages, toolCalls } =
-        await runChat(prompt, "selected-nodes", req.body.context, history, historyTruncated, req.body.conversationId, useTools);
+        await runChat(prompt, "selected-nodes", req.body.context, history, historyTruncated,
+          req.body.conversationId, useTools, req.body.strategy);
 
       storage.appendAudit(Object.assign({
         action: "chat",
@@ -929,6 +1629,9 @@ module.exports = function flowPilotRuntime(RED) {
         toolCallCount: toolCalls ? toolCalls.length : 0
       }, perf));
 
+      if (result.fallbackToClassic) {
+        return res.json({ fallbackToClassic: true, usage: result.usage || null });
+      }
       if (toolCalls) {
         return res.json({ toolCalls: toolCalls, messages: messages, content: result.content || null, usage: result.usage || null });
       }
@@ -948,6 +1651,11 @@ module.exports = function flowPilotRuntime(RED) {
       if (rawMsg && rawMsg.reasoning_content) { body.reasoningContent = rawMsg.reasoning_content; }
       res.json(body);
     } catch (err) {
+      if (err && err.status) {
+        const errBody = { error: err.code || err.message };
+        if (err.code) { errBody.message = err.message; }
+        return res.status(err.status).json(errBody);
+      }
       storage.appendAudit({ action: "chat_error", error: err.message });
       res.status(500).json({ error: err.message });
     }
@@ -972,7 +1680,60 @@ module.exports = function flowPilotRuntime(RED) {
   //    `context` (for describeSelectionContext / modify's originalNodes) and
   //    `prompt` (for transcript recording) are passed through from the
   //    initial request.
+  const EXECUTION_STRATEGIES = new Set(["agent", "classic"]);
+  const EXECUTION_ENTRIES = new Set([
+    "chat", "document", "generate", "build", "modify", "build-review", "build-existing"
+  ]);
+
+  function requireExecutionContract(req, res, settings, activeProvider) {
+    const body = (req && req.body) || {};
+    if (!EXECUTION_STRATEGIES.has(body.strategy) || !EXECUTION_ENTRIES.has(body.entry)) {
+      res.status(400).json({
+        error: "strategy_required",
+        message: "strategy and entry are required and must be recognized values."
+      });
+      return null;
+    }
+    if (body.strategy === "agent" &&
+        !(settings.enableAgentWrite === true && activeProvider && activeProvider.supportsTools === true)) {
+      res.status(409).json({
+        error: "agent_strategy_unavailable",
+        message: "The agent strategy requires enableAgentWrite and a tool-capable provider."
+      });
+      return null;
+    }
+    return {
+      strategy: body.strategy,
+      entry: body.entry,
+      conversationId: body.conversationId || null,
+      runId: body.runId || null,
+      // CLAUDE-014: plain-language note for the client-side decision (consent
+      // gate / ask_user / loop-checkpoint) that triggered this request, only
+      // sent when settings.debugLogging is on — threaded into
+      // maybeLogDebugEvent calls below so debug.log shows what the user
+      // actually decided instead of only raw tool-result JSON.
+      debugNote: body.debugNote || null
+    };
+  }
+
   RED.httpAdmin.post("/flowpilot/agent-step", RED.auth.needsPermission("settings.write"), async function (req, res) {
+    const settings = storage.getSettings();
+    const activeProvider = storage.getActiveProvider(settings);
+    const execution = requireExecutionContract(req, res, settings, activeProvider);
+    if (!execution) { return; }
+    if (Array.isArray(req.body.events) && typeof execution.runId === "string" && execution.runId) {
+      runEventsStore.set(execution.runId, req.body.events);
+      if (runEventsStore.size > RUN_EVENTS_MAX_STORED) {
+        runEventsStore.delete(runEventsStore.keys().next().value);
+      }
+      maybeLogDebugEvent("run_events", {
+        mode: req.body.mode || "chat",
+        runId: execution.runId,
+        events: req.body.events
+      });
+    }
+    if (!requireConfirmedProvider(res, activeProvider)) { return; }
+
     const messages = req.body && req.body.messages;
     if (!Array.isArray(messages) || messages.length === 0) {
       return res.status(400).json({ error: "messages array is required." });
@@ -980,13 +1741,36 @@ module.exports = function flowPilotRuntime(RED) {
     const mode = req.body.mode || "chat";
 
     try {
-      const settings = storage.getSettings();
-      const activeProvider = storage.getActiveProvider(settings);
-      const result = await getProvider(activeProvider).chat(activeProvider, messages, { tools: AGENT_READ_TOOLS, toolChoice: "auto" });
+      const toolsEnabled = activeProvider.supportsTools === true;
+      const offeredTools = toolsEnabled
+        ? agentToolsFor(settings, activeProvider, mode, execution.strategy === "agent")
+        : [];
+      let chatOptions = toolsEnabled
+        ? { tools: offeredTools, toolChoice: "auto" }
+        : undefined;
+      if (execution.strategy === "agent") {
+        chatOptions = agentTurnOptions(settings, chatOptions);
+      }
+      // Messages include client-produced role:"tool" results. Pass them
+      // straight to the adapter; OpenAI-compatible providers receive them
+      // unchanged and Anthropic converts only the outer message envelope to
+      // native tool_result blocks.
+      const provider = getProvider(activeProvider);
+      const result = execution.strategy === "agent"
+        ? await chatWithAgentCap(provider, activeProvider, messages, chatOptions)
+        : await provider.chat(activeProvider, messages, chatOptions);
+
+      if (result.fallbackToClassic) {
+        return res.json({ fallbackToClassic: true, usage: result.usage || null });
+      }
 
       storage.appendAudit(Object.assign({
         action: "agent_step",
         mode: mode,
+        strategy: execution.strategy,
+        entry: execution.entry,
+        conversationId: execution.conversationId,
+        runId: execution.runId,
         providerName: activeProvider.providerName,
         baseUrl: activeProvider.baseUrl,
         model: activeProvider.model,
@@ -994,17 +1778,49 @@ module.exports = function flowPilotRuntime(RED) {
       }, performanceAuditFields(messages, result.content, result)));
 
       if (result.toolCalls) {
-        return res.json({ toolCalls: result.toolCalls, content: result.content || null, usage: result.usage || null });
+        maybeLogDebugEvent("tool_call", {
+          mode: mode,
+          providerBaseUrl: activeProvider.baseUrl,
+          model: activeProvider.model,
+          messages: messages,
+          toolCalls: result.toolCalls,
+          responseContent: result.content || null,
+          debugNote: execution.debugNote || undefined
+        });
+        return res.json({
+          toolCalls: result.toolCalls,
+          toolTiers: toolTierMap(result.toolCalls),
+          content: result.content || null,
+          usage: result.usage || null
+        });
       }
 
+      maybeLogDebugEvent("assistant_reply", {
+        mode: mode,
+        providerBaseUrl: activeProvider.baseUrl,
+        model: activeProvider.model,
+        messages: messages,
+        responseChars: typeof result.content === "string" ? result.content.length : 0,
+        responseContent: result.content || "",
+        parseOutcome: "received",
+        debugNote: execution.debugNote || undefined
+      });
+
       if (mode !== "chat") {
         const context = req.body.context;
-        const described = describeSelectionContext(context, settings.redactionEnabled);
-        const generated = processGenerationContent(result.content || "", result, messages, mode, described, activeProvider);
+        const described = describeSelectionContext(context, settings);
+        const generated = processGenerationContent(
+          result.content || "", result, messages, mode, described, activeProvider,
+          req.body.prompt, execution
+        );
         recordTranscriptTurn(req.body.conversationId, mode, req.body.prompt || null, transcriptTextFromGenerationResult(generated));
         const finalize = (mode === "modify")
-          ? function (r) { return finalizeModifyResult(r, (context && Array.isArray(context.nodes)) ? context.nodes : []); }
-          : finalizeSimpleGeneration;
+          ? function (r) {
+              return finalizeModifyResult(
+                r, (context && Array.isArray(context.nodes)) ? context.nodes : [], execution
+              );
+            }
+          : function (r) { return finalizeSimpleGeneration(r, execution); };
         const { status, body } = finalize(generated);
         return res.status(status).json(body);
       }
@@ -1019,7 +1835,7 @@ module.exports = function flowPilotRuntime(RED) {
       if (questionOptions) { body.questionOptions = questionOptions; }
       res.json(body);
     } catch (err) {
-      sendGenerationError(res, mode + "_agent_step", err);
+      sendGenerationError(res, mode + "_agent_step", err, execution);
     }
   });
 
@@ -1077,6 +1893,9 @@ module.exports = function flowPilotRuntime(RED) {
   RED.httpAdmin.get("/flowpilot/conversations/:id", RED.auth.needsPermission("settings.read"), function (req, res) {
     const id = sanitizeConversationId(req.params.id);
     if (!id) { return res.status(400).json({ error: "Invalid conversation id." }); }
+    if (storage.listConversationIds().indexOf(id) === -1) {
+      return res.status(404).json({ error: "Conversation not found." });
+    }
     try {
       res.json({ id: id, messages: storage.readTranscript(id) });
     } catch (err) {
@@ -1087,6 +1906,9 @@ module.exports = function flowPilotRuntime(RED) {
   RED.httpAdmin.delete("/flowpilot/conversations/:id", RED.auth.needsPermission("settings.write"), function (req, res) {
     const id = sanitizeConversationId(req.params.id);
     if (!id) { return res.status(400).json({ error: "Invalid conversation id." }); }
+    if (storage.listConversationIds().indexOf(id) === -1) {
+      return res.status(404).json({ error: "Conversation not found." });
+    }
     try {
       storage.deleteTranscript(id);
       storage.appendAudit({ action: "conversation_delete", conversationId: id });
@@ -1112,11 +1934,37 @@ module.exports = function flowPilotRuntime(RED) {
   // reply at all." Never depends on chat history or flow context.
 
   RED.httpAdmin.post("/flowpilot/test", RED.auth.needsPermission("settings.write"), async function (req, res) {
+    if (!hasRequestBody(req.body)) {
+      return res.status(400).json({ error: "Request body is required." });
+    }
     const prompt = (req.body && req.body.prompt) || "Say hello from FlowPilot.";
 
     try {
+      // This IS the provider-confirmation check (ADR-007) — the one request
+      // allowed to touch a not-yet-confirmed baseUrl. runChat("connectivity-
+      // test") skips the confirmation gate for exactly this call.
       const { settings, activeProvider, result, perf, chatMessage } = await runChat(prompt, "connectivity-test");
 
+      // Strict pass criterion (B3): a 200 with SOME JSON body is not enough
+      // — an internal service or a cloud metadata endpoint can return that
+      // trivially. Require an actually provider-shaped chat-completion
+      // response, or the check fails and the provider stays unconfirmed.
+      // The error returned to the client is deliberately generic — never
+      // the upstream body — so a probe against a non-provider target
+      // yields nothing readable (the actual SSRF seal).
+      if (!isProviderShapedResponse(activeProvider.type, result.raw)) {
+        storage.appendAudit({
+          action: "chat_test_error",
+          providerName: activeProvider.providerName,
+          baseUrl: activeProvider.baseUrl,
+          error: "not_provider_shaped"
+        });
+        return res.status(422).json({
+          error: "provider_check_failed",
+          message: "Not a valid provider endpoint (no FlowPilot-compatible response)."
+        });
+      }
+
       storage.appendAudit(Object.assign({
         action: "chat_test",
         providerName: activeProvider.providerName,
@@ -1145,11 +1993,16 @@ module.exports = function flowPilotRuntime(RED) {
               toolsProbedAt: new Date().toISOString(),
               isReasoningModel: reasoning.isReasoningModel,
               reasoningProbedAt: new Date().toISOString(),
-              probedModel: activeProvider.model
+              probedModel: activeProvider.model,
+              // The check above passed — this exact baseUrl is now
+              // confirmed. Cleared automatically (reconcileProviderSecrets,
+              // lib/storage.js) the moment baseUrl or apiKey changes.
+              confirmedBaseUrl: activeProvider.baseUrl,
+              confirmedAt: new Date().toISOString()
             })
           : p;
       });
-      storage.saveSettings(Object.assign({}, settings, { providers: updatedProviders }));
+      storage.saveSettings(Object.assign({}, settings, { providers: updatedProviders }), { trustConfirmation: true });
 
       const toolLabel = probe.supportsTools
         ? "✓ Connected · ✓ Supports tools"
@@ -1180,15 +2033,34 @@ module.exports = function flowPilotRuntime(RED) {
   // probedModel, and returns { supportsTools, isReasoningModel, probedModel }.
 
   RED.httpAdmin.post("/flowpilot/probe", RED.auth.needsPermission("settings.write"), async function (req, res) {
+    if (!hasRequestBody(req.body)) {
+      return res.status(400).json({ error: "Request body is required." });
+    }
     try {
       const settings = storage.getSettings();
       const activeProvider = storage.getActiveProvider(settings);
 
+      // This is the OTHER route allowed to touch an unconfirmed baseUrl
+      // (ADR-007) — same confirming-check treatment as /flowpilot/test.
       const probe = await getProvider(activeProvider).probeTools(activeProvider);
       const chatResult = await getProvider(activeProvider).chat(activeProvider, [
         { role: "system", content: "You are a helpful assistant." },
         { role: "user", content: "Say hello." }
       ]);
+
+      if (!isProviderShapedResponse(activeProvider.type, chatResult.raw)) {
+        storage.appendAudit({
+          action: "auto_probe_error",
+          providerName: activeProvider.providerName,
+          baseUrl: activeProvider.baseUrl,
+          error: "not_provider_shaped"
+        });
+        return res.status(422).json({
+          error: "provider_check_failed",
+          message: "Not a valid provider endpoint (no FlowPilot-compatible response)."
+        });
+      }
+
       const reasoning = getProvider(activeProvider).detectReasoning(chatResult.raw);
 
       const updatedProviders = (settings.providers || []).map(function (p) {
@@ -1198,11 +2070,13 @@ module.exports = function flowPilotRuntime(RED) {
               toolsProbedAt: new Date().toISOString(),
               isReasoningModel: reasoning.isReasoningModel,
               reasoningProbedAt: new Date().toISOString(),
-              probedModel: activeProvider.model
+              probedModel: activeProvider.model,
+              confirmedBaseUrl: activeProvider.baseUrl,
+              confirmedAt: new Date().toISOString()
             })
           : p;
       });
-      storage.saveSettings(Object.assign({}, settings, { providers: updatedProviders }));
+      storage.saveSettings(Object.assign({}, settings, { providers: updatedProviders }), { trustConfirmation: true });
 
       storage.appendAudit({
         action: "auto_probe",
@@ -1239,7 +2113,7 @@ module.exports = function flowPilotRuntime(RED) {
   function buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated, auditAction) {
     const settings = storage.getSettings();
     const activeProvider = storage.getActiveProvider(settings);
-    const described = describeSelectionContext(context, settings.redactionEnabled);
+    const described = describeSelectionContext(context, settings);
     // Persona applies to the "explanation" field only (a real hand-off/
     // transition moment — "here's the flow I built for you") — never to
     // node names, ids, or any structural JSON, which stays exactly as each
@@ -1255,7 +2129,8 @@ module.exports = function flowPilotRuntime(RED) {
   // parsed envelope. Validated but non-critical — a malformed or missing
   // suggestion is just dropped (returns null), never an error, since chips
   // are an additive hint on top of the real response.
-  //   { mode: "generate"|"document"|"modify"|"chat", prompt: "...", selectionHint?: "..." }
+  //   { mode: "generate"|"document"|"modify"|"chat", prompt: "...",
+  //     selectionHint?: "...", targetNodeIds?: "all"|string[] }
   // ---------------------------------------------------------------------
   function extractSuggestedAction(parsed) {
     const sa = parsed && parsed.suggestedAction;
@@ -1267,6 +2142,14 @@ module.exports = function flowPilotRuntime(RED) {
     if (typeof sa.selectionHint === "string" && sa.selectionHint.trim()) {
       result.selectionHint = sa.selectionHint.trim();
     }
+    if (sa.targetNodeIds === "all") {
+      result.targetNodeIds = "all";
+    } else if (Array.isArray(sa.targetNodeIds)) {
+      const targetNodeIds = sa.targetNodeIds
+        .filter(function (id) { return typeof id === "string" && id.trim(); })
+        .map(function (id) { return id.trim(); });
+      if (targetNodeIds.length) { result.targetNodeIds = targetNodeIds; }
+    }
     return result;
   }
 
@@ -1297,71 +2180,6 @@ module.exports = function flowPilotRuntime(RED) {
   // createChatDataStreamSplitter below so the marker/JSON are never flashed
   // to the user mid-stream.
   // ---------------------------------------------------------------------
-  const CHAT_DATA_MARKER = "<<<FLOWPILOT_DATA>>>";
-
-  function splitChatDataBlock(content) {
-    const text = String(content || "");
-    const idx = text.indexOf(CHAT_DATA_MARKER);
-    if (idx === -1) { return { message: text, data: null }; }
-
-    const message = text.slice(0, idx).replace(/\s+$/, "");
-    const jsonStr = text.slice(idx + CHAT_DATA_MARKER.length).trim();
-    let data = null;
-    try { data = JSON.parse(jsonStr); } catch (e) { data = null; }
-    return { message: message, data: data };
-  }
-
-  // Streaming counterpart of splitChatDataBlock: buffers just enough of the
-  // tail to detect CHAT_DATA_MARKER even if it's split across provider
-  // chunks, without delaying normal text. push(delta) returns the portion of
-  // `delta` (plus any previously-held tail) that's safe to display now —
-  // possibly "". Once the marker is seen, all further input is buffered as
-  // the JSON data block instead of being displayed. finish() returns any
-  // held-back text that turned out NOT to be part of the marker (a false
-  // positive at end of stream) plus the parsed data block, if any.
-  // ---------------------------------------------------------------------
-  function createChatDataStreamSplitter() {
-    let held = "";
-    let inData = false;
-    let dataBuf = "";
-
-    function push(delta) {
-      if (inData) { dataBuf += delta; return ""; }
-
-      const combined = held + delta;
-      const idx = combined.indexOf(CHAT_DATA_MARKER);
-      if (idx !== -1) {
-        inData = true;
-        dataBuf = combined.slice(idx + CHAT_DATA_MARKER.length);
-        held = "";
-        return combined.slice(0, idx);
-      }
-
-      // No full marker yet — check whether the tail of `combined` is a
-      // prefix of the marker (i.e. the marker may be split across chunks)
-      // and hold that part back.
-      const maxOverlap = Math.min(combined.length, CHAT_DATA_MARKER.length - 1);
-      let overlap = 0;
-      for (let len = maxOverlap; len >= 1; len--) {
-        if (combined.slice(-len) === CHAT_DATA_MARKER.slice(0, len)) { overlap = len; break; }
-      }
-      held = overlap ? combined.slice(-overlap) : "";
-      return overlap ? combined.slice(0, -overlap) : combined;
-    }
-
-    function finish() {
-      const tail = held;
-      held = "";
-      let data = null;
-      if (inData) {
-        try { data = JSON.parse(dataBuf.trim()); } catch (e) { data = null; }
-      }
-      return { tail: tail, data: data };
-    }
-
-    return { push: push, finish: finish };
-  }
-
   // ---------------------------------------------------------------------
   // Shared helper: parse, validate and audit a completed provider response
   // for a generation-style request, returning { question } / { prose } /
@@ -1405,8 +2223,9 @@ module.exports = function flowPilotRuntime(RED) {
       });
   }
 
-  function processGenerationContent(content, providerResult, messages, auditAction, described, activeProvider, userPrompt) {
+  function processGenerationContent(content, providerResult, messages, auditAction, described, activeProvider, userPrompt, auditContext) {
     const perf = performanceAuditFields(messages, content, providerResult);
+    const auditFields = auditContext || {};
 
     // Mode-mismatch redirect: the model may respond in plain prose —
     // addressing a request that doesn't belong in generate/document/modify —
@@ -1415,11 +2234,11 @@ module.exports = function flowPilotRuntime(RED) {
     // it would otherwise grab the "{" inside the data block and treat it as
     // a broken envelope.
     let envelopeParsed;
-    if (content.indexOf(CHAT_DATA_MARKER) !== -1) {
+    if (findChatDataMarker(content)) {
       const preSplit = splitChatDataBlock(content);
       const proseMessage = preSplit.message.trim();
       if (proseMessage && proseMessage[0] !== "{") {
-        storage.appendAudit(Object.assign({ action: auditAction + "_prose" }, perf));
+        storage.appendAudit(Object.assign({ action: auditAction + "_prose" }, auditFields, perf));
         const proseResult = { prose: proseMessage };
         if (preSplit.data) {
           const proseAction = extractSuggestedAction(preSplit.data);
@@ -1458,7 +2277,7 @@ module.exports = function flowPilotRuntime(RED) {
         // render it as a normal assistant message and keep the action armed.
         // Errors stay reserved for empty responses or a found-but-broken {...}.
         if (parseErr.noJsonFound && content.trim()) {
-          storage.appendAudit(Object.assign({ action: auditAction + "_prose" }, perf));
+          storage.appendAudit(Object.assign({ action: auditAction + "_prose" }, auditFields, perf));
           // Mode-mismatch redirect: a prose reply may carry the same hidden
           // <<<FLOWPILOT_DATA>>> block as Chat, suggesting a mode switch (e.g.
           // "chat" when the request was actually a question, not a
@@ -1473,7 +2292,7 @@ module.exports = function flowPilotRuntime(RED) {
           }
           return proseResult;
         }
-        storage.appendAudit(Object.assign({ action: auditAction + "_parse_error", error: parseErr.message }, perf));
+        storage.appendAudit(Object.assign({ action: auditAction + "_parse_error", error: parseErr.message }, auditFields, perf));
         const err = new Error("Could not parse a flow from the response: " + parseErr.message);
         err.status = 422;
         err.raw = content;
@@ -1499,10 +2318,18 @@ module.exports = function flowPilotRuntime(RED) {
       if (typeof parsed.selectionHint === "string" && parsed.selectionHint.trim()) {
         redirect.selectionHint = parsed.selectionHint.trim();
       }
+      if (parsed.targetNodeIds === "all") {
+        redirect.targetNodeIds = "all";
+      } else if (Array.isArray(parsed.targetNodeIds)) {
+        const targetNodeIds = parsed.targetNodeIds
+          .filter(function (id) { return typeof id === "string" && id.trim(); })
+          .map(function (id) { return id.trim(); });
+        if (targetNodeIds.length) { redirect.targetNodeIds = targetNodeIds; }
+      }
       const redirectProse = (typeof parsed.explanation === "string" && parsed.explanation.trim())
         ? parsed.explanation.trim()
         : "This request belongs in " + parsed.mode + " mode.";
-      storage.appendAudit(Object.assign({ action: auditAction + "_prose" }, perf));
+      storage.appendAudit(Object.assign({ action: auditAction + "_mode_redirect" }, auditFields, perf));
       return { prose: redirectProse, suggestedAction: redirect };
     }
 
@@ -1539,7 +2366,7 @@ module.exports = function flowPilotRuntime(RED) {
     // assistant message and keeps the Execute action armed for the answer.
     if (typeof parsed.question === "string" && parsed.question.trim() &&
         (!Array.isArray(parsed.flow) || parsed.flow.length === 0)) {
-      storage.appendAudit(Object.assign({ action: auditAction + "_question" }, perf));
+      storage.appendAudit(Object.assign({ action: auditAction + "_question" }, auditFields, perf));
       const questionResult = { question: parsed.question, explanation: parsed.explanation || "" };
       const questionAction = extractSuggestedAction(parsed);
       if (questionAction) { questionResult.suggestedAction = questionAction; }
@@ -1565,6 +2392,24 @@ module.exports = function flowPilotRuntime(RED) {
         throw err;
       }
 
+      // Do not silently turn malformed structured fields into empty arrays.
+      // A model reply such as {"changes": {...}} is plainly an attempted
+      // Modify envelope, not prose or a legitimate no-op. Treat wrong field
+      // types like other envelope parse failures so the client uses its safe
+      // 422 handling and never presents raw JSON as a trusted assistant reply.
+      const modifyArrayFields = ["changes", "newNodes", "newWires", "removeNodes", "newGroups"];
+      const invalidArrayFields = modifyArrayFields.filter(function (field) {
+        return field in parsed && !Array.isArray(parsed[field]);
+      });
+      if (invalidArrayFields.length) {
+        const err = new Error("The response contained non-array modify field(s): " + invalidArrayFields.join(", ") + ".");
+        err.status = 422;
+        err.raw = content;
+        throw err;
+      }
+
+      enforceAgentContract(parsed, auditContext, false);
+
       const changes = Array.isArray(parsed.changes) ? parsed.changes : [];
       const newNodes = Array.isArray(parsed.newNodes) ? parsed.newNodes : [];
       const newWires = Array.isArray(parsed.newWires) ? parsed.newWires : [];
@@ -1596,7 +2441,7 @@ module.exports = function flowPilotRuntime(RED) {
         newGroupCount: newGroups.length,
         contextNodeCount: described ? described.nodeCount : 0,
         contextConnectionCount: described ? described.connectionCount : 0
-      }, perf));
+      }, auditFields, perf));
 
       const modifyResult = {
         explanation: parsed.explanation || "",
@@ -1606,6 +2451,12 @@ module.exports = function flowPilotRuntime(RED) {
         removeNodes: removeNodes,
         newGroups: newGroups
       };
+      if (Array.isArray(parsed.strippedFields) && parsed.strippedFields.length) {
+        modifyResult.strippedFields = parsed.strippedFields.slice();
+      }
+      if (Array.isArray(parsed.verifySteps) && parsed.verifySteps.length) {
+        modifyResult.verifySteps = parsed.verifySteps.slice();
+      }
       // Combine skipped-note sources: redaction (W0.2) and switch mismatch (W2).
       const skippedNotes = [redactionSkippedNote, parsed._switchMismatchNote].filter(Boolean);
       if (skippedNotes.length) { modifyResult.skippedNote = skippedNotes.join(" "); }
@@ -1614,6 +2465,8 @@ module.exports = function flowPilotRuntime(RED) {
       return modifyResult;
     }
 
+    enforceAgentContract(parsed, auditContext, false);
+
     const flow = Array.isArray(parsed.flow) ? parsed.flow : null;
     if (!flow) {
       const err = new Error("The response did not contain a 'flow' array.");
@@ -1630,7 +2483,7 @@ module.exports = function flowPilotRuntime(RED) {
       nodeCount: flow.length,
       contextNodeCount: described ? described.nodeCount : 0,
       contextConnectionCount: described ? described.connectionCount : 0
-    }, perf));
+    }, auditFields, perf));
 
     const flowResult = {
       explanation: parsed.explanation || "",
@@ -1638,6 +2491,9 @@ module.exports = function flowPilotRuntime(RED) {
       newNodes: Array.isArray(parsed.newNodes) ? parsed.newNodes : [],
       newWires: Array.isArray(parsed.newWires) ? parsed.newWires : []
     };
+    if (Array.isArray(parsed.strippedFields) && parsed.strippedFields.length) {
+      flowResult.strippedFields = parsed.strippedFields.slice();
+    }
     if (auditAction === "build") {
       const fpUidManifest = buildFpUidManifest(flow);
       if (fpUidManifest.length) { flowResult.fpUidManifest = fpUidManifest; }
@@ -1656,32 +2512,100 @@ module.exports = function flowPilotRuntime(RED) {
   // action name, and how the route validates its inputs beforehand. Throws
   // an Error with .status and (when applicable) .raw for the route to relay.
   // ---------------------------------------------------------------------
-  // Step 4: useTools offers AGENT_READ_TOOLS (explore-then-propose). If the
+  // Step 4: useTools offers the mode-appropriate agent tools. WRITE tools
+  // are Modify-only and require enableAgentWrite plus a tool-capable
+  // provider. If the
   // provider responds with tool_calls instead of a final envelope, returns
   // early with { toolCalls, messages, content, usage } — same shape as
   // runChat's early return — so the route can hand it to the frontend
   // without running processGenerationContent yet.
-  async function runFlowGeneration(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, useTools) {
+  async function runFlowGeneration(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, useTools, execution) {
     const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated, auditAction);
-    const responseFormat = directCompletionResponseFormat(activeProvider, auditAction, useTools);
-    const chatOptions = useTools
-      ? { tools: AGENT_READ_TOOLS, toolChoice: "auto" }
+    if (!isProviderConfirmed(activeProvider)) { throw providerUnconfirmedError(); }
+    const settings = storage.getSettings();
+    const toolsEnabled = !!useTools && activeProvider.supportsTools === true;
+    const offeredTools = toolsEnabled
+      ? agentToolsFor(settings, activeProvider, auditAction, execution && execution.strategy === "agent")
+      : [];
+    const responseFormat = directCompletionResponseFormat(activeProvider, auditAction, toolsEnabled);
+    const toolChoice = (auditAction === "modify" || auditAction === "generate") && execution &&
+      execution.strategy === "agent" ? "required" : "auto";
+    let chatOptions = toolsEnabled
+      ? { tools: offeredTools, toolChoice: toolChoice }
       : (responseFormat ? { responseFormat: responseFormat } : undefined);
-    const result = await getProvider(activeProvider).chat(activeProvider, messages, chatOptions);
+    const provider = getProvider(activeProvider);
+    let result;
+    if (execution && execution.strategy === "agent") {
+      chatOptions = agentTurnOptions(settings, chatOptions);
+      result = await chatWithAgentCap(provider, activeProvider, messages, chatOptions);
+    } else {
+      result = await provider.chat(activeProvider, messages, chatOptions);
+    }
+    if (result.fallbackToClassic) {
+      return { fallbackToClassic: true, usage: result.usage || null };
+    }
     if (result.toolCalls) {
-      return { toolCalls: result.toolCalls, messages: messages, content: result.content || null, usage: result.usage || null };
+      // F-5: this is the FIRST turn of an agent-strategy request (routed
+      // through /flowpilot/{generate,build,document,modify}, not the
+      // /flowpilot/agent-step continuation endpoint below, which already
+      // audits unconditionally) — it can carry a real WRITE tool call, so
+      // it must not be the one turn that leaves zero record. Previously
+      // this path returned before any storage.appendAudit call; a request
+      // whose very first turn was a tool call (e.g. an immediate ask_user,
+      // or — as here — the opening WRITE call of a multi-item Modify)
+      // vanished from audit.log entirely. maybeLogDebugEvent below is
+      // additive (only fires when settings.debugLogging is on); this
+      // appendAudit call is unconditional, matching /flowpilot/agent-step.
+      storage.appendAudit({
+        action: "first_turn_tool_call",
+        mode: auditAction,
+        strategy: (execution && execution.strategy) || null,
+        entry: (execution && execution.entry) || null,
+        conversationId: (execution && execution.conversationId) || null,
+        runId: (execution && execution.runId) || null,
+        providerName: activeProvider.providerName,
+        baseUrl: activeProvider.baseUrl,
+        model: activeProvider.model,
+        toolCallCount: result.toolCalls.length
+      });
+      maybeLogDebugEvent("tool_call", {
+        mode: auditAction,
+        providerBaseUrl: activeProvider.baseUrl,
+        model: activeProvider.model,
+        messages: messages,
+        toolCalls: result.toolCalls,
+        responseContent: result.content || null
+      });
+      return {
+        toolCalls: result.toolCalls,
+        toolTiers: toolTierMap(result.toolCalls),
+        messages: messages,
+        content: result.content || null,
+        usage: result.usage || null
+      };
     }
     const content = result.content || "";
     let parseOutcome = "unknown";
     try {
-      const generated = processGenerationContent(content, result, messages, auditAction, described, activeProvider, userPrompt);
+      const generated = processGenerationContent(
+        content, result, messages, auditAction, described, activeProvider, userPrompt, execution
+      );
       parseOutcome = generated.prose ? "prose" : generated.question ? "question" : "success";
       return generated;
     } catch (err) {
       parseOutcome = "parse_error:" + (err.message || "");
       throw err;
     } finally {
-      maybeLogAssembledPrompt(auditAction, messages, content, parseOutcome, activeProvider);
+      maybeLogDebugEvent("assistant_reply", {
+        mode: auditAction,
+        providerBaseUrl: activeProvider && activeProvider.baseUrl,
+        model: activeProvider && activeProvider.model,
+        messages: messages,
+        responseChars: typeof content === "string" ? content.length : 0,
+        responseContent: content,
+        parseOutcome: parseOutcome,
+        debugNote: (execution && execution.debugNote) || undefined
+      });
     }
   }
 
@@ -1693,8 +2617,9 @@ module.exports = function flowPilotRuntime(RED) {
   // while the rest of the JSON (the "flow" array etc.) is buffered until
   // this resolves.
   // ---------------------------------------------------------------------
-  async function runFlowGenerationStream(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, onDelta) {
+  async function runFlowGenerationStream(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, onDelta, auditContext) {
     const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated, auditAction);
+    if (!isProviderConfirmed(activeProvider)) { throw providerUnconfirmedError(); }
     const responseFormat = directCompletionResponseFormat(activeProvider, auditAction, false);
     const streamOptions = responseFormat ? { responseFormat: responseFormat } : undefined;
     const result = await getProvider(activeProvider).chatStream(
@@ -1703,26 +2628,41 @@ module.exports = function flowPilotRuntime(RED) {
     const content = result.content || "";
     let parseOutcome = "unknown";
     try {
-      const generated = processGenerationContent(content, result, messages, auditAction, described, activeProvider, userPrompt);
+      const generated = processGenerationContent(
+        content, result, messages, auditAction, described, activeProvider, userPrompt, auditContext
+      );
       parseOutcome = generated.prose ? "prose" : generated.question ? "question" : "success";
       return generated;
     } catch (err) {
       parseOutcome = "parse_error:" + (err.message || "");
       throw err;
     } finally {
-      maybeLogAssembledPrompt(auditAction, messages, content, parseOutcome, activeProvider);
+      maybeLogDebugEvent("assistant_reply", {
+        mode: auditAction,
+        providerBaseUrl: activeProvider && activeProvider.baseUrl,
+        model: activeProvider && activeProvider.model,
+        messages: messages,
+        responseChars: typeof content === "string" ? content.length : 0,
+        responseContent: content,
+        parseOutcome: parseOutcome,
+        debugNote: (auditContext && auditContext.debugNote) || undefined
+      });
     }
   }
 
   // Relays a runFlowGeneration error to the client with the right status,
   // falling back to 500 for anything that didn't set .status itself.
-  function sendGenerationError(res, auditAction, err) {
+  function sendGenerationError(res, auditAction, err, auditContext) {
     if (err && err.status) {
       const body = { error: err.message };
+      if (err.code) { body.code = err.code; }
       if (err.raw) { body.raw = err.raw; }
       return res.status(err.status).json(body);
     }
-    storage.appendAudit({ action: auditAction + "_error", error: err.message });
+    storage.appendAudit(Object.assign(
+      { action: auditAction + "_error", error: err.message },
+      auditContext || {}
+    ));
     res.status(500).json({ error: err.message });
   }
 
@@ -1733,7 +2673,7 @@ module.exports = function flowPilotRuntime(RED) {
   // Used by both the non-streaming route (res.status(status).json(body)) and
   // the streaming route (relayed as the final SSE event).
   // ---------------------------------------------------------------------
-  function finalizeSimpleGeneration(result) {
+  function finalizeSimpleGeneration(result, execution) {
     if (result.question) {
       const body = { explanation: result.explanation, question: result.question, flow: null };
       if (result.suggestedAction) { body.suggestedAction = result.suggestedAction; }
@@ -1746,6 +2686,19 @@ module.exports = function flowPilotRuntime(RED) {
       if (result.questionOptions) { proseBody.questionOptions = result.questionOptions; }
       return { status: 200, body: proseBody };
     }
+    if (execution && execution.strategy === "agent") {
+      const agentBody = {
+        explanation: result.explanation || "",
+        prose: true,
+        flow: null
+      };
+      if (Array.isArray(result.strippedFields) && result.strippedFields.length) {
+        agentBody.strippedFields = result.strippedFields.slice();
+      }
+      if (result.skippedNote) { agentBody.skippedNote = result.skippedNote; }
+      if (result.suggestedAction) { agentBody.suggestedAction = result.suggestedAction; }
+      return { status: 200, body: agentBody };
+    }
     return { status: 200, body: result };
   }
 
@@ -1760,7 +2713,7 @@ module.exports = function flowPilotRuntime(RED) {
   // the /flowpilot/modify route handler. Used by both the non-streaming and
   // streaming routes.
   // ---------------------------------------------------------------------
-  function finalizeModifyResult(result, originalNodes) {
+  function finalizeModifyResult(result, originalNodes, auditContext) {
     if (result.question) {
       const questionBody = { explanation: result.explanation, question: result.question, flow: null };
       if (result.suggestedAction) { questionBody.suggestedAction = result.suggestedAction; }
@@ -1773,6 +2726,22 @@ module.exports = function flowPilotRuntime(RED) {
       if (result.questionOptions) { proseBody.questionOptions = result.questionOptions; }
       return { status: 200, body: proseBody };
     }
+    if (auditContext && auditContext.strategy === "agent") {
+      const agentBody = {
+        explanation: result.explanation || "",
+        prose: true,
+        flow: null
+      };
+      if (Array.isArray(result.strippedFields) && result.strippedFields.length) {
+        agentBody.strippedFields = result.strippedFields.slice();
+      }
+      if (Array.isArray(result.verifySteps) && result.verifySteps.length) {
+        agentBody.verifySteps = result.verifySteps.slice();
+      }
+      if (result.skippedNote) { agentBody.skippedNote = result.skippedNote; }
+      if (result.suggestedAction) { agentBody.suggestedAction = result.suggestedAction; }
+      return { status: 200, body: agentBody };
+    }
 
     const originalIds = new Set(originalNodes.map(function (n) { return n.id; }));
 
@@ -1986,7 +2955,12 @@ module.exports = function flowPilotRuntime(RED) {
       }
     }
 
-    if (newGroups.length > 0) { storage.appendAudit({ action: "modify_groups", count: newGroups.length }); }
+    if (newGroups.length > 0) {
+      storage.appendAudit(Object.assign(
+        { action: "modify_groups", count: newGroups.length },
+        auditContext || {}
+      ));
+    }
 
     const verifySteps = [];
     validChanges.forEach(function (change) {
@@ -2045,7 +3019,7 @@ module.exports = function flowPilotRuntime(RED) {
   // `data: {"error": <body>, "status": <status>}`, since SSE responses can't
   // change their HTTP status after headers are sent.
   // ---------------------------------------------------------------------
-  async function runExecuteStream(req, res, systemPrompt, auditAction, userPrompt, context, history, historyTruncated, finalize, conversationId) {
+  async function runExecuteStream(req, res, systemPrompt, auditAction, userPrompt, context, history, historyTruncated, finalize, conversationId, auditContext) {
     res.writeHead(200, {
       "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache, no-transform",
@@ -2058,12 +3032,18 @@ module.exports = function flowPilotRuntime(RED) {
     try {
       result = await runFlowGenerationStream(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, function (delta) {
         res.write("data: " + JSON.stringify({ delta: delta }) + "\n\n");
-      });
+      }, auditContext);
     } catch (err) {
       const status = err && err.status ? err.status : 500;
       const body = { error: err.message };
+      if (err && err.code) { body.code = err.code; }
       if (err && err.raw) { body.raw = err.raw; }
-      if (!err || !err.status) { storage.appendAudit({ action: auditAction + "_error", error: err.message }); }
+      if (!err || !err.status) {
+        storage.appendAudit(Object.assign(
+          { action: auditAction + "_error", error: err.message },
+          auditContext || {}
+        ));
+      }
       res.write("data: " + JSON.stringify({ error: body, status: status }) + "\n\n");
       res.write("data: [DONE]\n\n");
       res.end();
@@ -2079,6 +3059,11 @@ module.exports = function flowPilotRuntime(RED) {
   }
 
   RED.httpAdmin.post("/flowpilot/generate", RED.auth.needsPermission("settings.write"), async function (req, res) {
+    const settings = storage.getSettings();
+    const activeProvider = storage.getActiveProvider(settings);
+    const execution = requireExecutionContract(req, res, settings, activeProvider);
+    if (!execution) { return; }
+
     const prompt = req.body && req.body.prompt;
 
     if (!prompt || !String(prompt).trim()) {
@@ -2087,11 +3072,12 @@ module.exports = function flowPilotRuntime(RED) {
 
     const history = sanitizeHistory(req.body.history);
     const historyTruncated = !!req.body.historyTruncated;
+    const finalize = function (result) { return finalizeSimpleGeneration(result, execution); };
 
     if (req.body.stream) {
       return runExecuteStream(
         req, res, generationSystemPrompt, "generate", prompt, req.body && req.body.context,
-        history, historyTruncated, finalizeSimpleGeneration, req.body.conversationId
+        history, historyTruncated, finalize, req.body.conversationId, execution
       );
     }
 
@@ -2099,13 +3085,19 @@ module.exports = function flowPilotRuntime(RED) {
       const useTools = !!req.body.tools;
       const generated = await runFlowGeneration(
         generationSystemPrompt, "generate", prompt, req.body && req.body.context,
-        history, historyTruncated, useTools
+        history, historyTruncated, useTools, execution
       );
       if (generated.toolCalls) {
-        return res.json({ toolCalls: generated.toolCalls, messages: generated.messages, content: generated.content, usage: generated.usage });
+        return res.json({
+          toolCalls: generated.toolCalls,
+          toolTiers: generated.toolTiers,
+          messages: generated.messages,
+          content: generated.content,
+          usage: generated.usage
+        });
       }
       recordTranscriptTurn(req.body.conversationId, "generate", prompt, transcriptTextFromGenerationResult(generated));
-      const { status, body } = finalizeSimpleGeneration(generated);
+      const { status, body } = finalize(generated);
       res.status(status).json(body);
     } catch (err) {
       sendGenerationError(res, "generate", err);
@@ -2142,7 +3134,13 @@ module.exports = function flowPilotRuntime(RED) {
         history, historyTruncated, useTools
       );
       if (built.toolCalls) {
-        return res.json({ toolCalls: built.toolCalls, messages: built.messages, content: built.content, usage: built.usage });
+        return res.json({
+          toolCalls: built.toolCalls,
+          toolTiers: built.toolTiers,
+          messages: built.messages,
+          content: built.content,
+          usage: built.usage
+        });
       }
       recordTranscriptTurn(req.body.conversationId, "build", prompt, transcriptTextFromGenerationResult(built));
       const { status, body } = finalizeSimpleGeneration(built);
@@ -2154,7 +3152,7 @@ module.exports = function flowPilotRuntime(RED) {
 
   RED.httpAdmin.post("/flowpilot/document", RED.auth.needsPermission("settings.write"), async function (req, res) {
     const context = req.body && req.body.context;
-    const described = describeSelectionContext(context, storage.getSettings().redactionEnabled);
+    const described = describeSelectionContext(context, storage.getSettings());
 
     if (!described) {
       return res.status(400).json({ error: "Select the node(s) you want documented first." });
@@ -2182,7 +3180,13 @@ module.exports = function flowPilotRuntime(RED) {
         history, historyTruncated, useTools
       );
       if (documented.toolCalls) {
-        return res.json({ toolCalls: documented.toolCalls, messages: documented.messages, content: documented.content, usage: documented.usage });
+        return res.json({
+          toolCalls: documented.toolCalls,
+          toolTiers: documented.toolTiers,
+          messages: documented.messages,
+          content: documented.content,
+          usage: documented.usage
+        });
       }
       recordTranscriptTurn(req.body.conversationId, "document", userPrompt, transcriptTextFromGenerationResult(documented));
       const { status, body } = finalizeSimpleGeneration(documented);
@@ -2193,8 +3197,13 @@ module.exports = function flowPilotRuntime(RED) {
   });
 
   RED.httpAdmin.post("/flowpilot/modify", RED.auth.needsPermission("settings.write"), async function (req, res) {
+    const settings = storage.getSettings();
+    const activeProvider = storage.getActiveProvider(settings);
+    const execution = requireExecutionContract(req, res, settings, activeProvider);
+    if (!execution) { return; }
+
     const context = req.body && req.body.context;
-    const described = describeSelectionContext(context, storage.getSettings().redactionEnabled);
+    const described = describeSelectionContext(context, settings);
 
     if (!described) {
       return res.status(400).json({ error: "Select the node(s) you want to modify first." });
@@ -2212,15 +3221,20 @@ module.exports = function flowPilotRuntime(RED) {
     const history = sanitizeHistory(req.body.history);
     const historyTruncated = !!req.body.historyTruncated;
 
-    const finalize = function (result) { return finalizeModifyResult(result, originalNodes); };
+    const finalize = function (result) { return finalizeModifyResult(result, originalNodes, execution); };
     const hasSwitch = Array.isArray(context && context.nodes) &&
       context.nodes.some(function (node) { return node && node.type === "switch"; });
-    const modifyPrompt = modifySystemPrompt({ hasSwitch: hasSwitch });
+    // Keep the legacy prompt byte-identical for the explicit classic
+    // strategy. Agent prompt behavior keys only off the propagated strategy.
+    const modifyPrompt = modifySystemPrompt({
+      hasSwitch: hasSwitch,
+      agentWriteEnabled: execution.strategy === "agent"
+    });
 
     if (req.body.stream) {
       return runExecuteStream(
         req, res, modifyPrompt, "modify", String(prompt).trim(), context,
-        history, historyTruncated, finalize, req.body.conversationId
+        history, historyTruncated, finalize, req.body.conversationId, execution
       );
     }
 
@@ -2228,16 +3242,22 @@ module.exports = function flowPilotRuntime(RED) {
       const useTools = !!req.body.tools;
       const result = await runFlowGeneration(
         modifyPrompt, "modify", String(prompt).trim(), context,
-        history, historyTruncated, useTools
+        history, historyTruncated, useTools, execution
       );
       if (result.toolCalls) {
-        return res.json({ toolCalls: result.toolCalls, messages: result.messages, content: result.content, usage: result.usage });
+        return res.json({
+          toolCalls: result.toolCalls,
+          toolTiers: result.toolTiers,
+          messages: result.messages,
+          content: result.content,
+          usage: result.usage
+        });
       }
       recordTranscriptTurn(req.body.conversationId, "modify", String(prompt).trim(), transcriptTextFromGenerationResult(result));
       const { status, body } = finalize(result);
       res.status(status).json(body);
     } catch (err) {
-      sendGenerationError(res, "modify", err);
+      sendGenerationError(res, "modify", err, execution);
     }
   });
 };