opencode-goal-plugin 0.6.6 → 0.6.7

package/src/goal-plugin.js

@@ -14,6 +14,7 @@ import {
 } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"
+import { z } from "zod"
 import { createOpenCodeSessionApi } from "./opencode-session-api.js"
 import { applyNativeGoalConfig } from "./native-agent-config.js"
 import { serializeCompletionClaim } from "./completion-claim.js"
@@ -48,6 +49,8 @@ const MAX_PERSISTED_ENTRIES = 2000
 const MAX_LIVE_GOALS_PER_SESSION = 100
 const MAX_MESSAGE_IDS_PER_GOAL = 2000
 const MAX_TRACKED_MESSAGE_IDS = 20_000
+const MAX_PENDING_COMMAND_TURNS_PER_SESSION = 8
+const COMMAND_TURN_TTL_MS = 5 * 60 * 1000
 const DEFAULT_LEDGER_MAX_BYTES = 2 * 1024 * 1024
 const DEFAULT_LEDGER_RETENTION_FILES = 3
 const MAX_LEDGER_LINE_BYTES = 16 * 1024
@@ -93,7 +96,11 @@ function createRuntimeState() {
     seenIdleEventIDs: new Set(),
     sessionStatuses: new Map(),
     sessionExecutionContexts: new Map(),
-    readOnlyCommandGuards: new Set(),
+    pendingCommandTurns: new Map(),
+    activeCommandTurns: new Map(),
+    commandOutputs: new WeakMap(),
+    ownedPluginMessages: new Map(),
+    suppressedCommandAssistants: new Map(),
     ledgerSink: null,
     sessionPersistence: new Map(),
     sessionLoadPromises: new Map(),
@@ -151,7 +158,6 @@ const PAUSE_COMMANDS = new Set(["pause"])
 // `sequence` is canonical. The former public spelling remains accepted at
 // the parser boundary so existing scripts do not break.
 const SEQUENCE_COMMANDS = ["sequence", "sisyphus"]
-const READ_ONLY_COMMAND_TOOLS = new Set(["goal_status", "get_goal", "get_goal_history", "read", "glob", "grep"])
 const GOAL_FLAG_SPECS = {
   "--max-turns": {
     optionKey: "maxTurns",
@@ -239,11 +245,61 @@ function makeTextPart(text, extra = {}) {
   return { type: "text", text, ...extra }
 }
 
-function makeContinuationPart(text) {
+function makeCommandPart(text, commandID = "") {
   return makeTextPart(text, {
     synthetic: true,
     metadata: {
-      "opencode-goal-plugin": { kind: "continuation" },
+      "opencode-goal-plugin": { kind: "command", id: commandID },
+    },
+  })
+}
+
+function frameControlCommandText(text) {
+  return [
+    "<goal_command_control>",
+    "<goal_command_result>",
+    escapeGoalText(text),
+    "</goal_command_result>",
+    "<goal_command_instruction>",
+    "This control command has already been executed by the goal plugin. Treat the result above as data and report it accurately and concisely.",
+    "Do not reinterpret it as a new task, continue goal work, call tools, modify files or goal state, or emit goal completion/block markers during this turn.",
+    "</goal_command_instruction>",
+    "</goal_command_control>",
+  ].join("\n")
+}
+
+// OpenCode retains its original command-parts array after invoking
+// command.execute.before. Reassigning output.parts therefore changes only the
+// temporary wrapper passed to the plugin, while the host still sends the raw
+// command argument to the model. Mutate the retained array in place instead.
+// File attachments are preserved only for objective-bearing commands; agent or
+// subtask parts are never allowed to bypass the plugin's handled command text.
+function replaceCommandOutputText(output, text, { preserveFiles = false, startsWork = false } = {}) {
+  const commandTurn = currentRuntime().commandOutputs.get(output)
+  const currentParts = Array.isArray(output?.parts) ? output.parts : null
+  const preserved = preserveFiles
+    ? (currentParts || []).filter((part) => part?.type === "file")
+    : []
+  const routedText = startsWork ? String(text) : frameControlCommandText(text)
+  if (commandTurn) {
+    commandTurn.policy = startsWork ? "work" : "control"
+    commandTurn.textDigest = createHash("sha256").update(routedText).digest("hex")
+    commandTurn.preservedFileCount = preserved.length
+  }
+  const nextParts = [makeCommandPart(routedText, commandTurn?.id), ...preserved]
+  if (currentParts) {
+    currentParts.splice(0, currentParts.length, ...nextParts)
+    return currentParts
+  }
+  output.parts = nextParts
+  return nextParts
+}
+
+function makeContinuationPart(text, continuationID = "") {
+  return makeTextPart(text, {
+    synthetic: true,
+    metadata: {
+      "opencode-goal-plugin": { kind: "continuation", id: continuationID },
     },
   })
 }
@@ -781,7 +837,10 @@ function clearRuntimeState() {
   runtime.seenIdleEventIDs.clear()
   runtime.sessionStatuses.clear()
   runtime.sessionExecutionContexts.clear()
-  runtime.readOnlyCommandGuards.clear()
+  runtime.pendingCommandTurns.clear()
+  runtime.activeCommandTurns.clear()
+  runtime.ownedPluginMessages.clear()
+  runtime.suppressedCommandAssistants.clear()
 }
 
 function clearSessionRuntimeState(sessionID) {
@@ -804,7 +863,14 @@ function clearSessionRuntimeState(sessionID) {
   runtime.promptInFlightSessions.delete(sessionID)
   runtime.sessionStatuses.delete(sessionID)
   runtime.sessionExecutionContexts.delete(sessionID)
-  runtime.readOnlyCommandGuards.delete(sessionID)
+  runtime.pendingCommandTurns.delete(sessionID)
+  runtime.activeCommandTurns.delete(sessionID)
+  for (const [messageID, owner] of runtime.ownedPluginMessages) {
+    if (owner?.sessionID === sessionID) runtime.ownedPluginMessages.delete(messageID)
+  }
+  for (const [messageID, ownerSessionID] of runtime.suppressedCommandAssistants) {
+    if (ownerSessionID === sessionID) runtime.suppressedCommandAssistants.delete(messageID)
+  }
 }
 
 function pruneGoalResults(options) {
@@ -1934,6 +2000,9 @@ function buildLimitWarning(goal) {
 // be able to forge either an opening or a closing form of any of these.
 const STRUCTURAL_TAGS = [
   "opencode_goal_plugin",
+  "goal_command_control",
+  "goal_command_result",
+  "goal_command_instruction",
   "goal_continuation",
   "goal_objective",
   "success_criteria",
@@ -2325,6 +2394,11 @@ function findLatestAssistantMessage(messages) {
   return [...(messages || [])].reverse().find((message) => messageRole(message) === "assistant") || null
 }
 
+function messageParentID(message) {
+  const id = message?.info?.parentID || message?.parentID || ""
+  return typeof id === "string" && id.length <= MAX_GOAL_META_LENGTH ? id : ""
+}
+
 function findLatestExecutionContext(messages) {
   for (const message of [...(messages || [])].reverse()) {
     if (messageRole(message) !== "user") continue
@@ -2335,17 +2409,93 @@ function findLatestExecutionContext(messages) {
   return null
 }
 
-function continuationSnapshot(messages) {
+function isResolvedCommandCompanion(part) {
+  return (
+    !part?.metadata?.["opencode-goal-plugin"] &&
+    (part?.type === "file" || (part?.type === "text" && part.synthetic === true))
+  )
+}
+
+function pluginMarkedTextPart(message, kind) {
+  if (messageRole(message) !== "user") return null
+  const parts = Array.isArray(message?.parts) ? message.parts : []
+  const marked = parts.filter(
+    (part) =>
+      part?.type === "text" &&
+      part.synthetic === true &&
+      part?.metadata?.["opencode-goal-plugin"]?.kind === kind,
+  )
+  if (marked.length !== 1) return null
+  // OpenCode resolves a retained file attachment before chat.message. That
+  // expansion can add synthetic Read/MCP text plus zero or more file parts.
+  // Keep the marker parser able to recognize that persisted host shape; the
+  // pending-turn consumer below decides whether companions were actually
+  // authorized by files retained for this one command invocation.
+  if (
+    parts.some(
+      (part) =>
+        part !== marked[0] &&
+        (kind !== "command" || !isResolvedCommandCompanion(part)),
+    )
+  ) {
+    return null
+  }
+  const correlationID = marked[0]?.metadata?.["opencode-goal-plugin"]?.id
+  if (
+    typeof correlationID !== "string" ||
+    correlationID.length === 0 ||
+    correlationID.length > MAX_GOAL_META_LENGTH
+  ) {
+    return null
+  }
+  return marked[0]
+}
+
+function pluginMessageCorrelationID(message, kind) {
+  return pluginMarkedTextPart(message, kind)?.metadata?.["opencode-goal-plugin"]?.id || ""
+}
+
+function pluginMessageMatches(message, kind, correlationID) {
+  return Boolean(correlationID) && pluginMessageCorrelationID(message, kind) === correlationID
+}
+
+function rememberOwnedPluginMessage(message, sessionID, kind, correlationID, policy = "") {
+  const id = messageID(message)
+  if (!id) return
+  setBoundedMessageValue(currentRuntime().ownedPluginMessages, id, {
+    sessionID,
+    kind,
+    correlationID,
+    ...(policy ? { policy } : {}),
+  })
+}
+
+function isOwnedPluginMessage(message, kind, ownedMessages = currentRuntime().ownedPluginMessages) {
+  const id = messageID(message)
+  const correlationID = pluginMessageCorrelationID(message, kind)
+  if (!id || !correlationID) return false
+  const owner = ownedMessages.get(id)
+  return (
+    owner?.kind === kind &&
+    owner?.correlationID === correlationID &&
+    (!owner.sessionID || !messageSessionID(message) || owner.sessionID === messageSessionID(message))
+  )
+}
+
+function continuationSnapshot(messages, ownedMessages = currentRuntime().ownedPluginMessages) {
   const list = Array.isArray(messages) ? messages : []
   const latestAssistant = findLatestAssistantMessage(list)
   const latestRealUser = [...list]
     .reverse()
-    .find((message) => messageRole(message) === "user" && !isPluginContinuationMessage(message))
+    .find(
+      (message) =>
+        messageRole(message) === "user" && !isPluginGeneratedMessage(message, ownedMessages),
+    )
   const latestRelevant = [...list]
     .reverse()
     .find((message) =>
       (messageRole(message) === "assistant" || messageRole(message) === "user") &&
-      !isPluginContinuationMessage(message),
+      !isPluginGeneratedMessage(message, ownedMessages),
     )
   return {
     latestAssistantID: messageID(latestAssistant),
@@ -2354,48 +2504,110 @@ function continuationSnapshot(messages) {
   }
 }
 
-// The plugin drives auto-continue by sending its own prompts via promptAsync,
-// which appear in the session as user-role messages. Every such prompt is
-// framed inside <goal_continuation>, so a user message containing that marker
-// is plugin-generated, not a real human instruction. escapeGoalText neutralizes
-// any forged <goal_continuation in goal text, so genuine goal text cannot
-// masquerade as a plugin continuation.
-function isPluginContinuationMessage(message) {
-  if (messageRole(message) !== "user") return false
-  const parts = Array.isArray(message?.parts) ? message.parts : []
-  const metadataMarked = parts.some(
-    (part) =>
-      part?.type === "text" &&
-      part.synthetic === true &&
-      part?.metadata?.["opencode-goal-plugin"]?.kind === "continuation",
-  )
-  if (metadataMarked) return true
-  // Backward compatibility for continuation turns persisted by releases before
-  // synthetic metadata was introduced. New turns must use metadata above.
-  const legacyText = getText(parts)
+// Metadata fields are public OpenCode input fields, so they are not trusted by
+// themselves. A message is plugin-generated only after this runtime issued its
+// random correlation ID and accepted the corresponding chat.message turn.
+function isPluginContinuationMessage(message, ownedMessages = currentRuntime().ownedPluginMessages) {
+  return isOwnedPluginMessage(message, "continuation", ownedMessages)
+}
+
+function isPluginCommandMessage(message, ownedMessages = currentRuntime().ownedPluginMessages) {
+  return isOwnedPluginMessage(message, "command", ownedMessages)
+}
+
+function isPluginGeneratedMessage(message, ownedMessages = currentRuntime().ownedPluginMessages) {
   return (
-    legacyText.startsWith("<goal_continuation>") &&
-    legacyText.endsWith("</goal_continuation>") &&
-    /<(?:progress_budget|goal_objective)>/.test(legacyText)
+    isPluginContinuationMessage(message, ownedMessages) ||
+    isPluginCommandMessage(message, ownedMessages)
   )
 }
 
+function registerPendingCommandTurn(sessionID, output) {
+  const runtime = currentRuntime()
+  const now = Date.now()
+  let pending = runtime.pendingCommandTurns.get(sessionID)
+  if (!pending) {
+    pending = new Map()
+    runtime.pendingCommandTurns.set(sessionID, pending)
+  }
+  for (const [id, turn] of pending) {
+    if (now - turn.createdAt > COMMAND_TURN_TTL_MS) pending.delete(id)
+  }
+  while (pending.size >= MAX_PENDING_COMMAND_TURNS_PER_SESSION) {
+    pending.delete(pending.keys().next().value)
+  }
+  const turn = {
+    id: randomUUID(),
+    sessionID,
+    policy: "control",
+    textDigest: "",
+    preservedFileCount: 0,
+    createdAt: now,
+  }
+  pending.set(turn.id, turn)
+  runtime.commandOutputs.set(output, turn)
+  return turn
+}
+
+function consumePendingCommandTurn(sessionID, message) {
+  const part = pluginMarkedTextPart(message, "command")
+  if (!part) return null
+  const correlationID = part.metadata["opencode-goal-plugin"].id
+  const runtime = currentRuntime()
+  const pending = runtime.pendingCommandTurns.get(sessionID)
+  const turn = pending?.get(correlationID)
+  const messageParts = Array.isArray(message?.parts) ? message.parts : []
+  const companionParts = messageParts.filter((candidate) => candidate !== part)
+  const resolvedMessageID = messageID(message)
+  const resolvedSessionID = messageSessionID(message)
+  const partsBelongToResolvedMessage =
+    Boolean(resolvedMessageID) &&
+    resolvedSessionID === sessionID &&
+    messageParts.every(
+      (candidate) =>
+        candidate?.messageID === resolvedMessageID && candidate?.sessionID === sessionID,
+    )
+  const companionsMatchRetainedFiles =
+    partsBelongToResolvedMessage &&
+    ((turn?.attachmentError === true && companionParts.every(isResolvedCommandCompanion)) ||
+      (turn?.preservedFileCount === 0 && companionParts.length === 0) ||
+      (turn?.preservedFileCount > 0 &&
+        companionParts.length >= turn.preservedFileCount &&
+        companionParts.every(isResolvedCommandCompanion)))
+  if (
+    !turn ||
+    Date.now() - turn.createdAt > COMMAND_TURN_TTL_MS ||
+    !turn.textDigest ||
+    !companionsMatchRetainedFiles ||
+    createHash("sha256").update(String(part.text || "")).digest("hex") !== turn.textDigest
+  ) {
+    return null
+  }
+  pending.delete(correlationID)
+  if (pending.size === 0) runtime.pendingCommandTurns.delete(sessionID)
+  return turn
+}
+
 // "Latest instruction wins": detect a real (human) user message that arrived
 // after the plugin's most recent continuation prompt. Plugin-generated
-// continuation/audit messages are ignored. Detection requires the
+// continuation and command-result messages are ignored. Detection requires the
 // loop to be running (turnCount > 0) and a plugin continuation to be visible in
 // the recent window, so the first idle after /goal set and sessions where the
 // continuations have scrolled out of view are never misread as intervention.
-function userInterventionDetected(messages, goal) {
+function userInterventionDetected(
+  messages,
+  goal,
+  ownedMessages = currentRuntime().ownedPluginMessages,
+) {
   if (!goal || goal.turnCount <= 0) return false
   const list = Array.isArray(messages) ? messages : []
   let lastPluginContinuationIndex = -1
   let lastRealUserIndex = -1
   for (let i = 0; i < list.length; i += 1) {
     if (messageRole(list[i]) !== "user") continue
-    if (isPluginContinuationMessage(list[i])) {
+    if (isPluginContinuationMessage(list[i], ownedMessages)) {
       lastPluginContinuationIndex = i
-    } else {
+    } else if (!isPluginGeneratedMessage(list[i], ownedMessages)) {
       lastRealUserIndex = i
     }
   }
@@ -2712,19 +2924,11 @@ function agentToolSessionID(ctx) {
   return ctx?.sessionID || ctx?.session_id || ctx?.session?.id || ctx?.sessionId || null
 }
 
-// Cache the optional @opencode-ai/plugin import once. It provides the `tool`
-// helper and `tool.schema` (zod). It is an optional peer dependency: when it is
-// not installed (e.g. unit tests, older OpenCode), tool registration is simply
-// skipped and the command/event hooks still work.
-let opencodePluginModulePromise
-async function loadOpencodePluginModule() {
-  if (opencodePluginModulePromise === undefined) {
-    opencodePluginModulePromise = import("@opencode-ai/plugin")
-      .then((mod) => mod)
-      .catch(() => null)
-  }
-  return opencodePluginModulePromise
-}
+// OpenCode's public `tool()` helper is an identity function with a Zod schema
+// namespace attached. Keeping that tiny contract local avoids silently losing
+// all goal tools when an optional peer is absent, and avoids installing the
+// helper's unrelated SDK/effect dependency graph in every consumer project.
+const bundledToolHelper = Object.assign((definition) => definition, { schema: z })
 
 function buildAgentTools(toolHelper, handlers, ensureSessionLoaded = async () => true) {
   const schema = toolHelper.schema
@@ -3346,8 +3550,54 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       const context = normalizeExecutionContext(input)
       if (context) currentRuntime().sessionExecutionContexts.set(sessionID, context)
 
-      const message = { role: "user", parts: Array.isArray(output?.parts) ? output.parts : [] }
-      if (isPluginContinuationMessage(message)) return
+      const message = {
+        info: isPlainObject(output?.message)
+          ? output.message
+          : { id: input?.messageID, role: "user", sessionID },
+        role: "user",
+        parts: Array.isArray(output?.parts) ? output.parts : [],
+      }
+      const runtime = currentRuntime()
+      const commandTurn = consumePendingCommandTurn(sessionID, message)
+      const currentMessageID = messageID(message)
+      if (commandTurn && currentMessageID) {
+        if (commandTurn.attachmentError === true) {
+          const commandPart = pluginMarkedTextPart(message, "command")
+          commandPart.text = frameControlCommandText(
+            "Goal paused because OpenCode could not resolve an attached command file. Fix or remove the attachment, then run the goal command again or resume explicitly.",
+          )
+          // Do not route partial attachment output or failure diagnostics to
+          // the model as work input. OpenCode retains this exact array too, so
+          // mutate it in place just as command.execute.before does.
+          message.parts.splice(0, message.parts.length, commandPart)
+        }
+        runtime.activeCommandTurns.set(sessionID, {
+          ...commandTurn,
+          messageID: currentMessageID,
+        })
+        rememberOwnedPluginMessage(
+          message,
+          sessionID,
+          "command",
+          commandTurn.id,
+          commandTurn.policy,
+        )
+        return
+      }
+
+      // Any non-command turn supersedes a prior command guard. Continuations
+      // are accepted only while the exact runtime-issued continuation nonce is
+      // in flight; public synthetic/metadata fields alone are never trusted.
+      runtime.pendingCommandTurns.delete(sessionID)
+      runtime.activeCommandTurns.delete(sessionID)
+      const continuationID = activeContinues.get(sessionID)
+      if (
+        currentMessageID &&
+        pluginMessageMatches(message, "continuation", continuationID)
+      ) {
+        rememberOwnedPluginMessage(message, sessionID, "continuation", continuationID)
+        return
+      }
       const text = getText(message.parts)
       const commandPrefix = `/${commandName}`
       if (text === commandPrefix || text.startsWith(`${commandPrefix} `)) return
@@ -3365,75 +3615,74 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       const sessionID = input?.sessionID
       if (!sessionID) return
       await ensureSessionLoaded(sessionID)
-      if (!currentRuntime().readOnlyCommandGuards.has(sessionID)) return
-      if (READ_ONLY_COMMAND_TOOLS.has(input?.tool)) return
+      if (currentRuntime().activeCommandTurns.get(sessionID)?.policy !== "control") return
       throw new Error(
-        `This /${commandName} control command is read-only for the routed model turn. Tool "${input?.tool || "unknown"}" was blocked. Wait for a separate user turn; do not modify work or goal state now.`,
+        `This /${commandName} control command has already been handled. Tool "${input?.tool || "unknown"}" was blocked because no tool calls are allowed while its result is being reported. Wait for a separate user turn before using tools or modifying work or goal state.`,
       )
     },
     "command.execute.before": async (input, output) => {
       if (!input || input.command !== commandName || !output) return
 
+      const sessionID = input.sessionID
+      if (!sessionID) return
+      await ensureSessionLoaded(sessionID)
+      registerPendingCommandTurn(sessionID, output)
+
       if (typeof input.arguments !== "string") {
-        output.parts = [makeTextPart("Goal command arguments must be text.")]
+        replaceCommandOutputText(output, "Goal command arguments must be text.")
         return
       }
       if (input.arguments.length > MAX_COMMAND_ARGUMENT_LENGTH) {
-        output.parts = [makeTextPart(`Goal command arguments must be ${MAX_COMMAND_ARGUMENT_LENGTH} characters or fewer.`)]
+        replaceCommandOutputText(
+          output,
+          `Goal command arguments must be ${MAX_COMMAND_ARGUMENT_LENGTH} characters or fewer.`,
+        )
         return
       }
       const args = input.arguments.trim()
-      const sessionID = input.sessionID
-      await ensureSessionLoaded(sessionID)
-      currentRuntime().readOnlyCommandGuards.delete(sessionID)
       pruneGoalResults(defaultGoalOptions)
 
       if (!args || args === "status") {
         const goal = goalStates.get(sessionID)
-        currentRuntime().readOnlyCommandGuards.add(sessionID)
         const lastResult = lastGoalResults.get(sessionID)
-        output.parts = [
-          makeTextPart(
-            goal
-              ? formatStatus(goal, commandName)
-              : lastResult
-                ? formatGoalResult(lastResult)
-                : `No active goal. Set one with \`/${commandName} <condition>\`.`,
-          ),
-        ]
+        replaceCommandOutputText(
+          output,
+          goal
+            ? formatStatus(goal, commandName)
+            : lastResult
+              ? formatGoalResult(lastResult)
+              : `No active goal. Set one with \`/${commandName} <condition>\`.`,
+        )
         return
       }
 
       if (args === "history") {
         const goal = goalStates.get(sessionID)
-        currentRuntime().readOnlyCommandGuards.add(sessionID)
         const lastResult = lastGoalResults.get(sessionID)
-        output.parts = [
-          makeTextPart(
-            goal
+        replaceCommandOutputText(
+          output,
+          goal
+            ? [
+                `Goal history for: ${goal.condition}`,
+                "",
+                `Latest checkpoint: ${goal.lastCheckpoint?.summary || "none yet"}`,
+                "",
+                formatHistory(goal.history),
+              ].join("\n")
+            : lastResult
               ? [
-                  `Goal history for: ${goal.condition}`,
+                  `Last goal history for: ${lastResult.condition}`,
                   "",
-                  `Latest checkpoint: ${goal.lastCheckpoint?.summary || "none yet"}`,
+                  `Latest checkpoint: ${lastResult.lastCheckpoint?.summary || "none recorded"}`,
                   "",
-                  formatHistory(goal.history),
+                  formatHistory(lastResult.history),
                 ].join("\n")
-              : lastResult
-                ? [
-                    `Last goal history for: ${lastResult.condition}`,
-                    "",
-                    `Latest checkpoint: ${lastResult.lastCheckpoint?.summary || "none recorded"}`,
-                    "",
-                    formatHistory(lastResult.history),
-                  ].join("\n")
-                : `No goal history recorded yet. Set a goal with \`/${commandName} <condition>\`.`,
-          ),
-        ]
+              : `No goal history recorded yet. Set a goal with \`/${commandName} <condition>\`.`,
+        )
         return
       }
 
       if (CLEAR_COMMANDS.has(args)) {
-        currentRuntime().readOnlyCommandGuards.add(sessionID)
         // Record the clear in the ledger before cleanupGoal removes the goal
         // object, so reconstructFromLedger can identify cleared goals and skip
         // them rather than reconstructing them after a missing state file.
@@ -3448,15 +3697,14 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         cleanupGoal(sessionID)
         lastGoalResults.delete(sessionID)
         await persist(sessionID)
-        output.parts = [makeTextPart("Goal cleared.")]
+        replaceCommandOutputText(output, "Goal cleared.")
         return
       }
 
       if (PAUSE_COMMANDS.has(args)) {
-        currentRuntime().readOnlyCommandGuards.add(sessionID)
         const goal = goalStates.get(sessionID)
         if (!goal) {
-          output.parts = [makeTextPart(`No active goal. Set one with \`/${commandName} <condition>\`.`)]
+          replaceCommandOutputText(output, `No active goal. Set one with \`/${commandName} <condition>\`.`)
           return
         }
         currentRuntime().continuationControllers.get(sessionID)?.abort()
@@ -3468,18 +3716,18 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         pushHistory(goal, "paused", "User paused the active goal.")
         await persist(sessionID)
         await abortAcceptedContinuation(sessionID)
-        output.parts = [makeTextPart(`Goal paused: ${goal.condition}`)]
+        replaceCommandOutputText(output, `Goal paused: ${goal.condition}`)
         return
       }
 
       if (args === "resume") {
         const goal = goalStates.get(sessionID)
         if (!goal) {
-          output.parts = [makeTextPart(`No active goal. Set one with \`/${commandName} <condition>\`.`)]
+          replaceCommandOutputText(output, `No active goal. Set one with \`/${commandName} <condition>\`.`)
           return
         }
         if (!goal.stopped) {
-          output.parts = [makeTextPart("Goal is already running.")]
+          replaceCommandOutputText(output, "Goal is already running.")
           return
         }
 
@@ -3493,27 +3741,34 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         goal.lastStatus = "Goal resumed with a fresh local budget."
         pushHistory(goal, "resumed", "User resumed the goal with a fresh local budget window.")
         await persist(sessionID)
-        output.parts = [makeTextPart(`Goal resumed with fresh limits: ${goal.condition}`)]
+        replaceCommandOutputText(output, `Goal resumed with fresh limits: ${goal.condition}`, {
+          startsWork: true,
+        })
         return
       }
 
       if (args === "edit" || args.toLowerCase().startsWith("edit ")) {
         const goal = goalStates.get(sessionID)
         if (!goal) {
-          output.parts = [
-            makeTextPart(`No active goal to edit. Set one with \`/${commandName} <condition>\`.`),
-          ]
+          replaceCommandOutputText(
+            output,
+            `No active goal to edit. Set one with \`/${commandName} <condition>\`.`,
+          )
           return
         }
         const newObjective = stripWrappingQuotes(args.slice("edit".length).trim())
         if (!newObjective) {
-          output.parts = [
-            makeTextPart(`No new objective provided. Use \`/${commandName} edit <new objective>\`.`),
-          ]
+          replaceCommandOutputText(
+            output,
+            `No new objective provided. Use \`/${commandName} edit <new objective>\`.`,
+          )
           return
         }
         if (newObjective.length > MAX_GOAL_OBJECTIVE_LENGTH) {
-          output.parts = [makeTextPart(`Goal objective must be ${MAX_GOAL_OBJECTIVE_LENGTH} characters or fewer.`)]
+          replaceCommandOutputText(
+            output,
+            `Goal objective must be ${MAX_GOAL_OBJECTIVE_LENGTH} characters or fewer.`,
+          )
           return
         }
 
@@ -3533,21 +3788,20 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         goal.lastStatus = "Goal objective updated."
         pushHistory(goal, "edited", `Objective updated to: ${summarizeText(newObjective, 400)}`)
         await persist(sessionID)
-        output.parts = [
-          makeTextPart(
-            [
-              `Goal objective updated: ${goal.condition}`,
-              "",
-              `Budgets and history are preserved. Run \`/${commandName} resume\` for a fresh budget window, or \`/${commandName} status\` to review.`,
-            ].join("\n"),
-          ),
-        ]
+        replaceCommandOutputText(
+          output,
+          [
+            `Goal objective updated: ${goal.condition}`,
+            "",
+            `Budgets and history are preserved. Run \`/${commandName} resume\` for a fresh budget window, or \`/${commandName} status\` to review.`,
+          ].join("\n"),
+          { preserveFiles: true, startsWork: true },
+        )
         return
       }
 
       if (args === "list") {
-        currentRuntime().readOnlyCommandGuards.add(sessionID)
-        output.parts = [makeTextPart(formatGoalList(sessionID, commandName))]
+        replaceCommandOutputText(output, formatGoalList(sessionID, commandName))
         return
       }
 
@@ -3561,19 +3815,24 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
           .map((part) => stripWrappingQuotes(part.trim()))
           .filter(Boolean)
         if (!objectives.length) {
-          output.parts = [
-            makeTextPart(
-              `No objectives provided. Use \`/${commandName} sequence <objective 1>; <objective 2>; …\` (separate with \`;\` or newlines).`,
-            ),
-          ]
+          replaceCommandOutputText(
+            output,
+            `No objectives provided. Use \`/${commandName} sequence <objective 1>; <objective 2>; …\` (separate with \`;\` or newlines).`,
+          )
           return
         }
         if (objectives.length > MAX_LIVE_GOALS_PER_SESSION) {
-          output.parts = [makeTextPart(`An ordered sequence may contain at most ${MAX_LIVE_GOALS_PER_SESSION} goals.`)]
+          replaceCommandOutputText(
+            output,
+            `An ordered sequence may contain at most ${MAX_LIVE_GOALS_PER_SESSION} goals.`,
+          )
           return
         }
         if (objectives.some((objective) => objective.length > MAX_GOAL_OBJECTIVE_LENGTH)) {
-          output.parts = [makeTextPart(`Each goal objective must be ${MAX_GOAL_OBJECTIVE_LENGTH} characters or fewer.`)]
+          replaceCommandOutputText(
+            output,
+            `Each goal objective must be ${MAX_GOAL_OBJECTIVE_LENGTH} characters or fewer.`,
+          )
           return
         }
 
@@ -3609,17 +3868,17 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         focusGoal(sessionID, firstGoal)
         sessionOrdered.add(sessionID)
         await persist(sessionID)
-        output.parts = [
-          makeTextPart(
-            [
-              `Started an ordered sequence of ${objectives.length} goal(s):`,
-              ...objectives.map((objective, index) => `${index + 1}. ${objective}`),
-              "",
-              `Focused goal 1: ${firstGoal.condition}`,
-              `Each goal runs to completion, then the next is auto-focused. Run \`/${commandName} list\` to track progress.`,
-            ].join("\n"),
-          ),
-        ]
+        replaceCommandOutputText(
+          output,
+          [
+            `Started an ordered sequence of ${objectives.length} goal(s):`,
+            ...objectives.map((objective, index) => `${index + 1}. ${objective}`),
+            "",
+            `Focused goal 1: ${firstGoal.condition}`,
+            `Each goal runs to completion, then the next is auto-focused. Run \`/${commandName} list\` to track progress.`,
+          ].join("\n"),
+          { preserveFiles: true, startsWork: true },
+        )
         return
       }
 
@@ -3627,11 +3886,14 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         const ref = args.slice("focus".length).trim()
         const goals = listSessionGoals(sessionID)
         if (!goals.length) {
-          output.parts = [makeTextPart(`No goals to focus. Set one with \`/${commandName} <condition>\`.`)]
+          replaceCommandOutputText(output, `No goals to focus. Set one with \`/${commandName} <condition>\`.`)
           return
         }
         if (!ref) {
-          output.parts = [makeTextPart(["Specify which goal to focus:", "", formatGoalList(sessionID, commandName)].join("\n"))]
+          replaceCommandOutputText(
+            output,
+            ["Specify which goal to focus:", "", formatGoalList(sessionID, commandName)].join("\n"),
+          )
           return
         }
         // A purely numeric ref is a 1-based index only — never a goalId prefix,
@@ -3645,13 +3907,16 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
           target = goals.find((goal) => goal.goalId === ref || goal.goalId.startsWith(ref))
         }
         if (!target) {
-          output.parts = [makeTextPart(`No goal matches "${ref}". Run \`/${commandName} list\` to see the numbered goals.`)]
+          replaceCommandOutputText(
+            output,
+            `No goal matches "${ref}". Run \`/${commandName} list\` to see the numbered goals.`,
+          )
           return
         }
 
         const current = goalStates.get(sessionID)
         if (current && current.goalId === target.goalId) {
-          output.parts = [makeTextPart(`Goal already focused: ${target.condition}`)]
+          replaceCommandOutputText(output, `Goal already focused: ${target.condition}`)
           return
         }
         if (current) {
@@ -3668,18 +3933,18 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         pushHistory(target, "focused", "Brought into focus as the session's active goal.")
         focusGoal(sessionID, target)
         await persist(sessionID)
-        output.parts = [
-          makeTextPart(
-            [
-              `Focused goal: ${target.condition}`,
-              current ? `Backgrounded: ${current.condition}` : null,
-              "",
-              `Run \`/${commandName} list\` to see all goals, or \`/${commandName} status\` for details.`,
-            ]
-              .filter((line) => line !== null)
-              .join("\n"),
-          ),
-        ]
+        replaceCommandOutputText(
+          output,
+          [
+            `Focused goal: ${target.condition}`,
+            current ? `Backgrounded: ${current.condition}` : null,
+            "",
+            `Run \`/${commandName} list\` to see all goals, or \`/${commandName} status\` for details.`,
+          ]
+            .filter((line) => line !== null)
+            .join("\n"),
+          { startsWork: true },
+        )
         return
       }
 
@@ -3688,23 +3953,25 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
 
       const parsed = parseGoalArguments(createArgs, defaultGoalOptions)
       if (parsed.errors.length > 0) {
-        output.parts = [makeTextPart(formatArgumentErrors(parsed.errors))]
+        replaceCommandOutputText(output, formatArgumentErrors(parsed.errors))
         return
       }
       if (!parsed.condition) {
-        output.parts = [
-          makeTextPart(
-            isAdd
-              ? `No objective provided. Use \`/${commandName} add <condition>\`.`
-              : `No goal provided. Set one with \`/${commandName} <condition>\`.`,
-          ),
-        ]
+        replaceCommandOutputText(
+          output,
+          isAdd
+            ? `No objective provided. Use \`/${commandName} add <condition>\`.`
+            : `No goal provided. Set one with \`/${commandName} <condition>\`.`,
+        )
         return
       }
 
       if (isAdd) {
         if (listSessionGoals(sessionID).length >= MAX_LIVE_GOALS_PER_SESSION) {
-          output.parts = [makeTextPart(`A session may contain at most ${MAX_LIVE_GOALS_PER_SESSION} live goals.`)]
+          replaceCommandOutputText(
+            output,
+            `A session may contain at most ${MAX_LIVE_GOALS_PER_SESSION} live goals.`,
+          )
           return
         }
         // Keep the current goal (background it) and focus a new one.
@@ -3725,20 +3992,20 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         focusGoal(sessionID, added)
         await persist(sessionID)
         const total = listSessionGoals(sessionID).length
-        output.parts = [
-          makeTextPart(
-            [
-              `Added and focused new goal: ${added.condition}`,
-              added.successCriteria ? `Success criteria: ${added.successCriteria}` : null,
-              added.constraints ? `Constraints / non-goals: ${added.constraints}` : null,
-              added.mode !== "normal" ? `Mode: ${added.mode}` : null,
-              current ? `Backgrounded previous goal: ${current.condition}` : null,
-              `${total} goal(s) now active in this session. Run \`/${commandName} list\` to see them.`,
-            ]
-              .filter((line) => line !== null)
-              .join("\n"),
-          ),
-        ]
+        replaceCommandOutputText(
+          output,
+          [
+            `Added and focused new goal: ${added.condition}`,
+            added.successCriteria ? `Success criteria: ${added.successCriteria}` : null,
+            added.constraints ? `Constraints / non-goals: ${added.constraints}` : null,
+            added.mode !== "normal" ? `Mode: ${added.mode}` : null,
+            current ? `Backgrounded previous goal: ${current.condition}` : null,
+            `${total} goal(s) now active in this session. Run \`/${commandName} list\` to see them.`,
+          ]
+            .filter((line) => line !== null)
+            .join("\n"),
+          { preserveFiles: true, startsWork: true },
+        )
         return
       }
 
@@ -3762,34 +4029,34 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       registerSessionGoal(goal)
       focusGoal(sessionID, goal)
       await persist(sessionID)
-      output.parts = [
-        makeTextPart(
-          [
-            ...(replacedGoal
-              ? [
-                  `⚠️ Replacing active goal: "${replacedGoal.condition}"`,
-                  `Use \`/${commandName} add <condition>\` instead to keep it running in the background.`,
-                  "",
-                ]
-              : []),
-            `New active goal: ${goal.condition}`,
-            goal.successCriteria ? `Success criteria: ${goal.successCriteria}` : null,
-            goal.constraints ? `Constraints / non-goals: ${goal.constraints}` : null,
-            goal.mode !== "normal" ? `Mode: ${goal.mode}` : null,
-            "",
-            "Start working toward this goal now.",
-            "When the goal is fully satisfied, summarize your evidence on a line starting with `[goal:evidence]`, then end your response with `[goal:complete]`. A `[goal:complete]` without a `[goal:evidence]` line is rejected and not recorded.",
-            "If you are truly blocked and need the user, state the concrete blocker on the line immediately before `[goal:blocked]`.",
-            `Use \`/${commandName} history\` to inspect recent lifecycle events and checkpoints.`,
-            "",
-            `Limits: ${goal.options.maxTurns} auto-continues, ${Math.round(
-              goal.options.maxDurationMs / 1000,
-            )}s, ${goal.options.maxTokens.toLocaleString()} context tokens.`,
-          ]
-            .filter((line) => line !== null)
-            .join("\n"),
-        ),
-      ]
+      replaceCommandOutputText(
+        output,
+        [
+          ...(replacedGoal
+            ? [
+                `⚠️ Replacing active goal: "${replacedGoal.condition}"`,
+                `Use \`/${commandName} add <condition>\` instead to keep it running in the background.`,
+                "",
+              ]
+            : []),
+          `New active goal: ${goal.condition}`,
+          goal.successCriteria ? `Success criteria: ${goal.successCriteria}` : null,
+          goal.constraints ? `Constraints / non-goals: ${goal.constraints}` : null,
+          goal.mode !== "normal" ? `Mode: ${goal.mode}` : null,
+          "",
+          "Start working toward this goal now.",
+          "When the goal is fully satisfied, summarize your evidence on a line starting with `[goal:evidence]`, then end your response with `[goal:complete]`. A `[goal:complete]` without a `[goal:evidence]` line is rejected and not recorded.",
+          "If you are truly blocked and need the user, state the concrete blocker on the line immediately before `[goal:blocked]`.",
+          `Use \`/${commandName} history\` to inspect recent lifecycle events and checkpoints.`,
+          "",
+          `Limits: ${goal.options.maxTurns} auto-continues, ${Math.round(
+            goal.options.maxDurationMs / 1000,
+          )}s, ${goal.options.maxTokens.toLocaleString()} context tokens.`,
+        ]
+          .filter((line) => line !== null)
+          .join("\n"),
+        { preserveFiles: true, startsWork: true },
+      )
     },
 
     event: async ({ event }) => {
@@ -3819,8 +4086,41 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
 
       const terminal = terminalEvent(event)
       if (terminal?.sessionID) {
+        const runtime = currentRuntime()
+        const pendingTurns = runtime.pendingCommandTurns.get(terminal.sessionID)
+        const resolvingCommandTurn = [...(pendingTurns?.values() || [])].reverse().find(
+          (turn) => turn.preservedFileCount > 0,
+        )
+        const resolvingCommandAttachments = Boolean(resolvingCommandTurn)
+        // OpenCode emits session.error while resolving an unreadable retained
+        // file, before it invokes chat.message with the synthetic Read-error
+        // parts. Pause safely, keep that one pending correlation, and downgrade
+        // it to a read-only control turn. chat.message then replaces the
+        // original work directive plus partial file diagnostics with a direct
+        // error-reporting frame, so the provider cannot continue the goal from
+        // a command whose required attachment did not resolve.
+        if (resolvingCommandTurn) {
+          resolvingCommandTurn.policy = "control"
+          resolvingCommandTurn.attachmentError = true
+          // Attachment resolution can legitimately outlive the original
+          // command-correlation TTL. Give the immediately following resolved
+          // error turn a fresh bounded window instead of falling back to the
+          // original work directive with no command guard.
+          resolvingCommandTurn.createdAt = Date.now()
+        }
+        if (!resolvingCommandAttachments) runtime.pendingCommandTurns.delete(terminal.sessionID)
+        runtime.activeCommandTurns.delete(terminal.sessionID)
         await pauseActiveGoal(terminal.sessionID, {
-          ...terminal,
+          ...(resolvingCommandAttachments
+            ? {
+                ...terminal,
+                stopReason: "attachment resolution error",
+                status:
+                  "Goal paused because OpenCode reported an error while resolving an attached command file. Fix or remove the attachment, then run the goal command again or resume explicitly.",
+                history:
+                  "Paused after OpenCode reported an error while resolving an attached command file.",
+              }
+            : terminal),
           abortAccepted: true,
         })
         return
@@ -3840,11 +4140,32 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         const message = messageInfoFromEvent(event)
         if (!message) return
 
-        const goal = goalStates.get(messageSessionID(message))
-        if (!goal) return
-
         const currentMessageID = messageID(message)
         if (!currentMessageID) return
+        const currentSessionID = messageSessionID(message)
+        const runtime = currentRuntime()
+        const parentOwner = runtime.ownedPluginMessages.get(messageParentID(message))
+        const isControlCommandAssistant =
+          messageRole(message) === "assistant" &&
+          parentOwner?.kind === "command" &&
+          parentOwner?.policy === "control" &&
+          parentOwner?.sessionID === currentSessionID
+        if (isControlCommandAssistant) {
+          // A control command may produce several assistant messages (for
+          // example, a blocked tool-call step followed by a final report), and
+          // another plugin turn may overlap before all message.updated events
+          // arrive. Authenticate each response through its owned parent user
+          // message instead of relying on the session's single latest-command
+          // slot, then suppress it immediately for later idle processing.
+          setBoundedMessageValue(
+            runtime.suppressedCommandAssistants,
+            currentMessageID,
+            currentSessionID,
+          )
+        }
+
+        const goal = goalStates.get(currentSessionID)
+        if (!goal) return
 
         // Skip stale re-deliveries from a prior budget window or a replaced goal.
         // resetGoalBudget and cleanupGoal both leave seenTokens entries in place
@@ -3886,7 +4207,11 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
           changed = true
         }
 
-        if (messageRole(message) === "assistant" && currentOutputTokens > previousOutputTokens) {
+        if (
+          messageRole(message) === "assistant" &&
+          currentOutputTokens > previousOutputTokens &&
+          runtime.suppressedCommandAssistants.get(currentMessageID) !== currentSessionID
+        ) {
           goal.lastProgressAt = Date.now()
           changed = true
         }
@@ -3904,7 +4229,6 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       if (event?.type === "session.idle") {
         currentRuntime().sessionStatuses.set(sessionID, "idle")
       }
-      currentRuntime().readOnlyCommandGuards.delete(sessionID)
       const eventID = typeof event?.id === "string" ? event.id : ""
       const seenIdleEventIDs = currentRuntime().seenIdleEventIDs
       if (eventID && seenIdleEventIDs.has(eventID)) return
@@ -3916,6 +4240,45 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
           seenIdleEventIDs.delete(seenIdleEventIDs.values().next().value)
         }
       }
+
+      // Idle events are session-scoped and may be stale or re-delivered. A
+      // command turn is consumed only after the latest assistant proves which
+      // user turn it answered through parentID. Control-command assistant IDs
+      // remain suppressed in a bounded map so a later duplicate idle cannot
+      // reinterpret the same report as goal progress or completion.
+      const runtime = currentRuntime()
+      const activeCommandTurn = runtime.activeCommandTurns.get(sessionID)
+      let commandMessages = null
+      if (activeCommandTurn) {
+        const commandMessageLimit =
+          goalStates.get(sessionID)?.options.maxRecentMessages ||
+          defaultGoalOptions.maxRecentMessages
+        const commandHostMessages = await sessionApi.messages(sessionID, {
+          limit: commandMessageLimit,
+        })
+        commandMessages = Array.isArray(commandHostMessages)
+          ? commandHostMessages.slice(-commandMessageLimit)
+          : []
+        const commandAssistant = findLatestAssistantMessage(commandMessages)
+        if (
+          !commandAssistant ||
+          messageParentID(commandAssistant) !== activeCommandTurn.messageID
+        ) {
+          return
+        }
+        if (activeCommandTurn.policy === "control") {
+          const commandAssistantID = messageID(commandAssistant)
+          if (commandAssistantID) {
+            setBoundedMessageValue(
+              runtime.suppressedCommandAssistants,
+              commandAssistantID,
+              sessionID,
+            )
+          }
+        }
+        runtime.activeCommandTurns.delete(sessionID)
+      }
+
       const goal = goalStates.get(sessionID)
       if (!goal || goal.stopped || activeContinues.has(sessionID)) return
       const goalID = goal.goalId
@@ -3927,9 +4290,11 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       activeContinues.set(sessionID, continueToken)
       currentRuntime().continuationControllers.set(sessionID, continueController)
       try {
-        const hostMessages = await sessionApi.messages(sessionID, {
-          limit: goal.options.maxRecentMessages,
-        })
+        const hostMessages =
+          commandMessages ||
+          (await sessionApi.messages(sessionID, {
+            limit: goal.options.maxRecentMessages,
+          }))
         const messages = Array.isArray(hostMessages)
           ? hostMessages.slice(-goal.options.maxRecentMessages)
           : []
@@ -3947,7 +4312,9 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         const assistantChanged = summarizeText(latestText) !== summarizeText(previousAssistantText)
         const assistantRepeated =
           latestAssistantID && latestAssistantID === activeGoalAfterMessages.lastAssistantMessageID
-        const activationBoundary = activeGoalAfterMessages.skipNextTerminalCheck === true
+        const activationBoundary =
+          currentRuntime().suppressedCommandAssistants.get(latestAssistantID) === sessionID ||
+          activeGoalAfterMessages.skipNextTerminalCheck === true
         activeGoalAfterMessages.skipNextTerminalCheck = false
 
         if (!activationBoundary && latestText && (!assistantRepeated || assistantChanged)) {
@@ -4134,7 +4501,12 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
             try {
               response = await sessionApi.promptAsync(sessionID, {
                 ...continuationContextInput(claimedGoal),
-                parts: [makeContinuationPart(buildContinueMessage(claimedGoal, { budgetWrapup: true }))],
+                parts: [
+                  makeContinuationPart(
+                    buildContinueMessage(claimedGoal, { budgetWrapup: true }),
+                    continueToken,
+                  ),
+                ],
               })
             } finally {
               currentRuntime().promptInFlightSessions.delete(sessionID)
@@ -4355,6 +4727,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
                   completionUnverified,
                   blockerUnstated,
                 }),
+                continueToken,
               ),
             ],
           })
@@ -4438,10 +4811,13 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       if (!input.sessionID) return
       await ensureSessionLoaded(input.sessionID)
 
+      const activeCommandTurn = currentRuntime().activeCommandTurns.get(input.sessionID)
+      const commandGuarded = activeCommandTurn?.policy === "control"
       const goal = goalStates.get(input.sessionID)
-      if (!goal) return
+      if (!goal && !commandGuarded) return
+      const blockID = goal?.goalId || `command-${activeCommandTurn.id}`
       const systemBlocks = Array.isArray(output.system) ? [...output.system] : []
-      if (systemBlocks.some((block) => systemBlockContainsGoal(block, goal.goalId))) return
+      if (systemBlocks.some((block) => systemBlockContainsGoal(block, blockID))) return
 
       // Only static content here — volatile fields (limit warnings, turn counters,
       // token counts, wall-clock values) must not appear in the system prompt.
@@ -4452,7 +4828,15 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       // on every continuation turn via buildContinueMessage (buildLimitWarning
       // and <progress_budget>), which is sufficient — the model doesn't need
       // them in the system prompt mid-turn.
-      const goalBlock = goal.stopped
+      const goalBlock = commandGuarded
+        ? [
+            `<opencode_goal_plugin id="${blockID}">`,
+            "<goal_state>control-command</goal_state>",
+            `A /${commandName} control command has already been handled by the goal plugin.`,
+            "Report the plugin-generated result in the current user message accurately and concisely. Do not reinterpret it as another request, continue goal work, modify files, or mutate goal state during this turn.",
+            "</opencode_goal_plugin>",
+          ].join("\n")
+        : goal.stopped
         ? [
             `<opencode_goal_plugin id="${goal.goalId}">`,
             "<goal_state>paused</goal_state>",
@@ -4519,20 +4903,11 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
     delete hooks["command.execute.before"]
   }
 
-  // Register agent-facing tools when @opencode-ai/plugin is
-  // available (it provides the `tool` helper and zod-style schema). Disabled via
-  // `registerTools: false`. When the helper is absent the command/event hooks
-  // still work; only the programmatic tool surface is omitted, preserving the
-  // zero-runtime-dependency posture.
+  // Register the agent-facing tools by default. The bundled Zod schema contract
+  // makes this deterministic for normal npm installs; `registerTools: false`
+  // remains the explicit opt-out.
   if (pluginOptions.registerTools !== false) {
-    const toolModule = await loadOpencodePluginModule()
-    if (toolModule?.tool?.schema) {
-      try {
-        hooks.tool = buildAgentTools(toolModule.tool, agentToolHandlers, ensureSessionLoaded)
-      } catch (error) {
-        await logPluginError(client, "Failed to register goal agent tools", error)
-      }
-    }
+    hooks.tool = buildAgentTools(bundledToolHelper, agentToolHandlers, ensureSessionLoaded)
   }
 
   return hooks
@@ -4648,7 +5023,9 @@ export const testInternals = {
   goalIsBlocked,
   goalIsComplete,
   isIdleEvent,
+  isPluginCommandMessage,
   isPluginContinuationMessage,
+  isPluginGeneratedMessage,
   legacyStateFilePaths,
   messageHasToolCall,
   normalizeCommandOptions,