opencode-discipline 0.2.1 → 0.3.0

package/README.md

@@ -28,6 +28,39 @@ It provides:
 bun run build
 ```
 
+## Notifications (optional)
+
+On startup, the plugin shows a small in-app toast: `opencode-discipline vX is running`.
+
+You can enable milestone notifications for key planning events:
+
+- `Need your answers` (agent question prompts)
+- `Plan is ready` (Wave 4 handoff stage)
+- `OpenCode has finished` (Build agent completion)
+
+Set one environment variable before running OpenCode:
+
+```bash
+export OPENCODE_DISCIPLINE_NOTIFY=metadata
+```
+
+Supported modes:
+
+- `off`
+- `metadata` (emit structured notification metadata)
+- `os` (default; desktop notification via `osascript`/`notify-send`/PowerShell)
+- `both` (metadata + OS)
+
+Optional custom command hook:
+
+```bash
+export OPENCODE_DISCIPLINE_NOTIFY_COMMAND='terminal-notifier -title "{title}" -message "{message}"'
+```
+
+Template variables: `{event}`, `{title}`, `{message}`, `{sessionID}`.
+
+Build completion notifications are emitted automatically when OpenCode reports the Build session as idle (`session.idle`).
+
 ## Test
 
 ```bash

package/agents/README.md

@@ -8,7 +8,7 @@ This package ships eleven agent definitions for disciplined plan-first execution
 | `build` | `anthropic/claude-opus-4-6` | primary | Executes approved plans phase-by-phase with verification gates |
 | `analyzer` | `openai/gpt-5.4` | agent | Traces control flow, data flow, and system interactions from file lists into step-by-step explanations |
 | `oracle` | `openai/gpt-5.4` | subagent | Read-only architecture and tradeoff advisor |
-| `librarian` | `openai/gpt-5.2` | subagent | Read-only research and documentation specialist |
+| `librarian` | `openai/gpt-5.2` | subagent | External knowledge specialist — docs, best practices, implementation guidance |
 | `reviewer` | `openai/gpt-5.4` | subagent | Read-only quality critic for plans and code |
 | `designer` | `anthropic/claude-sonnet-4-6` | subagent | Read-only UI/UX and accessibility advisor |
 | `deep` | `openai/gpt-5.3-codex` | subagent | Advanced implementation subagent for complex coding work |
@@ -43,7 +43,11 @@ User overrides take precedence per field; non-overridden fields use the plugin d
 ## Delegation flow
 
 ```text
-plan -> explore/explore-deep/analyzer/librarian -> oracle/reviewer -> accept_plan
+Explorer = codebase search ("what exists?")
+Librarian = external knowledge ("what should we do?")
+Golden rule: Explorer first, Librarian second.
+
+plan -> explore/explore-deep -> analyzer -> librarian (if needed) -> oracle -> accept_plan
 accept_plan -> build
-build -> explore/explore-deep/analyzer/librarian/oracle -> reviewer -> done
+build -> explore/explore-deep -> analyzer -> librarian (if needed) -> oracle -> reviewer -> done
 ```

package/agents/analyzer.md

@@ -31,7 +31,6 @@ permission:
     "*": deny
     "explore": allow
     "explore-deep": allow
-    "librarian": allow
 ---
 
 You are the Analyzer — a systems-thinking agent that turns raw file lists into clear, actionable understanding. Where explorers find *what* exists, you explain *how* it works.

package/agents/build.md

@@ -37,9 +37,10 @@ If the user references a plan file, or if `tasks/plans/` contains a recent plan:
 
 1. **Read the plan first.** Understand all phases, dependencies, and verification criteria before writing any code.
 2. **Work phase by phase.** Complete Phase 1 entirely, run its verification step, confirm it passes, then move to Phase 2. Never jump ahead.
-3. **Run verification after each phase.** Execute the exact command from the plan's "Verify" field. If it fails, fix it before moving on.
-4. **Check off items as you go.** Update the plan file: change `- [ ]` to `- [x]` for completed items.
-5. **If a phase fails verification twice**, stop. Tell the user what's failing and suggest switching to Plan agent to re-plan the remaining phases.
+3. **Read files on-demand, not in bulk.** The plan already has specific file paths and line numbers. Read each file as you work on it — do NOT spawn subagents to pre-gather all files upfront. That wastes your context window on code you won't touch for several phases.
+4. **Run verification after each phase.** Execute the exact command from the plan's "Verify" field. If it fails, fix it before moving on.
+5. **Check off items as you go.** Update the plan file: change `- [ ]` to `- [x]` for completed items.
+6. **If a phase fails verification twice**, stop. Tell the user what's failing and suggest switching to Plan agent to re-plan the remaining phases.
 
 ## When no plan exists
 
@@ -49,17 +50,20 @@ Work directly on the task. For non-trivial work (3+ files or architectural chang
 
 Keep your context window clean. You are an implementer, not a researcher.
 
+**Golden rule: Explorer first, Librarian second. Never the opposite.**
+- Explorer answers: "what exists in the codebase?"
+- Librarian answers: "what should we do?" (external docs, best practices)
+
 **Delegate to @explore when:**
-- You need a quick, simple file or pattern lookup (1-2 files, specific pattern)
+- You need to understand what exists in the codebase — file structure, function signatures, types, patterns
 - You need to check what imports or depends on a file before changing it
-- You already know roughly where to look and just need the exact path
+- **This is your default for any codebase research.** Explorer returns structured summaries, not raw file dumps.
 
 **Delegate to @librarian when:**
-- You need to understand existing code before making changes — send the research question, librarian handles the rest (it spawns explorers internally, reads files, returns organized report)
-- You need full contents of multiple files gathered and organized
-- You need external documentation (library APIs, framework docs)
-- You need to find reference implementations or examples
-- **This is your default for any research involving 3+ files.** One spawn, one response.
+- You need external documentation — library APIs, framework guides, migration docs
+- You need best practices or recommended patterns from outside the codebase
+- You need to validate an approach against official docs
+- **Librarian does NOT search the codebase.** It only fetches external knowledge. If it needs codebase context, it delegates to Explorer internally.
 
 **Delegate to @analyzer when:**
 - You need to understand *how* a system works, not just *what files* exist
@@ -76,9 +80,9 @@ Keep your context window clean. You are an implementer, not a researcher.
 - You've made changes touching 3+ files and want a sanity check
 
 **Delegation pattern for understanding a subsystem:**
-1. @librarian → "gather all code related to X" → returns file paths + organized contents (it spawns explore internally)
-2. @analyzer → "explain how X works based on this" → returns step-by-step flow analysis
-Two spawns max. Never send multi-file research to @explore directly — it's a locator, not a reader.
+1. @explore → "find all code related to X" → returns file paths + structured summaries
+2. @analyzer → "explain how X works" → returns step-by-step flow analysis
+3. @librarian (only if needed) → "what do the docs say about Y?" → returns external guidance
 
 **DO NOT delegate when:**
 - The task is straightforward and you already have the context

package/agents/explore.md

@@ -1,5 +1,5 @@
 ---
-description: Fast codebase search. Finds files, patterns, and structure quickly. Cheap and parallel-friendly.
+description: Fast codebase search. Finds files, patterns, and structure quickly. Returns structured snippets — enough context to act on. Cheap and parallel-friendly.
 model: anthropic/claude-haiku-4-5
 temperature: 0
 mode: subagent
@@ -27,28 +27,63 @@ permission:
     "echo *": allow
 ---
 
-You are a fast codebase explorer. Your job is to **find files and locate patterns** as quickly as possible. You return file paths, line numbers, and brief snippets — never full file dumps.
+You are the codebase explorer — the **internal search engine** for the agent suite. You answer one question: **"what exists in this codebase?"**
+
+You find files, read key sections, and return structured context. Your output gives callers enough to understand the code without reading every file themselves.
+
+## Your role in the agent suite
+
+```
+Explorer → "what exists in your code" (you)
+Librarian → "what should you do about it" (external docs)
+Analyzer → "how does it work step-by-step" (flow tracing)
+```
 
 ## How you work
 
-1. Start with project structure — `ls`, file tree, config files
-2. Use Glob for file patterns, Grep for content search
-3. Read just enough to confirm relevance — a few key lines, not entire files
-4. Return concise findings with exact file paths and line numbers
+1. **Find files** — use Glob for patterns, Grep for content search, `ls` for structure
+2. **Read key sections** — once you find relevant files, read enough to extract signatures, types, and key logic
+3. **Return structured context** — file paths, exports, function signatures, relevant code snippets
 
-## Scope guard
+## Output format
+
+```
+## Codebase: {what was searched for}
+
+### Files found
+- `path/to/file.ts` (N lines) — {role}
+  - Exports: `functionA(arg: Type): ReturnType`, `ComponentB`, `TypeC`
+  - Key logic: {what the file does, 1-2 sentences}
+  - Relevant lines: L42-L58 ({what's there})
+
+### Structure
+- {how these files relate to each other}
+- {directory organization pattern}
 
-You are a **locator**, not a researcher. Your output is file paths and line numbers, not full file contents.
+### Patterns observed
+- {naming conventions, error handling, state management approach}
+```
+
+### What to return
+
+**Always include:** file paths, line numbers, function/component signatures, type definitions, export lists, key conditional logic (2-5 lines max per snippet).
+
+**Never include:** full file contents, entire function bodies, JSX markup, import blocks, boilerplate. The caller doesn't need 200 lines — they need to know the shape.
+
+**Exception:** Files under 30 lines (configs, migrations, small utilities) — include verbatim since summarizing would be longer.
+
+## Scope guard
 
-If the caller asks you to return full contents of many files or explain how a system works, still do your part — find the file paths — but flag it:
+You are a **codebase locator and summarizer**. You search the repo and return structured context.
 
-> Found 8 relevant files: [paths]. Full content reading should go through @librarian, flow analysis through @analyzer.
+- If the caller asks for external docs or best practices → tell them to use @librarian
+- If the caller asks for step-by-step flow analysis → return the file paths and tell them to use @analyzer
+- If the search is too complex for you (cross-cutting dependencies, multi-step reasoning) → say so and recommend @explore-deep
 
 ## Rules
 
 - NEVER write or edit files
-- NEVER dump full file contents — return paths, line numbers, and brief context
+- NEVER return full file contents — return structured summaries with key snippets
 - Be fast — breadth first, then drill into relevant areas
 - Return structured results the caller can act on immediately
 - If you can't find what's needed, say so
-- If the request is too heavy for you, say so and recommend the right agent

package/agents/librarian.md

@@ -1,16 +1,16 @@
 ---
-description: Research specialist. Gathers context from codebase, external docs, and reference implementations before work begins. Returns structured findings.
+description: External knowledge specialist. Fetches documentation, best practices, and implementation guidance from outside the codebase. Pairs with Explorer — Explorer finds what exists in your code, Librarian finds what you should do.
 model: openai/gpt-5.2
 temperature: 0
 mode: subagent
 color: "#1D9E75"
 tools:
-  read: true
+  read: false
   write: false
   edit: false
   bash: true
-  glob: true
-  grep: true
+  glob: false
+  grep: false
   fetch: true
   task: true
 permission:
@@ -18,61 +18,71 @@ permission:
     "*": ask
     "rtk *": allow
     "echo *": allow
+  task:
+    "*": deny
+    "explore": allow
+    "explore-deep": allow
 ---
 
-You are the research specialist and **primary context gatherer** for the agent suite. When a caller needs to understand existing code before planning or building, you're the one they send the request to. You never implement.
+You are the external knowledge specialist. You find documentation, best practices, patterns, and implementation guidance from **outside the codebase**. You never search the codebase directly — that's Explorer's job.
 
-## How you work
+## Your role in the agent suite
 
-You own the full research chain. When given a research task:
+```
+Explorer → "what exists in your code"
+Librarian → "what should you do about it"
+```
 
-1. **Locate files** — delegate to @explore or @explore-deep to find relevant file paths quickly. Don't search manually when an explorer can do it faster.
-2. **Read the code** — once you have file paths, read the full contents yourself using Read. You're the one who ingests and organizes the code, not the explorer.
-3. **Fetch external docs** if needed — library documentation, API references, framework guides.
-4. **Return a structured report** — the caller gets one clean response with everything they need.
+When a caller needs context before planning or building, the flow is:
+1. **Explorer** scans the codebase → returns file paths, snippets, structure
+2. **You** take that context and find external knowledge → docs, patterns, best practices
+3. **Caller** gets both reality (Explorer) and direction (Librarian)
 
-### Why this matters for token efficiency
+## How you work
 
-The caller (often Opus) is expensive. By handling the full locate → read → organize chain internally, you save the caller from multiple round-trips. They spawn you once, get one structured response back. That's the goal.
+1. **Receive context** — the caller (or Explorer output) tells you what the codebase looks like. If you need codebase context and don't have it, delegate to @explore first.
+2. **Fetch external knowledge** — library docs, framework guides, API references, best practice articles, migration guides.
+3. **Validate patterns** — cross-reference what the codebase does with what the docs recommend.
+4. **Return actionable guidance** — not just "here's the docs" but "here's what you should do, based on the docs and your codebase."
 
 ## Output format
 
 ```
-## Research: {topic}
+## Guidance: {topic}
 
-### Key findings
-- {finding 1 — specific, with file paths or URLs}
-- {finding 2}
-- {finding 3}
+### Context received
+- {brief summary of what Explorer/caller told you about the codebase}
 
-### Files gathered
-- `path/to/file.ts` — {role, why it matters}
-  {full contents or key sections, depending on what the caller asked for}
+### Recommended approach
+- {concrete recommendation with reasoning}
+- {alternative if applicable}
 
-### Patterns observed
-- {how the codebase currently handles this pattern}
-- {naming conventions, error handling style, test patterns}
+### Documentation references
+- {URL or source} — {key takeaway relevant to this task}
+- {URL or source} — {key takeaway}
 
-### External references
-- {URL} — {what it says that's relevant}
+### Implementation patterns
+- {pattern name}: {how to apply it, with code snippets if helpful}
+- {anti-pattern to avoid}: {why, what to do instead}
 
-### Recommendations
-- {concrete suggestion based on findings}
-- {alternative approach if applicable}
+### Caveats
+- {version-specific gotchas, breaking changes, deprecations}
+- {edge cases the docs mention}
 ```
 
-## When to delegate internally
-
-- **@explore** — "find files matching X pattern" — fast, cheap, returns paths
-- **@explore-deep** — complex cross-cutting searches, dependency tracing across many directories
+## When to delegate to Explorer
 
-You read the files yourself after getting paths back. Never ask explorers to return full file contents.
+If the caller asks you a question that requires codebase knowledge you don't have:
+- Delegate to @explore — "find files related to X" or "what pattern does the codebase use for Y"
+- Wait for Explorer's response, then combine it with your external knowledge
+- Never guess about what's in the codebase — either you were told, or you ask Explorer
 
 ## Rules
 
-- NEVER write or modify any files
-- NEVER speculate when you can verify — always check the code
-- Be specific — file paths, line numbers, function names. Not "the auth module."
-- Keep output concise. The caller will read this and act on it — don't pad.
-- If you can't find what's needed, say so. Don't fabricate.
-- If the caller asks for flow analysis (how does X work step-by-step), gather the files and tell them to send your report to @analyzer for flow tracing.
+- NEVER read, write, or modify codebase files directly — you have no file tools
+- NEVER guess about codebase structure — if you need to know, delegate to @explore
+- ALWAYS cite your sources — URLs, doc versions, specific sections
+- Be specific and actionable — "use `middleware()` from v4.2+" not "check the docs"
+- Keep output concise. Your output lands in an expensive model's context window.
+- If you can't find relevant external docs, say so. Don't fabricate references.
+- If the caller asks for codebase analysis (how does X work?), tell them to use @explore or @analyzer instead — that's not your job.

package/agents/plan.md

@@ -61,16 +61,18 @@ When a user describes work, enter interview mode. Ask focused questions to elimi
 - Are there existing patterns in the codebase to follow or break from?
 
 While interviewing:
-- Delegate to @explore for quick, simple lookups (1-2 files, specific pattern)
-- Delegate to @librarian for any research involving 3+ files — it spawns explorers internally, reads the code, and returns one organized report. **This is your default for feature planning research.**
+- Delegate to @explore for codebase research — file structure, function signatures, types, patterns. **This is your default for understanding what exists.**
+- Delegate to @librarian for external knowledge — library docs, best practices, migration guides. **Librarian does NOT search the codebase.**
 - Delegate to @analyzer to understand how existing systems work (control flow, data flow, interactions)
 - Do NOT proceed to planning until requirements are clear
 - If the user says "just plan it" or "skip questions," ask the 2 most critical questions only, then proceed
 
+**Golden rule: Explorer first, Librarian second. Never the opposite.**
+
 **Delegation pattern for feature planning:**
-1. @librarian → "gather all code related to X" → returns organized file contents (handles exploration internally)
+1. @explore → "find all code related to X" → returns file paths + structured summaries
 2. @analyzer → "explain how X works" → returns step-by-step flow analysis
-Two spawns max. Never send multi-file research to @explore directly.
+3. @librarian (only if needed) → "what do the docs say about Y?" → returns external guidance
 
 ### Wave 2: Gap analysis (mandatory)
 

package/dist/index.js

@@ -6915,8 +6915,9 @@ var require_public_api = __commonJS((exports) => {
 });
 
 // src/index.ts
-import { accessSync, constants, existsSync as existsSync2 } from "fs";
+import { accessSync, constants, existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
 import { basename as basename2, dirname, relative, resolve as resolve2 } from "path";
+import { spawn } from "child_process";
 import { fileURLToPath } from "url";
 
 // node_modules/@opencode-ai/plugin/node_modules/zod/v4/classic/external.js
@@ -19513,6 +19514,9 @@ class WaveStateManager {
     if (!state) {
       throw new Error(`No active plan found for session '${sessionID}'.`);
     }
+    if (state.accepted) {
+      throw new Error("Plan has already been accepted. No further wave advances are needed. The planning session is complete.");
+    }
     if (state.wave >= 4) {
       throw new Error("Wave is already at 4 and cannot be advanced further.");
     }
@@ -19582,6 +19586,29 @@ class WaveStateManager {
     this.persist(nextState);
     return nextState;
   }
+  isAcceptedBuildSession(sessionID) {
+    for (const state of this.states.values()) {
+      if (state.acceptedBySessionID === sessionID) {
+        return true;
+      }
+    }
+    if (!existsSync(this.stateDir)) {
+      return false;
+    }
+    const entries = readdirSync2(this.stateDir).filter((entry) => entry.endsWith(".json"));
+    for (const entry of entries) {
+      try {
+        const path = join(this.stateDir, entry);
+        const parsed = JSON.parse(readFileSync2(path, "utf8"));
+        if (parsed.acceptedBySessionID === sessionID) {
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+    return false;
+  }
   persist(state) {
     this.ensureDir();
     const filePath = join(this.stateDir, `${state.planName}.json`);
@@ -19624,6 +19651,155 @@ var WAVE_NEXT_STEPS = {
   3: "writing the plan file",
   4: "plan review and refinement"
 };
+var PLUGIN_DISPLAY_NAME = "opencode-discipline";
+var startupToastShown = false;
+function parseNotificationMode(raw) {
+  const value = raw?.trim().toLowerCase();
+  if (!value) {
+    return "os";
+  }
+  if (value === "off" || value === "0" || value === "false" || value === "disabled") {
+    return "off";
+  }
+  if (value === "metadata") {
+    return "metadata";
+  }
+  if (value === "both" || value === "all") {
+    return "both";
+  }
+  return "os";
+}
+function readPluginVersion(pluginDir) {
+  try {
+    const packageJsonPath = resolve2(pluginDir, "../package.json");
+    const packageJson = JSON.parse(readFileSync3(packageJsonPath, "utf8"));
+    return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function showStartupToast(client, directory, version2) {
+  if (startupToastShown) {
+    return;
+  }
+  const tuiApi = client.tui;
+  if (!tuiApi || typeof tuiApi.showToast !== "function") {
+    return;
+  }
+  try {
+    await tuiApi.showToast({
+      query: { directory },
+      body: {
+        title: "Discipline Plugin",
+        message: `${PLUGIN_DISPLAY_NAME} v${version2} is running`,
+        variant: "info",
+        duration: 3000
+      }
+    });
+    startupToastShown = true;
+  } catch {}
+}
+function escapeAppleScriptString(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', "\\\"");
+}
+function escapePowerShellString(value) {
+  return value.replaceAll("'", "''");
+}
+
+class NotificationManager {
+  mode;
+  commandTemplate;
+  sentKeys = new Map;
+  constructor() {
+    this.mode = parseNotificationMode(process.env.OPENCODE_DISCIPLINE_NOTIFY);
+    this.commandTemplate = process.env.OPENCODE_DISCIPLINE_NOTIFY_COMMAND?.trim();
+  }
+  notify(input) {
+    if (this.mode === "off") {
+      return;
+    }
+    if (this.isSent(input.sessionID, input.dedupeKey)) {
+      return;
+    }
+    this.markSent(input.sessionID, input.dedupeKey);
+    if (this.mode === "metadata" || this.mode === "both") {
+      this.emitMetadata(input);
+    }
+    if (this.mode === "os" || this.mode === "both") {
+      this.emitOsNotification(input);
+    }
+  }
+  isSent(sessionID, key) {
+    const keys = this.sentKeys.get(sessionID);
+    return keys?.has(key) ?? false;
+  }
+  markSent(sessionID, key) {
+    const keys = this.sentKeys.get(sessionID) ?? new Set;
+    keys.add(key);
+    this.sentKeys.set(sessionID, keys);
+  }
+  emitMetadata(input) {
+    if (!input.toolContext || typeof input.toolContext !== "object") {
+      return;
+    }
+    const maybeMetadata = input.toolContext.metadata;
+    if (typeof maybeMetadata !== "function") {
+      return;
+    }
+    try {
+      maybeMetadata({
+        type: "discipline.notification",
+        event: input.event,
+        title: input.title,
+        message: input.message,
+        sessionID: input.sessionID,
+        createdAt: new Date().toISOString()
+      });
+    } catch {}
+  }
+  emitOsNotification(input) {
+    if (this.commandTemplate) {
+      const command = this.commandTemplate.replaceAll("{event}", input.event).replaceAll("{title}", input.title).replaceAll("{message}", input.message).replaceAll("{sessionID}", input.sessionID);
+      this.spawnDetached(process.platform === "win32" ? "cmd.exe" : "sh", process.platform === "win32" ? ["/d", "/s", "/c", command] : ["-lc", command]);
+      return;
+    }
+    if (process.platform === "darwin") {
+      const script = `display notification "${escapeAppleScriptString(input.message)}" with title "${escapeAppleScriptString(input.title)}"`;
+      this.spawnDetached("osascript", ["-e", script]);
+      return;
+    }
+    if (process.platform === "linux") {
+      this.spawnDetached("notify-send", [input.title, input.message]);
+      return;
+    }
+    if (process.platform === "win32") {
+      const script = [
+        "Add-Type -AssemblyName System.Windows.Forms",
+        "$notify = New-Object System.Windows.Forms.NotifyIcon",
+        "$notify.Icon = [System.Drawing.SystemIcons]::Information",
+        "$notify.BalloonTipTitle = '",
+        escapePowerShellString(input.title),
+        "'",
+        "$notify.BalloonTipText = '",
+        escapePowerShellString(input.message),
+        "'",
+        "$notify.Visible = $true",
+        "$notify.ShowBalloonTip(4000)"
+      ].join(" ");
+      this.spawnDetached("powershell", ["-NoProfile", "-Command", script]);
+    }
+  }
+  spawnDetached(command, args) {
+    try {
+      const child = spawn(command, args, {
+        stdio: "ignore",
+        detached: true
+      });
+      child.on("error", () => {});
+      child.unref();
+    } catch {}
+  }
+}
 function hasStringProp(obj, key) {
   return key in obj && typeof obj[key] === "string";
 }
@@ -19639,6 +19815,41 @@ function extractSessionID(result) {
   }
   return;
 }
+function extractSessionIDFromHookInput(input) {
+  if (!input || typeof input !== "object") {
+    return;
+  }
+  if (hasStringProp(input, "sessionID")) {
+    return input.sessionID;
+  }
+  if (hasStringProp(input, "id")) {
+    return input.id;
+  }
+  const value = input;
+  const path = value.path;
+  if (path && typeof path === "object" && hasStringProp(path, "id")) {
+    return path.id;
+  }
+  const session = value.session;
+  if (session && typeof session === "object" && hasStringProp(session, "id")) {
+    return session.id;
+  }
+  return;
+}
+function extractAgentFromHookInput(input) {
+  if (!input || typeof input !== "object") {
+    return;
+  }
+  if (hasStringProp(input, "agent")) {
+    return input.agent.toLowerCase();
+  }
+  const value = input;
+  const session = value.session;
+  if (session && typeof session === "object" && hasStringProp(session, "agent")) {
+    return session.agent.toLowerCase();
+  }
+  return;
+}
 function getWaveLabel(wave) {
   return WAVE_NAMES[wave];
 }
@@ -19661,6 +19872,7 @@ function isBlockedEnvRead(filePath) {
   return fileName.startsWith(".env.");
 }
 function buildWaveStateSystemBlock(wave, planName) {
+  const advanceGuidance = wave === 1 ? "Call `advance_wave` only after Wave 1 interview + checklist work is complete." : wave === 2 ? "Call `advance_wave` only after the Wave 2 Oracle check has completed and gap analysis is done." : wave === 3 ? "Call `advance_wave` only after the plan file is written and Wave 3 is complete." : "Do not call `advance_wave` again unless you are truly done with Wave 4 and ready for handoff decisions.";
   return [
     "## \uD83D\uDD12 Discipline Plugin \u2014 Wave State",
     "",
@@ -19674,7 +19886,7 @@ function buildWaveStateSystemBlock(wave, planName) {
     "- Wave 3 (Plan Generation): NOW write the plan to tasks/plans/{planName}.md using the structured template.",
     "- Wave 4 (Review): Self-review the plan. Delegate to @oracle for high-stakes decisions. Edit the plan if needed.",
     "",
-    `**You are in Wave ${wave}. Call \`advance_wave\` to move to the next wave.**`,
+    `**You are in Wave ${wave}.** ${advanceGuidance}`,
     "**Writing to tasks/plans/*.md is BLOCKED until Wave 3.**"
   ].join(`
 `);
@@ -19684,7 +19896,8 @@ function buildWave2OraclePrompt() {
     "## MANDATORY: Wave 2 Oracle Check",
     "Before you can advance to Wave 3, delegate to `@oracle` once for a gap-analysis sanity check.",
     'Use the Task tool with `subagent_type: "oracle"` and summarize the result in your analysis.',
-    "Wave 2 -> 3 is enforced: `advance_wave` will fail until this Oracle check is completed."
+    "Wave 2 -> 3 is enforced: `advance_wave` will fail until this Oracle check is completed.",
+    "Do NOT retry `advance_wave` until the Oracle task returns successfully."
   ].join(`
 `);
 }
@@ -19698,6 +19911,21 @@ function buildPlanReadOnlyReminder() {
   ].join(`
 `);
 }
+function buildPostAcceptPrompt(planName) {
+  const planPath = `tasks/plans/${planName}.md`;
+  return [
+    "## Discipline Plugin \u2014 Plan Accepted",
+    "",
+    `The plan \`${planPath}\` has been accepted and the planning session is complete.`,
+    "",
+    "**You are DONE. Do not call any more tools. Do not call advance_wave. Do not take further action.**",
+    "",
+    "Tell the user the plan is accepted and ready for a Build agent to execute.",
+    "If the automatic Build session handoff succeeded, confirm that.",
+    "If it fell back to manual, tell the user to switch to the Build agent."
+  ].join(`
+`);
+}
 function buildPlanHandoffPrompt(planName) {
   const planPath = `tasks/plans/${planName}.md`;
   return [
@@ -19890,6 +20118,25 @@ async function handleCompacting(ctx, input, output) {
   }
   output.context.push(buildCompactionContext(state));
 }
+async function handleSessionIdle(ctx, input, _output) {
+  const sessionID = extractSessionIDFromHookInput(input);
+  if (!sessionID) {
+    return;
+  }
+  const agent = extractAgentFromHookInput(input);
+  const isBuildIdle = agent === "build" || ctx.manager.isAcceptedBuildSession(sessionID);
+  if (!isBuildIdle) {
+    return;
+  }
+  ctx.notifications.notify({
+    sessionID,
+    event: "coding_complete",
+    title: "OpenCode has finished",
+    message: "The Build agent is done and OpenCode is ready for input.",
+    dedupeKey: "session-idle-coding-complete",
+    toolContext: input
+  });
+}
 async function handleSystemTransform(ctx, input, output) {
   const sessionID = input.sessionID;
   const state = sessionID ? ctx.manager.getState(sessionID) : undefined;
@@ -19898,19 +20145,32 @@ async function handleSystemTransform(ctx, input, output) {
     return;
   }
   output.system.push(buildWaveStateSystemBlock(state.wave, state.planName));
+  if (state.accepted) {
+    output.system.push(buildPostAcceptPrompt(state.planName));
+    return;
+  }
   if (isPlanContext(input.agent) && state.wave < 3) {
     output.system.push(buildPlanReadOnlyReminder());
   }
-  if (isPlanContext(input.agent) && state.wave === 2 && !state.accepted && !state.oracleReviewedAt) {
+  if (isPlanContext(input.agent) && state.wave === 2 && !state.oracleReviewedAt) {
     output.system.push(buildWave2OraclePrompt());
   }
-  if (state.wave === 4 && !state.accepted) {
+  if (state.wave === 4) {
     const planFilePath = resolve2(ctx.worktree, `tasks/plans/${state.planName}.md`);
     if (existsSync2(planFilePath)) {
+      if (sessionID) {
+        ctx.notifications.notify({
+          sessionID,
+          event: "plan_ready",
+          title: "Plan is ready",
+          message: `tasks/plans/${state.planName}.md is ready for handoff review.`,
+          dedupeKey: "wave-4-plan-ready"
+        });
+      }
       output.system.push(buildPlanHandoffPrompt(state.planName));
     }
   }
-  if (sessionID && isPlanContext(input.agent) && !state.accepted) {
+  if (sessionID && isPlanContext(input.agent)) {
     const nudgeState = getOrCreateTodoNudgeState(ctx, sessionID);
     const todos = await readSessionTodos(ctx.client, ctx.directory, sessionID);
     const hasSeededTodo = todos !== undefined && hasPlanningTodoChecklist(todos, state.planName);
@@ -19947,6 +20207,19 @@ async function handleToolExecuteBefore(ctx, input, output) {
   }
 }
 async function handleToolExecuteAfter(ctx, input, output) {
+  if (input.tool === "question") {
+    const condensed = output.output.replace(/\s+/g, " ").trim();
+    const questionText = condensed.length > 180 ? `${condensed.slice(0, 177)}...` : condensed;
+    ctx.notifications.notify({
+      sessionID: input.sessionID,
+      event: "need_answers",
+      title: "Need your answers",
+      message: questionText || "The agent asked a question and is waiting for your answer.",
+      dedupeKey: `question-${input.callID}`,
+      toolContext: output
+    });
+    return;
+  }
   const state = ctx.manager.getState(input.sessionID);
   if (!state || state.accepted) {
     return;
@@ -20006,9 +20279,31 @@ function createAdvanceWaveTool(ctx) {
         }
         const waveName = WAVE_NAMES[state.wave];
         const nextStep = WAVE_NEXT_STEPS[state.wave];
-        return `Wave ${state.wave} (${waveName}) started for plan '${state.planName}'. You may now proceed with ${nextStep}.`;
+        const advanceWhen = state.wave === 1 ? "Call `advance_wave` only after interview + checklist work is complete." : state.wave === 2 ? "Call `advance_wave` only after Oracle review is complete and gap analysis is done." : state.wave === 3 ? "Call `advance_wave` only after the plan file is written." : "Stay in Wave 4 for plan review/handoff; call `advance_wave` only if explicitly needed (normally you should use `accept_plan`).";
+        if (state.wave === 4) {
+          const planFilePath = resolve2(ctx.worktree, `tasks/plans/${state.planName}.md`);
+          if (existsSync2(planFilePath)) {
+            ctx.notifications.notify({
+              sessionID: args.sessionID,
+              event: "plan_ready",
+              title: "Plan is ready",
+              message: `tasks/plans/${state.planName}.md is ready for handoff review.`,
+              dedupeKey: "wave-4-plan-ready",
+              toolContext: context
+            });
+          }
+        }
+        return `Wave ${state.wave} (${waveName}) started for plan '${state.planName}'. You may now proceed with ${nextStep}. ${advanceWhen}`;
       } catch (error45) {
         const message = error45 instanceof Error ? error45.message : "Unknown error";
+        if (message.includes("Cannot advance to Wave 3 before Oracle gap review is completed")) {
+          return [
+            `Error: ${message}`,
+            "You are still in Wave 2 (Gap Analysis).",
+            'Next action: run Task with subagent_type="oracle" and wait for successful completion.',
+            "Do NOT call advance_wave again until that Oracle task succeeds."
+          ].join(" ");
+        }
         return `Error: ${message}`;
       }
     }
@@ -20097,8 +20392,9 @@ function createAcceptPlanTool(ctx) {
           "Plan accepted.",
           `Plan file: ${relativePlanPath}`,
           "Direct session handoff is unavailable in this environment.",
-          "Fallback: switch to Build agent and read the plan file first.",
-          `State saved with accepted timestamp ${acceptedState.acceptedAt}.`
+          "Fallback: tell the user to switch to the Build agent and read the plan file.",
+          `State saved with accepted timestamp ${acceptedState.acceptedAt}.`,
+          "IMPORTANT: The planning session is now COMPLETE. Do NOT call advance_wave or any other tools. Just confirm to the user."
         ].join(" ");
       }
       return [
@@ -20106,21 +20402,25 @@ function createAcceptPlanTool(ctx) {
         `Plan file: ${relativePlanPath}`,
         `Build session: ${buildSessionID}`,
         "First build action seeded: read the plan file with clean handoff context.",
-        `State saved with accepted timestamp ${acceptedState.acceptedAt}.`
+        `State saved with accepted timestamp ${acceptedState.acceptedAt}.`,
+        "IMPORTANT: The planning session is now COMPLETE. Do NOT call advance_wave or any other tools. Just confirm to the user."
       ].join(" ");
     }
   });
 }
 var DisciplinePlugin = async ({ worktree, directory, client }) => {
   const pluginDir = dirname(fileURLToPath(import.meta.url));
+  const pluginVersion = readPluginVersion(pluginDir);
   const agentConfigs = loadAgentConfigs(resolve2(pluginDir, "../agents"));
   const ctx = {
     manager: new WaveStateManager(worktree),
     todoNudges: new Map,
+    notifications: new NotificationManager,
     worktree,
     directory,
     client
   };
+  await showStartupToast(client, directory, pluginVersion);
   return {
     config: async (input) => {
       const agents = input.agent;
@@ -20134,6 +20434,7 @@ var DisciplinePlugin = async ({ worktree, directory, client }) => {
     "experimental.chat.system.transform": (input, output) => handleSystemTransform(ctx, input, output),
     "tool.execute.before": (input, output) => handleToolExecuteBefore(ctx, input, output),
     "tool.execute.after": (input, output) => handleToolExecuteAfter(ctx, input, output),
+    "session.idle": (input, output) => handleSessionIdle(ctx, input, output),
     tool: {
       advance_wave: createAdvanceWaveTool(ctx),
       accept_plan: createAcceptPlanTool(ctx)

package/dist/wave-state.d.ts

@@ -23,6 +23,7 @@ export declare class WaveStateManager {
     getPlanName(sessionID: string): string | undefined;
     isWaveAtLeast(sessionID: string, minWave: Wave): boolean;
     markAccepted(sessionID: string, buildSessionID: string): WaveState;
+    isAcceptedBuildSession(sessionID: string): boolean;
     private persist;
     private ensureDir;
     private loadStateFromDisk;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-discipline",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",