@manny-est/node-red-flowpilot 0.5.1 → 0.6.0-beta.1

package/flowpilot.js

@@ -1,14 +1,87 @@
 const http = require("http");
 const path = require("path");
 const createStorage = require("./lib/storage");
-const provider = require("./lib/provider-openai-compatible");
+const openaiProvider = require("./lib/provider-openai-compatible");
+const anthropicProvider = require("./lib/provider-anthropic");
+function getProvider(ap) {
+  return (ap && ap.type === "anthropic") ? anthropicProvider : openaiProvider;
+}
+
+const DIRECT_COMPLETION_SCHEMA = {
+  type: "object",
+  properties: {
+    explanation: { type: "string" },
+    flow: { type: "array" },
+    changes: { type: "array" },
+    newNodes: { type: "array" },
+    newWires: { type: "array" },
+    removeNodes: { type: "array" },
+    question: { type: "string" },
+    mode: { type: "string" }
+  },
+  additionalProperties: true
+};
+
+const SAFE_NODE_TYPES = new Set([
+  "inject", "function", "change", "switch", "filter", "json", "xml", "csv",
+  "base64", "html", "split", "join", "sort", "batch", "debug", "status",
+  "comment", "link in", "link out", "link call", "junction"
+]);
+
+const MODIFY_VERIFY_SKIP_PROPS = new Set([
+  "wires", "x", "y", "z", "g", "outputLabels", "inputLabels", "links"
+]);
+
+function classifyFlowNodes(nodes) {
+  const classes = { safe: [], sideEffecting: [] };
+  if (!Array.isArray(nodes)) { return classes; }
+
+  nodes.forEach(function (node) {
+    if (!node || typeof node !== "object") { return; }
+    const summary = {
+      id: node.id,
+      type: node.type,
+      name: node.name || ""
+    };
+    if (SAFE_NODE_TYPES.has(node.type)) {
+      classes.safe.push(summary);
+    } else {
+      classes.sideEffecting.push(summary);
+    }
+  });
+  return classes;
+}
+
+function directCompletionResponseFormat(activeProvider, auditAction, useTools) {
+  if (useTools || (activeProvider && activeProvider.type === "anthropic") ||
+      (auditAction !== "generate" && auditAction !== "modify")) {
+    return null;
+  }
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: "flowpilot_" + auditAction + "_response",
+      strict: false,
+      schema: DIRECT_COMPLETION_SCHEMA
+    }
+  };
+}
 const generationSystemPrompt = require("./lib/generation-system-prompt");
 const documentSystemPrompt = require("./lib/document-system-prompt");
 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;
 
 module.exports = function flowPilotRuntime(RED) {
   const storage = createStorage(RED.settings.userDir);
@@ -26,12 +99,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 = [
     {
@@ -140,6 +212,247 @@ 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"] },
+                {
+                  type: "array",
+                  items: { type: "string" },
+                  minItems: 1
+                }
+              ],
+              description: "Optional resolved node target for Document redirects."
+            }
+          },
+          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" && 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,
@@ -404,10 +717,12 @@ module.exports = function flowPilotRuntime(RED) {
   // entry reports the same shape.
   // ---------------------------------------------------------------------
   function performanceAuditFields(messages, content, providerResult) {
+    const promptChars = (messages || []).reduce(function (sum, m) {
+      return sum + (m && typeof m.content === "string" ? m.content.length : 0);
+    }, 0);
     const fields = {
-      promptChars: (messages || []).reduce(function (sum, m) {
-        return sum + (m && typeof m.content === "string" ? m.content.length : 0);
-      }, 0),
+      promptChars: promptChars,
+      promptTokenEst: Math.round(promptChars / 4),
       completionChars: (content || "").length
     };
     if (providerResult && providerResult.timing) { fields.timing = providerResult.timing; }
@@ -415,16 +730,186 @@ module.exports = function flowPilotRuntime(RED) {
     return fields;
   }
 
+  // W0.2: server-side redaction-placeholder validator. If a model echoes a
+  // [redacted:...] sentinel as a proposed value in changes[].set, drop that
+  // field before it reaches the client. This replaces the client-side
+  // CRITICAL rule that previously tried to prompt the model out of this.
+  // Returns { cleanedChanges, skippedNote } — skippedNote is null when nothing
+  // was dropped.
+  function isRedactionSentinel(v) {
+    if (typeof v === "string") {
+      return v === "[unserializable]" || v === "[redacted]" || v.indexOf("[redacted:") === 0;
+    }
+    if (Array.isArray(v)) { return v.some(isRedactionSentinel); }
+    if (v !== null && typeof v === "object") {
+      return Object.keys(v).some(function (k) { return isRedactionSentinel(v[k]); });
+    }
+    return false;
+  }
+
+  function stripRedactionPlaceholders(changes) {
+    const dropped = [];
+    const cleanedChanges = (Array.isArray(changes) ? changes : []).map(function (entry) {
+      if (!entry || typeof entry !== "object" || !entry.set) { return entry; }
+      const cleanSet = {};
+      const droppedKeys = [];
+      Object.keys(entry.set).forEach(function (k) {
+        if (isRedactionSentinel(entry.set[k])) {
+          droppedKeys.push(k);
+        } else {
+          cleanSet[k] = entry.set[k];
+        }
+      });
+      if (droppedKeys.length) {
+        dropped.push({ id: entry.id, keys: droppedKeys });
+      }
+      return Object.assign({}, entry, { set: cleanSet });
+    });
+
+    let skippedNote = null;
+    if (dropped.length) {
+      const parts = dropped.map(function (d) {
+        return d.keys.join(", ") + (d.id ? " on " + d.id : "");
+      });
+      skippedNote = "Dropped redacted field(s) — these are credentials or secrets " +
+        "that FlowPilot cannot write. They are unchanged on the canvas. " +
+        "Update them directly in the Node-RED node editor if needed. " +
+        "(" + parts.join("; ") + ")";
+    }
+    return { cleanedChanges: cleanedChanges, skippedNote: skippedNote };
+  }
+
+  // B2: sanitized context can contain "[unserializable]" for opaque
+  // node-internal values. Models can echo those fields back as empty values,
+  // false, zero, objects, or other guessed defaults. No proposed value is
+  // safely diffable against an unknown original, so drop the field before
+  // reconstructing the full flow. Visible originals remain legitimate Modify
+  // targets because they do not carry the sentinel.
+  function stripUnserializableEchoes(set, originalNode) {
+    const clean = Object.assign({}, (set && typeof set === "object") ? set : {});
+    if (!originalNode) { return clean; }
+    Object.keys(clean).forEach(function (k) {
+      if (originalNode[k] === "[unserializable]") {
+        delete clean[k];
+      }
+    });
+    return clean;
+  }
+
+  // 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.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.appendDebugLog(Object.assign({
+      type: type,
+      promptTokenEst: Math.round(promptChars / 4),
+      messageCount: messages.length
+    }, fields));
+  }
+
+  // W0.1: warn when estimated prompt token count approaches the provider's
+  // configured context window (numCtx). Overflow is silent — instructions
+  // vanish with no error, which is exactly the "model ignores my rules"
+  // signature. 32k tokens is the practical floor for prompts this size.
+  // Called after buildMessages; numCtx=0 means unknown/unset, skip check.
+  function warnNumCtxOverflow(messages, activeProvider, mode) {
+    const numCtx = (activeProvider && activeProvider.numCtx) ? activeProvider.numCtx : 0;
+    const promptChars = (messages || []).reduce(function (sum, m) {
+      return sum + (m && typeof m.content === "string" ? m.content.length : 0);
+    }, 0);
+    const promptTokenEst = Math.round(promptChars / 4);
+    if (numCtx > 0 && promptTokenEst > numCtx * 0.9) {
+      console.warn("[FlowPilot] num_ctx overflow risk: mode=%s estimated=%d tokens numCtx=%d (%.0f%% full)",
+        mode, promptTokenEst, numCtx, (promptTokenEst / numCtx) * 100);
+    }
+    return promptTokenEst;
+  }
+
   // ---------------------------------------------------------------------
   // Shared helper: format selected-node context (sanitized by the frontend)
   // into a system-message string for the model, plus counts for audit logs.
   // 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 : [];
@@ -436,7 +921,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 " +
@@ -447,37 +932,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 = settings.allowConfigContext === true &&
+      context && Array.isArray(context.configNodes) ? context.configNodes : [];
+    if (configNodes.length > 0) {
+      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;
   }
 
   // ---------------------------------------------------------------------
@@ -485,27 +1037,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 provider.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 };
     }
 
@@ -515,6 +1096,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);
 
@@ -532,11 +1122,18 @@ 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
     );
+    warnNumCtxOverflow(messages, activeProvider, "chat-stream");
 
     res.writeHead(200, {
       "Content-Type": "text/event-stream; charset=utf-8",
@@ -556,7 +1153,7 @@ module.exports = function flowPilotRuntime(RED) {
 
     let streamResult;
     try {
-      streamResult = await provider.chatStream(activeProvider, messages,
+      streamResult = await getProvider(activeProvider).chatStream(activeProvider, messages,
         function (delta) {
           const visible = splitter.push(delta);
           if (visible) {
@@ -602,13 +1199,41 @@ 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());
+      res.json(maskProviderSecrets(storage.getSettings()));
     } catch (err) {
       res.status(500).json({ error: err.message });
     }
@@ -662,18 +1287,110 @@ 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/
+  // models) 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, the only two routes allowed to
+  // contact an unconfirmed URL. confirmedBaseUrl/confirmedAt are written
+  // ONLY by those two routes on a passing check; 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 });
     }
@@ -685,10 +1402,14 @@ module.exports = function flowPilotRuntime(RED) {
   // that doesn't support /v1/models — see listModels().
 
   RED.httpAdmin.post("/flowpilot/models", 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);
-      const result = await provider.listModels(activeProvider);
+      if (!requireConfirmedProvider(res, activeProvider)) { return; }
+      const result = await getProvider(activeProvider).listModels(activeProvider);
       storage.appendAudit({
         action: "list_models",
         providerName: activeProvider.providerName,
@@ -720,6 +1441,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 });
@@ -733,7 +1459,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",
@@ -743,6 +1470,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 });
       }
@@ -762,6 +1492,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 });
     }
@@ -786,7 +1521,49 @@ 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 (!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." });
@@ -794,13 +1571,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 provider.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,
@@ -808,16 +1608,48 @@ 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 : []); }
+          ? function (r) {
+              return finalizeModifyResult(
+                r, (context && Array.isArray(context.nodes)) ? context.nodes : [], execution
+              );
+            }
           : finalizeSimpleGeneration;
         const { status, body } = finalize(generated);
         return res.status(status).json(body);
@@ -833,7 +1665,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);
     }
   });
 
@@ -891,6 +1723,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) {
@@ -901,6 +1736,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 });
@@ -926,11 +1764,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,
@@ -941,8 +1805,8 @@ module.exports = function flowPilotRuntime(RED) {
       // Capability probe — connectivity already succeeded above, so a
       // probe failure here just means "no tool support", not a /test failure.
       // Persist the result on the provider profile for the agentic tool-calling path.
-      const probe = await provider.probeTools(activeProvider);
-      const reasoning = provider.detectReasoning(result.raw);
+      const probe = await getProvider(activeProvider).probeTools(activeProvider);
+      const reasoning = getProvider(activeProvider).detectReasoning(result.raw);
       storage.appendAudit({
         action: "capability_probe",
         providerName: activeProvider.providerName,
@@ -959,11 +1823,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"
@@ -994,16 +1863,35 @@ 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);
 
-      const probe = await provider.probeTools(activeProvider);
-      const chatResult = await provider.chat(activeProvider, [
+      // 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." }
       ]);
-      const reasoning = provider.detectReasoning(chatResult.raw);
+
+      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) {
         return p.id === activeProvider.id
@@ -1012,11 +1900,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",
@@ -1050,16 +1940,17 @@ module.exports = function flowPilotRuntime(RED) {
   // out from runFlowGeneration so the streaming variant can build the
   // same request and swap provider.chat for provider.chatStream.
   // ---------------------------------------------------------------------
-  function buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated) {
+  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
     // mode's own system prompt above already specifies.
     const personaInstruction = personaPrompt.buildPersonaInstruction(settings.personaIntensity, { scope: "explanation" });
     const messages = buildMessages(systemPrompt + "\n\n" + personaInstruction, history, historyTruncated, described, userPrompt);
+    warnNumCtxOverflow(messages, activeProvider, auditAction);
     return { activeProvider, described, messages };
   }
 
@@ -1068,7 +1959,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;
@@ -1080,6 +1972,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;
   }
 
@@ -1110,71 +2010,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 } /
@@ -1185,8 +2020,42 @@ module.exports = function flowPilotRuntime(RED) {
   // provider.chatStream). Throws an Error with .status and (when applicable)
   // .raw for the route to relay.
   // ---------------------------------------------------------------------
-  function processGenerationContent(content, providerResult, messages, auditAction, described, activeProvider) {
+  function buildFpUidManifest(flow) {
+    if (!Array.isArray(flow)) { return []; }
+
+    return flow
+      .filter(function (node) {
+        return node && node.type === "debug" &&
+          typeof node.name === "string" && /^FP-UID\d+$/.test(node.name);
+      })
+      .sort(function (a, b) {
+        const bySequence = Number(a.name.slice(6)) - Number(b.name.slice(6));
+        if (bySequence !== 0) { return bySequence; }
+        const byName = a.name.localeCompare(b.name);
+        if (byName !== 0) { return byName; }
+        return String(a.id || "").localeCompare(String(b.id || ""));
+      })
+      .map(function (tap) {
+        const upstream = flow.find(function (node) {
+          return node && Array.isArray(node.wires) && node.wires.some(function (port) {
+            return Array.isArray(port) && port.indexOf(tap.id) !== -1;
+          });
+        });
+        const upstreamPort = upstream ? upstream.wires.findIndex(function (port) {
+          return Array.isArray(port) && port.indexOf(tap.id) !== -1;
+        }) : -1;
+        return {
+          name: tap.name,
+          id: tap.id,
+          wiredFrom: upstream ? upstream.id : null,
+          wiredFromPort: upstreamPort >= 0 ? upstreamPort : null
+        };
+      });
+  }
+
+  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 —
@@ -1195,11 +2064,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);
@@ -1238,7 +2107,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
@@ -1253,7 +2122,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;
@@ -1261,13 +2130,73 @@ module.exports = function flowPilotRuntime(RED) {
       }
     }
 
+    // Constrained-decoding providers cannot emit the legacy plain-prose
+    // redirect + hidden data block because response_format requires a JSON
+    // object. Accept the equivalent top-level {"mode":"..."} envelope and
+    // translate it back into the existing prose/suggestedAction result shape.
+    // Reuse the original request as the chip prompt when the model omits one.
+    if (typeof parsed.mode === "string" &&
+        ["generate", "document", "modify", "chat"].indexOf(parsed.mode) !== -1 &&
+        parsed.mode !== auditAction) {
+      const redirectPrompt = (typeof parsed.prompt === "string" && parsed.prompt.trim())
+        ? parsed.prompt.trim()
+        : String(userPrompt || "").trim();
+      const redirect = {
+        mode: parsed.mode,
+        prompt: redirectPrompt
+      };
+      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 + "_mode_redirect" }, auditFields, perf));
+      return { prose: redirectProse, suggestedAction: redirect };
+    }
+
+    // W2 — Class A repair pass. Run on every successfully-parsed envelope
+    // before the mode-specific branches below. Repairs that don't apply
+    // to a given mode's envelope shape are no-ops (e.g. repairFlowNodes
+    // on an empty/absent flow array). Switch mismatches are surfaced as a
+    // skippedNote on the modify result rather than a 422 — a targeted
+    // message the model can act on, without discarding the rest of the
+    // response.
+    {
+      const repaired = repairEnvelope(parsed);
+      parsed = repaired.envelope;
+      if (repaired.repairs.length) {
+        console.info("[FlowPilot] W2 validator repaired %d field(s): %s",
+          repaired.repairs.length,
+          repaired.repairs.map(function (r) { return r.rule + ":" + r.detail; }).join("; "));
+      }
+      if (repaired.switchMismatches.length) {
+        const detail = repaired.switchMismatches.map(function (m) {
+          return "node " + m.id + " has " + m.rulesLen + " rule(s) but " + m.wiresLen + " wire port(s)";
+        }).join("; ");
+        // Surface as a validation warning on the parsed envelope — the
+        // modify path will pick it up below and add it as a skippedNote.
+        parsed._switchMismatchNote = "Switch rules/wires mismatch — " + detail +
+          ". The number of wires[] entries must equal the number of rules[]. " +
+          "Please resend with the corrected switch node.";
+      }
+    }
+
     // Clarifying-question envelope. The model may ask ONE
     // follow-up question instead of producing a flow when the request is too
     // ambiguous to act on. The frontend renders the question as a normal
     // 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; }
@@ -1293,6 +2222,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 : [];
@@ -1306,28 +2253,43 @@ module.exports = function flowPilotRuntime(RED) {
       // since newNodes itself is copied through.
       const newGroups = Array.isArray(parsed.newGroups) ? parsed.newGroups : [];
 
+      // W0.2: strip any redaction-placeholder values from changes[].set before
+      // they reach the client. Code owns the user notification now — the CRITICAL
+      // block in the Modify prompt that tried to prevent this via instruction is
+      // deleted. skippedNote is surfaced in modifyResult for the frontend to show.
+      const { cleanedChanges, skippedNote: redactionSkippedNote } = stripRedactionPlaceholders(changes);
+
       storage.appendAudit(Object.assign({
         action: auditAction,
         providerName: activeProvider.providerName,
         baseUrl: activeProvider.baseUrl,
         model: activeProvider.model,
-        changeCount: changes.length,
+        changeCount: cleanedChanges.length,
         newNodeCount: newNodes.length,
         newWireCount: newWires.length,
         removeNodeCount: removeNodes.length,
         newGroupCount: newGroups.length,
         contextNodeCount: described ? described.nodeCount : 0,
         contextConnectionCount: described ? described.connectionCount : 0
-      }, perf));
+      }, auditFields, perf));
 
       const modifyResult = {
         explanation: parsed.explanation || "",
-        changes: changes,
+        changes: cleanedChanges,
         newNodes: newNodes,
         newWires: newWires,
         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(" "); }
       const modifyAction = extractSuggestedAction(parsed);
       if (modifyAction) { modifyResult.suggestedAction = modifyAction; }
       return modifyResult;
@@ -1349,7 +2311,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 || "",
@@ -1357,6 +2319,11 @@ module.exports = function flowPilotRuntime(RED) {
       newNodes: Array.isArray(parsed.newNodes) ? parsed.newNodes : [],
       newWires: Array.isArray(parsed.newWires) ? parsed.newWires : []
     };
+    if (auditAction === "build") {
+      const fpUidManifest = buildFpUidManifest(flow);
+      if (fpUidManifest.length) { flowResult.fpUidManifest = fpUidManifest; }
+      if (flow.length) { flowResult.stepNodeClasses = classifyFlowNodes(flow); }
+    }
     const flowAction = extractSuggestedAction(parsed);
     if (flowAction) { flowResult.suggestedAction = flowAction; }
     return flowResult;
@@ -1370,19 +2337,101 @@ 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) {
-    const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated);
-    const chatOptions = useTools ? { tools: AGENT_READ_TOOLS, toolChoice: "auto" } : undefined;
-    const result = await provider.chat(activeProvider, messages, chatOptions);
+  async function runFlowGeneration(systemPrompt, auditAction, userPrompt, context, history, historyTruncated, useTools, execution) {
+    const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated, auditAction);
+    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" && execution &&
+      execution.strategy === "agent" ? "required" : "auto";
+    let chatOptions = toolsEnabled
+      ? { tools: offeredTools, toolChoice: toolChoice }
+      : (responseFormat ? { responseFormat: responseFormat } : undefined);
+    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, execution
+      );
+      parseOutcome = generated.prose ? "prose" : generated.question ? "question" : "success";
+      return generated;
+    } catch (err) {
+      parseOutcome = "parse_error:" + (err.message || "");
+      throw err;
+    } finally {
+      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
+      });
     }
-    return processGenerationContent(result.content || "", result, messages, auditAction, described, activeProvider);
   }
 
   // ---------------------------------------------------------------------
@@ -1393,21 +2442,52 @@ 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) {
-    const { activeProvider, described, messages } = buildGenerationContext(systemPrompt, userPrompt, context, history, historyTruncated);
-    const result = await provider.chatStream(activeProvider, messages, onDelta);
-    return processGenerationContent(result.content || "", result, messages, auditAction, described, activeProvider);
+  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(
+      activeProvider, messages, onDelta, undefined, streamOptions
+    );
+    const content = result.content || "";
+    let parseOutcome = "unknown";
+    try {
+      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 {
+      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 });
   }
 
@@ -1445,7 +2525,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; }
@@ -1458,6 +2538,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; }));
 
@@ -1534,10 +2630,17 @@ module.exports = function flowPilotRuntime(RED) {
     // Each patch's "set" is shallow-merged onto a copy of the original node.
     // "id", "x", "y", "z" can never move via a patch — strip them
     // defensively even though the prompt already forbids them.
+    const originalById = {};
+    originalNodes.forEach(function (n) {
+      if (n && n.id !== undefined && n.id !== null) {
+        originalById[String(n.id)] = n;
+      }
+    });
+
     const patchById = {};
     validChanges.forEach(function (c) {
       const set = (c.set && typeof c.set === "object") ? c.set : {};
-      const clean = Object.assign({}, set);
+      const clean = stripUnserializableEchoes(set, originalById[String(c.id)]);
       delete clean.id;
       delete clean.x;
       delete clean.y;
@@ -1664,7 +2767,41 @@ 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) {
+      const set = patchById[String(change.id)] || {};
+      Object.keys(set).forEach(function (prop) {
+        if (MODIFY_VERIFY_SKIP_PROPS.has(prop)) { return; }
+        verifySteps.push({
+          nodeId: change.id,
+          check: "property",
+          prop: prop,
+          expected: set[prop]
+        });
+      });
+    });
+    newNodes.forEach(function (node) {
+      if (!node || node.id === undefined || node.id === null) { return; }
+      verifySteps.push({ nodeId: node.id, check: "exists" });
+    });
+    finalRemoveNodes.forEach(function (id) {
+      verifySteps.push({ nodeId: id, check: "absent" });
+    });
+    newWires.forEach(function (wire) {
+      verifySteps.push({
+        fromId: wire.from,
+        fromPort: wire.fromPort || 0,
+        toId: wire.to,
+        check: "wire"
+      });
+    });
 
     const body = {
       explanation: result.explanation,
@@ -1674,6 +2811,7 @@ module.exports = function flowPilotRuntime(RED) {
       removeNodes: finalRemoveNodes,
       newGroups: newGroups
     };
+    if (verifySteps.length) { body.verifySteps = verifySteps; }
     if (skippedDescriptions.length > 0) { body.skippedNote = skippedDescriptions.join(". ") + "."; }
     if (result.suggestedAction) { body.suggestedAction = result.suggestedAction; }
 
@@ -1693,7 +2831,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",
@@ -1706,12 +2844,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();
@@ -1750,7 +2894,13 @@ module.exports = function flowPilotRuntime(RED) {
         history, historyTruncated, useTools
       );
       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);
@@ -1790,7 +2940,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);
@@ -1802,7 +2958,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." });
@@ -1830,7 +2986,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);
@@ -1841,8 +3003,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." });
@@ -1860,29 +3027,43 @@ 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"; });
+    // 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, modifySystemPrompt, "modify", String(prompt).trim(), context,
-        history, historyTruncated, finalize, req.body.conversationId
+        req, res, modifyPrompt, "modify", String(prompt).trim(), context,
+        history, historyTruncated, finalize, req.body.conversationId, execution
       );
     }
 
     try {
       const useTools = !!req.body.tools;
       const result = await runFlowGeneration(
-        modifySystemPrompt, "modify", String(prompt).trim(), context,
-        history, historyTruncated, useTools
+        modifyPrompt, "modify", String(prompt).trim(), context,
+        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);
     }
   });
 };