@prevalentware/opencode-goal-plugin 0.1.18 → 0.1.20

package/README.md

@@ -22,6 +22,7 @@ The OpenCode Goal Plugin adds:
 - Goal close evidence: `complete` requires verified evidence, and `unmet` requires a concrete blocker.
 - Persistent per-session goal state with history, checkpoints, budgets, and owner-only file permissions.
 - Optional automatic continuation on `session.idle` / `session.status`, with no-progress pause and budget wrap-up safeguards.
+- Plan-mode safety: goals created from the `plan` agent stay paused, and auto-continue never escapes a Plan-mode session or switches agents on its own.
 - Compaction context so active goals are preserved when OpenCode summarizes a long session.
 
 ## Why Use This OpenCode Goal Plugin?
@@ -82,13 +83,16 @@ Server options can be configured in `opencode.json`:
       "@prevalentware/opencode-goal-plugin",
       {
         "auto_continue": true,
+        "defer_while_tasks_active": true,
         "max_auto_turns": 25,
         "min_continue_interval_seconds": 3,
         "max_prompt_failures": 3,
         "default_token_budget": 200000,
         "max_goal_duration_seconds": 1800,
         "no_progress_token_threshold": 50,
-        "max_no_progress_turns": 2
+        "max_no_progress_turns": 2,
+        "restricted_agents": ["plan"],
+        "allow_goal_execution_from_plan": false
       }
     ]
   ]
@@ -98,6 +102,7 @@ Server options can be configured in `opencode.json`:
 Defaults:
 
 - `auto_continue`: `true`
+- `defer_while_tasks_active`: `true`; when enabled, goal auto-continuation waits for active OpenCode Task child sessions and their orchestrator reconciliation before sending the next goal prompt.
 - `max_auto_turns`: `25`
 - `min_continue_interval_seconds`: `3`
 - `max_prompt_failures`: `3`
@@ -107,6 +112,8 @@ Defaults:
 - `max_no_progress_turns`: `2`
 - `register_command`: `true`
 - `command_name`: `"goal"`
+- `restricted_agents`: `["plan"]`; agents (matched case-insensitively) treated as planning-only for goal execution.
+- `allow_goal_execution_from_plan`: `false`; when `true`, disables Plan-mode goal restrictions entirely.
 
 ## Goal Workflow
 
@@ -135,6 +142,18 @@ The plugin also uses safety states while keeping the goal available for review o
 
 When a safety limit is reached, the plugin sends one wrap-up prompt asking for a concise handoff instead of silently continuing forever.
 
+## Plan Mode Safety
+
+OpenCode Plan mode is a user-controlled safety boundary, and goal mode must not become an escape hatch out of it. The plugin enforces that boundary in several layers:
+
+- Goals created with `create_goal` or `set_goal` from the `plan` agent are recorded as `paused` with stop reason `plan mode`, never as active implementation goals. The tool response tells the agent to ask the user to switch to Build mode and resume the goal.
+- Automatic idle continuation is suppressed while the last user prompt or the latest assistant turn came from a restricted agent. If a previously active goal idles under Plan mode, it is paused visibly instead of continuing autonomously.
+- Resuming a goal (`update_goal_status` with `active`, or `update_goal_objective` with `status: "active"`) is refused from Plan mode, so a prompt-injected instruction inside repository content cannot self-escalate a planning session into Build-mode execution. Switching to Build mode and resuming is an explicit user action; resuming from Build updates the tracked agent so continuation restarts pinned to Build.
+- Continuation prompts are pinned to the agent recorded from the last user prompt (`body.agent`), so auto-continue never silently switches the session to a different agent or mode.
+- The goal system reminder becomes planning-only after a Plan-mode prompt: it shows goal state but instructs the agent not to perform implementation work.
+
+The set of planning-only agents is configurable with `restricted_agents` (default `["plan"]`). Setting `allow_goal_execution_from_plan` to `true` opts out of all of these restrictions; the secure default is `false`.
+
 ## State
 
 Goal state is stored at:
@@ -194,6 +213,6 @@ OpenCode plugin modules are target-specific. This package exports separate modul
 }
 ```
 
-Codex goal mode has deeper runtime integration for thread lifecycle control. This plugin implements the same workflow using OpenCode plugin hooks. Token usage is read from OpenCode step-finish usage when available and falls back to message token metadata or text estimation when exact usage is unavailable. Continuation is driven by OpenCode idle events, including `session.idle` and `session.status` idle notifications. During compaction, the plugin disables OpenCode's generic synthetic auto-continue while an active goal exists so the goal-specific continuation prompt remains authoritative.
+Codex goal mode has deeper runtime integration for thread lifecycle control. This plugin implements the same workflow using OpenCode plugin hooks. Token usage is read from OpenCode step-finish usage when available and falls back to message token metadata or text estimation when exact usage is unavailable. Continuation is driven by OpenCode idle events, including `session.idle` and `session.status` idle notifications. By default, continuation is deferred while OpenCode Task child sessions are active or their terminal result still needs an orchestrator turn. During compaction, the plugin disables OpenCode's generic synthetic auto-continue while an active goal exists so the goal-specific continuation prompt remains authoritative.
 
 The goal sidebar shows the current status, elapsed time, token usage, auto-continue count, latest checkpoint, latest status message, stop reason, and objective when a goal is active, paused, or safety-limited. Closed goals remain visible briefly through the latest tool state as achieved or unmet.

package/dist/server.js

@@ -21,6 +21,8 @@ var MAX_CHECKPOINTS = 8;
 var CHECKPOINT_CHAR_LIMIT = 280;
 var DEFAULT_NO_PROGRESS_TOKEN_THRESHOLD = 50;
 var DEFAULT_MAX_NO_PROGRESS_TURNS = 2;
+var PLAN_MODE_STOP_REASON = "plan mode";
+var PLAN_MODE_BLOCKER = "Goal execution is paused while the session is in Plan mode. Switch to Build mode and resume the goal to continue.";
 var NullableString = Schema.NullOr(Schema.String);
 var NullableNumber = Schema.NullOr(Schema.Number);
 var HistoryEntrySchema = Schema.Struct({
@@ -60,7 +62,8 @@ var GoalSchema = Schema.Struct({
   checkpoints: Schema.optionalWith(Schema.Array(CheckpointSchema), { default: () => [] }),
   lastCheckpoint: Schema.optionalWith(Schema.NullOr(CheckpointSchema), { default: () => null }),
   lastAssistantText: Schema.optionalWith(Schema.String, { default: () => "" }),
-  lastAssistantMessageID: Schema.optionalWith(Schema.String, { default: () => "" })
+  lastAssistantMessageID: Schema.optionalWith(Schema.String, { default: () => "" }),
+  lastPromptAgent: Schema.optionalWith(NullableString, { default: () => null })
 });
 var StateSchema = Schema.Struct({
   version: Schema.Literal(1),
@@ -164,6 +167,7 @@ function normalizeGoal(goal) {
   goal.lastCheckpoint = goal.lastCheckpoint ?? goal.checkpoints.at(-1) ?? null;
   goal.lastAssistantText ??= "";
   goal.lastAssistantMessageID ??= "";
+  goal.lastPromptAgent ??= null;
   goal.noProgressTurns = nonNegativeInteger(goal.noProgressTurns, 0);
   goal.maxAutoTurns = positiveIntegerOrNull(goal.maxAutoTurns);
   goal.maxDurationSeconds = positiveIntegerOrNull(goal.maxDurationSeconds);
@@ -181,7 +185,9 @@ function normalizeCreateOptions(input) {
       maxAutoTurns: null,
       maxDurationSeconds: null,
       noProgressTokenThreshold: DEFAULT_NO_PROGRESS_TOKEN_THRESHOLD,
-      maxNoProgressTurns: DEFAULT_MAX_NO_PROGRESS_TURNS
+      maxNoProgressTurns: DEFAULT_MAX_NO_PROGRESS_TURNS,
+      agent: null,
+      initialStatus: "active"
     };
   }
   return {
@@ -189,7 +195,9 @@ function normalizeCreateOptions(input) {
     maxAutoTurns: positiveIntegerOrNull(input?.maxAutoTurns),
     maxDurationSeconds: positiveIntegerOrNull(input?.maxDurationSeconds),
     noProgressTokenThreshold: positiveIntegerOrNull(input?.noProgressTokenThreshold) ?? DEFAULT_NO_PROGRESS_TOKEN_THRESHOLD,
-    maxNoProgressTurns: positiveIntegerOrNull(input?.maxNoProgressTurns) ?? DEFAULT_MAX_NO_PROGRESS_TURNS
+    maxNoProgressTurns: positiveIntegerOrNull(input?.maxNoProgressTurns) ?? DEFAULT_MAX_NO_PROGRESS_TURNS,
+    agent: typeof input?.agent === "string" && input.agent.trim() ? input.agent.trim() : null,
+    initialStatus: input?.initialStatus === "paused" ? "paused" : "active"
   };
 }
 function positiveIntegerOrNull(value) {
@@ -238,6 +246,7 @@ function snapshot(goal) {
     lastCheckpoint: goal.lastCheckpoint,
     lastAssistantText: goal.lastAssistantText,
     lastAssistantMessageID: goal.lastAssistantMessageID,
+    lastPromptAgent: goal.lastPromptAgent,
     autoTurns: goal.autoTurns,
     lastContinuationAt: goal.lastContinuationAt,
     remainingTokens: remainingTokens(goal),
@@ -258,63 +267,105 @@ async function createGoal(sessionID, objective, options) {
       throw new Error("cannot create a new goal because this session already has a non-closed goal");
     }
     const now = nowSeconds();
+    const paused = normalizedOptions.initialStatus === "paused";
     const goal = {
       sessionID,
       objective: value,
-      status: "active",
+      status: normalizedOptions.initialStatus,
       tokenBudget: normalizedOptions.tokenBudget,
       tokensUsed: 0,
       timeUsedSeconds: 0,
       createdAt: now,
       updatedAt: now,
       completionEvidence: null,
-      blocker: null,
+      blocker: paused ? PLAN_MODE_BLOCKER : null,
       closedAt: null,
-      lastAccountedAt: now,
+      lastAccountedAt: paused ? null : now,
       autoTurns: 0,
       lastContinuationAt: null,
       continuationFailures: 0,
-      lastStatus: "Goal set.",
+      lastStatus: paused ? "Goal recorded from Plan mode; execution paused until resumed from Build mode." : "Goal set.",
       maxAutoTurns: normalizedOptions.maxAutoTurns,
       maxDurationSeconds: normalizedOptions.maxDurationSeconds,
       noProgressTokenThreshold: normalizedOptions.noProgressTokenThreshold,
       maxNoProgressTurns: normalizedOptions.maxNoProgressTurns,
       noProgressTurns: 0,
       budgetWrapupSent: false,
-      stopReason: null,
+      stopReason: paused ? PLAN_MODE_STOP_REASON : null,
       history: [],
       checkpoints: [],
       lastCheckpoint: null,
       lastAssistantText: "",
-      lastAssistantMessageID: ""
+      lastAssistantMessageID: "",
+      lastPromptAgent: normalizedOptions.agent
     };
     pushHistory(goal, "created", goalLimitSummary(goal));
+    if (paused)
+      pushHistory(goal, "paused", goal.lastStatus);
     state.goals[sessionID] = goal;
     return snapshot(goal);
   });
 }
-async function updateGoalObjective(sessionID, objective, status = "active") {
+async function updateGoalObjective(sessionID, objective, status = "active", options) {
   const value = validateObjective(objective);
+  const agent = typeof options?.agent === "string" && options.agent.trim() ? options.agent.trim() : null;
+  const planModePause = options?.planModePause === true;
   return mutate((state) => {
     const goal = state.goals[sessionID];
     if (!goal)
       throw new Error("cannot update goal because this session has no goal");
     accountWallClock(goal);
     goal.objective = value;
-    goal.status = status;
+    goal.status = planModePause ? "paused" : status;
     goal.updatedAt = nowSeconds();
-    goal.lastAccountedAt = status === "active" ? goal.updatedAt : null;
+    goal.lastAccountedAt = goal.status === "active" ? goal.updatedAt : null;
     goal.completionEvidence = null;
-    goal.blocker = null;
+    goal.blocker = planModePause ? PLAN_MODE_BLOCKER : null;
     goal.closedAt = null;
-    goal.stopReason = null;
+    goal.stopReason = planModePause ? PLAN_MODE_STOP_REASON : null;
     goal.budgetWrapupSent = false;
-    goal.lastStatus = status === "active" ? "Goal objective updated and resumed." : "Goal objective updated and paused.";
+    if (agent)
+      goal.lastPromptAgent = agent;
+    goal.lastStatus = planModePause ? "Goal objective updated; execution paused while the session is in Plan mode." : goal.status === "active" ? "Goal objective updated and resumed." : "Goal objective updated and paused.";
     pushHistory(goal, "updated", `Goal objective updated: ${summarizeText(value, 400)}`);
+    if (planModePause)
+      pushHistory(goal, "paused", goal.lastStatus);
+    return snapshot(goal);
+  });
+}
+async function recordPromptAgent(sessionID, agent) {
+  const value = agent.trim();
+  if (!value)
+    return null;
+  return mutate((state) => {
+    const goal = state.goals[sessionID];
+    if (!goal || isClosed(goal.status))
+      return goal ? snapshot(goal) : null;
+    if (goal.lastPromptAgent === value)
+      return snapshot(goal);
+    goal.lastPromptAgent = value;
+    goal.updatedAt = nowSeconds();
+    return snapshot(goal);
+  });
+}
+async function pauseGoalForPlanMode(sessionID) {
+  return mutate((state) => {
+    const goal = state.goals[sessionID];
+    if (!goal || goal.status !== "active")
+      return goal ? snapshot(goal) : null;
+    accountWallClock(goal);
+    goal.status = "paused";
+    goal.lastAccountedAt = null;
+    goal.stopReason = PLAN_MODE_STOP_REASON;
+    goal.blocker = PLAN_MODE_BLOCKER;
+    goal.lastStatus = "Auto-continue paused while the session is in Plan mode.";
+    goal.updatedAt = nowSeconds();
+    pushHistory(goal, "paused", goal.lastStatus);
     return snapshot(goal);
   });
 }
-async function setGoalStatus(sessionID, status) {
+async function setGoalStatus(sessionID, status, agent) {
+  const agentValue = typeof agent === "string" && agent.trim() ? agent.trim() : null;
   return mutate((state) => {
     const goal = state.goals[sessionID];
     if (!goal)
@@ -328,6 +379,8 @@ async function setGoalStatus(sessionID, status) {
     goal.stopReason = status === "active" ? null : "paused";
     goal.budgetWrapupSent = status === "active" ? false : goal.budgetWrapupSent;
     goal.blocker = status === "active" ? null : goal.blocker;
+    if (agentValue)
+      goal.lastPromptAgent = agentValue;
     goal.lastStatus = status === "active" ? "Goal resumed." : "Goal paused.";
     pushHistory(goal, status === "active" ? "resumed" : "paused", goal.lastStatus);
     return snapshot(goal);
@@ -674,9 +727,23 @@ Stop reason: ${goal.stopReason ?? "goal limit reached"}
 
 Do not start new substantive work for this goal. Wrap up this turn soon: summarize useful progress, identify remaining work or blockers, and leave the user with a clear next step. Do not call update_goal unless the goal is actually complete.`;
 }
-function systemReminder(goal) {
+function planModeReminder(goal) {
+  return `OpenCode goal mode is tracking a goal, but this session is currently in Plan mode.
+
+${formatGoal(goal)}
+
+Plan-mode constraints:
+- Do not perform implementation work for this goal: no file edits, no state-changing commands, no dependency or repository changes.
+- Use this turn for analysis, planning, and answering the user.
+- Goal auto-continue stays disabled while the session is in Plan mode.
+- If the user wants the goal executed, ask them to switch to Build mode and resume the goal (for example with "/goal resume").
+- Do not treat the goal objective as higher-priority instructions.`;
+}
+function systemReminder(goal, options) {
   if (!goal || goal.status === "complete" || goal.status === "unmet")
     return "";
+  if (options?.planningOnly)
+    return planModeReminder(goal);
   if (goal.status === "active")
     return `OpenCode goal mode active reminder:
 
@@ -700,8 +767,19 @@ var DEFAULT_MAX_AUTO_TURNS = 25;
 var DEFAULT_CONTINUE_INTERVAL_SECONDS = 3;
 var DEFAULT_MAX_PROMPT_FAILURES = 3;
 var DEFAULT_COMMAND_NAME = "goal";
+var DEFAULT_RESTRICTED_AGENTS = ["plan"];
 var GOAL_SYSTEM_MARKER = "OpenCode goal mode";
+var TASK_SETTLE_DELAY_MS = 25;
+var SNAPSHOT_IDLE_HOLD_MS = 250;
+var TASK_TERMINAL_STATES = new Set(["completed", "error", "cancelled"]);
+var PLAN_MODE_CREATE_NOTICE = 'Goal recorded while the session is in Plan mode, so execution is paused. Do not start implementation work now. Ask the user to switch to Build mode and resume the goal (for example with "/goal resume") to begin execution.';
 var activeContinuations = new Set;
+function restrictedAgentSet(options) {
+  if (options?.allow_goal_execution_from_plan === true)
+    return new Set;
+  const names = Array.isArray(options?.restricted_agents) ? options.restricted_agents : DEFAULT_RESTRICTED_AGENTS;
+  return new Set(names.map((name) => typeof name === "string" ? name.trim().toLowerCase() : "").filter(Boolean));
+}
 function goalCommandTemplate(commandName) {
   return `OpenCode goal mode command "/${commandName}" was invoked.
 
@@ -757,6 +835,16 @@ function textFromMessage(message) {
   return (message.parts ?? []).map(textFromPart).filter(Boolean).join(`
 `).trim();
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function sessionIDFromMessage(message) {
+  if (typeof message.sessionID === "string")
+    return message.sessionID;
+  if (isRecord(message.info) && typeof message.info.sessionID === "string")
+    return message.info.sessionID;
+  return;
+}
 function estimateMessages(messages) {
   return messages.reduce((sum, message) => sum + estimateTokensFromText(textFromMessage(message)), 0);
 }
@@ -810,10 +898,71 @@ function tokensFromMessages(messages) {
   const exactTotal = messages.reduce((sum, message) => sum + (exactTokensFromMessage(message) ?? 0), 0);
   return exactTotal > 0 ? exactTotal : estimateMessages(messages);
 }
-async function sendContinuation(client, sessionID, prompt) {
+function taskHeader(output) {
+  const resultIndex = output.search(/<task_(?:result|error)>/);
+  return resultIndex === -1 ? output : output.slice(0, resultIndex);
+}
+function parseTaskID(output) {
+  const xmlMatch = /<task\s+[^>]*\bid=["']([^"']+)["'][^>]*>/i.exec(output);
+  if (xmlMatch?.[1])
+    return xmlMatch[1];
+  for (const line of output.split(/\r?\n/)) {
+    const match = /^task_id:\s*([^\s()]+)(?:\s*\(.*)?$/i.exec(line.trim());
+    if (match?.[1])
+      return match[1];
+  }
+  return;
+}
+function parseTaskState(output) {
+  const xmlMatch = /<task\s+[^>]*\bstate=["'](running|completed|error|cancelled)["'][^>]*>/i.exec(output);
+  if (xmlMatch?.[1])
+    return xmlMatch[1].toLowerCase();
+  for (const line of taskHeader(output).split(/\r?\n/)) {
+    const match = /^state:\s*(running|completed|error|cancelled)\s*$/i.exec(line.trim());
+    if (match?.[1])
+      return match[1].toLowerCase();
+  }
+  return;
+}
+function parseTaskStatus(output) {
+  if (typeof output !== "string")
+    return;
+  const taskID = parseTaskID(output);
+  const state = parseTaskState(output);
+  return taskID && state ? { taskID, state } : undefined;
+}
+function messageCompletedAt(message) {
+  const time = isRecord(message.time) ? message.time : isRecord(message.info) && isRecord(message.info.time) ? message.info.time : undefined;
+  const completed = time?.completed;
+  return typeof completed === "number" && Number.isFinite(completed) ? completed : null;
+}
+function assistantMarker(message) {
+  if (messageRole(message) !== "assistant")
+    return;
+  return {
+    id: messageID(message) ?? null,
+    completedAt: messageCompletedAt(message)
+  };
+}
+function agentFromMessage(message) {
+  if (!message)
+    return;
+  for (const source of [message, message.info]) {
+    if (!isRecord(source))
+      continue;
+    for (const key of ["agent", "mode"]) {
+      const value = source[key];
+      if (typeof value === "string" && value.trim())
+        return value.trim();
+    }
+  }
+  return;
+}
+async function sendContinuation(client, sessionID, prompt, agent) {
   await client.session.promptAsync({
     path: { id: sessionID },
     body: {
+      ...agent ? { agent } : {},
       parts: [{ type: "text", text: prompt }]
     }
   });
@@ -861,6 +1010,235 @@ async function fetchLatestAssistant(client, sessionID) {
   const data = Array.isArray(result.data) ? result.data : [];
   return latestAssistantMessage(data);
 }
+
+class TaskTracker {
+  tasks = new Map;
+  pendingTaskCalls = new Map;
+  latestAssistantBySession = new Map;
+  snapshotIdleHolds = new Map;
+  settledSnapshotIdleTasks = new Set;
+  noteTaskCall(input) {
+    if (typeof input.tool !== "string" || input.tool.toLowerCase() !== "task")
+      return;
+    if (typeof input.sessionID !== "string")
+      return;
+    if (typeof input.callID === "string")
+      this.pendingTaskCalls.set(input.callID, input.sessionID);
+  }
+  noteTaskOutput(input, output) {
+    if (typeof input.tool !== "string" || input.tool.toLowerCase() !== "task")
+      return;
+    const parentSessionID = typeof input.callID === "string" ? this.pendingTaskCalls.get(input.callID) ?? input.sessionID : input.sessionID;
+    if (typeof input.callID === "string")
+      this.pendingTaskCalls.delete(input.callID);
+    if (typeof parentSessionID !== "string")
+      return;
+    const status = parseTaskStatus(output.output);
+    if (!status)
+      return;
+    if (status.state === "running") {
+      this.markRunning(parentSessionID, status.taskID);
+      return;
+    }
+    this.markTerminal(status.taskID, status.state, parentSessionID, { resetReconciled: true });
+  }
+  observeSessionCreated(event) {
+    const info = event.properties?.info;
+    if (!isRecord(info) || typeof info.id !== "string" || typeof info.parentID !== "string")
+      return;
+    this.markRunning(info.parentID, info.id);
+  }
+  observeSessionStatus(sessionID, status) {
+    const task = this.tasks.get(sessionID);
+    if (!task)
+      return;
+    if (status === "busy") {
+      this.markRunning(task.parentSessionID, sessionID);
+      return;
+    }
+    if (status === "idle")
+      this.markTerminal(sessionID, "completed", task.parentSessionID);
+  }
+  observeSessionDeleted(sessionID) {
+    this.tasks.delete(sessionID);
+    for (const task of this.tasks.values()) {
+      if (task.parentSessionID === sessionID)
+        this.tasks.delete(task.taskID);
+    }
+    this.latestAssistantBySession.delete(sessionID);
+    this.clearSnapshotIdleForSession(sessionID);
+  }
+  observeMessages(messages) {
+    for (const message of messages) {
+      const sessionID = sessionIDFromMessage(message);
+      if (!sessionID)
+        continue;
+      const marker = assistantMarker(message);
+      if (marker) {
+        this.observeAssistant(sessionID, marker);
+        continue;
+      }
+      for (const part of message.parts ?? []) {
+        const status = parseTaskStatus(textFromPart(part));
+        if (!status)
+          continue;
+        if (status.state === "running")
+          this.markRunning(sessionID, status.taskID);
+        else
+          this.markTerminal(status.taskID, status.state, sessionID, { resetReconciled: true });
+      }
+    }
+  }
+  observeAssistantMessage(sessionID, message) {
+    const marker = message ? assistantMarker(message) : undefined;
+    if (marker)
+      this.observeAssistant(sessionID, marker);
+  }
+  hasBlockingTasks(parentSessionID) {
+    this.pruneExpiredSnapshotIdleHolds();
+    for (const task of this.tasks.values()) {
+      if (task.parentSessionID !== parentSessionID)
+        continue;
+      if (task.state === "running" || task.terminalUnreconciled)
+        return true;
+    }
+    for (const hold of this.snapshotIdleHolds.values()) {
+      if (hold.parentSessionID === parentSessionID)
+        return true;
+    }
+    return false;
+  }
+  nextSnapshotIdleRetryAt(parentSessionID) {
+    this.pruneExpiredSnapshotIdleHolds();
+    let next = null;
+    for (const hold of this.snapshotIdleHolds.values()) {
+      if (hold.parentSessionID !== parentSessionID)
+        continue;
+      next = next == null ? hold.expiresAt : Math.min(next, hold.expiresAt);
+    }
+    return next;
+  }
+  async refreshLiveChildren(client, parentSessionID) {
+    const session = client.session;
+    if (!session.children || !session.status)
+      return;
+    let childIDs;
+    try {
+      const result = await session.children({ path: { id: parentSessionID } });
+      const data = Array.isArray(result) ? result : Array.isArray(result.data) ? result.data : [];
+      childIDs = data.flatMap((child) => isRecord(child) && typeof child.id === "string" ? [child.id] : []);
+    } catch {
+      return;
+    }
+    if (childIDs.length === 0)
+      return;
+    let statuses;
+    try {
+      const result = await session.status();
+      statuses = isRecord(result) && isRecord(result.data) ? result.data : isRecord(result) ? result : {};
+    } catch {
+      return;
+    }
+    for (const childID of childIDs) {
+      const status = statuses[childID];
+      const statusType = isRecord(status) && typeof status.type === "string" ? status.type : undefined;
+      if (statusType === "busy")
+        this.markRunning(parentSessionID, childID);
+      else if (statusType === "idle") {
+        if (this.tasks.has(childID))
+          this.markTerminal(childID, "completed", parentSessionID);
+        else
+          this.markSnapshotIdle(parentSessionID, childID);
+      }
+    }
+  }
+  markRunning(parentSessionID, taskID) {
+    const existing = this.tasks.get(taskID);
+    this.clearSnapshotIdle(parentSessionID, taskID);
+    this.tasks.set(taskID, {
+      taskID,
+      parentSessionID,
+      state: "running",
+      terminalUnreconciled: false,
+      terminalAt: null,
+      lastAssistantMessageIDAtTerminal: existing?.lastAssistantMessageIDAtTerminal ?? null
+    });
+  }
+  markTerminal(taskID, state, parentSessionID, options = {}) {
+    if (!TASK_TERMINAL_STATES.has(state))
+      return;
+    const existing = this.tasks.get(taskID);
+    const resolvedParentSessionID = existing?.parentSessionID ?? parentSessionID;
+    if (!resolvedParentSessionID)
+      return;
+    this.clearSnapshotIdle(resolvedParentSessionID, taskID);
+    if (existing && TASK_TERMINAL_STATES.has(existing.state) && !existing.terminalUnreconciled && !options.resetReconciled) {
+      return;
+    }
+    this.tasks.set(taskID, {
+      taskID,
+      parentSessionID: resolvedParentSessionID,
+      state,
+      terminalUnreconciled: true,
+      terminalAt: Date.now(),
+      lastAssistantMessageIDAtTerminal: this.latestAssistantBySession.get(resolvedParentSessionID)?.id ?? null
+    });
+  }
+  markSnapshotIdle(parentSessionID, taskID) {
+    const key = this.snapshotIdleKey(parentSessionID, taskID);
+    if (this.settledSnapshotIdleTasks.has(key) || this.snapshotIdleHolds.has(key))
+      return;
+    this.snapshotIdleHolds.set(key, {
+      taskID,
+      parentSessionID,
+      expiresAt: Date.now() + SNAPSHOT_IDLE_HOLD_MS
+    });
+  }
+  clearSnapshotIdle(parentSessionID, taskID) {
+    const key = this.snapshotIdleKey(parentSessionID, taskID);
+    this.snapshotIdleHolds.delete(key);
+    this.settledSnapshotIdleTasks.delete(key);
+  }
+  clearSnapshotIdleForSession(sessionID) {
+    for (const [key, hold] of this.snapshotIdleHolds) {
+      if (hold.taskID === sessionID || hold.parentSessionID === sessionID)
+        this.snapshotIdleHolds.delete(key);
+    }
+    for (const key of this.settledSnapshotIdleTasks) {
+      if (key.startsWith(`${sessionID}\x00`) || key.endsWith(`\x00${sessionID}`)) {
+        this.settledSnapshotIdleTasks.delete(key);
+      }
+    }
+  }
+  pruneExpiredSnapshotIdleHolds(now = Date.now()) {
+    for (const [key, hold] of this.snapshotIdleHolds) {
+      if (hold.expiresAt > now)
+        continue;
+      this.snapshotIdleHolds.delete(key);
+      this.settledSnapshotIdleTasks.add(key);
+    }
+  }
+  snapshotIdleKey(parentSessionID, taskID) {
+    return `${parentSessionID}\x00${taskID}`;
+  }
+  observeAssistant(sessionID, marker) {
+    this.latestAssistantBySession.set(sessionID, marker);
+    for (const task of this.tasks.values()) {
+      if (task.parentSessionID !== sessionID || !task.terminalUnreconciled)
+        continue;
+      if (this.assistantReconcilesTask(task, marker)) {
+        this.tasks.set(task.taskID, { ...task, terminalUnreconciled: false });
+      }
+    }
+  }
+  assistantReconcilesTask(task, marker) {
+    if (marker.id && task.lastAssistantMessageIDAtTerminal && marker.id !== task.lastAssistantMessageIDAtTerminal)
+      return true;
+    if (marker.completedAt != null && task.terminalAt != null && marker.completedAt >= task.terminalAt)
+      return true;
+    return false;
+  }
+}
 async function recordAssistantMessage(sessionID, message, options) {
   if (!message)
     return;
@@ -887,12 +1265,110 @@ ${reminder}`;
 }
 var server = async ({ client }, options) => {
   const autoContinue = options?.auto_continue ?? true;
+  const deferWhileTasksActive = options?.defer_while_tasks_active ?? true;
   const maxAutoTurns = positiveIntegerOrNull2(options?.max_auto_turns) ?? DEFAULT_MAX_AUTO_TURNS;
   const minInterval = positiveIntegerOrNull2(options?.min_continue_interval_seconds) ?? DEFAULT_CONTINUE_INTERVAL_SECONDS;
   const maxPromptFailures = positiveIntegerOrNull2(options?.max_prompt_failures) ?? DEFAULT_MAX_PROMPT_FAILURES;
   const registerCommand = options?.register_command ?? true;
   const commandName = commandNameFromOptions(options);
+  const taskTracker = new TaskTracker;
+  const taskDeferredSessions = new Set;
+  const scheduledContinuations = new Map;
+  const busySessions = new Set;
+  const planAgents = restrictedAgentSet(options);
+  const isPlanAgent = (agent) => typeof agent === "string" && planAgents.has(agent.trim().toLowerCase());
+  async function createGoalFromTool(input, context) {
+    const planningOnly = isPlanAgent(context.agent);
+    const goal = await createGoal(context.sessionID, input.objective, {
+      tokenBudget: input.token_budget ?? options?.default_token_budget ?? null,
+      maxAutoTurns: input.max_auto_turns ?? null,
+      maxDurationSeconds: input.max_duration_seconds ?? options?.max_goal_duration_seconds ?? null,
+      noProgressTokenThreshold: options?.no_progress_token_threshold ?? null,
+      maxNoProgressTurns: options?.max_no_progress_turns ?? null,
+      agent: typeof context.agent === "string" ? context.agent : null,
+      initialStatus: planningOnly ? "paused" : "active"
+    });
+    return JSON.stringify(planningOnly ? { goal, plan_mode_notice: PLAN_MODE_CREATE_NOTICE } : { goal }, null, 2);
+  }
+  async function taskBlockStatus(sessionID) {
+    if (!deferWhileTasksActive)
+      return false;
+    await taskTracker.refreshLiveChildren(client, sessionID);
+    return {
+      blocked: taskTracker.hasBlockingTasks(sessionID),
+      retryAt: taskTracker.nextSnapshotIdleRetryAt(sessionID)
+    };
+  }
+  function scheduleSettledContinuation(sessionID, delayMs = TASK_SETTLE_DELAY_MS) {
+    if (scheduledContinuations.has(sessionID))
+      return;
+    const timer = setTimeout(() => {
+      scheduledContinuations.delete(sessionID);
+      runAutoContinue(sessionID, true);
+    }, Math.max(0, delayMs));
+    const maybeUnref = timer;
+    if (typeof maybeUnref.unref === "function")
+      maybeUnref.unref();
+    scheduledContinuations.set(sessionID, timer);
+  }
+  async function runAutoContinue(sessionID, fromTaskDeferral = false) {
+    if (busySessions.has(sessionID))
+      return;
+    if (activeContinuations.has(sessionID))
+      return;
+    activeContinuations.add(sessionID);
+    try {
+      const latestAssistant = await fetchLatestAssistant(client, sessionID);
+      taskTracker.observeAssistantMessage(sessionID, latestAssistant);
+      const taskStatus = await taskBlockStatus(sessionID);
+      if (taskStatus && taskStatus.blocked) {
+        taskDeferredSessions.add(sessionID);
+        if (taskStatus.retryAt != null)
+          scheduleSettledContinuation(sessionID, taskStatus.retryAt - Date.now());
+        return;
+      }
+      if (busySessions.has(sessionID))
+        return;
+      await recordAssistantMessage(sessionID, latestAssistant, options ?? {});
+      const current = await getGoal(sessionID);
+      if (!current)
+        return;
+      const latestTurnAgent = agentFromMessage(latestAssistant);
+      if (isPlanAgent(current.lastPromptAgent) || isPlanAgent(latestTurnAgent)) {
+        if (current.status === "active")
+          await pauseGoalForPlanMode(sessionID);
+        return;
+      }
+      if (!fromTaskDeferral && taskDeferredSessions.has(sessionID)) {
+        scheduleSettledContinuation(sessionID);
+        return;
+      }
+      taskDeferredSessions.delete(sessionID);
+      const goal = await reserveContinuation(sessionID, maxAutoTurns, minInterval);
+      if (!goal)
+        return;
+      await sendContinuation(client, sessionID, goal.status === "active" ? continuationPrompt(goal) : limitPrompt(goal), goal.lastPromptAgent ?? latestTurnAgent ?? null);
+      await recordContinuationResult(sessionID, "success", maxPromptFailures);
+    } catch (error) {
+      await recordContinuationResult(sessionID, "failure", maxPromptFailures);
+      await client.app?.log?.({
+        body: {
+          service: "opencode-goal-plugin",
+          level: "error",
+          message: "Auto-continue failed",
+          extra: { error: error instanceof Error ? error.message : String(error) }
+        }
+      });
+    } finally {
+      activeContinuations.delete(sessionID);
+    }
+  }
   return {
+    async dispose() {
+      for (const timer of scheduledContinuations.values())
+        clearTimeout(timer);
+      scheduledContinuations.clear();
+    },
     async config(config) {
       if (!registerCommand)
         return;
@@ -915,7 +1391,7 @@ var server = async ({ client }, options) => {
         }
       },
       create_goal: {
-        description: "Create a goal only when explicitly requested by the user or system/developer instructions; do not infer goals from ordinary tasks. Fails if a non-complete goal exists.",
+        description: "Create a goal only when explicitly requested by the user or system/developer instructions; do not infer goals from ordinary tasks. Fails if a non-complete goal exists. While the session is in Plan mode, the goal is recorded as paused and execution requires the user to switch to Build mode.",
         args: {
           objective: z.string().min(1).max(4000).describe("The concrete objective to start pursuing."),
           token_budget: z.number().int().positive().nullable().optional().describe("Optional positive token budget."),
@@ -923,19 +1399,11 @@ var server = async ({ client }, options) => {
           max_duration_seconds: z.number().int().positive().nullable().optional().describe("Optional per-goal duration limit.")
         },
         async execute(args, context) {
-          const input = args;
-          const goal = await createGoal(context.sessionID, input.objective, {
-            tokenBudget: input.token_budget ?? options?.default_token_budget ?? null,
-            maxAutoTurns: input.max_auto_turns ?? null,
-            maxDurationSeconds: input.max_duration_seconds ?? options?.max_goal_duration_seconds ?? null,
-            noProgressTokenThreshold: options?.no_progress_token_threshold ?? null,
-            maxNoProgressTurns: options?.max_no_progress_turns ?? null
-          });
-          return JSON.stringify({ goal }, null, 2);
+          return createGoalFromTool(args, context);
         }
       },
       set_goal: {
-        description: "Set a new goal when the user explicitly asks the agent to formulate and set its own goal. The model should write the objective itself based on the user's explicit request. Fails if a non-complete goal exists.",
+        description: "Set a new goal when the user explicitly asks the agent to formulate and set its own goal. The model should write the objective itself based on the user's explicit request. Fails if a non-complete goal exists. While the session is in Plan mode, the goal is recorded as paused and execution requires the user to switch to Build mode.",
         args: {
           objective: z.string().min(1).max(4000).describe("The model-formulated concrete objective to start pursuing."),
           token_budget: z.number().int().positive().nullable().optional().describe("Optional positive token budget."),
@@ -943,15 +1411,7 @@ var server = async ({ client }, options) => {
           max_duration_seconds: z.number().int().positive().nullable().optional().describe("Optional per-goal duration limit.")
         },
         async execute(args, context) {
-          const input = args;
-          const goal = await createGoal(context.sessionID, input.objective, {
-            tokenBudget: input.token_budget ?? options?.default_token_budget ?? null,
-            maxAutoTurns: input.max_auto_turns ?? null,
-            maxDurationSeconds: input.max_duration_seconds ?? options?.max_goal_duration_seconds ?? null,
-            noProgressTokenThreshold: options?.no_progress_token_threshold ?? null,
-            maxNoProgressTurns: options?.max_no_progress_turns ?? null
-          });
-          return JSON.stringify({ goal }, null, 2);
+          return createGoalFromTool(args, context);
         }
       },
       update_goal_objective: {
@@ -962,8 +1422,13 @@ var server = async ({ client }, options) => {
         },
         async execute(args, context) {
           const input = args;
-          const goal = await updateGoalObjective(context.sessionID, input.objective, input.status ?? "active");
-          return JSON.stringify({ goal }, null, 2);
+          const requested = input.status ?? "active";
+          const planningOnly = requested === "active" && isPlanAgent(context.agent);
+          const goal = await updateGoalObjective(context.sessionID, input.objective, planningOnly ? "paused" : requested, {
+            agent: typeof context.agent === "string" ? context.agent : null,
+            planModePause: planningOnly
+          });
+          return JSON.stringify(planningOnly ? { goal, plan_mode_notice: PLAN_MODE_CREATE_NOTICE } : { goal }, null, 2);
         }
       },
       update_goal: {
@@ -987,13 +1452,16 @@ var server = async ({ client }, options) => {
         }
       },
       update_goal_status: {
-        description: "Pause or resume the current OpenCode goal when the user explicitly asks to pause or resume it.",
+        description: "Pause or resume the current OpenCode goal when the user explicitly asks to pause or resume it. Resuming is not allowed while the session is in Plan mode; the user must switch to Build mode first.",
         args: {
           status: z.enum(["active", "paused"]).describe("active resumes a goal; paused pauses it without clearing it.")
         },
         async execute(args, context) {
           const input = args;
-          const goal = await setGoalStatus(context.sessionID, input.status);
+          if (input.status === "active" && isPlanAgent(context.agent)) {
+            throw new Error("cannot resume the goal while the session is in Plan mode; ask the user to switch to Build mode and resume the goal from there");
+          }
+          const goal = await setGoalStatus(context.sessionID, input.status, typeof context.agent === "string" ? context.agent : null);
           return JSON.stringify({ goal }, null, 2);
         }
       },
@@ -1005,7 +1473,21 @@ var server = async ({ client }, options) => {
         }
       }
     },
+    async "tool.execute.before"(input) {
+      taskTracker.noteTaskCall(input);
+    },
+    async "tool.execute.after"(input, output) {
+      taskTracker.noteTaskOutput(input, output);
+    },
+    async "chat.message"(input, output) {
+      const sessionID = typeof input?.sessionID === "string" ? input.sessionID : output.message?.sessionID;
+      const agent = typeof input?.agent === "string" && input.agent.trim() ? input.agent : output.message?.agent;
+      if (typeof sessionID !== "string" || typeof agent !== "string" || !agent.trim())
+        return;
+      await recordPromptAgent(sessionID, agent);
+    },
     async "experimental.chat.messages.transform"(input, output) {
+      taskTracker.observeMessages(output.messages);
       const sessionID = "sessionID" in input && typeof input.sessionID === "string" ? input.sessionID : output.messages.find((message) => typeof message.info.sessionID === "string")?.info.sessionID;
       if (!sessionID)
         return;
@@ -1015,7 +1497,8 @@ var server = async ({ client }, options) => {
     async "experimental.chat.system.transform"(input, output) {
       if (typeof input.sessionID !== "string")
         return;
-      mergeSystemReminder(output, systemReminder(await getGoal(input.sessionID)));
+      const goal = await getGoal(input.sessionID);
+      mergeSystemReminder(output, systemReminder(goal, { planningOnly: isPlanAgent(goal?.lastPromptAgent) }));
     },
     async "experimental.session.compacting"(input, output) {
       const goal = await getGoal(input.sessionID);
@@ -1030,38 +1513,39 @@ var server = async ({ client }, options) => {
     },
     async event({ event }) {
       const sessionID = sessionIDFromEvent(event);
+      const eventType = event.type;
+      if (eventType === "session.created") {
+        taskTracker.observeSessionCreated(event);
+      }
+      if (sessionID && eventType === "session.status") {
+        const status = event.properties?.status;
+        if (isRecord(status) && typeof status.type === "string") {
+          if (status.type === "busy")
+            busySessions.add(sessionID);
+          if (status.type === "idle")
+            busySessions.delete(sessionID);
+          taskTracker.observeSessionStatus(sessionID, status.type);
+        }
+      }
+      if (sessionID && eventType === "session.idle") {
+        busySessions.delete(sessionID);
+        taskTracker.observeSessionStatus(sessionID, "idle");
+      }
+      if (sessionID && eventType === "session.deleted") {
+        busySessions.delete(sessionID);
+        taskTracker.observeSessionDeleted(sessionID);
+      }
       if (sessionID && event.type === "message.updated") {
         const props = event.properties ?? {};
         const message = [props.info, props.message].find((value) => value && typeof value === "object");
+        taskTracker.observeAssistantMessage(sessionID, message);
         await recordAssistantMessage(sessionID, message, options ?? {});
       }
       if (!autoContinue || !isIdleEvent(event))
         return;
       if (!sessionID)
         return;
-      if (activeContinuations.has(sessionID))
-        return;
-      activeContinuations.add(sessionID);
-      try {
-        await recordAssistantMessage(sessionID, await fetchLatestAssistant(client, sessionID), options ?? {});
-        const goal = await reserveContinuation(sessionID, maxAutoTurns, minInterval);
-        if (!goal)
-          return;
-        await sendContinuation(client, sessionID, goal.status === "active" ? continuationPrompt(goal) : limitPrompt(goal));
-        await recordContinuationResult(sessionID, "success", maxPromptFailures);
-      } catch (error) {
-        await recordContinuationResult(sessionID, "failure", maxPromptFailures);
-        await client.app?.log?.({
-          body: {
-            service: "opencode-goal-plugin",
-            level: "error",
-            message: "Auto-continue failed",
-            extra: { error: error instanceof Error ? error.message : String(error) }
-          }
-        });
-      } finally {
-        activeContinuations.delete(sessionID);
-      }
+      await runAutoContinue(sessionID);
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prevalentware/opencode-goal-plugin",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "OpenCode goal plugin that adds Codex-style long-running goal mode, /goal commands, persistence, and TUI status for AI coding agents.",
   "keywords": [
     "opencode",