refactor: rename workflow tool boundary

docs/records/2026-05-02-bug-hunt-findings.md

@@ -261,9 +261,9 @@ cluster, no edits, no test runs.
   Forensics-marker expiry fires silently after 2 hours. Users returning to a paused forensics session find the marker cleared with no log entry explaining why.
   Suggested fix: Log an expiry event at `INFO` level when the timer fires.
 
-- `workflow-mcp.ts:456-471` [edge case] **Status: CONFIRMED**
-  Error message for local-transport MCP suggests `/sf mcp init`, which does not resolve the structured-questions limitation for local transports.
-  Suggested fix: Clarify in the error message that structured questions require remote transport, not just MCP initialisation.
+- Former workflow transport helper (now `workflow-tools.js`) [edge case] **Status: CONFIRMED**
+  Error message for the old local-transport path suggested `/sf mcp init`, which did not resolve the structured-questions limitation for local transports.
+  Suggested fix: Keep workflow questions on native SF structured-question support; MCP remains client-only for external tools.
 
 - `workflow-reconcile.ts:752-759` [idempotency] **Status: CONFIRMED**
   After resolving the last conflict, `resolveConflict()` calls `reconcileWorktreeLogs()` a second time (line 758). If this second reconcile fails, the conflict is left in a partially-applied state with no rollback.

packages/pi-agent-core/src/interactive-questions.ts

@@ -5,8 +5,8 @@
  * gate hooks and LLM-facing JSON do not drift between local TUI, remote
  * Slack/Discord/Telegram, and MCP elicitation paths.
  *
- * Consumer: SF ask_user_questions extension, remote question manager, and the
- * packaged MCP server.
+ * Consumer: SF ask_user_questions extension, remote question manager, and
+ * structured-question transports.
  */
 
 export interface QuestionOption {

src/resources/extensions/sf/auto-direct-dispatch.js

@@ -24,7 +24,7 @@ import { deriveState } from "./state.js";
 import {
 	getRequiredWorkflowToolsForAutoUnit,
 	getWorkflowTransportSupportError,
-} from "./workflow-mcp.js";
+} from "./workflow-tools.js";
 export async function dispatchDirectPhase(ctx, pi, phase, base) {
 	const state = await deriveState(base);
 	const mid = state.activeMilestone?.id;

src/resources/extensions/sf/auto-model-selection.js

@@ -30,7 +30,7 @@ import { getSessionModelOverride } from "./session-model-override.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { applyModelPolicyFilter } from "./uok/model-policy.js";
 import { logWarning } from "./workflow-logger.js";
-import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
+import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-tools.js";
 /**
  * Thrown when the model-policy gate rejects every candidate model for a unit
  * dispatch (#4959 / #4681 / #4850).  The auto-loop catches this specifically

src/resources/extensions/sf/auto/phases.js

@@ -103,7 +103,7 @@ import {
 import {
 	getRequiredWorkflowToolsForAutoUnit,
 	getWorkflowTransportSupportError,
-} from "../workflow-mcp.js";
+} from "../workflow-tools.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { detectStuck } from "./detect-stuck.js";
 import {

src/resources/extensions/sf/bootstrap/ask-gate.js

@@ -9,11 +9,11 @@
  * `ask_user_questions`. If the return value has `allow: false`, return the
  * `reason` string as the tool's error response so the agent re-plans.
  *
- * // TODO: integrate into ask_user_questions tool registry once the workflow-mcp
+ * // TODO: integrate into ask_user_questions tool registry once the workflow tools
  * //        handler and any pi-coding-agent tool registration path surface a
  * //        pre-invoke hook point. Current wiring entry point candidates:
  * //          - packages/pi-coding-agent/src/modes/rpc/rpc-mode.ts (tool dispatch)
- * //          - src/resources/extensions/sf/workflow-mcp.ts (MCP form elicitation)
+ * //          - src/resources/extensions/sf/workflow-tools.js (structured question support)
  */
 import { isAutoActive, isCanAskUser } from "../auto.js";
 import { logWarning } from "../workflow-logger.js";

src/resources/extensions/sf/bootstrap/exec-tools.js

@@ -171,7 +171,7 @@ export function registerExecTools(pi) {
 		promptSnippet:
 			"Snapshot and reload the pi-agent so it resumes the same session with fresh extension code",
 		promptGuidelines: [
-			"Use this to reload extension code (MCP servers, tools) without losing the session.",
+			"Use this to reload extension code, external MCP server config, or native tools without losing the session.",
 			"The supervisor will resume the same session automatically in headless mode.",
 			"In interactive TUI: the process exits and you restart manually.",
 		],

src/resources/extensions/sf/guided-flow.js

@@ -84,7 +84,7 @@ import {
 	getRequiredWorkflowToolsForGuidedUnit,
 	getWorkflowTransportSupportError,
 	supportsStructuredQuestions,
-} from "./workflow-mcp.js";
+} from "./workflow-tools.js";
 
 export {
 	buildExistingMilestonesContext,

src/resources/extensions/sf/workflow-tools.js

@@ -1,3 +1,11 @@
+/**
+ * Workflow Tools — required native tool contracts for guided and autonomous units.
+ *
+ * Purpose: keep workflow dispatch validation tied to native SF agent tools while
+ * preserving the explicit "no workflow MCP transport" boundary.
+ *
+ * Consumer: guided-flow, auto dispatch, auto phases, and model selection checks.
+ */
 export function getRequiredWorkflowToolsForGuidedUnit(unitType) {
 	switch (unitType) {
 		case "discuss-milestone":
@@ -51,11 +59,6 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType) {
 			return [];
 	}
 }
-export function usesWorkflowMcpTransport(authMode, baseUrl) {
-	void authMode;
-	void baseUrl;
-	return false;
-}
 export function supportsStructuredQuestions(activeTools, options = {}) {
 	void options;
 	if (!activeTools.includes("ask_user_questions")) return false;