opencode-goal-plugin 0.1.9 → 0.1.11

package/.nvmrc

@@ -0,0 +1 @@
+22

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.11 — 2026-06-04
+
+- Add `npm run smoke`, a package-export smoke test that exercises the `/goal` command hook without invoking a model.
+- Run CI across Node 18, 20, and 22, and wire the package-entry smoke test into the workflow.
+- Harden persisted-state loading with schema validation and explicit skipping of malformed goal/result entries.
+- Make hook handling more defensive around message payload shapes and `system` block normalization.
+- Expand docs around compatibility, release checks, smoke testing, and security reporting fallback.
+
+## 0.1.10 — 2026-05-30
+
+- Fix `experimental.chat.system.transform` to merge the goal continuation block into the primary system entry instead of pushing a separate one. Prevents `"System message must be at the beginning."` errors on strict-template backends (Qwen on vLLM, several Llama.cpp/Mistral templates). See issue #1.
+
 ## 0.1.9 — 2026-05-18
 
 > This release makes the goal plugin much more reliable for real unattended use. Goals now persist across restarts, recover in a safe paused state, expose better status/history visibility, and use smarter no-progress detection to avoid premature stalls. It also hardens persistence with atomic writes, stricter file permissions, and regression tests around corrupt or missing state.

package/CONTRIBUTING.md

@@ -4,9 +4,18 @@ Thanks for helping improve `opencode-goal-plugin`.
 
 ## Development
 
+Use the pinned Node version when possible:
+
+```sh
+nvm use
+```
+
 Run the local checks before submitting changes:
 
 ```sh
+npm test
+npm run test:coverage
+npm run smoke
 npm run check
 npm run pack:check
 ```
@@ -15,11 +24,27 @@ For behavior changes, add or update tests in `test/goal-plugin.test.js`.
 
 ## OpenCode Compatibility
 
-This plugin depends on OpenCode plugin hooks, including experimental hooks. When changing hook usage or command behavior:
+This plugin depends on OpenCode plugin hooks, including experimental hooks. When changing hook usage, command behavior, or system-prompt transforms:
 
 1. Check the current OpenCode plugin and command documentation.
-2. Test against a real OpenCode install when possible.
-3. Update the README compatibility note if the tested version changes.
+2. Run `npm run smoke` to verify the packaged entrypoint and command hook surface.
+3. Test against a real OpenCode install when possible.
+4. Update the README compatibility snapshot if the tested surface changes.
+
+`npm run smoke` verifies the package export path and `/goal` command hook without invoking a model. It does not replace a real OpenCode smoke test after hook or command behavior changes.
+
+## Release checklist
+
+Before publishing or tagging a release:
+
+- update `CHANGELOG.md`
+- run `npm test`
+- run `npm run test:coverage`
+- run `npm run smoke`
+- run `npm run check`
+- run `npm run pack:check`
+- perform at least one manual OpenCode smoke test if hook behavior changed
+- refresh compatibility notes if the tested OpenCode surface changed
 
 ## Pull Requests
 
@@ -29,4 +54,3 @@ Keep pull requests focused. Include:
 - why it changed
 - the checks you ran
 - any manual OpenCode smoke testing performed
-

package/README.md

@@ -4,7 +4,16 @@ An experimental session-scoped `/goal` command for [OpenCode](https://opencode.a
 
 Set a goal and the plugin keeps it in context, auto-continues the session whenever the assistant goes idle, and stops when the goal is marked complete, a blocker is reported, or a safety limit is reached.
 
-Compatibility: tested against OpenCode 1.15.4. The plugin relies on experimental OpenCode hooks; pin or re-test against your OpenCode version before using it for unattended long-running work.
+Compatibility: this plugin relies on experimental OpenCode hooks. Re-test against the exact OpenCode build and provider/backend stack you plan to use for unattended work.
+
+## Compatibility snapshot
+
+| Surface | Status |
+|---|---|
+| Node.js | Declared support: `>=18`; CI covers Node 18, 20, and 22 |
+| Package entrypoint | `npm run smoke` verifies the package export path plus `/goal` command-hook behavior from a local install without invoking a model |
+| OpenCode host | Manually smoke-tested against OpenCode 1.15.10 using the `opencode-go` provider (`qwen3.7-plus`) on this repo's local hardening branch; re-test your own version/provider stack before relying on unattended runs |
+| Provider/backend quirks | Strict-template backends require the goal block to merge into the primary `system` message; covered by regression tests |
 
 ## Install
 
@@ -209,19 +218,28 @@ Keep test files outside OpenCode's auto-loaded plugin directory — OpenCode wil
 
 ### Smoke-test checklist
 
-1. Install or file-load the plugin in a temporary OpenCode config.
-2. Add a `goal` command with `"template": "$ARGUMENTS"`.
-3. Run `/goal status` — should report no active goal.
-4. Run `/goal inspect this repo and stop immediately with [goal:blocked] if you need user input`.
-5. Verify `/goal status`, `/goal pause`, `/goal resume`, and `/goal clear` behave as expected.
+1. Run `npm run smoke` to verify the package export path and `/goal` command hook without a model call.
+2. Install or file-load the plugin in a temporary OpenCode config.
+3. Add a `goal` command with `"template": "$ARGUMENTS"`.
+4. Run `/goal status` — should report no active goal.
+5. Run `/goal inspect this repo and stop immediately with [goal:blocked] if you need user input`.
+6. Verify `/goal status`, `/goal pause`, `/goal resume`, and `/goal clear` behave as expected.
+7. If you changed hook payload handling or command behavior, repeat the smoke test against the exact OpenCode version and provider/backend combination you care about.
+
+### Release checklist
+
+- Confirm `npm test`, `npm run test:coverage`, `npm run check`, `npm run smoke`, and `npm run pack:check` all pass.
+- Re-test against a real OpenCode install when touching command hooks, idle-event handling, or system-prompt transforms.
+- Update compatibility notes and changelog entries when behavior or tested surfaces change.
 
 ## Development
 
 ```sh
-npm test            # run the test suite
-npm run test:coverage  # run tests with coverage
-npm run check       # syntax check + tests
-npm run pack:check  # verify package contents before publishing
+npm test                # run the test suite
+npm run test:coverage   # run tests with coverage
+npm run smoke           # verify package export + command hook without a model call
+npm run check           # syntax check + tests
+npm run pack:check      # verify package contents before publishing
 ```
 
 ## License

package/SECURITY.md

@@ -6,13 +6,18 @@ This project is experimental. Security fixes are provided for the latest publish
 
 ## Reporting a Vulnerability
 
-Please report security issues through GitHub's private vulnerability reporting for this repository.
+GitHub private vulnerability reporting may not always be enabled for this repository.
 
-Do not open a public issue for vulnerabilities that could expose user data, credentials, or local system access.
+Until a dedicated private reporting channel is documented here, do **not** open a public issue with exploit details, credentials, local paths, or reproduction steps that could expose user data or local system access.
+
+Instead:
+
+1. open a minimal public issue asking for a private contact path, or
+2. contact the maintainer through their GitHub profile and request a private handoff.
 
 ## Scope
 
-This plugin does not intentionally read credentials, write files, or execute shell commands. It observes OpenCode session events, injects goal context into prompts, and sends continuation prompts through OpenCode's SDK client.
+This plugin does not intentionally read credentials, write arbitrary user files, or execute shell commands. It observes OpenCode session events, injects goal context into prompts, and sends continuation prompts through OpenCode's SDK client.
 
 Relevant security-sensitive areas include:
 
@@ -20,5 +25,6 @@ Relevant security-sensitive areas include:
 - unexpected auto-continuation behavior
 - incorrect command or hook handling across OpenCode versions
 - leakage of goal text through logs or status output
+- malformed persisted state causing stale or unexpected goal recovery
 
-The goal text is wrapped in `<goal_objective>` tags and the closing tag is escaped before insertion. Other structural tags used in continuation prompts (`<goal_continuation>`, `<progress_budget>`, etc.) are not escaped. Crafted goal text containing those literal strings would close the tag early in the plaintext prompt; the model treats it as text rather than structure, so the practical risk for a local single-user tool is negligible. Do not paste untrusted third-party text into a goal; treat goal text as if you typed it directly into the assistant.
+The goal text is wrapped in `<goal_objective>` tags and the closing tag is escaped before insertion. Other structural tags used in continuation prompts (`<goal_continuation>`, `<progress_budget>`, etc.) are not escaped. Crafted goal text containing those literal strings would close the tag early in the plaintext prompt; the model still receives plaintext rather than true privileged structure, but you should still treat goal text as trusted local input rather than pasting in arbitrary third-party content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Session-scoped /goal workflow for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",
@@ -10,16 +10,19 @@
   },
   "files": [
     "src",
+    "scripts",
     "examples",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
-    "LICENSE"
+    "LICENSE",
+    ".nvmrc"
   ],
   "scripts": {
     "test": "node --test",
     "test:coverage": "node --test --experimental-test-coverage",
+    "smoke": "node scripts/smoke-command-hook.mjs",
     "check": "node -c src/goal-plugin.js && npm test",
     "pack:check": "npm pack --dry-run"
   },

package/scripts/smoke-command-hook.mjs

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict"
+import pluginModule, { GoalPlugin } from "opencode-goal-plugin"
+
+const sessionID = `smoke-${Date.now()}`
+const promptCalls = []
+const logCalls = []
+
+const client = {
+  app: {
+    log: async (input) => {
+      logCalls.push(input)
+    },
+  },
+  session: {
+    messages: async () => ({ data: [] }),
+    promptAsync: async (input) => {
+      promptCalls.push(input)
+      return {}
+    },
+  },
+}
+
+assert.equal(pluginModule.id, "opencode-goal-plugin")
+assert.equal(pluginModule.server, GoalPlugin)
+
+const hooks = await GoalPlugin({ client }, { minDelayMs: 1 })
+assert.equal(typeof hooks["command.execute.before"], "function")
+assert.equal(typeof hooks.event, "function")
+assert.equal(typeof hooks["experimental.chat.system.transform"], "function")
+
+const commandHook = hooks["command.execute.before"]
+
+async function runGoalCommand(args) {
+  const output = { parts: [] }
+  await commandHook({ command: "goal", sessionID, arguments: args }, output)
+  assert.equal(output.parts.length, 1)
+  assert.equal(output.parts[0].type, "text")
+  return output.parts[0].text
+}
+
+assert.match(await runGoalCommand("status"), /No active goal/)
+assert.match(await runGoalCommand("ship a smoke test --max-turns 1"), /New active goal/)
+assert.match(await runGoalCommand("status"), /Active goal: ship a smoke test/)
+assert.match(await runGoalCommand("clear"), /Goal cleared/)
+assert.match(await runGoalCommand("status"), /No active goal/)
+assert.equal(promptCalls.length, 0)
+assert.equal(logCalls.length, 0)
+
+console.log("opencode-goal-plugin command hook smoke passed")

package/src/goal-plugin.js

@@ -295,6 +295,11 @@ function parsePositiveIntegerStrict(value) {
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null
 }
 
+function toNonNegativeInteger(value, fallback = 0) {
+  const parsed = Number(value)
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : fallback
+}
+
 function stripWrappingQuotes(value) {
   return value.replace(/^["']|["']$/g, "")
 }
@@ -358,6 +363,109 @@ function normalizePersistenceOptions(options = {}) {
   }
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function normalizeTimestamp(value, fallback = Date.now()) {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}
+
+function normalizeHistoryEntries(entries) {
+  if (!Array.isArray(entries)) return []
+  return entries
+    .filter(isPlainObject)
+    .map((entry) =>
+      makeHistoryEntry(
+        typeof entry.type === "string" && entry.type.trim() ? entry.type.trim() : "event",
+        typeof entry.detail === "string" ? entry.detail : "",
+        normalizeTimestamp(entry.timestamp),
+      ),
+    )
+}
+
+function normalizeCheckpointEntry(entry) {
+  if (!isPlainObject(entry)) return null
+  const summary = summarizeText(entry.summary)
+  if (!summary) return null
+  return {
+    summary,
+    timestamp: normalizeTimestamp(entry.timestamp),
+  }
+}
+
+function normalizeCheckpointEntries(entries) {
+  if (!Array.isArray(entries)) return []
+  return entries.map(normalizeCheckpointEntry).filter(Boolean)
+}
+
+function normalizePersistedGoal(rawGoal) {
+  if (!isPlainObject(rawGoal)) return null
+  if (typeof rawGoal.sessionID !== "string" || !rawGoal.sessionID.trim()) return null
+  if (typeof rawGoal.condition !== "string" || !rawGoal.condition.trim()) return null
+
+  const checkpoints = normalizeCheckpointEntries(rawGoal.checkpoints)
+  const lastCheckpoint = normalizeCheckpointEntry(rawGoal.lastCheckpoint) || checkpoints.at(-1) || null
+
+  return {
+    goalId:
+      typeof rawGoal.goalId === "string" && rawGoal.goalId.trim()
+        ? rawGoal.goalId
+        : randomUUID(),
+    condition: rawGoal.condition.trim(),
+    sessionID: rawGoal.sessionID.trim(),
+    turnCount: toNonNegativeInteger(rawGoal.turnCount),
+    startedAt: normalizeTimestamp(rawGoal.startedAt),
+    totalTokens: toNonNegativeInteger(rawGoal.totalTokens),
+    options: normalizeOptions(isPlainObject(rawGoal.options) ? rawGoal.options : {}),
+    lastStatus: typeof rawGoal.lastStatus === "string" ? rawGoal.lastStatus : "Goal recovered.",
+    lastAssistantText:
+      typeof rawGoal.lastAssistantText === "string" ? rawGoal.lastAssistantText : "",
+    lastAssistantMessageID:
+      typeof rawGoal.lastAssistantMessageID === "string" ? rawGoal.lastAssistantMessageID : "",
+    lastContinueAt: toNonNegativeInteger(rawGoal.lastContinueAt),
+    lastProgressAt: toNonNegativeInteger(rawGoal.lastProgressAt),
+    noProgressTurns: toNonNegativeInteger(rawGoal.noProgressTurns),
+    blockedReason: typeof rawGoal.blockedReason === "string" ? rawGoal.blockedReason : "",
+    budgetWrapupSent: rawGoal.budgetWrapupSent === true,
+    stopped: rawGoal.stopped === true,
+    stopReason: typeof rawGoal.stopReason === "string" ? rawGoal.stopReason : "",
+    promptFailures: toNonNegativeInteger(rawGoal.promptFailures),
+    messageIDs: Array.isArray(rawGoal.messageIDs)
+      ? rawGoal.messageIDs.filter((messageID) => typeof messageID === "string" && messageID)
+      : [],
+    history: normalizeHistoryEntries(rawGoal.history).slice(-MAX_HISTORY_ENTRIES),
+    checkpoints: checkpoints.slice(-MAX_CHECKPOINTS),
+    lastCheckpoint,
+  }
+}
+
+function normalizePersistedResult(rawResult) {
+  if (!isPlainObject(rawResult)) return null
+  if (typeof rawResult.sessionID !== "string" || !rawResult.sessionID.trim()) return null
+  if (typeof rawResult.condition !== "string" || !rawResult.condition.trim()) return null
+
+  const checkpoints = normalizeCheckpointEntries(rawResult.checkpoints)
+  const lastCheckpoint = normalizeCheckpointEntry(rawResult.lastCheckpoint) || checkpoints.at(-1) || null
+
+  return {
+    sessionID: rawResult.sessionID.trim(),
+    condition: rawResult.condition.trim(),
+    state: typeof rawResult.state === "string" && rawResult.state.trim() ? rawResult.state : "unknown",
+    reason: typeof rawResult.reason === "string" ? rawResult.reason : "",
+    blockedReason: typeof rawResult.blockedReason === "string" ? rawResult.blockedReason : "",
+    turnCount: toNonNegativeInteger(rawResult.turnCount),
+    totalTokens: toNonNegativeInteger(rawResult.totalTokens),
+    startedAt: normalizeTimestamp(rawResult.startedAt),
+    finishedAt: normalizeTimestamp(rawResult.finishedAt),
+    lastStatus: typeof rawResult.lastStatus === "string" ? rawResult.lastStatus : "",
+    lastCheckpoint,
+    checkpoints: checkpoints.slice(-MAX_CHECKPOINTS),
+    history: normalizeHistoryEntries(rawResult.history).slice(-MAX_HISTORY_ENTRIES),
+  }
+}
+
 function serializeGoal(goal) {
   return {
     ...goal,
@@ -405,13 +513,47 @@ async function loadPersistedState(persistenceOptions, client) {
       return "invalid"
     }
 
+    if (!Array.isArray(parsed.goals) || !Array.isArray(parsed.results)) {
+      await logPluginError(client, "Skipped persisted goal state: malformed goals/results arrays.")
+      return "invalid"
+    }
+
+    const loadedGoals = []
+    let skippedGoals = 0
+    for (const rawGoal of parsed.goals) {
+      const normalizedGoal = normalizePersistedGoal(rawGoal)
+      if (normalizedGoal) {
+        loadedGoals.push(normalizedGoal)
+      } else {
+        skippedGoals += 1
+      }
+    }
+
+    const loadedResults = []
+    let skippedResults = 0
+    for (const rawResult of parsed.results) {
+      const normalizedResult = normalizePersistedResult(rawResult)
+      if (normalizedResult) {
+        loadedResults.push(normalizedResult)
+      } else {
+        skippedResults += 1
+      }
+    }
+
+    if (skippedGoals > 0 || skippedResults > 0) {
+      await logPluginError(
+        client,
+        `Skipped invalid persisted entries: ${skippedGoals} goal(s), ${skippedResults} result(s).`,
+      )
+    }
+
     clearRuntimeState()
 
-    for (const goal of parsed.goals || []) {
+    for (const goal of loadedGoals) {
       goalStates.set(goal.sessionID, deserializeGoal(goal))
     }
 
-    for (const result of parsed.results || []) {
+    for (const result of loadedResults) {
       lastGoalResults.set(result.sessionID, result)
     }
 
@@ -634,12 +776,104 @@ function formatArgumentErrors(errors) {
   ].join("\n")
 }
 
+function messageRole(message) {
+  return message?.info?.role || message?.role || ""
+}
+
+function messageID(message) {
+  return message?.info?.id || message?.id || ""
+}
+
+function messageSessionID(message) {
+  return message?.info?.sessionID || message?.sessionID || ""
+}
+
+function messageTokens(message) {
+  return isPlainObject(message?.info?.tokens)
+    ? message.info.tokens
+    : isPlainObject(message?.tokens)
+      ? message.tokens
+      : {}
+}
+
+function totalTokensForMessage(message) {
+  const tokens = messageTokens(message)
+  return (
+    toNonNegativeInteger(tokens.input) +
+    toNonNegativeInteger(tokens.output) +
+    toNonNegativeInteger(tokens.reasoning)
+  )
+}
+
+function messageInfoFromEvent(event) {
+  const candidates = [
+    event?.properties?.info,
+    event?.properties?.message?.info,
+    event?.properties?.message,
+  ]
+  return candidates.find(isPlainObject) || null
+}
+
+function appendGoalToSystemBlock(block, goalBlock) {
+  if (typeof block === "string") {
+    return `${block}\n\n${goalBlock}`
+  }
+
+  if (!isPlainObject(block)) return null
+
+  if (typeof block.text === "string") {
+    return {
+      ...block,
+      text: `${block.text}\n\n${goalBlock}`,
+    }
+  }
+
+  if (typeof block.content === "string") {
+    return {
+      ...block,
+      content: `${block.content}\n\n${goalBlock}`,
+    }
+  }
+
+  if (Array.isArray(block.content)) {
+    const content = [...block.content]
+    const firstTextIndex = content.findIndex(
+      (part) => isPlainObject(part) && typeof part.text === "string",
+    )
+    if (firstTextIndex >= 0) {
+      content[firstTextIndex] = {
+        ...content[firstTextIndex],
+        text: `${content[firstTextIndex].text}\n\n${goalBlock}`,
+      }
+      return {
+        ...block,
+        content,
+      }
+    }
+  }
+
+  return null
+}
+
+function systemBlockContainsGoal(block) {
+  if (typeof block === "string") return block.includes("<goal_objective>")
+  if (!isPlainObject(block)) return false
+  if (typeof block.text === "string") return block.text.includes("<goal_objective>")
+  if (typeof block.content === "string") return block.content.includes("<goal_objective>")
+  if (Array.isArray(block.content)) {
+    return block.content.some(
+      (part) => isPlainObject(part) && typeof part.text === "string" && part.text.includes("<goal_objective>"),
+    )
+  }
+  return false
+}
+
 function findLatestAssistantMessage(messages) {
-  return [...(messages || [])].reverse().find((message) => message.info?.role === "assistant") || null
+  return [...(messages || [])].reverse().find((message) => messageRole(message) === "assistant") || null
 }
 
 function outputTokensForMessage(message) {
-  return message?.info?.tokens?.output || 0
+  return toNonNegativeInteger(messageTokens(message).output)
 }
 
 function budgetWrapupNeeded(goal) {
@@ -821,34 +1055,34 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
 
     event: async ({ event }) => {
       if (event.type === "message.updated") {
-        const message = event.properties?.info
+        const message = messageInfoFromEvent(event)
         if (!message) return
 
-        const goal = goalStates.get(message.sessionID)
+        const goal = goalStates.get(messageSessionID(message))
         if (!goal) return
 
+        const currentMessageID = messageID(message)
+        if (!currentMessageID) return
+
         let changed = false
-        const currentOutputTokens = message.tokens?.output || 0
-        const previousOutputTokens = seenOutputTokens.get(message.id) || 0
-        const currentTokens =
-          (message.tokens?.input || 0) +
-          currentOutputTokens +
-          (message.tokens?.reasoning || 0)
-        const previousTokens = seenTokens.get(message.id) || 0
+        const currentOutputTokens = outputTokensForMessage(message)
+        const previousOutputTokens = seenOutputTokens.get(currentMessageID) || 0
+        const currentTokens = totalTokensForMessage(message)
+        const previousTokens = seenTokens.get(currentMessageID) || 0
         if (currentTokens > previousTokens) {
           goal.totalTokens += currentTokens - previousTokens
-          seenTokens.set(message.id, currentTokens)
-          goal.messageIDs.add(message.id)
+          seenTokens.set(currentMessageID, currentTokens)
+          goal.messageIDs.add(currentMessageID)
           changed = true
         }
 
         if (currentOutputTokens > previousOutputTokens) {
-          seenOutputTokens.set(message.id, currentOutputTokens)
-          goal.messageIDs.add(message.id)
+          seenOutputTokens.set(currentMessageID, currentOutputTokens)
+          goal.messageIDs.add(currentMessageID)
           changed = true
         }
 
-        if (message.role === "assistant" && currentOutputTokens > previousOutputTokens) {
+        if (messageRole(message) === "assistant" && currentOutputTokens > previousOutputTokens) {
           goal.lastProgressAt = Date.now()
           changed = true
         }
@@ -1057,17 +1291,29 @@ export const GoalPlugin = async ({ client }, pluginOptions = {}) => {
       const goal = goalStates.get(input.sessionID)
       if (!goal) return
       if (goal.stopped) return
-      if (output.system.some((block) => block.includes("<goal_objective>"))) return
-
-      output.system.push(
-        [
-          buildGoalBlock(goal),
-          "Keep working until the goal is fully satisfied.",
-          "When fully satisfied, end the response with `[goal:complete]`.",
-          "If user input is required, explain the blocker in the line immediately before `[goal:blocked]`.",
-          buildLimitWarning(goal),
-        ].filter(Boolean).join("\n"),
-      )
+      const systemBlocks = Array.isArray(output.system) ? [...output.system] : []
+      if (systemBlocks.some(systemBlockContainsGoal)) return
+
+      const goalBlock = [
+        buildGoalBlock(goal),
+        "Keep working until the goal is fully satisfied.",
+        "When fully satisfied, end the response with `[goal:complete]`.",
+        "If user input is required, explain the blocker in the line immediately before `[goal:blocked]`.",
+        buildLimitWarning(goal),
+      ].filter(Boolean).join("\n")
+
+      if (systemBlocks.length === 0) {
+        output.system = [goalBlock]
+        return
+      }
+
+      const mergedFirstBlock = appendGoalToSystemBlock(systemBlocks[0], goalBlock)
+      if (mergedFirstBlock) {
+        systemBlocks[0] = mergedFirstBlock
+      } else {
+        systemBlocks.unshift(goalBlock)
+      }
+      output.system = systemBlocks
     },
   }
 }