opencode-goal-plugin 0.8.2 → 0.10.0

package/src/goal-plugin.js

@@ -73,6 +73,9 @@ const DEFAULT_OPTIONS = {
   maxTurns: 10,
   maxDurationMs: 15 * 60 * 1000,
   maxTokens: 200000,
+  // Cumulative OpenCode-reported API cost, in US dollars, before the goal
+  // pauses. 0 disables the cap; enforcement depends on provider cost metadata.
+  maxCostUsd: 0,
   minDelayMs: 1500,
   maxRecentMessages: 50,
   noProgressTokenThreshold: 50,
@@ -111,6 +114,11 @@ function createRuntimeState() {
     seenIdleEventIDs: new Set(),
     sessionStatuses: new Map(),
     sessionExecutionContexts: new Map(),
+    // Session-title indicator: the user's own title, captured before the plugin
+    // first overwrites it, and the last title the plugin wrote (so an unchanged
+    // render skips the API call).
+    sessionTitles: new Map(),
+    appliedTitles: new Map(),
     pendingCommandTurns: new Map(),
     activeCommandTurns: new Map(),
     commandOutputs: new WeakMap(),
@@ -223,6 +231,8 @@ const GOAL_FLAG_SPECS = {
   // Inline budget shorthand for the context-token limit. Accepts a plain
   // integer or a k/m suffix (e.g. --budget 100k == --max-tokens 100000).
   "--budget": { type: "tokens", optionKey: "maxTokens" },
+  // Per-goal cost cap in US dollars (e.g. --max-cost 5 or --max-cost 2.50).
+  "--max-cost": { type: "usd", optionKey: "maxCostUsd" },
   "--success": { type: "string", target: "meta", metaKey: "successCriteria" },
   "--success-criteria": { type: "string", target: "meta", metaKey: "successCriteria" },
   "--constraints": { type: "string", target: "meta", metaKey: "constraints" },
@@ -298,6 +308,47 @@ function frameControlCommandText(text) {
   ].join("\n")
 }
 
+// Routed text for the turn that creates a goal. A held goal must not be told
+// to start working: command text reaches the model as a normal turn on current
+// OpenCode builds, so that line would be the escape the plan guard exists to
+// prevent.
+function buildGoalCommandNotice(goal, { heldLabel = "", replacedGoal = null, commandName = "goal" } = {}) {
+  return [
+    ...(replacedGoal
+      ? [
+          `⚠️ Replacing active goal: "${replacedGoal.condition}"`,
+          `Use \`/${commandName} add <condition>\` instead to keep it running in the background.`,
+          "",
+        ]
+      : []),
+    heldLabel ? `Goal recorded but held: ${goal.condition}` : `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,
+    "",
+    ...(heldLabel
+      ? [
+          `The ${heldLabel} agent is planning-only, so this goal is not running.`,
+          "Do not begin work on it now. Continue planning only.",
+          `Switch to an executing agent, then run \`/${commandName} resume\` to start work.`,
+        ]
+      : [
+          "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${
+      goal.options.maxCostUsd > 0 ? `, $${goal.options.maxCostUsd.toFixed(2)} cost` : ""
+    }.`,
+  ]
+    .filter((line) => line !== null)
+    .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
@@ -396,8 +447,107 @@ function continuationContextInput(goal) {
   return context ? { ...context } : {}
 }
 
+// Planning-only agents must never be driven into execution by the goal loop.
+// `plan` is OpenCode's built-in read-only agent; `restrictedAgents` lets a
+// deployment name others (for example a review-only agent).
+const DEFAULT_RESTRICTED_AGENTS = ["plan"]
+
+function normalizeRestrictedAgents(value) {
+  // Anything that is not an array (including undefined) keeps the safe default;
+  // an explicit empty array is a deliberate opt-out.
+  if (!Array.isArray(value)) return [...DEFAULT_RESTRICTED_AGENTS]
+  const names = value
+    .map((entry) => (typeof entry === "string" ? entry.trim().toLowerCase() : ""))
+    .filter(Boolean)
+  return [...new Set(names)]
+}
+
+function isRestrictedAgent(agent, restrictedAgents = DEFAULT_RESTRICTED_AGENTS) {
+  if (typeof agent !== "string") return false
+  const name = agent.trim().toLowerCase()
+  if (!name) return false
+  return restrictedAgents.includes(name)
+}
+
 function isPlanAgent(agent) {
-  return typeof agent === "string" && agent.trim().toLowerCase() === "plan"
+  return isRestrictedAgent(agent, DEFAULT_RESTRICTED_AGENTS)
+}
+
+// Session-title status indicator. OpenCode renders the session title
+// persistently, so mirroring goal progress into it gives unattended runs a
+// continuous heartbeat without a TUI plugin entrypoint. Opt-in, because it
+// overwrites a user-visible field.
+const SESSION_TITLE_OBJECTIVE_LIMIT = 48
+const SESSION_TITLE_ICONS = ["▶", "⏸", "⛔", "✅"]
+
+// The title sits in a narrow column, so every field is abbreviated hard.
+function formatCompactDuration(ms) {
+  const totalSeconds = Math.max(0, Math.round(ms / 1000))
+  if (totalSeconds < 60) return `${totalSeconds}s`
+  const totalMinutes = Math.floor(totalSeconds / 60)
+  if (totalMinutes < 60) return `${totalMinutes}m`
+  const hours = Math.floor(totalMinutes / 60)
+  const minutes = totalMinutes % 60
+  return minutes ? `${hours}h${minutes}m` : `${hours}h`
+}
+
+function formatCompactTokens(tokens) {
+  const value = toNonNegativeInteger(tokens)
+  if (value < 1000) return String(value)
+  if (value < 1_000_000) {
+    const thousands = value / 1000
+    return `${thousands < 10 ? thousands.toFixed(1) : Math.round(thousands)}k`
+  }
+  const millions = value / 1_000_000
+  return `${millions < 10 ? millions.toFixed(1) : Math.round(millions)}m`
+}
+
+// Blocked and paused are distinct to a watching human: one needs input, the
+// other just needs a resume.
+function goalStatusIcon(goal) {
+  if (goal.blockedReason) return "⛔"
+  if (goal.stopped) return "⏸"
+  return "▶"
+}
+
+// One-line goal status for the session title, e.g.
+// "▶ ship the release · 3/10 · 2m · 45k/200k".
+function buildSessionTitle(goal, now = Date.now()) {
+  const elapsedMs = Math.max(0, (goal.pausedAt || now) - goal.startedAt)
+  return [
+    `${goalStatusIcon(goal)} ${summarizeText(goal.condition, SESSION_TITLE_OBJECTIVE_LIMIT)}`,
+    `${goal.turnCount}/${goal.options.maxTurns}`,
+    formatCompactDuration(elapsedMs),
+    `${formatCompactTokens(goal.totalTokens)}/${formatCompactTokens(goal.options.maxTokens)}`,
+  ].join(" · ")
+}
+
+// Title for a goal that just completed. Archived results carry the counters
+// but not the option snapshot, so the "/limit" halves are dropped.
+function buildCompletedSessionTitle(result) {
+  const turns = toNonNegativeInteger(result.turnCount)
+  return [
+    `✅ ${summarizeText(result.condition, SESSION_TITLE_OBJECTIVE_LIMIT)}`,
+    `${turns} turn${turns === 1 ? "" : "s"}`,
+    formatCompactDuration(Math.max(0, result.finishedAt - result.startedAt)),
+    formatCompactTokens(result.totalTokens),
+  ].join(" · ")
+}
+
+// Recognize a title this plugin wrote. The captured "original" is what
+// `/goal clear` restores, so capturing one of our own status lines would make
+// clear promote a stale status string to the permanent session title. That is
+// exactly the state a hard process kill leaves behind.
+function looksLikePluginSessionTitle(title) {
+  const text = typeof title === "string" ? title.trimStart() : ""
+  return SESSION_TITLE_ICONS.some((icon) => text.startsWith(`${icon} `))
+}
+
+// Stop reason for a goal held because a planning-only agent is active. The
+// built-in `plan` case keeps its established wording so persisted state and
+// existing consumers stay stable.
+function restrictedAgentStopReason(agent) {
+  return isPlanAgent(agent) ? "plan agent active" : `${String(agent).trim().toLowerCase()} agent active`
 }
 
 function terminalEvent(event) {
@@ -725,6 +875,11 @@ function formatStatus(
     `Auto-continues sent: ${goal.turnCount}/${goal.options.maxTurns}`,
     `Context tokens: ${goal.totalTokens.toLocaleString()}/${goal.options.maxTokens.toLocaleString()}`,
     formatUsage(goal.usage),
+    ...(costCapFor(goal)
+      ? [
+          `Cost budget: ${costCapFor(goal).known ? `$${costCapFor(goal).spent.toFixed(4)}` : "unknown"}/$${costCapFor(goal).limit.toFixed(2)}`,
+        ]
+      : []),
     `Elapsed: ${elapsed}s/${Math.round(goal.options.maxDurationMs / 1000)}s`,
     `Last progress: ${lastProgress}`,
     `No-progress turns: ${goal.noProgressTurns}`,
@@ -789,9 +944,26 @@ function stopReason(goal) {
     return `max duration reached (${Math.round(goal.options.maxDurationMs / 1000)}s)`
   }
   if (goal.totalTokens >= goal.options.maxTokens) return `max context tokens reached (${goal.options.maxTokens.toLocaleString()})`
+  const costCap = costCapFor(goal)
+  if (costCap && costCap.reached) return `max cost reached ($${costCap.limit.toFixed(2)})`
   return null
 }
 
+// Cost cap state, or null when the cap is disabled. The cap can only be
+// enforced when the provider reports cost; an unknown cost never trips it.
+function costCapFor(goal) {
+  const limit = Number(goal?.options?.maxCostUsd)
+  if (!Number.isFinite(limit) || limit <= 0) return null
+  const usage = normalizeUsage(goal.usage)
+  return {
+    limit,
+    spent: usage.cost,
+    known: usage.costKnown,
+    remaining: Math.max(0, limit - usage.cost),
+    reached: usage.costKnown && usage.cost >= limit,
+  }
+}
+
 function sessionGoalMap(sessionID) {
   let map = sessionGoals.get(sessionID)
   if (!map) {
@@ -920,6 +1092,8 @@ function clearRuntimeState() {
   runtime.seenIdleEventIDs.clear()
   runtime.sessionStatuses.clear()
   runtime.sessionExecutionContexts.clear()
+  runtime.sessionTitles.clear()
+  runtime.appliedTitles.clear()
   runtime.pendingCommandTurns.clear()
   runtime.activeCommandTurns.clear()
   runtime.ownedPluginMessages.clear()
@@ -1170,6 +1344,10 @@ function normalizeOptions(options = {}) {
     maxTurns: toPositiveInteger(options.maxTurns, DEFAULT_OPTIONS.maxTurns),
     maxDurationMs: toPositiveInteger(options.maxDurationMs, DEFAULT_OPTIONS.maxDurationMs),
     maxTokens: toPositiveInteger(options.maxTokens, DEFAULT_OPTIONS.maxTokens),
+    maxCostUsd:
+      Number.isFinite(Number(options.maxCostUsd)) && Number(options.maxCostUsd) > 0
+        ? Number(options.maxCostUsd)
+        : DEFAULT_OPTIONS.maxCostUsd,
     minDelayMs: toPositiveInteger(options.minDelayMs, DEFAULT_OPTIONS.minDelayMs),
     maxRecentMessages: toPositiveInteger(
       options.maxRecentMessages,
@@ -2133,29 +2311,55 @@ async function logPluginWarning(client, message) {
   return logPluginMessage(client, "warn", message)
 }
 
+// Cosmetic failures (session-title updates) log at debug and never fall back to
+// the console: a title that failed to render must not look like a goal fault.
+async function logPluginDebug(client, message, error) {
+  if (!client?.app?.log) return
+  try {
+    await client.app.log({
+      body: {
+        service: "opencode-goal-plugin",
+        level: "debug",
+        message,
+        ...(error === undefined
+          ? {}
+          : { extra: { error: error?.message || error?.name || String(error) } }),
+      },
+    })
+  } catch {
+    // Diagnostics must never affect the goal loop.
+  }
+}
+
+// A fenced ```span``` in the arguments is objective text verbatim: double-dash
+// tokens inside it are never parsed as goal flags and it is never consumed as
+// a flag value, so a command line can be quoted inside an objective.
 function parseGoalArguments(args, defaults) {
-  const parts = args.match(/"[^"]*"|'[^']*'|\S+/g) || []
+  const parts = Array.from(
+    args.matchAll(/```([\s\S]*?)```|"[^"]*"|'[^']*'|\S+/g),
+    (match) => ({ value: match[1] ?? match[0], literal: match[1] !== undefined }),
+  )
   const condition = []
   const options = { ...defaults }
   const meta = { ...GOAL_META_DEFAULTS }
   const errors = []
+  const isFlagValue = (candidate) =>
+    candidate !== undefined && !candidate.literal && !candidate.value.startsWith("--")
 
   for (let i = 0; i < parts.length; i += 1) {
-    const part = parts[i]
+    const { value: part, literal } = parts[i]
 
-    if (part.startsWith("--")) {
+    if (!literal && part.startsWith("--")) {
       const [flagName, inlineValue] = part.split(/=(.*)/s, 2)
       const flagSpec = GOAL_FLAG_SPECS[flagName]
 
       if (!flagSpec) {
-        const next = parts[i + 1]
-        if (inlineValue === undefined && next !== undefined && !next.startsWith("--")) i += 1
+        if (inlineValue === undefined && isFlagValue(parts[i + 1])) i += 1
         errors.push(`Unsupported flag: ${flagName}`)
         continue
       }
 
-      const next = parts[i + 1]
-      const value = inlineValue ?? (next !== undefined && !next.startsWith("--") ? next : undefined)
+      const value = inlineValue ?? (isFlagValue(parts[i + 1]) ? parts[i + 1].value : undefined)
       if (inlineValue === undefined && value !== undefined) i += 1
 
       if (value === undefined) {
@@ -2177,6 +2381,16 @@ function parseGoalArguments(args, defaults) {
         continue
       }
 
+      if (flagSpec.type === "usd") {
+        const cost = /^\$?\d+(?:\.\d+)?$/.test(rawValue.trim()) ? Number(rawValue.trim().replace(/^\$/, "")) : NaN
+        if (!Number.isFinite(cost) || cost <= 0) {
+          errors.push(`Invalid cost budget for ${flagName}: ${value} (use a positive number of US dollars)`)
+          continue
+        }
+        options[flagSpec.optionKey] = cost
+        continue
+      }
+
       if (flagSpec.type === "string") {
         const text = rawValue.trim()
         if (!text) {
@@ -2207,7 +2421,7 @@ function parseGoalArguments(args, defaults) {
       continue
     }
 
-    condition.push(stripWrappingQuotes(part))
+    condition.push(literal ? part.trim() : stripWrappingQuotes(part))
   }
 
   const parsedCondition = condition.join(" ").trim()
@@ -2258,6 +2472,10 @@ function buildLimitWarning(goal) {
   if (remainingTokens <= goal.options.warnTokensRemaining) {
     warnings.push(`${Math.max(0, remainingTokens).toLocaleString()} context token(s) remaining`)
   }
+  const costCap = costCapFor(goal)
+  if (costCap?.known && costCap.remaining <= costCap.limit * 0.1) {
+    warnings.push(`$${costCap.remaining.toFixed(2)} of the $${costCap.limit.toFixed(2)} cost budget remaining`)
+  }
 
   return warnings.length ? ` Limits are near: ${warnings.join(", ")}.` : ""
 }
@@ -2351,6 +2569,9 @@ function buildContinueMessage(
     "<progress_budget>",
     `turns_remaining: ${remainingTurns}`,
     `tokens_remaining: ${remainingTokens}`,
+    ...(costCapFor(goal)
+      ? [`cost_remaining_usd: ${costCapFor(goal).known ? costCapFor(goal).remaining.toFixed(2) : "unknown"}`]
+      : []),
     `elapsed_seconds: ${elapsedSeconds}`,
     "</progress_budget>",
   ]
@@ -2442,7 +2663,9 @@ function buildCompactionContext(goal) {
     "The summary below is reconstructed deterministically from the plugin's persisted goal record, not from chat memory.",
     buildGoalBlock(goal),
     `Goal status: ${goal.stopped ? goal.stopReason || "stopped" : "active"}.`,
-    `Auto-continues used: ${goal.turnCount}/${goal.options.maxTurns}. Context tokens: ${goal.totalTokens}/${goal.options.maxTokens}. Elapsed: ${elapsedSeconds}s.`,
+    `Auto-continues used: ${goal.turnCount}/${goal.options.maxTurns}. Context tokens: ${goal.totalTokens}/${goal.options.maxTokens}. Elapsed: ${elapsedSeconds}s.${
+      costCapFor(goal) ? ` Cost: ${costCapFor(goal).known ? `$${costCapFor(goal).spent.toFixed(2)}` : "unknown"}/$${costCapFor(goal).limit.toFixed(2)}.` : ""
+    }`,
     goal.lastCheckpoint ? `Latest checkpoint: ${escapeGoalText(summarizeText(goal.lastCheckpoint.summary, 200))}` : null,
     ...buildCompactionProgressSummary(goal),
     "After compaction, continue from the next concrete unfinished step while the goal is active. Verify the result against the goal objective before ending; output [goal:complete] (preceded by a [goal:evidence] line) only when fully satisfied, or [goal:blocked] (preceded by a concrete blocker) only if user input is required.",
@@ -3035,7 +3258,32 @@ function buildAgentToolHandlers({
   auditMessagesEnabled = false,
   announceLifecycle = () => {},
   commandName = "goal",
+  agentGoalAuthority = "full",
 }) {
+  // "status" authority: agents may report on a goal (complete, block, pause,
+  // resume) and create one when none is live, but only the user, through the
+  // slash command, may replace, edit, or clear a goal. Returns the refusal
+  // text, or null when the action is allowed.
+  function agentLockMessage(sessionID, action) {
+    if (agentGoalAuthority !== "status") return null
+    if (action === "replace" && !goalStates.has(sessionID) && listSessionGoals(sessionID).length === 0) {
+      return null
+    }
+    const verb =
+      action === "replace"
+        ? "replace the active goal"
+        : action === "edit"
+          ? "change the goal objective"
+          : "clear the goal"
+    const hint =
+      action === "replace"
+        ? `/${commandName} <objective>, /${commandName} add <objective>, or /${commandName} edit <objective>`
+        : action === "edit"
+          ? `/${commandName} edit <objective>`
+          : `/${commandName} clear`
+    return `Agents cannot ${verb} in this session (agentGoalAuthority: "status"). Ask the user to run ${hint}.`
+  }
+
   // Use persistTerminalState (which logs on failure) for terminal operations when
   // available; fall back to plain persist for callers that don't wire it up (e.g.
   // tests using buildAgentToolHandlers directly).
@@ -3075,6 +3323,8 @@ function buildAgentToolHandlers({
   async function setGoal(sessionID, args = {}) {
     const objective = typeof args.objective === "string" ? args.objective.trim() : ""
     if (!objective) return "No objective provided. Pass a non-empty `objective`."
+    const replaceLock = agentLockMessage(sessionID, "replace")
+    if (replaceLock) return replaceLock
     if (objective.length > MAX_GOAL_OBJECTIVE_LENGTH)
       return `Invalid objective: must be ${MAX_GOAL_OBJECTIVE_LENGTH} characters or fewer.`
     for (const [field, value] of [["successCriteria", args.successCriteria], ["constraints", args.constraints]]) {
@@ -3090,6 +3340,8 @@ function buildAgentToolHandlers({
       return `Invalid maxTokens: ${args.maxTokens} — must be a positive integer.`
     if (Number.isFinite(args.maxDurationMs) && args.maxDurationMs <= 0)
       return `Invalid maxDurationMs: ${args.maxDurationMs} — must be a positive number.`
+    if (Number.isFinite(args.maxCostUsd) && args.maxCostUsd <= 0)
+      return `Invalid maxCostUsd: ${args.maxCostUsd} — must be a positive number of US dollars.`
     if (args.mode !== undefined && !GOAL_MODES.has(String(args.mode).toLowerCase()))
       return `Invalid mode: ${args.mode} (expected ${[...GOAL_MODES].join(" or ")}).`
     const options = normalizeOptions({
@@ -3097,6 +3349,7 @@ function buildAgentToolHandlers({
       ...(Number.isFinite(args.maxTurns) ? { maxTurns: args.maxTurns } : {}),
       ...(Number.isFinite(args.maxTokens) ? { maxTokens: args.maxTokens } : {}),
       ...(Number.isFinite(args.maxDurationMs) ? { maxDurationMs: args.maxDurationMs } : {}),
+      ...(Number.isFinite(args.maxCostUsd) ? { maxCostUsd: args.maxCostUsd } : {}),
     })
     const meta = {
       successCriteria: typeof args.successCriteria === "string" ? args.successCriteria : "",
@@ -3134,6 +3387,10 @@ function buildAgentToolHandlers({
   async function updateGoal(sessionID, args = {}) {
     let goal = goalStates.get(sessionID)
     if (!goal) return "No active goal to update. Use set_goal first."
+    if (typeof args.objective === "string" && args.objective.trim()) {
+      const editLock = agentLockMessage(sessionID, "edit")
+      if (editLock) return editLock
+    }
 
     // Reject the combination of an objective update with status='complete': the
     // completion would be archived under a condition that was never executed,
@@ -3439,6 +3696,8 @@ function buildAgentToolHandlers({
   }
 
   async function clearGoal(sessionID) {
+    const clearLock = agentLockMessage(sessionID, "clear")
+    if (clearLock) return clearLock
     // Mirror `/goal clear`: drop the ordered flag, ALL backgrounded goals, and the
     // focused goal + result. Without sessionGoals.delete, background goals added via
     // `/goal add` survive clear and resurrect as the focused goal on restart.
@@ -3472,7 +3731,7 @@ function buildAgentToolHandlers({
       : "Goal cleared."
   }
 
-  return { getGoal, getGoalHistory, setGoal, updateGoal, clearGoal }
+  return { getGoal, getGoalHistory, setGoal, updateGoal, clearGoal, agentLockMessage }
 }
 
 function agentToolSessionID(ctx) {
@@ -3582,6 +3841,8 @@ function buildAgentTools(
       if (typeof args.objective !== "string" || !args.objective.trim()) {
         return goalToolFailure("invalid_objective", "No objective provided. Pass a non-empty objective.")
       }
+      const locked = handlers.agentLockMessage?.(sessionID, "replace")
+      if (locked) return goalToolFailure("agent_authority", locked)
       return goalToolSuccess(await handlers.setGoal(sessionID, args))
     },
     update: async (sessionID, args) => {
@@ -3628,6 +3889,7 @@ function buildAgentTools(
         maxTurns: schema.number().optional(),
         maxTokens: schema.number().optional(),
         maxDurationMs: schema.number().optional(),
+        maxCostUsd: schema.number().optional(),
         successCriteria: schema.string().optional(),
         constraints: schema.string().optional(),
         mode: schema.string().optional(),
@@ -3690,6 +3952,7 @@ function buildAgentTools(
         maxTurns: schema.number().optional(),
         maxTokens: schema.number().optional(),
         maxDurationMs: schema.number().optional(),
+        maxCostUsd: schema.number().optional(),
         successCriteria: schema.string().optional(),
         constraints: schema.string().optional(),
         mode: schema.string().optional(),
@@ -3956,6 +4219,121 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
     cwd: pluginOptions.cwd || directory,
   })
   const { commandName, registerCommand } = normalizeCommandOptions(pluginOptions)
+  const restrictedAgents = normalizeRestrictedAgents(pluginOptions.restrictedAgents)
+  const agentGoalAuthority = pluginOptions.agentGoalAuthority === "status" ? "status" : "full"
+  // Opt-out for deployments that deliberately drive execution from a planning
+  // agent. Defaults to false: unattended work must not escape Plan mode.
+  const allowGoalExecutionFromPlan = pluginOptions.allowGoalExecutionFromPlan === true
+
+  // Opt-in: mirrors live goal status into the OpenCode session title, which the
+  // TUI renders persistently. Off by default because it overwrites a
+  // user-visible field.
+  const sessionTitleStatus = pluginOptions.sessionTitleStatus === true
+
+  // Title updates are cosmetic: every path swallows errors after logging at
+  // debug level so a failure can never interrupt the goal loop.
+  const syncSessionTitle = async (sessionID) => {
+    if (!sessionTitleStatus || !sessionID) return
+    const goal = goalStates.get(sessionID)
+    let title
+    if (goal) {
+      title = buildSessionTitle(goal)
+    } else {
+      // No live goal. Completion archives the goal, so without this branch
+      // the last "running" line would stay on the session until /goal clear.
+      // Only rewrite a title this process already owns, and only for an
+      // achieved result; clear still restores the captured original.
+      const result = lastGoalResults.get(sessionID)
+      if (!currentRuntime().appliedTitles.has(sessionID) || result?.state !== "achieved") return
+      title = buildCompletedSessionTitle(result)
+    }
+    if (currentRuntime().appliedTitles.get(sessionID) === title) return
+    try {
+      if (!currentRuntime().sessionTitles.has(sessionID)) {
+        const session = await sessionApi.get(sessionID)
+        const existing = typeof session?.title === "string" ? session.title : ""
+        // A status line left behind by a previous process is not the user's
+        // title; capture empty so clear leaves the host's title alone rather
+        // than restoring stale goal status.
+        currentRuntime().sessionTitles.set(
+          sessionID,
+          looksLikePluginSessionTitle(existing) ? "" : existing,
+        )
+      }
+      await sessionApi.update(sessionID, { title })
+      currentRuntime().appliedTitles.set(sessionID, title)
+    } catch (error) {
+      await logPluginDebug(client, "Failed to update session title", error)
+    }
+  }
+
+  const restoreSessionTitle = async (sessionID) => {
+    if (!sessionTitleStatus || !sessionID) return
+    const runtime = currentRuntime()
+    if (!runtime.sessionTitles.has(sessionID)) return
+    const original = runtime.sessionTitles.get(sessionID)
+    runtime.sessionTitles.delete(sessionID)
+    runtime.appliedTitles.delete(sessionID)
+    // Empty means there was nothing genuine to restore (no title, or the
+    // session only carried a status line from a previous process).
+    if (!original) return
+    try {
+      await sessionApi.update(sessionID, { title: original })
+    } catch (error) {
+      await logPluginDebug(client, "Failed to restore session title", error)
+    }
+  }
+
+  // The restricted agent currently driving this session, or "" when execution
+  // is permitted. Reads the execution context the host reports through
+  // `chat.message`, `chat.params`, and `session.updated`.
+  // Resolve the agent driving a session, preferring the execution context the
+  // host reports through `chat.message` / `chat.params` / `session.updated`.
+  //
+  // That context is empty for the first command in a session: OpenCode runs
+  // `command.execute.before` before any of those signals fire. Relying on it
+  // alone made the restriction fail open exactly where it matters most — a
+  // freshly opened session in Plan mode — so fall back to the session record,
+  // which carries the selected agent from the moment the user picks it.
+  const resolveSessionAgent = async (sessionID) => {
+    if (!sessionID) return ""
+    const cached = currentRuntime().sessionExecutionContexts.get(sessionID)?.agent
+    if (typeof cached === "string" && cached.trim()) return cached.trim()
+    try {
+      const session = await sessionApi.get(sessionID)
+      const agent = typeof session?.agent === "string" ? session.agent.trim() : ""
+      // Remember it so later hooks in the same turn do not re-fetch. `replace`
+      // is intentionally false: this must not clobber a richer context (model,
+      // variant) that a host signal may already have recorded.
+      if (agent) rememberSessionExecutionContext(sessionID, { agent })
+      return agent
+    } catch (error) {
+      // Hosts that do not expose the agent fail open, matching the behavior
+      // before the restriction existed.
+      await logPluginDebug(client, "Failed to resolve the session agent", error)
+      return ""
+    }
+  }
+
+  const restrictedAgentFor = async (sessionID) => {
+    if (allowGoalExecutionFromPlan) return ""
+    const agent = await resolveSessionAgent(sessionID)
+    return isRestrictedAgent(agent, restrictedAgents) ? agent : ""
+  }
+
+  // Record a newly created goal as held rather than active. Mirrors the idle
+  // guard's stop reason so `/goal status` reads the same either way.
+  const holdGoalForRestrictedAgent = (goal, agent) => {
+    const label = isPlanAgent(agent) ? "Plan" : agent
+    goal.stopped = true
+    goal.stopReason = restrictedAgentStopReason(agent)
+    goal.lastStatus =
+      `Goal recorded but held: the ${label} agent is planning-only. ` +
+      `Switch to an executing agent, then run /${commandName} resume to start work.`
+    pauseGoalClock(goal)
+    pushHistory(goal, "paused", `Created while the ${label} agent was active; held until an executing agent resumes it.`)
+    return label
+  }
 
   // Each session owns an independent snapshot, ledger, write chain, and
   // lifetime lease. A project can therefore host any number of unrelated goal
@@ -4238,6 +4616,7 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
     auditMessagesEnabled,
     announceLifecycle,
     commandName,
+    agentGoalAuthority,
   })
 
   const abortAcceptedContinuation = async (sessionID) => {
@@ -4481,12 +4860,13 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
 
     if (currentRuntime().sessionStatuses.get(sessionID) !== "idle") return null
 
-    const currentContext = currentRuntime().sessionExecutionContexts.get(sessionID)
-    if (isPlanAgent(currentContext?.agent)) {
+    const activeRestrictedAgent = await restrictedAgentFor(sessionID)
+    if (activeRestrictedAgent) {
+      const label = isPlanAgent(activeRestrictedAgent) ? "Plan" : activeRestrictedAgent
       await pauseActiveGoal(sessionID, {
-        stopReason: "plan agent active",
-        status: "Auto-continue paused because the active agent switched to Plan.",
-        history: "Paused before auto-continue because the active session agent switched to Plan.",
+        stopReason: restrictedAgentStopReason(activeRestrictedAgent),
+        status: `Auto-continue paused because the active agent switched to ${label}.`,
+        history: `Paused before auto-continue because the active session agent switched to ${label}.`,
       })
       return null
     }
@@ -4710,6 +5090,36 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
           // mutate it in place just as command.execute.before does.
           message.parts.splice(0, message.parts.length, commandPart)
         }
+        // A goal created by the first command of a fresh session could not
+        // know the active agent at creation time (command.execute.before runs
+        // before any chat hook and the Session record carries no agent). The
+        // routed turn does carry it: re-evaluate the planning-only restriction
+        // and hold the goal before the model is told to start working.
+        if (commandTurn.startedGoal && commandTurn.attachmentError !== true) {
+          const startedGoal = goalStates.get(sessionID)
+          const startedByThisCommand =
+            Boolean(startedGoal) &&
+            !startedGoal.stopped &&
+            startedGoal.goalId === commandTurn.startedGoal.goalId &&
+            startedGoal.runId === commandTurn.startedGoal.runId
+          const lateRestrictedAgent = startedByThisCommand ? await restrictedAgentFor(sessionID) : ""
+          if (lateRestrictedAgent) {
+            const heldLabel = holdGoalForRestrictedAgent(startedGoal, lateRestrictedAgent)
+            await persist(sessionID)
+            announceLifecycle(sessionID, `Goal recorded but held while ${heldLabel} is active.`, {
+              goal: startedGoal,
+              transition: "paused",
+              expectedState: "paused",
+            })
+            const commandPart = pluginMarkedTextPart(message, "command")
+            const routedText = frameControlCommandText(
+              buildGoalCommandNotice(startedGoal, { heldLabel, commandName }),
+            )
+            commandPart.text = routedText
+            commandTurn.policy = "control"
+            commandTurn.textDigest = createHash("sha256").update(routedText).digest("hex")
+          }
+        }
         runtime.activeCommandTurns.set(sessionID, {
           ...commandTurn,
           messageID: currentMessageID,
@@ -4873,6 +5283,8 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
             requireCurrent: false,
           })
         }
+        // Hand the session title back to the user now that no goal owns it.
+        if (clearStillCurrent) await restoreSessionTitle(sessionID)
         replaceCommandOutputText(
           output,
           !clearStillCurrent
@@ -5240,6 +5652,15 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         `Goal created with limits: ${goal.options.maxTurns} auto-continues, ${Math.round(goal.options.maxDurationMs / 1000)}s, ${goal.options.maxTokens.toLocaleString()} context tokens.`,
       )
 
+      // A goal set while a planning-only agent is active is recorded but held,
+      // so the objective and its budget survive the mode switch. Without this
+      // the goal is created live and the routed command text tells the model to
+      // start working; the idle guard only catches it on the *next* idle.
+      const creationRestrictedAgent = await restrictedAgentFor(sessionID)
+      if (creationRestrictedAgent) {
+        holdGoalForRestrictedAgent(goal, creationRestrictedAgent)
+      }
+
       // Replace the focused goal (cleanupGoal discards it); backgrounded goals
       // for this session are preserved. Use `/goal add` to keep the current
       // goal and add another. Clear any ordered-sequence flag so the new
@@ -5251,39 +5672,38 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
       registerSessionGoal(goal)
       focusGoal(sessionID, goal)
       await persist(sessionID)
-      announceLifecycle(sessionID, replacedGoal ? "Goal replaced and active." : "Goal active.", {
-        goal,
-        transition: replacedGoal ? "replaced-active" : "active",
-        expectedState: "active",
-      })
-      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 },
+      // The agent is often unknown here: OpenCode runs command.execute.before
+      // before any chat hook for the turn and its Session record carries no
+      // agent. Remember which goal this command started so chat.message, which
+      // does receive the agent, can still hold it (see that hook).
+      const creationCommandTurn = currentRuntime().commandOutputs.get(output)
+      if (creationCommandTurn && !creationRestrictedAgent) {
+        creationCommandTurn.startedGoal = { goalId: goal.goalId, runId: goal.runId }
+      }
+      const heldLabel = creationRestrictedAgent
+        ? isPlanAgent(creationRestrictedAgent)
+          ? "Plan"
+          : creationRestrictedAgent
+        : ""
+      announceLifecycle(
+        sessionID,
+        heldLabel
+          ? `Goal recorded but held while ${heldLabel} is active.`
+          : replacedGoal
+            ? "Goal replaced and active."
+            : "Goal active.",
+        {
+          goal,
+          transition: heldLabel ? "paused" : replacedGoal ? "replaced-active" : "active",
+          expectedState: heldLabel ? "paused" : "active",
+        },
       )
+      replaceCommandOutputText(output, buildGoalCommandNotice(goal, { heldLabel, replacedGoal, commandName }), {
+        preserveFiles: true,
+        // A held goal is a control turn, not a work turn: `startsWork: false`
+        // routes it through the read-only command framing.
+        startsWork: !heldLabel,
+      })
     },
 
     event: async ({ event }) => {
@@ -6471,6 +6891,37 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
 
   // register_command toggle: when disabled, the plugin does not own
   // a slash command and only the event/transform/compaction hooks remain.
+  // Session-title indicator: rather than threading a sync call through every
+  // state-mutating site (a missed one shows the user a stale status), wrap the
+  // two hooks that gate all state change. The sync no-ops when the rendered
+  // title is unchanged, and runs in `finally` so the displayed status matches
+  // the state actually reached even if a hook throws.
+  if (sessionTitleStatus) {
+    for (const hookName of ["command.execute.before", "event"]) {
+      const original = hooks[hookName]
+      if (typeof original !== "function") continue
+      hooks[hookName] = async (...args) => {
+        try {
+          return await original(...args)
+        } finally {
+          let titleSessionID = ""
+          if (hookName === "event") {
+            // `message.updated` streams many times per assistant turn. Awaiting
+            // a title sync on each would put an API round-trip in the streaming
+            // path for a cosmetic update; idle, compaction, and interruption
+            // events already cover every state the indicator renders.
+            if (args[0]?.event?.type !== "message.updated") {
+              titleSessionID = getSessionID(args[0]?.event)
+            }
+          } else {
+            titleSessionID = args[0]?.sessionID
+          }
+          await syncSessionTitle(titleSessionID)
+        }
+      }
+    }
+  }
+
   if (!registerCommand) {
     delete hooks["command.execute.before"]
   }
@@ -6607,6 +7058,15 @@ export const testInternals = {
   isIdleEvent,
   isPluginCommandMessage,
   isPluginContinuationMessage,
+  isPlanAgent,
+  buildSessionTitle,
+  buildCompletedSessionTitle,
+  formatCompactDuration,
+  formatCompactTokens,
+  goalStatusIcon,
+  looksLikePluginSessionTitle,
+  isRestrictedAgent,
+  normalizeRestrictedAgents,
   isPluginGeneratedMessage,
   legacyStateFilePaths,
   messageHasToolCall,
@@ -6626,5 +7086,6 @@ export const testInternals = {
   resolveStateFilePath,
   runtimeSessionDiagnostics,
   stopReason,
+  costCapFor,
   xdgStateFilePath,
 }