opencode-goal-plugin 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.9.0 — 2026-08-29
+
+- Add plan-mode safety: a goal set while a planning-only agent is active is recorded but held instead of starting, with stop reason `plan agent active`, its budget preserved, and a read-only control turn that tells the model not to begin work. Auto-continue already paused when the session switched to Plan; this closes the creation path, where the goal previously started and ran the loop before any idle occurred. The active agent is read from the host's execution context with a fallback to the session record, which matters because `command.execute.before` runs before `chat.message`/`chat.params` — without the fallback the restriction failed open on the first command in a session. Configurable via `restrictedAgents` (default `["plan"]`) and `allowGoalExecutionFromPlan` (default `false`); the default-on behavior is pinned by the mutation contract. Note the restriction stops the goal loop, not the single routed command turn, which OpenCode does not fully intercept.
+- Add an opt-in session-title status indicator (`sessionTitleStatus`), mirroring live goal status — state icon, objective, turns, elapsed, and tokens — into the OpenCode session title so unattended runs show a continuous heartbeat. The original title is captured before the first overwrite and restored by `/goal clear`; unchanged renders skip the API call, and update failures are logged at debug level without interrupting the goal loop. The indicator refreshes on commands and on idle/compaction/interruption events but never on the `message.updated` events that stream during a turn, keeping API round-trips out of the response path. Status lines written by a previous process are recognized as the plugin's own, so a restart followed by `/goal clear` cannot promote stale goal status to the session's permanent title.
+- Verify both features against a live OpenCode 1.18.25 TUI, not only unit and contract tests: a goal set under Plan records `stopped: true` with zero auto-continues, and the status indicator renders in the session title.
+- Document OpenCode 2 status explicitly: unsupported and untested, with the existing dual-shape session adapter noted and a concrete checklist of what a supported claim would require. Records that this plugin is server-only, so its configuration lives entirely in `opencode.json` on any OpenCode line.
+
 ## 0.8.2 — 2026-08-21
 
 - Harden the post-compaction goal continuation guard introduced in

package/README.md

@@ -31,13 +31,14 @@ This project is independently implemented for OpenCode. Product names used elsew
 | Operating systems | Filesystem-sensitive lifecycle tests run on Linux, macOS, and Windows |
 | Package entrypoint | Installed-tarball contracts verify both export paths, consumer TypeScript resolution, hooks, and all 11 tools |
 | Provider/backend quirks | Strict-template backends require the goal block to merge into the primary `system` message; covered by regression tests |
+| OpenCode 2 | Not supported and not yet tested; the peer/engine pin is `>=1.17.15 <2`. See the [OpenCode 2 section](docs/compatibility.md#opencode-2) |
 
 See the [compatibility policy](docs/compatibility.md) for the supported public
 surface and versioning expectations.
 
 ### OpenCode version compatibility
 
-Tested against real OpenCode 1.17.15 processes with live provider credentials and no mocked plugin hooks. State, ledger entries, and workspace files were checked independently of terminal or model prose:
+Tested against real OpenCode 1.17.15 and 1.18.25 processes with live provider credentials and no mocked plugin hooks. State, ledger entries, and workspace files were checked independently of terminal or model prose:
 
 | OpenCode Version | Provider Tested | `/goal status` | Auto-continue | Evidence-gated completion | Historical custom-command presentation (v0.6.6) |
 |---|---|---|---|---|---|
@@ -45,6 +46,7 @@ Tested against real OpenCode 1.17.15 processes with live provider credentials an
 | 1.17.15 | opencode-go (`qwen3.7-plus`) | ✅ | ✅ | ✅ Self-corrected after one rejection (bare `[goal:complete]` with no evidence), then completed cleanly | ⚠️ Not displayed |
 | 1.17.15 | opencode-go (`glm-5.2`) | ✅ | ✅ | ✅ Clean `[goal:evidence]` + `[goal:complete]` on the first attempt | ⚠️ Not displayed |
 | 1.17.15 | deepseek (`deepseek-chat`) | ✅ | ✅ | ✅ Clean `[goal:evidence]` + `[goal:complete]` on the first attempt; also verified end-to-end via the [demo](demo/) — autonomously fixed a real bug and reported evidence-backed completion | ⚠️ Not displayed |
+| 1.18.25 | opencode (`nemotron-3.5-lightning-free`) | ✅ | ✅ Held correctly under the Plan agent (`stopped: true`, zero auto-continues) | ✅ Clean `[goal:evidence]` + `[goal:complete]` | ⚠️ Not displayed; command text routed to model |
 
 `/goal status` and auto-continue are graded on **state correctness** (verified directly against persisted state: correct limits, turn/stop accounting, completion state, and file effects), not on terminal rendering. The `deepseek-v4-flash-free` canary suite additionally covers pause/resume across processes, blocker/restart, hard-process recovery, real host compaction, and stale-history clear enforcement. See [`docs/providers.md`](docs/providers.md) for the complete lifecycle matrix and session evidence.
 
@@ -401,6 +403,62 @@ await GoalPlugin(
 
 `timeoutMs` caps how long the built-in child-session auditor waits for a verdict. `failurePolicy` defaults to `reject`: an unavailable API, missing child-session ID, provider error, or timeout rejects the audit and pauses the goal for review. Set it to `approve` only as an explicit compatibility escape hatch; an actual negative or malformed verifier verdict still rejects. `auditorOptions` is ignored when a custom `auditor` function is supplied.
 
+## Status indicator
+
+Unattended runs are easier to trust when you can see the goal is still alive. Set `sessionTitleStatus: true` and the plugin mirrors live goal status into the OpenCode session title, which the TUI renders persistently:
+
+```
+▶ ship the release · 3/10 · 2m · 45k/200k
+```
+
+Status icon, objective, auto-continues used / limit, elapsed time, and context tokens / budget. The icon distinguishes running (`▶`), paused (`⏸`), and blocked (`⛔`) — blocked outranks paused because it needs you, not just a resume. A paused goal freezes its elapsed clock rather than running on.
+
+```json
+{
+  "plugin": [
+    ["opencode-goal-plugin", { "sessionTitleStatus": true }]
+  ]
+}
+```
+
+The option is **off by default** because it overwrites a user-visible field. When enabled, the session's original title is captured before the first overwrite and restored by `/goal clear`. A render identical to the last one skips the API call, so `/goal status` and other read-only commands cost nothing. Title updates are cosmetic: a failure is logged at debug level and never interrupts the goal loop.
+
+The indicator refreshes on goal commands and on idle, compaction, and interruption events — **not** on the `message.updated` events that stream during an assistant turn. Streaming refreshes would put an API round-trip in the response path for a cosmetic update, and idle is the cadence a human actually reads the indicator at.
+
+The captured original title lives in memory only, so a hard process kill leaves the last status line on the session. The plugin recognizes its own status lines and will not mistake one for your title, so `/goal clear` after a restart leaves the host's title alone rather than restoring stale goal status — but it cannot recover the title the session had before the goal started. Rename the session if you want it back.
+
+This needs no TUI plugin entrypoint, no `@opentui` dependencies, and no build step.
+
+## Plan-mode safety
+
+A planning-only agent is never driven into execution by the goal loop. OpenCode's built-in `plan` agent is restricted by default:
+
+- A goal set while `plan` is active is **recorded but held**, with stop reason `plan agent active`. The objective and its budget survive, so nothing is lost — the goal simply does not start.
+- The routed confirmation text for a held goal **omits the "start working" instruction** and is sent as a read-only control turn. This matters because command text reaches the model as a normal turn on current OpenCode builds (see [Limitations](#limitations)).
+- Auto-continue stays suppressed on **every idle** while a restricted agent is active, so switching into `plan` mid-goal pauses the loop.
+- Continuations retain the agent that started the goal, so the loop cannot drift into a different agent.
+
+The active agent is read from the execution context the host reports, falling back to the session record. That fallback matters: OpenCode runs `command.execute.before` before any `chat.message`/`chat.params` for the turn, so the context is empty for the first command in a session — the exact case a freshly opened Plan-mode session hits.
+
+**What this does and does not prevent.** The restriction stops the *goal loop*: a held goal sends zero auto-continues, so no unattended work happens. It cannot stop a model from acting on the single routed command turn, because OpenCode's `command.execute.before` does not fully intercept command text (see [Limitations](#limitations)). A held goal's routed text explicitly tells the model not to begin work and is sent as a read-only control turn, but a non-compliant model may still act on that one turn. Verified against OpenCode 1.18.25: a goal set under Plan records `stopped: true`, `stopReason: plan agent active`, and `turnCount: 0`.
+
+Run `/goal resume` after switching back to an executing agent to start the work.
+
+| Option | Default | Controls |
+|---|---|---|
+| `restrictedAgents` | `["plan"]` | Agent names treated as planning-only (case-insensitive). Pass `[]` to release the restriction. |
+| `allowGoalExecutionFromPlan` | `false` | Set `true` to allow goal creation and auto-continue while a restricted agent is active. |
+
+```json
+{
+  "plugin": [
+    ["opencode-goal-plugin", { "restrictedAgents": ["plan", "review"] }]
+  ]
+}
+```
+
+The restriction being on by default is pinned by the mutation contract: hardcoding `allowGoalExecutionFromPlan` to `true` fails the suite.
+
 ## Prompt safety
 
 The goal text is wrapped in `<goal_objective>` tags and labeled as user-provided task data. The assistant is told to treat it as a task description, not as elevated instructions that can override system, developer, tool, or repository policies.

package/docs/compatibility.md

@@ -81,6 +81,56 @@ comes from the rewritten turn's escaped reporting frame, fail-closed tool
 blocking, and parent-correlated lifecycle suppression. The system transform
 remains registered as additional protection for hosts that support it.
 
+## OpenCode 2
+
+**Status: not supported, and not yet tested.**
+
+The package declares `engines.opencode` and the `@opencode-ai/plugin` peer as
+`>=1.17.15 <2`. That bound is deliberate: no claim in this repository is made
+without a verified run behind it, and the project has not yet exercised the
+plugin against an OpenCode 2 build. Treat OpenCode 2 as unverified rather than
+as known-broken.
+
+### What already exists in this direction
+
+- `createOpenCodeSessionApi` speaks both the legacy generated-client shape
+  (`{ path, body, query }`) and the flattened shape (`{ sessionID, ... }`),
+  selected per operation and remembered after the first success. The
+  `sdkShape: "flat"` option pins the flattened shape for embedded clients.
+- Only read-only operations are ever replayed against the alternate shape, so a
+  shape probe can never duplicate a mutating call. This invariant is pinned by
+  the mutation contract.
+
+### What a supported v2 claim would require
+
+Before the pin is widened, all of the following need to pass against a real
+OpenCode 2 build, not a mock:
+
+1. Plugin load and hook registration through the v2 plugin entrypoint.
+2. `command.execute.before`, `event`, `experimental.chat.system.transform`,
+   `experimental.session.compacting`, and `experimental.compaction.autocontinue`
+   firing with the shapes the plugin expects.
+3. The execution-context signals (`chat.message`, `chat.params`,
+   `session.updated`) still reporting the active agent, which the planning-only
+   restriction depends on.
+4. Session-API calls (`messages`, `promptAsync`, `create`, `get`, `update`,
+   `abort`) under whichever argument shape v2 ships.
+5. Goal-specific compaction context and recovery of running child sessions after
+   a plugin restart, which are the areas most likely to differ.
+
+### Configuration
+
+This plugin is **server-only**: `package.json` exports the root and
+`opencode-goal-plugin/server`, and there is no TUI plugin entrypoint. Its
+configuration therefore lives entirely in `opencode.json` (the `plugin` and
+`command` keys) on any OpenCode line.
+
+Plugins that *do* ship a TUI component are registered in a second file whose
+location differs between OpenCode lines, and those formats must not be mixed.
+That distinction does not apply here — including for the
+[status indicator](../README.md#status-indicator), which reaches the TUI through
+the session title rather than through a TUI plugin.
+
 ## Versioning
 
 Semantic-versioning intent is:

package/index.d.ts

@@ -311,6 +311,34 @@ export interface GoalPluginOptions {
   /** Register collision-safe native `goal` and `goal-verify` agents through OpenCode's config hook. */
   registerAgents?: boolean
 
+  /**
+   * Mirror live goal status into the OpenCode session title, which the TUI
+   * renders persistently (e.g. `▶ ship the release · 3/10 · 2m · 45k/200k`),
+   * giving unattended runs a continuous heartbeat without a TUI plugin.
+   *
+   * The session's original title is captured before the first overwrite and
+   * restored by `/goal clear`. Title updates are cosmetic: a failure is logged
+   * at debug level and never interrupts the goal loop.
+   * @default false
+   */
+  sessionTitleStatus?: boolean
+
+  /**
+   * Agent names treated as planning-only. A goal created while one of these
+   * agents is active is recorded but held paused instead of starting, and
+   * auto-continue stays suppressed while one is active. Matching is
+   * case-insensitive. Pass `[]` to release the restriction entirely.
+   * @default ["plan"]
+   */
+  restrictedAgents?: string[]
+
+  /**
+   * Opt out of the planning-only restriction, allowing goals to be created and
+   * auto-continued while a {@link restrictedAgents} agent is active.
+   * @default false
+   */
+  allowGoalExecutionFromPlan?: boolean
+
   /** Name of the native primary goal agent. @default "goal" */
   goalAgentName?: string
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goal-plugin",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Durable, guarded goal workflows for OpenCode.",
   "type": "module",
   "main": "./src/goal-plugin.js",

package/src/goal-plugin.js

@@ -111,6 +111,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(),
@@ -396,8 +401,95 @@ 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(" · ")
+}
+
+// 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) {
@@ -920,6 +1012,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()
@@ -2133,6 +2227,26 @@ 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.
+  }
+}
+
 function parseGoalArguments(args, defaults) {
   const parts = args.match(/"[^"]*"|'[^']*'|\S+/g) || []
   const condition = []
@@ -3956,6 +4070,110 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
     cwd: pluginOptions.cwd || directory,
   })
   const { commandName, registerCommand } = normalizeCommandOptions(pluginOptions)
+  const restrictedAgents = normalizeRestrictedAgents(pluginOptions.restrictedAgents)
+  // 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)
+    if (!goal) return
+    const title = buildSessionTitle(goal)
+    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
@@ -4481,12 +4699,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
     }
@@ -4873,6 +5092,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 +5461,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,11 +5481,24 @@ 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",
-      })
+      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,
         [
@@ -5266,14 +5509,25 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
                 "",
               ]
             : []),
-          `New active goal: ${goal.condition}`,
+          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,
           "",
-          "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]`.",
+          // A held goal must not be told to start working. Command text reaches
+          // the model as a normal turn on current OpenCode builds, so this line
+          // would be the escape the plan guard exists to prevent.
+          ...(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(
@@ -5282,7 +5536,9 @@ async function createGoalPlugin({ client, directory } = {}, pluginOptions = {})
         ]
           .filter((line) => line !== null)
           .join("\n"),
-        { preserveFiles: true, startsWork: true },
+        // A held goal is a control turn, not a work turn: `startsWork: false`
+        // routes it through the read-only command framing.
+        { preserveFiles: true, startsWork: !heldLabel },
       )
     },
 
@@ -6471,6 +6727,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 +6894,14 @@ export const testInternals = {
   isIdleEvent,
   isPluginCommandMessage,
   isPluginContinuationMessage,
+  isPlanAgent,
+  buildSessionTitle,
+  formatCompactDuration,
+  formatCompactTokens,
+  goalStatusIcon,
+  looksLikePluginSessionTitle,
+  isRestrictedAgent,
+  normalizeRestrictedAgents,
   isPluginGeneratedMessage,
   legacyStateFilePaths,
   messageHasToolCall,