From 039c9cd0c891e292267825a67a0b6455f91734f1 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 14:19:35 +0200
Subject: [PATCH 01/22] fix(context-injector): use camelCase filePath property
 name

The context-injector hook was using snake_case 'file_path' but OpenCode
tools use camelCase 'filePath', causing directory context injection to
silently fail for all file read/edit operations.

- Change input.args?.file_path to input.args?.filePath
- Add tests for context injection behavior
---
 src/hooks/context-injector.ts        |  2 +-
 tests/hooks/context-injector.test.ts | 76 ++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 tests/hooks/context-injector.test.ts

diff --git a/src/hooks/context-injector.ts b/src/hooks/context-injector.ts
index 30048b8..3e5102f 100644
--- a/src/hooks/context-injector.ts
+++ b/src/hooks/context-injector.ts
@@ -143,7 +143,7 @@ export function createContextInjectorHook(ctx: PluginInput) {
     ) => {
       if (!FILE_ACCESS_TOOLS.includes(input.tool)) return;
 
-      const filePath = input.args?.file_path as string | undefined;
+      const filePath = input.args?.filePath as string | undefined;
       if (!filePath) return;
 
       try {
diff --git a/tests/hooks/context-injector.test.ts b/tests/hooks/context-injector.test.ts
new file mode 100644
index 0000000..6e4f737
--- /dev/null
+++ b/tests/hooks/context-injector.test.ts
@@ -0,0 +1,76 @@
+// tests/hooks/context-injector.test.ts
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Mock PluginInput
+function createMockCtx(directory: string) {
+  return {
+    directory,
+    client: {
+      session: {},
+      tui: {},
+    },
+  };
+}
+
+describe("context-injector", () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = mkdtempSync(join(tmpdir(), "context-injector-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  describe("tool.execute.after hook", () => {
+    it("should extract filePath from tool args using camelCase", async () => {
+      // Create a README.md in a subdirectory
+      const subDir = join(testDir, "src", "components");
+      mkdirSync(subDir, { recursive: true });
+      writeFileSync(join(subDir, "README.md"), "# Components\n\nComponent documentation.");
+
+      // Create a file to "read"
+      const targetFile = join(subDir, "Button.tsx");
+      writeFileSync(targetFile, "export const Button = () => <button />;");
+
+      // Import the hook dynamically to get fresh module
+      const { createContextInjectorHook } = await import("../../src/hooks/context-injector");
+      const ctx = createMockCtx(testDir);
+      const hooks = createContextInjectorHook(ctx as any);
+
+      // Simulate tool execution with camelCase filePath (as OpenCode sends it)
+      const input = {
+        tool: "read",
+        args: { filePath: targetFile }, // camelCase - this is what OpenCode sends
+      };
+      const output = { output: "file contents here" };
+
+      await hooks["tool.execute.after"](input, output);
+
+      // Should have injected directory context
+      expect(output.output).toContain("directory-context");
+      expect(output.output).toContain("Components");
+    });
+
+    it("should not inject context for non-file-access tools", async () => {
+      const { createContextInjectorHook } = await import("../../src/hooks/context-injector");
+      const ctx = createMockCtx(testDir);
+      const hooks = createContextInjectorHook(ctx as any);
+
+      const input = {
+        tool: "bash",
+        args: { command: "ls" },
+      };
+      const output = { output: "file1.txt\nfile2.txt" };
+
+      await hooks["tool.execute.after"](input, output);
+
+      // Should NOT have injected context
+      expect(output.output).not.toContain("directory-context");
+    });
+  });
+});

From cdc3c05e37e49cfbf7be45960e8188426319ea5a Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 14:20:14 +0200
Subject: [PATCH 02/22] fix(pty): add error handling for spawn failures

Wrap spawn() call in try-catch to provide descriptive error messages
when command not found or other spawn failures occur.

- Add try-catch around bun-pty spawn() call
- Throw descriptive error with command name and original message
- Add test for command not found scenario
- Note: bun-pty silently ignores invalid workdir (library limitation)
---
 src/tools/pty/manager.ts        | 20 +++++++++++++-------
 tests/tools/pty/manager.test.ts | 12 ++++++++++++
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/tools/pty/manager.ts b/src/tools/pty/manager.ts
index ec74ac4..ef82f2c 100644
--- a/src/tools/pty/manager.ts
+++ b/src/tools/pty/manager.ts
@@ -20,13 +20,19 @@ export class PTYManager {
     const env = { ...process.env, ...opts.env } as Record<string, string>;
     const title = opts.title ?? (`${opts.command} ${args.join(" ")}`.trim() || `Terminal ${id.slice(-4)}`);
 
-    const ptyProcess: IPty = spawn(opts.command, args, {
-      name: "xterm-256color",
-      cols: 120,
-      rows: 40,
-      cwd: workdir,
-      env,
-    });
+    let ptyProcess: IPty;
+    try {
+      ptyProcess = spawn(opts.command, args, {
+        name: "xterm-256color",
+        cols: 120,
+        rows: 40,
+        cwd: workdir,
+        env,
+      });
+    } catch (e) {
+      const errorMsg = e instanceof Error ? e.message : String(e);
+      throw new Error(`Failed to spawn PTY for command "${opts.command}": ${errorMsg}`);
+    }
 
     const buffer = new RingBuffer();
     const session: PTYSession = {
diff --git a/tests/tools/pty/manager.test.ts b/tests/tools/pty/manager.test.ts
index af4f6f9..d2e7005 100644
--- a/tests/tools/pty/manager.test.ts
+++ b/tests/tools/pty/manager.test.ts
@@ -48,6 +48,18 @@ describe("PTYManager", () => {
 
       expect(info.title).toBe("Dev Server");
     });
+
+    it("should throw descriptive error when command not found", () => {
+      expect(() => {
+        manager.spawn({
+          command: "nonexistent_command_xyz_12345",
+          parentSessionId: "test-session",
+        });
+      }).toThrow(/Failed to spawn PTY.*nonexistent_command_xyz_12345/);
+    });
+
+    // Note: bun-pty does not throw for invalid workdir - it silently uses cwd instead
+    // This is a limitation of the underlying library, not something we can catch
   });
 
   describe("list", () => {

From ff904f7601b8ae08053837fd8c94e29e8033ac24 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 14:22:25 +0200
Subject: [PATCH 03/22] feat(utils): add errors.ts utility for unified error
 handling

---
 src/utils/errors.ts        |  57 +++++++++++++++++++++
 tests/utils/errors.test.ts | 101 +++++++++++++++++++++++++++++++++++++
 2 files changed, 158 insertions(+)
 create mode 100644 src/utils/errors.ts
 create mode 100644 tests/utils/errors.test.ts

diff --git a/src/utils/errors.ts b/src/utils/errors.ts
new file mode 100644
index 0000000..49c042e
--- /dev/null
+++ b/src/utils/errors.ts
@@ -0,0 +1,57 @@
+// src/utils/errors.ts
+// Unified error handling utilities
+// Used by tools and hooks for consistent error formatting and logging
+
+/**
+ * Safely extract error message from unknown error type.
+ * Handles Error instances, strings, and other types.
+ */
+export function extractErrorMessage(e: unknown): string {
+  if (e instanceof Error) {
+    return e.message;
+  }
+  return String(e);
+}
+
+/**
+ * Format error message for tool responses (LLM-facing).
+ * @param message - The error message
+ * @param context - Optional context about what operation failed
+ */
+export function formatToolError(message: string, context?: string): string {
+  if (context && context.trim()) {
+    return `Error (${context}): ${message}`;
+  }
+  return `Error: ${message}`;
+}
+
+/**
+ * Execute a function and log any errors without throwing.
+ * Use for non-critical operations that shouldn't fail the main flow.
+ * @param module - Module name for log prefix
+ * @param fn - Function to execute
+ * @returns Result or undefined if error occurred
+ */
+export function catchAndLog<T>(module: string, fn: () => T): T | undefined {
+  try {
+    return fn();
+  } catch (e) {
+    console.error(`[${module}] ${extractErrorMessage(e)}`);
+    return undefined;
+  }
+}
+
+/**
+ * Async version of catchAndLog.
+ * @param module - Module name for log prefix
+ * @param fn - Async function to execute
+ * @returns Result or undefined if error occurred
+ */
+export async function catchAndLogAsync<T>(module: string, fn: () => Promise<T>): Promise<T | undefined> {
+  try {
+    return await fn();
+  } catch (e) {
+    console.error(`[${module}] ${extractErrorMessage(e)}`);
+    return undefined;
+  }
+}
diff --git a/tests/utils/errors.test.ts b/tests/utils/errors.test.ts
new file mode 100644
index 0000000..ca66417
--- /dev/null
+++ b/tests/utils/errors.test.ts
@@ -0,0 +1,101 @@
+// tests/utils/errors.test.ts
+import { describe, it, expect, mock, spyOn } from "bun:test";
+
+describe("errors utility", () => {
+  describe("extractErrorMessage", () => {
+    it("should extract message from Error instance", async () => {
+      const { extractErrorMessage } = await import("../../src/utils/errors");
+      const error = new Error("Something went wrong");
+      expect(extractErrorMessage(error)).toBe("Something went wrong");
+    });
+
+    it("should convert string to message", async () => {
+      const { extractErrorMessage } = await import("../../src/utils/errors");
+      expect(extractErrorMessage("plain string error")).toBe("plain string error");
+    });
+
+    it("should convert number to string", async () => {
+      const { extractErrorMessage } = await import("../../src/utils/errors");
+      expect(extractErrorMessage(404)).toBe("404");
+    });
+
+    it("should handle null", async () => {
+      const { extractErrorMessage } = await import("../../src/utils/errors");
+      expect(extractErrorMessage(null)).toBe("null");
+    });
+
+    it("should handle undefined", async () => {
+      const { extractErrorMessage } = await import("../../src/utils/errors");
+      expect(extractErrorMessage(undefined)).toBe("undefined");
+    });
+
+    it("should handle object with toString", async () => {
+      const { extractErrorMessage } = await import("../../src/utils/errors");
+      const obj = { toString: () => "custom object" };
+      expect(extractErrorMessage(obj)).toBe("custom object");
+    });
+  });
+
+  describe("formatToolError", () => {
+    it("should format error without context", async () => {
+      const { formatToolError } = await import("../../src/utils/errors");
+      expect(formatToolError("File not found")).toBe("Error: File not found");
+    });
+
+    it("should format error with context", async () => {
+      const { formatToolError } = await import("../../src/utils/errors");
+      expect(formatToolError("File not found", "reading config.json")).toBe(
+        "Error (reading config.json): File not found",
+      );
+    });
+
+    it("should handle empty context", async () => {
+      const { formatToolError } = await import("../../src/utils/errors");
+      expect(formatToolError("File not found", "")).toBe("Error: File not found");
+    });
+  });
+
+  describe("catchAndLog", () => {
+    it("should return result on success", async () => {
+      const { catchAndLog } = await import("../../src/utils/errors");
+      const result = catchAndLog("test-module", () => 42);
+      expect(result).toBe(42);
+    });
+
+    it("should return undefined on error and log", async () => {
+      const { catchAndLog } = await import("../../src/utils/errors");
+      const consoleSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      const result = catchAndLog("test-module", () => {
+        throw new Error("oops");
+      });
+
+      expect(result).toBeUndefined();
+      expect(consoleSpy).toHaveBeenCalledWith("[test-module] oops");
+
+      consoleSpy.mockRestore();
+    });
+
+    it("should handle async functions", async () => {
+      const { catchAndLogAsync } = await import("../../src/utils/errors");
+      const result = await catchAndLogAsync("test-module", async () => {
+        return "async result";
+      });
+      expect(result).toBe("async result");
+    });
+
+    it("should handle async errors", async () => {
+      const { catchAndLogAsync } = await import("../../src/utils/errors");
+      const consoleSpy = spyOn(console, "error").mockImplementation(() => {});
+
+      const result = await catchAndLogAsync("test-module", async () => {
+        throw new Error("async oops");
+      });
+
+      expect(result).toBeUndefined();
+      expect(consoleSpy).toHaveBeenCalledWith("[test-module] async oops");
+
+      consoleSpy.mockRestore();
+    });
+  });
+});

From baca78c62851b52fd74ca4425340ca8ce764d837 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 14:22:37 +0200
Subject: [PATCH 04/22] feat(utils): add logger.ts utility for standardized
 logging

---
 src/utils/logger.ts        | 50 ++++++++++++++++++++++++
 tests/utils/logger.test.ts | 78 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 128 insertions(+)
 create mode 100644 src/utils/logger.ts
 create mode 100644 tests/utils/logger.test.ts

diff --git a/src/utils/logger.ts b/src/utils/logger.ts
new file mode 100644
index 0000000..7907f47
--- /dev/null
+++ b/src/utils/logger.ts
@@ -0,0 +1,50 @@
+// src/utils/logger.ts
+// Standardized logging with module prefixes
+// Used across hooks and tools for consistent log formatting
+
+/**
+ * Logger with standardized [module] prefix format.
+ *
+ * Usage:
+ *   log.info("my-hook", "Processing file");
+ *   log.error("my-tool", "Failed to read", error);
+ *   log.debug("my-module", "Verbose info"); // Only when DEBUG env set
+ */
+export const log = {
+  /**
+   * Debug level - only outputs when DEBUG environment variable is set.
+   */
+  debug(module: string, message: string): void {
+    if (process.env.DEBUG) {
+      console.log(`[${module}] ${message}`);
+    }
+  },
+
+  /**
+   * Info level - general informational messages.
+   */
+  info(module: string, message: string): void {
+    console.log(`[${module}] ${message}`);
+  },
+
+  /**
+   * Warning level - non-fatal issues.
+   */
+  warn(module: string, message: string): void {
+    console.warn(`[${module}] ${message}`);
+  },
+
+  /**
+   * Error level - errors that were caught and handled.
+   * @param module - Module name for prefix
+   * @param message - Error description
+   * @param error - Optional error object for additional context
+   */
+  error(module: string, message: string, error?: unknown): void {
+    if (error !== undefined) {
+      console.error(`[${module}] ${message}`, error);
+    } else {
+      console.error(`[${module}] ${message}`);
+    }
+  },
+};
diff --git a/tests/utils/logger.test.ts b/tests/utils/logger.test.ts
new file mode 100644
index 0000000..a9687c7
--- /dev/null
+++ b/tests/utils/logger.test.ts
@@ -0,0 +1,78 @@
+// tests/utils/logger.test.ts
+import { describe, it, expect, spyOn, beforeEach, afterEach } from "bun:test";
+
+describe("logger utility", () => {
+  let consoleLogSpy: ReturnType<typeof spyOn>;
+  let consoleWarnSpy: ReturnType<typeof spyOn>;
+  let consoleErrorSpy: ReturnType<typeof spyOn>;
+  let originalDebug: string | undefined;
+
+  beforeEach(() => {
+    consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+    consoleWarnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+    originalDebug = process.env.DEBUG;
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+    consoleWarnSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    if (originalDebug !== undefined) {
+      process.env.DEBUG = originalDebug;
+    } else {
+      delete process.env.DEBUG;
+    }
+  });
+
+  describe("log.info", () => {
+    it("should log with module prefix", async () => {
+      const { log } = await import("../../src/utils/logger");
+      log.info("my-module", "Hello world");
+      expect(consoleLogSpy).toHaveBeenCalledWith("[my-module] Hello world");
+    });
+  });
+
+  describe("log.warn", () => {
+    it("should warn with module prefix", async () => {
+      const { log } = await import("../../src/utils/logger");
+      log.warn("my-module", "Something fishy");
+      expect(consoleWarnSpy).toHaveBeenCalledWith("[my-module] Something fishy");
+    });
+  });
+
+  describe("log.error", () => {
+    it("should error with module prefix", async () => {
+      const { log } = await import("../../src/utils/logger");
+      log.error("my-module", "Something broke");
+      expect(consoleErrorSpy).toHaveBeenCalledWith("[my-module] Something broke");
+    });
+
+    it("should include error object when provided", async () => {
+      const { log } = await import("../../src/utils/logger");
+      const err = new Error("details");
+      log.error("my-module", "Something broke", err);
+      expect(consoleErrorSpy).toHaveBeenCalledWith("[my-module] Something broke", err);
+    });
+  });
+
+  describe("log.debug", () => {
+    it("should not log when DEBUG is not set", async () => {
+      delete process.env.DEBUG;
+      // Re-import to pick up env change
+      const { log } = await import("../../src/utils/logger");
+      log.debug("my-module", "Debug info");
+      expect(consoleLogSpy).not.toHaveBeenCalled();
+    });
+
+    it("should log when DEBUG is set", async () => {
+      process.env.DEBUG = "1";
+      // Need fresh import to pick up env change
+      // Clear module cache
+      delete require.cache[require.resolve("../../src/utils/logger")];
+      const { log } = await import("../../src/utils/logger");
+      log.debug("my-module", "Debug info");
+      expect(consoleLogSpy).toHaveBeenCalledWith("[my-module] Debug info");
+    });
+  });
+});

From de37ae57e39dc44ed448c021549d9eea3e8441cb Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 14:23:26 +0200
Subject: [PATCH 05/22] feat(utils): add centralized config utility

Add src/utils/config.ts with compile-time constants organized by domain:
- compaction: threshold, cooldown, timeout settings
- contextWindow: warning/critical thresholds
- tokens: estimation settings
- paths: ledger dirs, context files, patterns
- timeouts: btca, toast durations
- limits: file sizes, PTY buffer, cache settings

Add comprehensive tests in tests/utils/config.test.ts (29 tests)
---
 src/utils/config.ts        | 103 +++++++++++++++++++++++
 tests/utils/config.test.ts | 163 +++++++++++++++++++++++++++++++++++++
 2 files changed, 266 insertions(+)
 create mode 100644 src/utils/config.ts
 create mode 100644 tests/utils/config.test.ts

diff --git a/src/utils/config.ts b/src/utils/config.ts
new file mode 100644
index 0000000..3414937
--- /dev/null
+++ b/src/utils/config.ts
@@ -0,0 +1,103 @@
+// src/utils/config.ts
+// Centralized configuration constants
+// Organized by domain for easy discovery and maintenance
+
+/**
+ * Application configuration constants.
+ * All values are compile-time constants - no runtime configuration.
+ */
+export const config = {
+  /**
+   * Auto-compaction settings
+   */
+  compaction: {
+    /** Trigger compaction when context usage exceeds this ratio */
+    threshold: 0.5,
+    /** Minimum time between compaction attempts (ms) */
+    cooldownMs: 30_000,
+    /** Maximum time to wait for compaction to complete (ms) */
+    timeoutMs: 120_000,
+  },
+
+  /**
+   * Context window monitoring settings
+   */
+  contextWindow: {
+    /** Show warning when context usage exceeds this ratio */
+    warningThreshold: 0.7,
+    /** Show critical warning when context usage exceeds this ratio */
+    criticalThreshold: 0.85,
+    /** Minimum time between warning toasts (ms) */
+    warningCooldownMs: 120_000,
+  },
+
+  /**
+   * Token estimation settings
+   */
+  tokens: {
+    /** Characters per token for estimation */
+    charsPerToken: 4,
+    /** Default context window limit (tokens) */
+    defaultContextLimit: 200_000,
+    /** Default max output tokens */
+    defaultMaxOutputTokens: 50_000,
+    /** Safety margin for output (ratio of remaining context) */
+    safetyMargin: 0.5,
+    /** Lines to preserve when truncating output */
+    preserveHeaderLines: 3,
+  },
+
+  /**
+   * File path patterns and directories
+   */
+  paths: {
+    /** Directory for ledger files */
+    ledgerDir: "thoughts/ledgers",
+    /** Prefix for ledger filenames */
+    ledgerPrefix: "CONTINUITY_",
+    /** Context files to inject from project root */
+    rootContextFiles: ["ARCHITECTURE.md", "CODE_STYLE.md", "README.md"] as readonly string[],
+    /** Context files to collect when walking up directories */
+    dirContextFiles: ["README.md"] as readonly string[],
+    /** Pattern to match plan files */
+    planPattern: /thoughts\/shared\/plans\/.*\.md$/,
+    /** Pattern to match ledger files */
+    ledgerPattern: /thoughts\/ledgers\/CONTINUITY_.*\.md$/,
+  },
+
+  /**
+   * Timeout settings
+   */
+  timeouts: {
+    /** BTCA command timeout (ms) */
+    btcaMs: 120_000,
+    /** Success toast duration (ms) */
+    toastSuccessMs: 3000,
+    /** Warning toast duration (ms) */
+    toastWarningMs: 4000,
+    /** Error toast duration (ms) */
+    toastErrorMs: 5000,
+  },
+
+  /**
+   * Various limits
+   */
+  limits: {
+    /** File size threshold for triggering extraction (bytes) */
+    largeFileBytes: 100 * 1024,
+    /** Max lines to return without extraction */
+    maxLinesNoExtract: 200,
+    /** Max lines in PTY buffer */
+    ptyMaxBufferLines: 50_000,
+    /** Default read limit for PTY */
+    ptyDefaultReadLimit: 500,
+    /** Max line length for PTY output */
+    ptyMaxLineLength: 2000,
+    /** Max matches to show from ast-grep */
+    astGrepMaxMatches: 100,
+    /** Context cache TTL (ms) */
+    contextCacheTtlMs: 30_000,
+    /** Max entries in context cache */
+    contextCacheMaxSize: 100,
+  },
+} as const;
diff --git a/tests/utils/config.test.ts b/tests/utils/config.test.ts
new file mode 100644
index 0000000..160a839
--- /dev/null
+++ b/tests/utils/config.test.ts
@@ -0,0 +1,163 @@
+// tests/utils/config.test.ts
+import { describe, it, expect } from "bun:test";
+
+describe("config utility", () => {
+  describe("config.compaction", () => {
+    it("should have threshold", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.compaction.threshold).toBe(0.5);
+    });
+
+    it("should have cooldownMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.compaction.cooldownMs).toBe(30_000);
+    });
+
+    it("should have timeoutMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.compaction.timeoutMs).toBe(120_000);
+    });
+  });
+
+  describe("config.contextWindow", () => {
+    it("should have warningThreshold", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.contextWindow.warningThreshold).toBe(0.7);
+    });
+
+    it("should have criticalThreshold", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.contextWindow.criticalThreshold).toBe(0.85);
+    });
+
+    it("should have warningCooldownMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.contextWindow.warningCooldownMs).toBe(120_000);
+    });
+  });
+
+  describe("config.tokens", () => {
+    it("should have charsPerToken", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.tokens.charsPerToken).toBe(4);
+    });
+
+    it("should have defaultContextLimit", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.tokens.defaultContextLimit).toBe(200_000);
+    });
+
+    it("should have defaultMaxOutputTokens", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.tokens.defaultMaxOutputTokens).toBe(50_000);
+    });
+
+    it("should have safetyMargin", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.tokens.safetyMargin).toBe(0.5);
+    });
+
+    it("should have preserveHeaderLines", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.tokens.preserveHeaderLines).toBe(3);
+    });
+  });
+
+  describe("config.paths", () => {
+    it("should have ledgerDir", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.paths.ledgerDir).toBe("thoughts/ledgers");
+    });
+
+    it("should have ledgerPrefix", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.paths.ledgerPrefix).toBe("CONTINUITY_");
+    });
+
+    it("should have rootContextFiles", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.paths.rootContextFiles).toEqual(["ARCHITECTURE.md", "CODE_STYLE.md", "README.md"]);
+    });
+
+    it("should have dirContextFiles", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.paths.dirContextFiles).toEqual(["README.md"]);
+    });
+
+    it("should have planPattern regex", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.paths.planPattern.test("thoughts/shared/plans/2026-01-01-test.md")).toBe(true);
+      expect(config.paths.planPattern.test("other/path.md")).toBe(false);
+    });
+
+    it("should have ledgerPattern regex", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.paths.ledgerPattern.test("thoughts/ledgers/CONTINUITY_abc123.md")).toBe(true);
+      expect(config.paths.ledgerPattern.test("other/path.md")).toBe(false);
+    });
+  });
+
+  describe("config.timeouts", () => {
+    it("should have btcaMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.timeouts.btcaMs).toBe(120_000);
+    });
+
+    it("should have toastSuccessMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.timeouts.toastSuccessMs).toBe(3000);
+    });
+
+    it("should have toastWarningMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.timeouts.toastWarningMs).toBe(4000);
+    });
+
+    it("should have toastErrorMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.timeouts.toastErrorMs).toBe(5000);
+    });
+  });
+
+  describe("config.limits", () => {
+    it("should have largeFileBytes", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.largeFileBytes).toBe(100 * 1024);
+    });
+
+    it("should have maxLinesNoExtract", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.maxLinesNoExtract).toBe(200);
+    });
+
+    it("should have ptyMaxBufferLines", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.ptyMaxBufferLines).toBe(50_000);
+    });
+
+    it("should have ptyDefaultReadLimit", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.ptyDefaultReadLimit).toBe(500);
+    });
+
+    it("should have ptyMaxLineLength", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.ptyMaxLineLength).toBe(2000);
+    });
+
+    it("should have astGrepMaxMatches", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.astGrepMaxMatches).toBe(100);
+    });
+
+    it("should have contextCacheTtlMs", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.contextCacheTtlMs).toBe(30_000);
+    });
+
+    it("should have contextCacheMaxSize", async () => {
+      const { config } = await import("../../src/utils/config");
+      expect(config.limits.contextCacheMaxSize).toBe(100);
+    });
+  });
+});

From 91fc9e705aed211062536e58e9024b2e18992256 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 14:43:34 +0200
Subject: [PATCH 06/22] fix: validate model configuration and fallback to
 defaults

When a user configures an agent with an unavailable provider/model in
micode.json, instead of crashing at runtime, we now:

- Validate models at plugin startup against available providers
- Log a warning for invalid models
- Remove the invalid model from config, letting the agent use its default

Handles edge cases: empty strings, malformed models (no slash), and
models with multiple slashes in the ID.

Closes #10
---
 src/config-loader.test.ts | 255 ++++++++++++++++++++++++++++++++++++++
 src/config-loader.ts      |  63 ++++++++++
 src/index.ts              |  16 ++-
 3 files changed, 332 insertions(+), 2 deletions(-)
 create mode 100644 src/config-loader.test.ts

diff --git a/src/config-loader.test.ts b/src/config-loader.test.ts
new file mode 100644
index 0000000..7734bbc
--- /dev/null
+++ b/src/config-loader.test.ts
@@ -0,0 +1,255 @@
+// src/config-loader.test.ts
+import { describe, expect, test } from "bun:test";
+import type { AgentConfig } from "@opencode-ai/sdk";
+import { validateAgentModels, type MicodeConfig, type ProviderInfo } from "./config-loader";
+
+// Helper to create a minimal ProviderInfo for testing
+function createProvider(id: string, modelIds: string[]): ProviderInfo {
+  const models: Record<string, unknown> = {};
+  for (const modelId of modelIds) {
+    models[modelId] = { id: modelId };
+  }
+  return { id, models };
+}
+
+// Helper to create minimal AgentConfig
+function createAgentConfig(model: string): AgentConfig {
+  return {
+    model,
+    systemPrompt: "test",
+  } as AgentConfig;
+}
+
+describe("validateAgentModels", () => {
+  test("returns config unchanged when all models are valid", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "openai/gpt-4" },
+        brainstormer: { model: "anthropic/claude-3" },
+      },
+    };
+
+    const providers: ProviderInfo[] = [
+      createProvider("openai", ["gpt-4", "gpt-3.5"]),
+      createProvider("anthropic", ["claude-3", "claude-2"]),
+    ];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-3.5"),
+      brainstormer: createAgentConfig("anthropic/claude-2"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    expect(result.agents?.commander?.model).toBe("openai/gpt-4");
+    expect(result.agents?.brainstormer?.model).toBe("anthropic/claude-3");
+  });
+
+  test("removes model override when provider does not exist", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "nonexistent/gpt-4" },
+      },
+    };
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-4"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // Model should be removed, falling back to default
+    expect(result.agents?.commander?.model).toBeUndefined();
+  });
+
+  test("removes model override when model does not exist in provider", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "openai/nonexistent-model" },
+      },
+    };
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4", "gpt-3.5"])];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-4"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // Model should be removed, falling back to default
+    expect(result.agents?.commander?.model).toBeUndefined();
+  });
+
+  test("preserves other properties when model is invalid", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: {
+          model: "nonexistent/model",
+          temperature: 0.7,
+          maxTokens: 4000,
+        },
+      },
+    };
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-4"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // Model removed but other properties preserved
+    expect(result.agents?.commander?.model).toBeUndefined();
+    expect(result.agents?.commander?.temperature).toBe(0.7);
+    expect(result.agents?.commander?.maxTokens).toBe(4000);
+  });
+
+  test("handles config with no agents", () => {
+    const userConfig: MicodeConfig = {};
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-4"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    expect(result).toEqual({});
+  });
+
+  test("handles agent override with no model specified", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { temperature: 0.5 },
+      },
+    };
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-4"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // No model to validate, config unchanged
+    expect(result.agents?.commander?.temperature).toBe(0.5);
+    expect(result.agents?.commander?.model).toBeUndefined();
+  });
+
+  test("handles empty providers list", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "openai/gpt-4" },
+      },
+    };
+
+    const providers: ProviderInfo[] = [];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-4"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // No providers available, model should be removed
+    expect(result.agents?.commander?.model).toBeUndefined();
+  });
+
+  test("validates multiple agents with mixed valid/invalid models", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "openai/gpt-4" }, // valid
+        brainstormer: { model: "fake/model" }, // invalid provider
+        planner: { model: "openai/fake-model" }, // invalid model
+        reviewer: { model: "anthropic/claude-3" }, // valid
+      },
+    };
+
+    const providers: ProviderInfo[] = [
+      createProvider("openai", ["gpt-4", "gpt-3.5"]),
+      createProvider("anthropic", ["claude-3"]),
+    ];
+
+    const defaultAgents: Record<string, AgentConfig> = {
+      commander: createAgentConfig("openai/gpt-3.5"),
+      brainstormer: createAgentConfig("openai/gpt-3.5"),
+      planner: createAgentConfig("openai/gpt-3.5"),
+      reviewer: createAgentConfig("anthropic/claude-3"),
+    };
+
+    const result = validateAgentModels(userConfig, providers);
+
+    expect(result.agents?.commander?.model).toBe("openai/gpt-4");
+    expect(result.agents?.brainstormer?.model).toBeUndefined();
+    expect(result.agents?.planner?.model).toBeUndefined();
+    expect(result.agents?.reviewer?.model).toBe("anthropic/claude-3");
+  });
+
+  test("removes empty string model", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "", temperature: 0.5 },
+      },
+    };
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // Empty string model should be removed as invalid
+    expect(result.agents?.commander?.model).toBeUndefined();
+    expect(result.agents?.commander?.temperature).toBe(0.5);
+  });
+
+  test("removes model string without slash (malformed)", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "gpt-4-no-provider" },
+      },
+    };
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // Malformed model (no slash) should be removed
+    expect(result.agents?.commander?.model).toBeUndefined();
+  });
+
+  test("handles model with multiple slashes in model ID", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "openai/gpt-4/turbo" },
+      },
+    };
+
+    // Model ID is "gpt-4/turbo" (contains slash)
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4/turbo"])];
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // Should be valid - "gpt-4/turbo" is the full model ID
+    expect(result.agents?.commander?.model).toBe("openai/gpt-4/turbo");
+  });
+
+  test("returns consistent shape when all agents have invalid models", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "invalid/model" },
+      },
+    };
+
+    const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // Should return { agents: {} } for consistency, not {}
+    expect(result).toEqual({ agents: {} });
+  });
+});
diff --git a/src/config-loader.ts b/src/config-loader.ts
index d467cb3..1fd48d9 100644
--- a/src/config-loader.ts
+++ b/src/config-loader.ts
@@ -4,6 +4,12 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import type { AgentConfig } from "@opencode-ai/sdk";
 
+// Minimal type for provider validation - only what we need
+export interface ProviderInfo {
+  id: string;
+  models: Record<string, unknown>;
+}
+
 // Safe properties that users can override
 const SAFE_AGENT_PROPERTIES = ["model", "temperature", "maxTokens"] as const;
 
@@ -87,3 +93,60 @@ export function mergeAgentConfigs(
 
   return merged;
 }
+
+/**
+ * Validate that configured models exist in available providers
+ * Removes invalid model overrides and logs warnings
+ */
+export function validateAgentModels(userConfig: MicodeConfig, providers: ProviderInfo[]): MicodeConfig {
+  if (!userConfig.agents) {
+    return userConfig;
+  }
+
+  // Build lookup map for providers and their models
+  const providerMap = new Map<string, Set<string>>();
+  for (const provider of providers) {
+    providerMap.set(provider.id, new Set(Object.keys(provider.models)));
+  }
+
+  const validatedAgents: Record<string, AgentOverride> = {};
+
+  for (const [agentName, override] of Object.entries(userConfig.agents)) {
+    // No model specified - keep other properties as-is
+    if (override.model === undefined) {
+      validatedAgents[agentName] = override;
+      continue;
+    }
+
+    // Empty or whitespace-only model - treat as invalid
+    const trimmedModel = override.model.trim();
+    if (!trimmedModel) {
+      const { model: _removed, ...otherProps } = override;
+      console.warn(`[micode] Empty model for agent "${agentName}". Using default model.`);
+      if (Object.keys(otherProps).length > 0) {
+        validatedAgents[agentName] = otherProps;
+      }
+      continue;
+    }
+
+    // Parse "provider/model" format
+    const [providerID, ...rest] = trimmedModel.split("/");
+    const modelID = rest.join("/");
+
+    const providerModels = providerMap.get(providerID);
+    const isValid = providerModels?.has(modelID) ?? false;
+
+    if (isValid) {
+      validatedAgents[agentName] = override;
+    } else {
+      // Remove invalid model but keep other properties
+      const { model: _removed, ...otherProps } = override;
+      console.warn(`[micode] Model "${override.model}" not found for agent "${agentName}". Using default model.`);
+      if (Object.keys(otherProps).length > 0) {
+        validatedAgents[agentName] = otherProps;
+      }
+    }
+  }
+
+  return { agents: validatedAgents };
+}
diff --git a/src/index.ts b/src/index.ts
index 7ace5f7..57e1ce1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -26,7 +26,7 @@ import { createFileOpsTrackerHook, getFileOps } from "./hooks/file-ops-tracker";
 import { PTYManager, createPtyTools } from "./tools/pty";
 
 // Config loader
-import { loadMicodeConfig, mergeAgentConfigs } from "./config-loader";
+import { loadMicodeConfig, mergeAgentConfigs, validateAgentModels } from "./config-loader";
 
 // Think mode: detect keywords and enable extended thinking
 const THINK_KEYWORDS = [
@@ -76,7 +76,19 @@ const OpenCodeConfigPlugin: Plugin = async (ctx) => {
   }
 
   // Load user config for model overrides
-  const userConfig = await loadMicodeConfig();
+  let userConfig = await loadMicodeConfig();
+
+  // Validate configured models against available providers
+  if (userConfig?.agents) {
+    try {
+      const providersResponse = await ctx.client.provider.list();
+      if (providersResponse.data?.all) {
+        userConfig = validateAgentModels(userConfig, providersResponse.data.all);
+      }
+    } catch (e) {
+      console.warn("[micode] Failed to validate model configuration:", e);
+    }
+  }
 
   // Think mode state per session
   const thinkModeState = new Map<string, boolean>();

From ed94785ff9e63e6f0e3b273a581a62e85b9dc735 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 14:51:12 +0200
Subject: [PATCH 07/22] refactor: use centralized config, logger, and error
 utilities

Update hooks and tools to use the new utility modules:
- auto-compact: config.* for thresholds/timeouts, extractErrorMessage
- context-injector: config.paths.* and config.limits.*
- context-window-monitor: config.contextWindow.*
- ledger-loader: config.paths.ledgerDir/ledgerPrefix
- token-aware-truncation: config.tokens.*
- artifact-auto-index: log.error instead of console.error

Part of tech debt remediation (Phase 3).
---
 biome.json                          |  8 +------
 src/hooks/artifact-auto-index.ts    |  3 ++-
 src/hooks/auto-compact.ts           | 35 ++++++++++++-----------------
 src/hooks/context-injector.ts       | 17 +++++---------
 src/hooks/context-window-monitor.ts | 21 +++++++----------
 src/hooks/ledger-loader.ts          | 10 ++++-----
 src/hooks/token-aware-truncation.ts | 28 +++++++++--------------
 src/tools/spawn-agent.ts            |  4 +---
 8 files changed, 46 insertions(+), 80 deletions(-)

diff --git a/biome.json b/biome.json
index 41e8052..56db870 100644
--- a/biome.json
+++ b/biome.json
@@ -40,13 +40,7 @@
         "organizeImports": {
           "level": "on",
           "options": {
-            "groups": [
-              [":BUN:", ":NODE:"],
-              ":BLANK_LINE:",
-              [":PACKAGE:"],
-              ":BLANK_LINE:",
-              ":PATH:"
-            ]
+            "groups": [[":BUN:", ":NODE:"], ":BLANK_LINE:", [":PACKAGE:"], ":BLANK_LINE:", ":PATH:"]
           }
         }
       }
diff --git a/src/hooks/artifact-auto-index.ts b/src/hooks/artifact-auto-index.ts
index bebc246..648d4c3 100644
--- a/src/hooks/artifact-auto-index.ts
+++ b/src/hooks/artifact-auto-index.ts
@@ -4,6 +4,7 @@
 import type { PluginInput } from "@opencode-ai/plugin";
 import { readFileSync } from "node:fs";
 import { getArtifactIndex } from "../tools/artifact-index";
+import { log } from "../utils/logger";
 
 const LEDGER_PATH_PATTERN = /thoughts\/ledgers\/CONTINUITY_(.+)\.md$/;
 const PLAN_PATH_PATTERN = /thoughts\/shared\/plans\/(.+)\.md$/;
@@ -102,7 +103,7 @@ export function createArtifactAutoIndexHook(_ctx: PluginInput) {
         }
       } catch (e) {
         // Silent failure - don't interrupt user flow
-        console.error(`[artifact-auto-index] Error indexing ${filePath}:`, e);
+        log.error("artifact-auto-index", `Error indexing ${filePath}`, e);
       }
     },
   };
diff --git a/src/hooks/auto-compact.ts b/src/hooks/auto-compact.ts
index 165c0aa..e5a32a8 100644
--- a/src/hooks/auto-compact.ts
+++ b/src/hooks/auto-compact.ts
@@ -1,15 +1,11 @@
-import type { PluginInput } from "@opencode-ai/plugin";
-import { getContextLimit } from "../utils/model-limits";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-// Compact when this percentage of context is used
-const COMPACT_THRESHOLD = 0.5;
-
-const LEDGER_DIR = "thoughts/ledgers";
+import type { PluginInput } from "@opencode-ai/plugin";
 
-// Timeout for waiting for compaction to complete (2 minutes)
-const COMPACTION_TIMEOUT_MS = 120_000;
+import { config } from "../utils/config";
+import { extractErrorMessage } from "../utils/errors";
+import { getContextLimit } from "../utils/model-limits";
 
 interface PendingCompaction {
   resolve: () => void;
@@ -23,9 +19,6 @@ interface AutoCompactState {
   pendingCompactions: Map<string, PendingCompaction>;
 }
 
-// Cooldown between compaction attempts (prevent rapid re-triggering)
-const COMPACT_COOLDOWN_MS = 30_000; // 30 seconds
-
 export function createAutoCompactHook(ctx: PluginInput) {
   const state: AutoCompactState = {
     inProgress: new Set(),
@@ -65,13 +58,13 @@ export function createAutoCompactHook(ctx: PluginInput) {
       if (!summaryText.trim()) return;
 
       // Create ledger directory if needed
-      const ledgerDir = join(ctx.directory, LEDGER_DIR);
+      const ledgerDir = join(ctx.directory, config.paths.ledgerDir);
       await mkdir(ledgerDir, { recursive: true });
 
       // Write ledger file - summary is already structured (Factory.ai/pi-mono format)
       const timestamp = new Date().toISOString();
       const sessionName = sessionID.slice(0, 8); // Use first 8 chars of session ID
-      const ledgerPath = join(ledgerDir, `CONTINUITY_${sessionName}.md`);
+      const ledgerPath = join(ledgerDir, `${config.paths.ledgerPrefix}${sessionName}.md`);
 
       // Add metadata header, then the structured summary as-is
       const ledgerContent = `---
@@ -94,7 +87,7 @@ ${summaryText}
       const timeoutId = setTimeout(() => {
         state.pendingCompactions.delete(sessionID);
         reject(new Error("Compaction timed out"));
-      }, COMPACTION_TIMEOUT_MS);
+      }, config.compaction.timeoutMs);
 
       state.pendingCompactions.set(sessionID, { resolve, reject, timeoutId });
     });
@@ -112,7 +105,7 @@ ${summaryText}
 
     // Check cooldown
     const lastCompact = state.lastCompactTime.get(sessionID) || 0;
-    if (Date.now() - lastCompact < COMPACT_COOLDOWN_MS) {
+    if (Date.now() - lastCompact < config.compaction.cooldownMs) {
       return;
     }
 
@@ -120,7 +113,7 @@ ${summaryText}
 
     try {
       const usedPercent = Math.round(usageRatio * 100);
-      const thresholdPercent = Math.round(COMPACT_THRESHOLD * 100);
+      const thresholdPercent = Math.round(config.compaction.threshold * 100);
 
       await ctx.client.tui
         .showToast({
@@ -128,7 +121,7 @@ ${summaryText}
             title: "Auto Compacting",
             message: `Context at ${usedPercent}% (threshold: ${thresholdPercent}%). Summarizing...`,
             variant: "warning",
-            duration: 3000,
+            duration: config.timeouts.toastWarningMs,
           },
         })
         .catch(() => {});
@@ -158,19 +151,19 @@ ${summaryText}
             title: "Compaction Complete",
             message: "Session summarized and ledger updated.",
             variant: "success",
-            duration: 3000,
+            duration: config.timeouts.toastSuccessMs,
           },
         })
         .catch(() => {});
     } catch (e) {
-      const errorMsg = e instanceof Error ? e.message : String(e);
+      const errorMsg = extractErrorMessage(e);
       await ctx.client.tui
         .showToast({
           body: {
             title: "Compaction Failed",
             message: errorMsg.slice(0, 100),
             variant: "error",
-            duration: 5000,
+            duration: config.timeouts.toastErrorMs,
           },
         })
         .catch(() => {});
@@ -233,7 +226,7 @@ ${summaryText}
         const usageRatio = totalUsed / contextLimit;
 
         // Trigger compaction if over threshold
-        if (usageRatio >= COMPACT_THRESHOLD) {
+        if (usageRatio >= config.compaction.threshold) {
           triggerCompaction(sessionID, providerID, modelID, usageRatio);
         }
       }
diff --git a/src/hooks/context-injector.ts b/src/hooks/context-injector.ts
index 3e5102f..d142571 100644
--- a/src/hooks/context-injector.ts
+++ b/src/hooks/context-injector.ts
@@ -1,12 +1,7 @@
 import type { PluginInput } from "@opencode-ai/plugin";
 import { readFile } from "node:fs/promises";
 import { join, dirname, resolve } from "node:path";
-
-// Files to inject at project root level (AGENTS.md and CLAUDE.md handled by OpenCode natively)
-const ROOT_CONTEXT_FILES = ["ARCHITECTURE.md", "CODE_STYLE.md", "README.md"] as const;
-
-// Files to collect when walking up directories (AGENTS.md handled by OpenCode natively)
-const DIRECTORY_CONTEXT_FILES = ["README.md"] as const;
+import { config } from "../utils/config";
 
 // Tools that trigger directory-aware context injection
 const FILE_ACCESS_TOOLS = ["Read", "read", "Edit", "edit"];
@@ -18,8 +13,6 @@ interface ContextCache {
   lastRootCheck: number;
 }
 
-const CACHE_TTL = 30_000; // 30 seconds
-
 export function createContextInjectorHook(ctx: PluginInput) {
   const cache: ContextCache = {
     rootContent: new Map(),
@@ -30,14 +23,14 @@ export function createContextInjectorHook(ctx: PluginInput) {
   async function loadRootContextFiles(): Promise<Map<string, string>> {
     const now = Date.now();
 
-    if (now - cache.lastRootCheck < CACHE_TTL && cache.rootContent.size > 0) {
+    if (now - cache.lastRootCheck < config.limits.contextCacheTtlMs && cache.rootContent.size > 0) {
       return cache.rootContent;
     }
 
     cache.rootContent.clear();
     cache.lastRootCheck = now;
 
-    for (const filename of ROOT_CONTEXT_FILES) {
+    for (const filename of config.paths.rootContextFiles) {
       try {
         const filepath = join(ctx.directory, filename);
         const content = await readFile(filepath, "utf-8");
@@ -67,7 +60,7 @@ export function createContextInjectorHook(ctx: PluginInput) {
 
     // Walk up from file directory to project root
     while (currentDir.startsWith(projectRoot) || currentDir === projectRoot) {
-      for (const filename of DIRECTORY_CONTEXT_FILES) {
+      for (const filename of config.paths.dirContextFiles) {
         const contextPath = join(currentDir, filename);
         const relPath = currentDir.replace(projectRoot, "").replace(/^\//, "") || ".";
         const key = `${relPath}/${filename}`;
@@ -98,7 +91,7 @@ export function createContextInjectorHook(ctx: PluginInput) {
     cache.directoryContent.set(cacheKey, collected);
 
     // Limit cache size
-    if (cache.directoryContent.size > 100) {
+    if (cache.directoryContent.size > config.limits.contextCacheMaxSize) {
       const firstKey = cache.directoryContent.keys().next().value;
       if (firstKey) cache.directoryContent.delete(firstKey);
     }
diff --git a/src/hooks/context-window-monitor.ts b/src/hooks/context-window-monitor.ts
index 206ebdc..07a7e35 100644
--- a/src/hooks/context-window-monitor.ts
+++ b/src/hooks/context-window-monitor.ts
@@ -1,17 +1,12 @@
 import type { PluginInput } from "@opencode-ai/plugin";
+import { config } from "../utils/config";
 import { getContextLimit } from "../utils/model-limits";
 
-// Thresholds for context window warnings
-const WARNING_THRESHOLD = 0.7; // 70% - remind there's still room
-const CRITICAL_THRESHOLD = 0.85; // 85% - getting tight
-
 interface MonitorState {
   lastWarningTime: Map<string, number>;
   lastUsageRatio: Map<string, number>;
 }
 
-const WARNING_COOLDOWN_MS = 120_000; // 2 minutes between warnings
-
 export function createContextWindowMonitorHook(ctx: PluginInput) {
   const state: MonitorState = {
     lastWarningTime: new Map(),
@@ -21,11 +16,11 @@ export function createContextWindowMonitorHook(ctx: PluginInput) {
   function getEncouragementMessage(usageRatio: number): string {
     const remaining = Math.round((1 - usageRatio) * 100);
 
-    if (usageRatio < WARNING_THRESHOLD) {
+    if (usageRatio < config.contextWindow.warningThreshold) {
       return ""; // No message needed
     }
 
-    if (usageRatio < CRITICAL_THRESHOLD) {
+    if (usageRatio < config.contextWindow.criticalThreshold) {
       return `Context: ${remaining}% remaining. Plenty of room - don't rush.`;
     }
 
@@ -40,7 +35,7 @@ export function createContextWindowMonitorHook(ctx: PluginInput) {
     ) => {
       const usageRatio = state.lastUsageRatio.get(input.sessionID);
 
-      if (usageRatio && usageRatio >= WARNING_THRESHOLD) {
+      if (usageRatio && usageRatio >= config.contextWindow.warningThreshold) {
         const message = getEncouragementMessage(usageRatio);
         if (message && output.system) {
           output.system = `${output.system}\n\n<context-status>${message}</context-status>`;
@@ -80,13 +75,13 @@ export function createContextWindowMonitorHook(ctx: PluginInput) {
         state.lastUsageRatio.set(sessionID, usageRatio);
 
         // Show toast warning if threshold crossed
-        if (usageRatio >= WARNING_THRESHOLD) {
+        if (usageRatio >= config.contextWindow.warningThreshold) {
           const lastWarning = state.lastWarningTime.get(sessionID) || 0;
-          if (Date.now() - lastWarning > WARNING_COOLDOWN_MS) {
+          if (Date.now() - lastWarning > config.contextWindow.warningCooldownMs) {
             state.lastWarningTime.set(sessionID, Date.now());
 
             const remaining = Math.round((1 - usageRatio) * 100);
-            const variant = usageRatio >= CRITICAL_THRESHOLD ? "warning" : "info";
+            const variant = usageRatio >= config.contextWindow.criticalThreshold ? "warning" : "info";
 
             await ctx.client.tui
               .showToast({
@@ -94,7 +89,7 @@ export function createContextWindowMonitorHook(ctx: PluginInput) {
                   title: "Context Window",
                   message: `${remaining}% remaining (${Math.round(totalUsed / 1000)}K / ${Math.round(contextLimit / 1000)}K tokens)`,
                   variant,
-                  duration: 4000,
+                  duration: config.timeouts.toastWarningMs,
                 },
               })
               .catch(() => {});
diff --git a/src/hooks/ledger-loader.ts b/src/hooks/ledger-loader.ts
index ad26c1b..31703bd 100644
--- a/src/hooks/ledger-loader.ts
+++ b/src/hooks/ledger-loader.ts
@@ -2,9 +2,7 @@
 import type { PluginInput } from "@opencode-ai/plugin";
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
-
-const LEDGER_DIR = "thoughts/ledgers";
-const LEDGER_PREFIX = "CONTINUITY_";
+import { config } from "../utils/config";
 
 export interface LedgerInfo {
   sessionName: string;
@@ -13,11 +11,11 @@ export interface LedgerInfo {
 }
 
 export async function findCurrentLedger(directory: string): Promise<LedgerInfo | null> {
-  const ledgerDir = join(directory, LEDGER_DIR);
+  const ledgerDir = join(directory, config.paths.ledgerDir);
 
   try {
     const files = await readdir(ledgerDir);
-    const ledgerFiles = files.filter((f) => f.startsWith(LEDGER_PREFIX) && f.endsWith(".md"));
+    const ledgerFiles = files.filter((f) => f.startsWith(config.paths.ledgerPrefix) && f.endsWith(".md"));
 
     if (ledgerFiles.length === 0) return null;
 
@@ -40,7 +38,7 @@ export async function findCurrentLedger(directory: string): Promise<LedgerInfo |
 
     const filePath = join(ledgerDir, latestFile);
     const content = await readFile(filePath, "utf-8");
-    const sessionName = latestFile.replace(LEDGER_PREFIX, "").replace(".md", "");
+    const sessionName = latestFile.replace(config.paths.ledgerPrefix, "").replace(".md", "");
 
     return { sessionName, filePath, content };
   } catch {
diff --git a/src/hooks/token-aware-truncation.ts b/src/hooks/token-aware-truncation.ts
index 3eec96c..d578390 100644
--- a/src/hooks/token-aware-truncation.ts
+++ b/src/hooks/token-aware-truncation.ts
@@ -1,23 +1,17 @@
 import type { PluginInput } from "@opencode-ai/plugin";
+import { config } from "../utils/config";
 
 // Tools that benefit from truncation
 const TRUNCATABLE_TOOLS = ["grep", "Grep", "glob", "Glob", "ast_grep_search"];
 
-// Token estimation (conservative: 4 chars = 1 token)
-const CHARS_PER_TOKEN = 4;
-const DEFAULT_CONTEXT_LIMIT = 200_000;
-const DEFAULT_MAX_OUTPUT_TOKENS = 50_000;
-const SAFETY_MARGIN = 0.5; // Keep 50% headroom
-const PRESERVE_HEADER_LINES = 3;
-
 function estimateTokens(text: string): number {
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
+  return Math.ceil(text.length / config.tokens.charsPerToken);
 }
 
 function truncateToTokenLimit(
   output: string,
   maxTokens: number,
-  preserveLines: number = PRESERVE_HEADER_LINES,
+  preserveLines: number = config.tokens.preserveHeaderLines,
 ): string {
   const currentTokens = estimateTokens(output);
 
@@ -85,7 +79,7 @@ export function createTokenAwareTruncationHook(ctx: PluginInput) {
 
       const messages = (resp as { data?: unknown[] }).data;
       if (!Array.isArray(messages) || messages.length === 0) {
-        return { used: 0, limit: DEFAULT_CONTEXT_LIMIT };
+        return { used: 0, limit: config.tokens.defaultContextLimit };
       }
 
       // Find last assistant message with usage info
@@ -96,7 +90,7 @@ export function createTokenAwareTruncationHook(ctx: PluginInput) {
       }) as Record<string, unknown> | undefined;
 
       if (!lastAssistant) {
-        return { used: 0, limit: DEFAULT_CONTEXT_LIMIT };
+        return { used: 0, limit: config.tokens.defaultContextLimit };
       }
 
       const info = lastAssistant.info as Record<string, unknown> | undefined;
@@ -107,25 +101,25 @@ export function createTokenAwareTruncationHook(ctx: PluginInput) {
       const used = inputTokens + cacheRead;
 
       // Get model limit (simplified - use default for now)
-      const limit = DEFAULT_CONTEXT_LIMIT;
+      const limit = config.tokens.defaultContextLimit;
 
       const result = { used, limit };
       state.sessionTokenUsage.set(sessionID, result);
       return result;
     } catch {
-      return state.sessionTokenUsage.get(sessionID) || { used: 0, limit: DEFAULT_CONTEXT_LIMIT };
+      return state.sessionTokenUsage.get(sessionID) || { used: 0, limit: config.tokens.defaultContextLimit };
     }
   }
 
   function calculateMaxOutputTokens(used: number, limit: number): number {
     const remaining = limit - used;
-    const available = Math.floor(remaining * SAFETY_MARGIN);
+    const available = Math.floor(remaining * config.tokens.safetyMargin);
 
     if (available <= 0) {
       return 0;
     }
 
-    return Math.min(available, DEFAULT_MAX_OUTPUT_TOKENS);
+    return Math.min(available, config.tokens.defaultMaxOutputTokens);
   }
 
   return {
@@ -180,8 +174,8 @@ export function createTokenAwareTruncationHook(ctx: PluginInput) {
       } catch {
         // On error, apply static truncation as fallback
         const currentTokens = estimateTokens(output.output);
-        if (currentTokens > DEFAULT_MAX_OUTPUT_TOKENS) {
-          output.output = truncateToTokenLimit(output.output, DEFAULT_MAX_OUTPUT_TOKENS);
+        if (currentTokens > config.tokens.defaultMaxOutputTokens) {
+          output.output = truncateToTokenLimit(output.output, config.tokens.defaultMaxOutputTokens);
         }
       }
     },
diff --git a/src/tools/spawn-agent.ts b/src/tools/spawn-agent.ts
index 68bf2d9..adada0f 100644
--- a/src/tools/spawn-agent.ts
+++ b/src/tools/spawn-agent.ts
@@ -63,9 +63,7 @@ For parallel execution, call spawn_agent multiple times in ONE message.`,
 
         // Find the last assistant message
         const messages = messagesResp.data || [];
-        const lastAssistant = messages
-          .filter((m) => m.info?.role === "assistant")
-          .pop();
+        const lastAssistant = messages.filter((m) => m.info?.role === "assistant").pop();
 
         const result =
           lastAssistant?.parts

From 05f2ad66eadade71bf63ede4909b4105c3722829 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 16:19:41 +0200
Subject: [PATCH 08/22] docs: add milestone artifact indexing design

---
 ...1-16-milestone-artifact-indexing-design.md | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md

diff --git a/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md b/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
new file mode 100644
index 0000000..02671d0
--- /dev/null
+++ b/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
@@ -0,0 +1,54 @@
+---
+title: Milestone Artifact Indexing Design
+date: 2026-01-16
+status: draft
+---
+
+# Problem Statement
+We need a milestone-driven artifact indexing strategy that supports reliable search and retrieval while keeping legacy plan/ledger indexing behavior unchanged.
+
+# Constraints
+- Milestone-driven artifacts are stored only in SQLite.
+- Do not link to milestone summaries.
+- Legacy plan/ledger indexing remains untouched.
+
+# Approach
+Introduce a classifier that selects exactly one artifact type per milestone-driven artifact using clear criteria. The selected type is stored alongside metadata, and the milestone identifier is saved in the artifact metadata for downstream filtering and retrieval.
+
+# Architecture
+Artifacts are stored in SQLite with a classifier-driven type field and metadata payload. The indexing pipeline is isolated from legacy plan/ledger indexing to avoid behavioral changes.
+
+# Components
+- SQLite artifact store (milestone-driven artifacts only).
+- Classification agent that assigns a single artifact type.
+- Indexing pipeline that writes metadata, type, and payload.
+- Search/query layer that filters by milestone metadata.
+
+# Metadata Fields
+- milestone_id
+- artifact_type
+- source_session_id
+- created_at
+- tags
+
+# Data Flow
+1. Artifact ingested for a milestone.
+2. Classification agent selects one type using criteria:
+   - Prefer feature over decision over session when multiple criteria match.
+3. Artifact metadata is persisted with the milestone identifier.
+4. Artifact is written to SQLite for indexing and search.
+
+# Error Handling
+- If classification fails, fall back to storing the artifact as a session artifact.
+- Log the classification failure for follow-up without blocking ingestion.
+
+# Testing Strategy
+- Classification agent chooses a single type and respects the feature > decision > session tie-break.
+- End-to-end flow persists milestone metadata and stores artifacts in SQLite.
+- Search filters by milestone metadata and returns only indexed artifacts.
+- Error paths cover classifier failures and the session fallback behavior.
+
+# Open Questions
+- What criteria should the classifier use to distinguish feature versus decision when both are plausible?
+- Should milestone metadata include a normalized milestone slug in addition to the identifier?
+- Do we need a backfill path for previously ingested milestone artifacts?

From 649caa8041c15bcd86044f36542752883f3150e7 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 16:22:05 +0200
Subject: [PATCH 09/22] docs(design): clarify milestone artifact classification

---
 ...-01-16-milestone-artifact-indexing-design.md | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md b/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
index 02671d0..3376309 100644
--- a/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
+++ b/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
@@ -13,7 +13,7 @@ We need a milestone-driven artifact indexing strategy that supports reliable sea
 - Legacy plan/ledger indexing remains untouched.
 
 # Approach
-Introduce a classifier that selects exactly one artifact type per milestone-driven artifact using clear criteria. The selected type is stored alongside metadata, and the milestone identifier is saved in the artifact metadata for downstream filtering and retrieval.
+Introduce a classifier that selects exactly one artifact type per milestone-driven artifact using clear criteria. The selected type is stored alongside metadata, and the milestone identifier is saved in the artifact metadata for downstream filtering and retrieval. No milestone summary links are generated as part of this flow.
 
 # Architecture
 Artifacts are stored in SQLite with a classifier-driven type field and metadata payload. The indexing pipeline is isolated from legacy plan/ledger indexing to avoid behavioral changes.
@@ -25,7 +25,7 @@ Artifacts are stored in SQLite with a classifier-driven type field and metadata
 - Search/query layer that filters by milestone metadata.
 
 # Metadata Fields
-- milestone_id
+- milestone_id (stored in metadata for filtering and retrieval)
 - artifact_type
 - source_session_id
 - created_at
@@ -34,19 +34,22 @@ Artifacts are stored in SQLite with a classifier-driven type field and metadata
 # Data Flow
 1. Artifact ingested for a milestone.
 2. Classification agent selects one type using criteria:
+   - Feature: milestone content includes scoped implementation details, requirements, or capability changes.
+   - Decision: milestone content captures a resolved choice, trade-off, or rationale.
+   - Session: milestone content is primarily meeting notes, status updates, or discussion without a decision.
    - Prefer feature over decision over session when multiple criteria match.
 3. Artifact metadata is persisted with the milestone identifier.
 4. Artifact is written to SQLite for indexing and search.
 
 # Error Handling
-- If classification fails, fall back to storing the artifact as a session artifact.
+- If classification fails, fall back to storing the artifact as a session artifact (mandatory).
 - Log the classification failure for follow-up without blocking ingestion.
 
 # Testing Strategy
-- Classification agent chooses a single type and respects the feature > decision > session tie-break.
-- End-to-end flow persists milestone metadata and stores artifacts in SQLite.
-- Search filters by milestone metadata and returns only indexed artifacts.
-- Error paths cover classifier failures and the session fallback behavior.
+- Classification tests verify criteria for feature/decision/session and the tie-break behavior.
+- Flow tests validate ingest → classify → persist metadata → SQLite storage.
+- Search tests confirm milestone metadata filtering and indexed-only results.
+- Error path tests cover classifier failures, required session fallback, and logging.
 
 # Open Questions
 - What criteria should the classifier use to distinguish feature versus decision when both are plausible?

From 16207f43634c2bc8684d4a5775ec9528f59f0849 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 17:17:00 +0200
Subject: [PATCH 10/22] feat(indexing): add milestone artifact search tool

---
 src/index.ts                                  | 59 ++++++++++++-------
 src/tools/milestone-artifact-search.ts        | 48 +++++++++++++++
 tests/tools/milestone-artifact-search.test.ts | 10 ++++
 ...1-16-milestone-artifact-indexing-design.md | 24 +++++---
 4 files changed, 112 insertions(+), 29 deletions(-)
 create mode 100644 src/tools/milestone-artifact-search.ts
 create mode 100644 tests/tools/milestone-artifact-search.test.ts

diff --git a/src/index.ts b/src/index.ts
index 57e1ce1..fcdfbfb 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,30 +3,28 @@ import type { McpLocalConfig } from "@opencode-ai/sdk";
 
 // Agents
 import { agents, PRIMARY_AGENT_NAME } from "./agents";
-
-// Tools
-import { ast_grep_search, ast_grep_replace, checkAstGrepAvailable } from "./tools/ast-grep";
-import { btca_ask, checkBtcaAvailable } from "./tools/btca";
-import { look_at } from "./tools/look-at";
-import { artifact_search } from "./tools/artifact-search";
-import { createSpawnAgentTool } from "./tools/spawn-agent";
-
+// Config loader
+import { loadMicodeConfig, mergeAgentConfigs, validateAgentModels } from "./config-loader";
+import { createArtifactAutoIndexHook } from "./hooks/artifact-auto-index";
 // Hooks
 import { createAutoCompactHook } from "./hooks/auto-compact";
+import { createCommentCheckerHook } from "./hooks/comment-checker";
 import { createContextInjectorHook } from "./hooks/context-injector";
-import { createSessionRecoveryHook } from "./hooks/session-recovery";
-import { createTokenAwareTruncationHook } from "./hooks/token-aware-truncation";
 import { createContextWindowMonitorHook } from "./hooks/context-window-monitor";
-import { createCommentCheckerHook } from "./hooks/comment-checker";
-import { createLedgerLoaderHook } from "./hooks/ledger-loader";
-import { createArtifactAutoIndexHook } from "./hooks/artifact-auto-index";
 import { createFileOpsTrackerHook, getFileOps } from "./hooks/file-ops-tracker";
-
+import { createLedgerLoaderHook } from "./hooks/ledger-loader";
+import { createSessionRecoveryHook } from "./hooks/session-recovery";
+import { createTokenAwareTruncationHook } from "./hooks/token-aware-truncation";
+import { artifact_search } from "./tools/artifact-search";
+// Tools
+import { ast_grep_replace, ast_grep_search, checkAstGrepAvailable } from "./tools/ast-grep";
+import { btca_ask, checkBtcaAvailable } from "./tools/btca";
+import { look_at } from "./tools/look-at";
+import { milestone_artifact_search } from "./tools/milestone-artifact-search";
+import { createOcttoTools, createSessionStore } from "./tools/octto";
 // PTY System
-import { PTYManager, createPtyTools } from "./tools/pty";
-
-// Config loader
-import { loadMicodeConfig, mergeAgentConfigs, validateAgentModels } from "./config-loader";
+import { createPtyTools, PTYManager } from "./tools/pty";
+import { createSpawnAgentTool } from "./tools/spawn-agent";
 
 // Think mode: detect keywords and enable extended thinking
 const THINK_KEYWORDS = [
@@ -111,6 +109,13 @@ const OpenCodeConfigPlugin: Plugin = async (ctx) => {
   // Spawn agent tool (for subagents to spawn other subagents)
   const spawn_agent = createSpawnAgentTool(ctx);
 
+  // Octto (browser-based brainstorming) tools
+  const octtoSessionStore = createSessionStore();
+  const octtoTools = createOcttoTools(octtoSessionStore, ctx.client);
+
+  // Track octto sessions per opencode session for cleanup
+  const octtoSessionsMap = new Map<string, Set<string>>();
+
   return {
     // Tools
     tool: {
@@ -119,8 +124,10 @@ const OpenCodeConfigPlugin: Plugin = async (ctx) => {
       btca_ask,
       look_at,
       artifact_search,
+      milestone_artifact_search,
       spawn_agent,
       ...ptyTools,
+      ...octtoTools,
     },
 
     config: async (config) => {
@@ -304,12 +311,22 @@ IMPORTANT:
     },
 
     event: async ({ event }) => {
-      // Session cleanup (think mode + PTY)
+      // Session cleanup (think mode + PTY + octto)
       if (event.type === "session.deleted") {
         const props = event.properties as { info?: { id?: string } } | undefined;
         if (props?.info?.id) {
-          thinkModeState.delete(props.info.id);
-          ptyManager.cleanupBySession(props.info.id);
+          const sessionId = props.info.id;
+          thinkModeState.delete(sessionId);
+          ptyManager.cleanupBySession(sessionId);
+
+          // Cleanup octto sessions
+          const octtoSessions = octtoSessionsMap.get(sessionId);
+          if (octtoSessions) {
+            for (const octtoSessionId of octtoSessions) {
+              await octtoSessionStore.endSession(octtoSessionId).catch(() => {});
+            }
+            octtoSessionsMap.delete(sessionId);
+          }
         }
       }
 
diff --git a/src/tools/milestone-artifact-search.ts b/src/tools/milestone-artifact-search.ts
new file mode 100644
index 0000000..6b1d0e5
--- /dev/null
+++ b/src/tools/milestone-artifact-search.ts
@@ -0,0 +1,48 @@
+import { tool } from "@opencode-ai/plugin/tool";
+
+import { getArtifactIndex } from "./artifact-index";
+
+const ARTIFACT_TYPES = ["feature", "decision", "session"] as const;
+
+export const milestone_artifact_search = tool({
+  description: `Search milestone-driven artifacts stored in SQLite.
+Use this to find feature, decision, or session artifacts for a specific milestone.
+Returns ranked results filtered by milestone metadata.`,
+  args: {
+    query: tool.schema.string().describe("Search query for milestone artifacts"),
+    milestone_id: tool.schema.string().optional().describe("Optional milestone identifier to filter results"),
+    artifact_type: tool.schema.enum(ARTIFACT_TYPES).optional().describe("Optional artifact type to filter results"),
+    limit: tool.schema.number().optional().describe("Max results to return (default: 10)"),
+  },
+  execute: async (args) => {
+    try {
+      const index = await getArtifactIndex();
+      const results = await index.searchMilestoneArtifacts(args.query, {
+        milestoneId: args.milestone_id,
+        artifactType: args.artifact_type,
+        limit: args.limit,
+      });
+
+      if (results.length === 0) {
+        return "No milestone artifact results found for that query.";
+      }
+
+      let output = `## Milestone Artifact Search Results\n\nFound ${results.length} result(s).\n\n`;
+
+      for (const result of results) {
+        const tags = result.tags.length ? result.tags.join(", ") : "none";
+        output += `### ${result.milestoneId} · ${result.artifactType}\n`;
+        output += `- ID: ${result.id}\n`;
+        output += `- Source Session: ${result.sourceSessionId ?? "unknown"}\n`;
+        output += `- Created: ${result.createdAt ?? "unknown"}\n`;
+        output += `- Tags: ${tags}\n`;
+        output += `- Payload: ${result.payload}\n`;
+        output += `- Score: ${result.score.toFixed(2)}\n\n`;
+      }
+
+      return output;
+    } catch (error) {
+      return `Error searching milestone artifacts: ${error instanceof Error ? error.message : String(error)}`;
+    }
+  },
+});
diff --git a/tests/tools/milestone-artifact-search.test.ts b/tests/tools/milestone-artifact-search.test.ts
new file mode 100644
index 0000000..07df8a4
--- /dev/null
+++ b/tests/tools/milestone-artifact-search.test.ts
@@ -0,0 +1,10 @@
+import { describe, expect, it } from "bun:test";
+
+describe("milestone-artifact-search tool", () => {
+  it("defines milestone_id and artifact_type args", async () => {
+    const fs = await import("node:fs/promises");
+    const source = await fs.readFile("src/tools/milestone-artifact-search.ts", "utf-8");
+    expect(source).toContain("milestone_id");
+    expect(source).toContain("artifact_type");
+  });
+});
diff --git a/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md b/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
index 3376309..abe1f26 100644
--- a/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
+++ b/thoughts/shared/designs/2026-01-16-milestone-artifact-indexing-design.md
@@ -13,10 +13,10 @@ We need a milestone-driven artifact indexing strategy that supports reliable sea
 - Legacy plan/ledger indexing remains untouched.
 
 # Approach
-Introduce a classifier that selects exactly one artifact type per milestone-driven artifact using clear criteria. The selected type is stored alongside metadata, and the milestone identifier is saved in the artifact metadata for downstream filtering and retrieval. No milestone summary links are generated as part of this flow.
+Introduce a classifier that selects exactly one artifact type per milestone-driven artifact using clear criteria and an explicit tie-break order (feature > decision > session). The selected type is stored alongside metadata, and the milestone identifier is saved in the artifact metadata for downstream filtering and retrieval. No milestone summary links are generated as part of this flow.
 
 # Architecture
-Artifacts are stored in SQLite with a classifier-driven type field and metadata payload. The indexing pipeline is isolated from legacy plan/ledger indexing to avoid behavioral changes.
+All milestone-driven artifacts are stored only in SQLite with a classifier-driven type field and metadata payload. The indexing pipeline is isolated from legacy plan/ledger indexing to avoid behavioral changes.
 
 # Components
 - SQLite artifact store (milestone-driven artifacts only).
@@ -31,25 +31,33 @@ Artifacts are stored in SQLite with a classifier-driven type field and metadata
 - created_at
 - tags
 
+# Metadata Fields (Explicit)
+- milestone_id (stored in metadata for filtering and retrieval)
+- artifact_type
+- source_session_id
+- created_at
+- tags
+
 # Data Flow
 1. Artifact ingested for a milestone.
-2. Classification agent selects one type using criteria:
+2. Classification agent selects exactly one type using criteria:
    - Feature: milestone content includes scoped implementation details, requirements, or capability changes.
    - Decision: milestone content captures a resolved choice, trade-off, or rationale.
    - Session: milestone content is primarily meeting notes, status updates, or discussion without a decision.
-   - Prefer feature over decision over session when multiple criteria match.
+   - Tie-break: prefer feature over decision over session when multiple criteria match.
 3. Artifact metadata is persisted with the milestone identifier.
 4. Artifact is written to SQLite for indexing and search.
 
 # Error Handling
 - If classification fails, fall back to storing the artifact as a session artifact (mandatory).
+- Fallback to a session artifact on classifier failure is mandatory for all ingests.
 - Log the classification failure for follow-up without blocking ingestion.
 
 # Testing Strategy
-- Classification tests verify criteria for feature/decision/session and the tie-break behavior.
-- Flow tests validate ingest → classify → persist metadata → SQLite storage.
-- Search tests confirm milestone metadata filtering and indexed-only results.
-- Error path tests cover classifier failures, required session fallback, and logging.
+- Classification tests (e.g., `tests/indexing/classifier/*.test.ts`) verify criteria for feature/decision/session and the tie-break behavior.
+- Flow tests (e.g., `tests/indexing/flows/milestone-ingest.test.ts`) validate ingest → classify → persist metadata → SQLite storage.
+- Search tests (e.g., `tests/indexing/search/milestone-search.test.ts`) confirm milestone metadata filtering and indexed-only results.
+- Error path tests (e.g., `tests/indexing/flows/milestone-error-paths.test.ts`) cover classifier failures, required session fallback, and logging.
 
 # Open Questions
 - What criteria should the classifier use to distinguish feature versus decision when both are plausible?

From 4db82b695b32e041e6d30bbca60b2dcef3e235d2 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Fri, 16 Jan 2026 19:25:33 +0200
Subject: [PATCH 11/22] feat(octto): add browser-based brainstorming system

Integrate octto (interactive browser-based brainstorming) into micode
as a separate primary agent alongside the existing brainstormer.

Infrastructure (src/octto/):
- session/: HTTP server + WebSocket for browser communication
- state/: Brainstorm state persistence to thoughts/brainstorms/
- ui/: Self-contained HTML/CSS/JS bundle for browser UI
- types.ts: 15+ question type configurations

Tools (src/tools/octto/):
- brainstorm.ts: create_brainstorm, await_brainstorm_complete, end_brainstorm
- questions.ts: 15 question type tools (pick_one, confirm, slider, etc.)
- responses.ts: get_answer, get_next_answer, list_questions
- session.ts: start_session, end_session
- processor.ts: Answer processing with probe agent integration

Agents (src/agents/):
- octto.ts: Primary orchestrator for brainstorm sessions
- bootstrapper.ts: Creates 2-4 exploration branches from request
- probe.ts: Evaluates branch Q&A and generates follow-up questions

Config:
- Added octto section to src/utils/config.ts with timeouts and limits
- ID generators moved to octto/session/utils.ts (single source of truth)
---
 src/agents/bootstrapper.ts     |  165 ++++
 src/agents/index.ts            |    9 +
 src/agents/octto.ts            |   71 ++
 src/agents/probe.ts            |  122 +++
 src/octto/constants.ts         |   20 +
 src/octto/session/browser.ts   |   32 +
 src/octto/session/index.ts     |   25 +
 src/octto/session/server.ts    |   88 ++
 src/octto/session/sessions.ts  |  383 ++++++++
 src/octto/session/types.ts     |  305 ++++++
 src/octto/session/utils.ts     |   25 +
 src/octto/session/waiter.ts    |  132 +++
 src/octto/state/index.ts       |    5 +
 src/octto/state/persistence.ts |   65 ++
 src/octto/state/store.ts       |  159 ++++
 src/octto/state/types.ts       |   51 +
 src/octto/types.ts             |  376 ++++++++
 src/octto/ui/bundle.ts         | 1599 ++++++++++++++++++++++++++++++++
 src/octto/ui/index.ts          |    2 +
 src/tools/octto/brainstorm.ts  |  325 +++++++
 src/tools/octto/extractor.ts   |   95 ++
 src/tools/octto/factory.ts     |   84 ++
 src/tools/octto/formatters.ts  |   59 ++
 src/tools/octto/index.ts       |   24 +
 src/tools/octto/processor.ts   |  165 ++++
 src/tools/octto/questions.ts   |  488 ++++++++++
 src/tools/octto/responses.ts   |  135 +++
 src/tools/octto/session.ts     |  104 +++
 src/tools/octto/types.ts       |   16 +
 src/tools/octto/utils.ts       |    4 +
 src/utils/config.ts            |   14 +
 31 files changed, 5147 insertions(+)
 create mode 100644 src/agents/bootstrapper.ts
 create mode 100644 src/agents/octto.ts
 create mode 100644 src/agents/probe.ts
 create mode 100644 src/octto/constants.ts
 create mode 100644 src/octto/session/browser.ts
 create mode 100644 src/octto/session/index.ts
 create mode 100644 src/octto/session/server.ts
 create mode 100644 src/octto/session/sessions.ts
 create mode 100644 src/octto/session/types.ts
 create mode 100644 src/octto/session/utils.ts
 create mode 100644 src/octto/session/waiter.ts
 create mode 100644 src/octto/state/index.ts
 create mode 100644 src/octto/state/persistence.ts
 create mode 100644 src/octto/state/store.ts
 create mode 100644 src/octto/state/types.ts
 create mode 100644 src/octto/types.ts
 create mode 100644 src/octto/ui/bundle.ts
 create mode 100644 src/octto/ui/index.ts
 create mode 100644 src/tools/octto/brainstorm.ts
 create mode 100644 src/tools/octto/extractor.ts
 create mode 100644 src/tools/octto/factory.ts
 create mode 100644 src/tools/octto/formatters.ts
 create mode 100644 src/tools/octto/index.ts
 create mode 100644 src/tools/octto/processor.ts
 create mode 100644 src/tools/octto/questions.ts
 create mode 100644 src/tools/octto/responses.ts
 create mode 100644 src/tools/octto/session.ts
 create mode 100644 src/tools/octto/types.ts
 create mode 100644 src/tools/octto/utils.ts

diff --git a/src/agents/bootstrapper.ts b/src/agents/bootstrapper.ts
new file mode 100644
index 0000000..301aae5
--- /dev/null
+++ b/src/agents/bootstrapper.ts
@@ -0,0 +1,165 @@
+// src/agents/bootstrapper.ts
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+export const bootstrapperAgent: AgentConfig = {
+  description: "Analyzes a request and creates exploration branches with scopes for octto brainstorming",
+  mode: "subagent",
+  model: "openai/gpt-5.2-codex",
+  temperature: 0.5,
+  prompt: `<purpose>
+Analyze the user's request and create 2-4 exploration branches.
+Each branch explores ONE specific aspect of the design.
+</purpose>
+
+<output-format>
+Return ONLY a JSON object. No markdown, no explanation.
+
+{
+  "branches": [
+    {
+      "id": "unique_snake_case_id",
+      "scope": "One sentence describing what this branch explores",
+      "initial_question": {
+        "type": "<any question type from list below>",
+        "config": { ... }
+      }
+    }
+  ]
+}
+</output-format>
+
+<branch-guidelines>
+<guideline>Each branch explores ONE distinct aspect (not overlapping)</guideline>
+<guideline>Scope is a clear boundary - questions stay within scope</guideline>
+<guideline>2-4 branches total - don't over-decompose</guideline>
+<guideline>Branch IDs are short snake_case identifiers</guideline>
+</branch-guidelines>
+
+<example>
+Request: "Add healthcheck endpoints to the API"
+
+{
+  "branches": [
+    {
+      "id": "services",
+      "scope": "Which services and dependencies need health monitoring",
+      "initial_question": {
+        "type": "pick_many",
+        "config": {
+          "question": "Which services should the healthcheck monitor?",
+          "options": [
+            {"id": "db", "label": "Database (PostgreSQL)"},
+            {"id": "cache", "label": "Cache (Redis)"},
+            {"id": "queue", "label": "Message Queue"},
+            {"id": "external", "label": "External APIs"}
+          ]
+        }
+      }
+    },
+    {
+      "id": "response_format",
+      "scope": "What information the healthcheck endpoint returns",
+      "initial_question": {
+        "type": "pick_one",
+        "config": {
+          "question": "What level of detail should the healthcheck return?",
+          "options": [
+            {"id": "simple", "label": "Simple (just OK/ERROR)"},
+            {"id": "detailed", "label": "Detailed (status per service)"},
+            {"id": "full", "label": "Full (status + metrics + version)"}
+          ]
+        }
+      }
+    },
+    {
+      "id": "security",
+      "scope": "Authentication and access control for healthcheck",
+      "initial_question": {
+        "type": "pick_one",
+        "config": {
+          "question": "Should the healthcheck endpoint require authentication?",
+          "options": [
+            {"id": "public", "label": "Public (no auth)"},
+            {"id": "internal", "label": "Internal only (IP whitelist)"},
+            {"id": "authenticated", "label": "Requires API key"}
+          ]
+        }
+      }
+    }
+  ]
+}
+</example>
+
+<question-types>
+<type name="pick_one">
+Single choice. config: { question, options: [{id, label, description?}], recommended?, context? }
+</type>
+
+<type name="pick_many">
+Multiple choice. config: { question, options: [{id, label, description?}], recommended?: string[], min?, max?, context? }
+</type>
+
+<type name="confirm">
+Yes/no. config: { question, context?, yesLabel?, noLabel?, allowCancel? }
+</type>
+
+<type name="ask_text">
+Free text. config: { question, placeholder?, context?, multiline? }
+</type>
+
+<type name="slider">
+Numeric range. config: { question, min, max, step?, defaultValue?, context? }
+</type>
+
+<type name="rank">
+Order items. config: { question, options: [{id, label, description?}], context? }
+</type>
+
+<type name="rate">
+Rate items (stars). config: { question, options: [{id, label, description?}], min?, max?, context? }
+</type>
+
+<type name="thumbs">
+Thumbs up/down. config: { question, context? }
+</type>
+
+<type name="show_options">
+Options with pros/cons. config: { question, options: [{id, label, description?, pros?: string[], cons?: string[]}], recommended?, allowFeedback?, context? }
+</type>
+
+<type name="show_diff">
+Code diff review. config: { question, before, after, filePath?, language? }
+</type>
+
+<type name="ask_code">
+Code input. config: { question, language?, placeholder?, context? }
+</type>
+
+<type name="ask_image">
+Image upload. config: { question, multiple?, maxImages?, context? }
+</type>
+
+<type name="ask_file">
+File upload. config: { question, multiple?, maxFiles?, accept?: string[], context? }
+</type>
+
+<type name="emoji_react">
+Emoji selection. config: { question, emojis?: string[], context? }
+</type>
+
+<type name="review_section">
+Section review. config: { question, content, context? }
+</type>
+
+<type name="show_plan">
+Plan review. config: { question, sections: [{id, title, content}] }
+</type>
+</question-types>
+
+<never-do>
+<forbidden>Never create more than 4 branches</forbidden>
+<forbidden>Never create overlapping scopes</forbidden>
+<forbidden>Never wrap output in markdown code blocks</forbidden>
+<forbidden>Never include text outside the JSON</forbidden>
+</never-do>`,
+};
diff --git a/src/agents/index.ts b/src/agents/index.ts
index f67877e..99cb308 100644
--- a/src/agents/index.ts
+++ b/src/agents/index.ts
@@ -1,5 +1,6 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
 import { brainstormerAgent } from "./brainstormer";
+import { bootstrapperAgent } from "./bootstrapper";
 import { codebaseLocatorAgent } from "./codebase-locator";
 import { codebaseAnalyzerAgent } from "./codebase-analyzer";
 import { patternFinderAgent } from "./pattern-finder";
@@ -11,10 +12,13 @@ import { primaryAgent, PRIMARY_AGENT_NAME } from "./commander";
 import { projectInitializerAgent } from "./project-initializer";
 import { ledgerCreatorAgent } from "./ledger-creator";
 import { artifactSearcherAgent } from "./artifact-searcher";
+import { octtoAgent } from "./octto";
+import { probeAgent } from "./probe";
 
 export const agents: Record<string, AgentConfig> = {
   [PRIMARY_AGENT_NAME]: primaryAgent,
   brainstormer: brainstormerAgent,
+  bootstrapper: bootstrapperAgent,
   "codebase-locator": codebaseLocatorAgent,
   "codebase-analyzer": codebaseAnalyzerAgent,
   "pattern-finder": patternFinderAgent,
@@ -25,12 +29,15 @@ export const agents: Record<string, AgentConfig> = {
   "project-initializer": projectInitializerAgent,
   "ledger-creator": ledgerCreatorAgent,
   "artifact-searcher": artifactSearcherAgent,
+  octto: octtoAgent,
+  probe: probeAgent,
 };
 
 export {
   primaryAgent,
   PRIMARY_AGENT_NAME,
   brainstormerAgent,
+  bootstrapperAgent,
   codebaseLocatorAgent,
   codebaseAnalyzerAgent,
   patternFinderAgent,
@@ -41,4 +48,6 @@ export {
   projectInitializerAgent,
   ledgerCreatorAgent,
   artifactSearcherAgent,
+  octtoAgent,
+  probeAgent,
 };
diff --git a/src/agents/octto.ts b/src/agents/octto.ts
new file mode 100644
index 0000000..d6c6ddb
--- /dev/null
+++ b/src/agents/octto.ts
@@ -0,0 +1,71 @@
+// src/agents/octto.ts
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+export const octtoAgent: AgentConfig = {
+  description: "Runs interactive browser-based brainstorming sessions using branch-based exploration",
+  mode: "primary",
+  model: "openai/gpt-5.2-codex",
+  temperature: 0.7,
+  prompt: `<environment>
+You are running as part of the "micode" OpenCode plugin (NOT Claude Code).
+OpenCode is a different platform with its own agent system.
+This agent uses browser-based interactive UI for brainstorming sessions.
+</environment>
+
+<purpose>
+Run brainstorming sessions using branch-based exploration.
+Each branch explores one aspect of the design within its scope.
+Opens a browser window where users answer questions interactively.
+</purpose>
+
+<workflow>
+<step number="1" name="bootstrap">
+Call bootstrapper subagent to create branches:
+background_task(agent="bootstrapper", prompt="Create branches for: {request}")
+Parse the JSON response to get branches array.
+</step>
+
+<step number="2" name="create-session">
+Create brainstorm session with the branches:
+create_brainstorm(request="{request}", branches=[...parsed branches...])
+Save the session_id and browser_session_id from the response.
+</step>
+
+<step number="3" name="await-completion">
+Wait for brainstorm to complete (handles everything automatically):
+await_brainstorm_complete(session_id, browser_session_id)
+This processes all answers asynchronously and returns when all branches are done.
+</step>
+
+<step number="4" name="finalize">
+End the session and write design document:
+end_brainstorm(session_id)
+Write to thoughts/shared/plans/YYYY-MM-DD-{topic}-design.md
+</step>
+</workflow>
+
+<tools>
+<tool name="create_brainstorm" args="request, branches">Start session with branches, returns session_id AND browser_session_id</tool>
+<tool name="await_brainstorm_complete" args="session_id, browser_session_id">Wait for all branches to complete - handles answer processing automatically</tool>
+<tool name="end_brainstorm" args="session_id">End session and get final findings</tool>
+</tools>
+
+<critical-rules>
+<rule>You MUST use create_brainstorm to start sessions - it creates the state file for branch tracking</rule>
+<rule>The bootstrapper returns {"branches": [...]} - pass this directly to create_brainstorm</rule>
+<rule>create_brainstorm returns TWO IDs: session_id (for state) and browser_session_id (for await_brainstorm_complete)</rule>
+<rule>await_brainstorm_complete handles all answer processing - no manual loop needed</rule>
+</critical-rules>
+
+<never-do>
+<forbidden>NEVER use start_session directly - always use create_brainstorm</forbidden>
+<forbidden>NEVER manually loop with get_next_answer - use await_brainstorm_complete instead</forbidden>
+</never-do>
+
+<design-document-format>
+After end_brainstorm, write to thoughts/shared/plans/YYYY-MM-DD-{topic}-design.md with:
+<section name="problem">Problem statement from original request</section>
+<section name="findings">Findings by branch - each branch's finding</section>
+<section name="recommendation">Recommended approach - synthesize all findings</section>
+</design-document-format>`,
+};
diff --git a/src/agents/probe.ts b/src/agents/probe.ts
new file mode 100644
index 0000000..c5b89eb
--- /dev/null
+++ b/src/agents/probe.ts
@@ -0,0 +1,122 @@
+// src/agents/probe.ts
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+export const probeAgent: AgentConfig = {
+  description: "Evaluates octto branch Q&A and decides whether to ask more or complete with finding",
+  mode: "subagent",
+  model: "openai/gpt-5.2-codex",
+  temperature: 0.5,
+  prompt: `<purpose>
+You evaluate a brainstorming branch's Q&A history and decide:
+1. Need more information? Return a follow-up question
+2. Have enough? Return a finding that synthesizes the user's preferences
+</purpose>
+
+<context>
+You receive:
+- The original user request
+- All branches with their scopes (to understand the full picture)
+- The Q&A history for the branch you're evaluating
+</context>
+
+<output-format>
+Return ONLY a JSON object. No markdown, no explanation.
+
+If MORE information needed:
+{
+  "done": false,
+  "question": {
+    "type": "pick_one|pick_many|...",
+    "config": { ... }
+  }
+}
+
+If ENOUGH information gathered:
+{
+  "done": true,
+  "finding": "Clear summary of what the user wants for this aspect"
+}
+</output-format>
+
+<guidance>
+<principle>Stay within the branch's scope - don't ask about other branches' concerns</principle>
+<principle>2-4 questions per branch is usually enough - be concise</principle>
+<principle>Complete when you understand the user's intent for this aspect</principle>
+<principle>Synthesize a finding that captures the decision/preference clearly</principle>
+<principle>Choose question types that best fit what you're trying to learn</principle>
+</guidance>
+
+<question-types>
+<type name="pick_one">
+Single choice. config: { question, options: [{id, label, description?}], recommended?, context? }
+</type>
+
+<type name="pick_many">
+Multiple choice. config: { question, options: [{id, label, description?}], recommended?: string[], min?, max?, context? }
+</type>
+
+<type name="confirm">
+Yes/no. config: { question, context?, yesLabel?, noLabel?, allowCancel? }
+</type>
+
+<type name="ask_text">
+Free text. config: { question, placeholder?, context?, multiline? }
+</type>
+
+<type name="slider">
+Numeric range. config: { question, min, max, step?, defaultValue?, context? }
+</type>
+
+<type name="rank">
+Order items. config: { question, options: [{id, label, description?}], context? }
+</type>
+
+<type name="rate">
+Rate items (stars). config: { question, options: [{id, label, description?}], min?, max?, context? }
+</type>
+
+<type name="thumbs">
+Thumbs up/down. config: { question, context? }
+</type>
+
+<type name="show_options">
+Options with pros/cons. config: { question, options: [{id, label, description?, pros?: string[], cons?: string[]}], recommended?, allowFeedback?, context? }
+</type>
+
+<type name="show_diff">
+Code diff review. config: { question, before, after, filePath?, language? }
+</type>
+
+<type name="ask_code">
+Code input. config: { question, language?, placeholder?, context? }
+</type>
+
+<type name="ask_image">
+Image upload. config: { question, multiple?, maxImages?, context? }
+</type>
+
+<type name="ask_file">
+File upload. config: { question, multiple?, maxFiles?, accept?: string[], context? }
+</type>
+
+<type name="emoji_react">
+Emoji selection. config: { question, emojis?: string[], context? }
+</type>
+
+<type name="review_section">
+Section review. config: { question, content, context? }
+</type>
+
+<type name="show_plan">
+Plan review. config: { question, sections: [{id, title, content}] }
+</type>
+</question-types>
+
+<never-do>
+<forbidden>Never ask questions outside the branch's scope</forbidden>
+<forbidden>Never ask more than needed - if you understand, complete the branch</forbidden>
+<forbidden>Never wrap output in markdown code blocks</forbidden>
+<forbidden>Never include text outside the JSON</forbidden>
+<forbidden>Never repeat questions that were already asked</forbidden>
+</never-do>`,
+};
diff --git a/src/octto/constants.ts b/src/octto/constants.ts
new file mode 100644
index 0000000..e016b67
--- /dev/null
+++ b/src/octto/constants.ts
@@ -0,0 +1,20 @@
+// src/octto/constants.ts
+// Re-exports from centralized config for backward compatibility
+// Single source of truth is in src/utils/config.ts
+
+import { config } from "../utils/config";
+
+/** Default timeout for waiting for user answers (5 minutes) */
+export const DEFAULT_ANSWER_TIMEOUT_MS = config.octto.answerTimeoutMs;
+
+/** Default maximum number of follow-up questions per branch */
+export const DEFAULT_MAX_QUESTIONS = 15;
+
+/** Default timeout for brainstorm review (10 minutes) */
+export const DEFAULT_REVIEW_TIMEOUT_MS = config.octto.reviewTimeoutMs;
+
+/** Maximum number of brainstorm iterations */
+export const MAX_ITERATIONS = config.octto.maxIterations;
+
+/** Directory for persisting brainstorm state files */
+export const STATE_DIR = config.octto.stateDir;
diff --git a/src/octto/session/browser.ts b/src/octto/session/browser.ts
new file mode 100644
index 0000000..6c44e00
--- /dev/null
+++ b/src/octto/session/browser.ts
@@ -0,0 +1,32 @@
+// src/octto/session/browser.ts
+// Cross-platform browser opener
+
+/**
+ * Opens the default browser to the specified URL.
+ * Detects platform and uses appropriate command.
+ */
+export async function openBrowser(url: string): Promise<void> {
+  const platform = process.platform;
+
+  let command: string[];
+
+  switch (platform) {
+    case "darwin":
+      command = ["open", url];
+      break;
+    case "win32":
+      command = ["cmd", "/c", "start", url];
+      break;
+    default:
+      // Linux and others
+      command = ["xdg-open", url];
+      break;
+  }
+
+  const proc = Bun.spawn(command, {
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+
+  await proc.exited;
+}
diff --git a/src/octto/session/index.ts b/src/octto/session/index.ts
new file mode 100644
index 0000000..0d4c431
--- /dev/null
+++ b/src/octto/session/index.ts
@@ -0,0 +1,25 @@
+// src/octto/session/index.ts
+export type { SessionStore, SessionStoreOptions } from "./sessions";
+export { createSessionStore } from "./sessions";
+export type {
+  Answer,
+  AskCodeAnswer,
+  AskFileAnswer,
+  AskImageAnswer,
+  AskTextAnswer,
+  BaseConfig,
+  ConfirmAnswer,
+  EmojiReactAnswer,
+  PickManyAnswer,
+  PickOneAnswer,
+  QuestionAnswers,
+  QuestionConfig,
+  QuestionType,
+  RankAnswer,
+  RateAnswer,
+  ReviewAnswer,
+  ShowOptionsAnswer,
+  SliderAnswer,
+  ThumbsAnswer,
+} from "./types";
+export { QUESTION_TYPES, QUESTIONS, STATUSES, WS_MESSAGES } from "./types";
diff --git a/src/octto/session/server.ts b/src/octto/session/server.ts
new file mode 100644
index 0000000..ecde39e
--- /dev/null
+++ b/src/octto/session/server.ts
@@ -0,0 +1,88 @@
+// src/octto/session/server.ts
+import type { Server, ServerWebSocket } from "bun";
+
+import { getHtmlBundle } from "../ui";
+
+import type { SessionStore } from "./sessions";
+import type { WsClientMessage } from "./types";
+
+interface WsData {
+  sessionId: string;
+}
+
+export async function createServer(
+  sessionId: string,
+  store: SessionStore,
+): Promise<{ server: Server<WsData>; port: number }> {
+  const htmlBundle = getHtmlBundle();
+
+  const server = Bun.serve<WsData>({
+    port: 0, // Random available port
+    fetch(req, server) {
+      const url = new URL(req.url);
+
+      // WebSocket upgrade
+      if (url.pathname === "/ws") {
+        const success = server.upgrade(req, {
+          data: { sessionId },
+        });
+        if (success) {
+          return undefined;
+        }
+        return new Response("WebSocket upgrade failed", { status: 400 });
+      }
+
+      // Serve the bundled HTML app
+      if (url.pathname === "/" || url.pathname === "/index.html") {
+        return new Response(htmlBundle, {
+          headers: {
+            "Content-Type": "text/html; charset=utf-8",
+          },
+        });
+      }
+
+      return new Response("Not Found", { status: 404 });
+    },
+    websocket: {
+      open(ws: ServerWebSocket<WsData>) {
+        const { sessionId } = ws.data;
+        store.handleWsConnect(sessionId, ws);
+      },
+      close(ws: ServerWebSocket<WsData>) {
+        const { sessionId } = ws.data;
+        store.handleWsDisconnect(sessionId);
+      },
+      message(ws: ServerWebSocket<WsData>, message: string | Buffer) {
+        const { sessionId } = ws.data;
+
+        let parsed: WsClientMessage;
+        try {
+          parsed = JSON.parse(message.toString()) as WsClientMessage;
+        } catch (error) {
+          console.error("[octto] Failed to parse WebSocket message:", error);
+          ws.send(
+            JSON.stringify({
+              type: "error",
+              error: "Invalid message format",
+              details: error instanceof Error ? error.message : "Parse failed",
+            }),
+          );
+          return;
+        }
+
+        store.handleWsMessage(sessionId, parsed);
+      },
+    },
+  });
+
+  // Port is always defined when using port: 0
+  const port = server.port;
+  if (port === undefined) {
+    throw new Error("Failed to get server port");
+  }
+
+  return {
+    server,
+    port,
+  };
+}
diff --git a/src/octto/session/sessions.ts b/src/octto/session/sessions.ts
new file mode 100644
index 0000000..fac6f69
--- /dev/null
+++ b/src/octto/session/sessions.ts
@@ -0,0 +1,383 @@
+// src/octto/session/sessions.ts
+import type { ServerWebSocket } from "bun";
+
+import { DEFAULT_ANSWER_TIMEOUT_MS } from "../constants";
+import { generateQuestionId, generateSessionId } from "./utils";
+import { openBrowser } from "./browser";
+import { createServer } from "./server";
+import {
+  type Answer,
+  type BaseConfig,
+  type EndSessionOutput,
+  type GetAnswerInput,
+  type GetAnswerOutput,
+  type GetNextAnswerInput,
+  type GetNextAnswerOutput,
+  type ListQuestionsOutput,
+  type PushQuestionOutput,
+  type Question,
+  type QuestionType,
+  type Session,
+  STATUSES,
+  type StartSessionInput,
+  type StartSessionOutput,
+  WS_MESSAGES,
+  type WsClientMessage,
+  type WsServerMessage,
+} from "./types";
+import { createWaiters } from "./waiter";
+
+export interface SessionStoreOptions {
+  /** Skip opening browser - useful for tests */
+  skipBrowser?: boolean;
+}
+
+export interface SessionStore {
+  startSession: (input: StartSessionInput) => Promise<StartSessionOutput>;
+  endSession: (sessionId: string) => Promise<EndSessionOutput>;
+  pushQuestion: (sessionId: string, type: QuestionType, config: BaseConfig) => PushQuestionOutput;
+  getAnswer: (input: GetAnswerInput) => Promise<GetAnswerOutput>;
+  getNextAnswer: (input: GetNextAnswerInput) => Promise<GetNextAnswerOutput>;
+  cancelQuestion: (questionId: string) => { ok: boolean };
+  listQuestions: (sessionId?: string) => ListQuestionsOutput;
+  handleWsConnect: (sessionId: string, ws: ServerWebSocket<unknown>) => void;
+  handleWsDisconnect: (sessionId: string) => void;
+  handleWsMessage: (sessionId: string, message: WsClientMessage) => void;
+  getSession: (sessionId: string) => Session | undefined;
+  cleanup: () => Promise<void>;
+}
+
+export function createSessionStore(options: SessionStoreOptions = {}): SessionStore {
+  const sessions = new Map<string, Session>();
+  const questionToSession = new Map<string, string>();
+  const responseWaiters = createWaiters<string, Answer | { cancelled: true }>();
+  const sessionWaiters = createWaiters<string, { questionId: string; response: Answer }>();
+
+  const store: SessionStore = {
+    async startSession(input: StartSessionInput): Promise<StartSessionOutput> {
+      const sessionId = generateSessionId();
+      const { server, port } = await createServer(sessionId, store);
+      const url = `http://localhost:${port}`;
+
+      const session: Session = {
+        id: sessionId,
+        title: input.title,
+        port,
+        url,
+        createdAt: new Date(),
+        questions: new Map(),
+        wsConnected: false,
+        server,
+      };
+      sessions.set(sessionId, session);
+
+      const questionIds = (input.questions ?? []).map((q) => {
+        const questionId = generateQuestionId();
+        const question: Question = {
+          id: questionId,
+          sessionId,
+          type: q.type,
+          config: q.config,
+          status: STATUSES.PENDING,
+          createdAt: new Date(),
+        };
+        session.questions.set(questionId, question);
+        questionToSession.set(questionId, sessionId);
+        return questionId;
+      });
+
+      if (!options.skipBrowser) {
+        await openBrowser(url).catch((error) => {
+          sessions.delete(sessionId);
+          for (const qId of questionIds) questionToSession.delete(qId);
+          server.stop();
+          throw error;
+        });
+      }
+
+      return {
+        session_id: sessionId,
+        url,
+        question_ids: questionIds.length > 0 ? questionIds : undefined,
+      };
+    },
+
+    async endSession(sessionId: string): Promise<EndSessionOutput> {
+      const session = sessions.get(sessionId);
+      if (!session) {
+        return { ok: false };
+      }
+
+      if (session.wsClient) {
+        const msg: WsServerMessage = { type: WS_MESSAGES.END };
+        session.wsClient.send(JSON.stringify(msg));
+      }
+
+      if (session.server) {
+        session.server.stop();
+      }
+
+      for (const questionId of session.questions.keys()) {
+        questionToSession.delete(questionId);
+        responseWaiters.clear(questionId);
+      }
+
+      sessions.delete(sessionId);
+      return { ok: true };
+    },
+
+    pushQuestion(sessionId: string, type: QuestionType, config: BaseConfig): PushQuestionOutput {
+      const session = sessions.get(sessionId);
+      if (!session) {
+        throw new Error(`Session not found: ${sessionId}`);
+      }
+
+      const questionId = generateQuestionId();
+
+      const question: Question = {
+        id: questionId,
+        sessionId,
+        type,
+        config,
+        status: STATUSES.PENDING,
+        createdAt: new Date(),
+      };
+
+      session.questions.set(questionId, question);
+      questionToSession.set(questionId, sessionId);
+
+      if (session.wsConnected && session.wsClient) {
+        const msg: WsServerMessage = {
+          type: WS_MESSAGES.QUESTION,
+          id: questionId,
+          questionType: type,
+          config,
+        };
+        session.wsClient.send(JSON.stringify(msg));
+      } else if (!options.skipBrowser) {
+        openBrowser(session.url).catch(console.error);
+      }
+
+      return { question_id: questionId };
+    },
+
+    async getAnswer(input: GetAnswerInput): Promise<GetAnswerOutput> {
+      const sessionId = questionToSession.get(input.question_id);
+      if (!sessionId) {
+        return { completed: false, status: STATUSES.CANCELLED, reason: STATUSES.CANCELLED };
+      }
+
+      const session = sessions.get(sessionId);
+      if (!session) {
+        return { completed: false, status: STATUSES.CANCELLED, reason: STATUSES.CANCELLED };
+      }
+
+      const question = session.questions.get(input.question_id);
+      if (!question) {
+        return { completed: false, status: STATUSES.CANCELLED, reason: STATUSES.CANCELLED };
+      }
+
+      if (question.status === STATUSES.ANSWERED) {
+        return { completed: true, status: STATUSES.ANSWERED, response: question.response };
+      }
+
+      if (question.status === STATUSES.CANCELLED || question.status === STATUSES.TIMEOUT) {
+        return { completed: false, status: question.status, reason: question.status };
+      }
+
+      if (!input.block) {
+        return { completed: false, status: STATUSES.PENDING, reason: STATUSES.PENDING };
+      }
+
+      const timeout = input.timeout ?? DEFAULT_ANSWER_TIMEOUT_MS;
+
+      return new Promise<GetAnswerOutput>((resolve) => {
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+        const cleanup = responseWaiters.register(input.question_id, (response) => {
+          if (timeoutId) clearTimeout(timeoutId);
+          if (response && typeof response === "object" && "cancelled" in response) {
+            resolve({ completed: false, status: STATUSES.CANCELLED, reason: STATUSES.CANCELLED });
+          } else {
+            resolve({ completed: true, status: STATUSES.ANSWERED, response });
+          }
+        });
+
+        timeoutId = setTimeout(() => {
+          cleanup();
+          question.status = STATUSES.TIMEOUT;
+          resolve({ completed: false, status: STATUSES.TIMEOUT, reason: STATUSES.TIMEOUT });
+        }, timeout);
+      });
+    },
+
+    async getNextAnswer(input: GetNextAnswerInput): Promise<GetNextAnswerOutput> {
+      const session = sessions.get(input.session_id);
+      if (!session) {
+        return { completed: false, status: STATUSES.NONE_PENDING, reason: STATUSES.NONE_PENDING };
+      }
+
+      for (const question of session.questions.values()) {
+        if (question.status === STATUSES.ANSWERED && !question.retrieved) {
+          question.retrieved = true;
+          return {
+            completed: true,
+            question_id: question.id,
+            question_type: question.type,
+            status: STATUSES.ANSWERED,
+            response: question.response,
+          };
+        }
+      }
+
+      const hasPending = Array.from(session.questions.values()).some((q) => q.status === STATUSES.PENDING);
+
+      if (!hasPending) {
+        return { completed: false, status: STATUSES.NONE_PENDING, reason: STATUSES.NONE_PENDING };
+      }
+
+      if (!input.block) {
+        return { completed: false, status: STATUSES.PENDING };
+      }
+
+      const timeout = input.timeout ?? DEFAULT_ANSWER_TIMEOUT_MS;
+
+      return new Promise<GetNextAnswerOutput>((resolve) => {
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+        const cleanup = sessionWaiters.register(input.session_id, ({ questionId, response }) => {
+          if (timeoutId) clearTimeout(timeoutId);
+          const question = session.questions.get(questionId);
+          if (question) question.retrieved = true;
+          resolve({
+            completed: true,
+            question_id: questionId,
+            question_type: question?.type,
+            status: STATUSES.ANSWERED,
+            response,
+          });
+        });
+
+        timeoutId = setTimeout(() => {
+          cleanup();
+          resolve({ completed: false, status: STATUSES.TIMEOUT, reason: STATUSES.TIMEOUT });
+        }, timeout);
+      });
+    },
+
+    cancelQuestion(questionId: string): { ok: boolean } {
+      const sessionId = questionToSession.get(questionId);
+      if (!sessionId) {
+        return { ok: false };
+      }
+
+      const session = sessions.get(sessionId);
+      if (!session) {
+        return { ok: false };
+      }
+
+      const question = session.questions.get(questionId);
+      if (!question || question.status !== STATUSES.PENDING) {
+        return { ok: false };
+      }
+
+      question.status = STATUSES.CANCELLED;
+
+      if (session.wsClient) {
+        const msg: WsServerMessage = { type: WS_MESSAGES.CANCEL, id: questionId };
+        session.wsClient.send(JSON.stringify(msg));
+      }
+
+      responseWaiters.notifyAll(questionId, { cancelled: true });
+
+      return { ok: true };
+    },
+
+    listQuestions(sessionId?: string): ListQuestionsOutput {
+      const questions: ListQuestionsOutput["questions"] = [];
+
+      const sessionsToCheck = sessionId ? [sessions.get(sessionId)].filter(Boolean) : Array.from(sessions.values());
+
+      for (const session of sessionsToCheck) {
+        if (!session) continue;
+        for (const question of session.questions.values()) {
+          questions.push({
+            id: question.id,
+            type: question.type,
+            status: question.status,
+            createdAt: question.createdAt.toISOString(),
+            answeredAt: question.answeredAt?.toISOString(),
+          });
+        }
+      }
+
+      questions.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+
+      return { questions };
+    },
+
+    handleWsConnect(sessionId: string, ws: ServerWebSocket<unknown>): void {
+      const session = sessions.get(sessionId);
+      if (!session) return;
+
+      session.wsConnected = true;
+      session.wsClient = ws;
+
+      for (const question of session.questions.values()) {
+        if (question.status === STATUSES.PENDING) {
+          const msg: WsServerMessage = {
+            type: WS_MESSAGES.QUESTION,
+            id: question.id,
+            questionType: question.type,
+            config: question.config,
+          };
+          ws.send(JSON.stringify(msg));
+        }
+      }
+    },
+
+    handleWsDisconnect(sessionId: string): void {
+      const session = sessions.get(sessionId);
+      if (!session) return;
+
+      session.wsConnected = false;
+      session.wsClient = undefined;
+    },
+
+    handleWsMessage(sessionId: string, message: WsClientMessage): void {
+      if (message.type === WS_MESSAGES.CONNECTED) {
+        return;
+      }
+
+      if (message.type === WS_MESSAGES.RESPONSE) {
+        const session = sessions.get(sessionId);
+        if (!session) return;
+
+        const question = session.questions.get(message.id);
+        if (!question || question.status !== STATUSES.PENDING) return;
+
+        question.status = STATUSES.ANSWERED;
+        question.answeredAt = new Date();
+        question.response = message.answer;
+
+        responseWaiters.notifyAll(message.id, message.answer);
+        sessionWaiters.notifyFirst(sessionId, {
+          questionId: message.id,
+          response: message.answer,
+        });
+      }
+    },
+
+    getSession(sessionId: string): Session | undefined {
+      return sessions.get(sessionId);
+    },
+
+    async cleanup(): Promise<void> {
+      for (const sessionId of sessions.keys()) {
+        await store.endSession(sessionId);
+      }
+    },
+  };
+
+  return store;
+}
diff --git a/src/octto/session/types.ts b/src/octto/session/types.ts
new file mode 100644
index 0000000..e236257
--- /dev/null
+++ b/src/octto/session/types.ts
@@ -0,0 +1,305 @@
+// src/octto/session/types.ts
+// Session and Question types for the octto module
+import type { ServerWebSocket } from "bun";
+
+import type {
+  AskCodeConfig,
+  AskFileConfig,
+  AskImageConfig,
+  AskTextConfig,
+  ConfirmConfig,
+  EmojiReactConfig,
+  PickManyConfig,
+  PickOneConfig,
+  RankConfig,
+  RateConfig,
+  ReviewSectionConfig,
+  ShowDiffConfig,
+  ShowOptionsConfig,
+  ShowPlanConfig,
+  SliderConfig,
+  ThumbsConfig,
+} from "../types";
+
+export const STATUSES = {
+  PENDING: "pending",
+  ANSWERED: "answered",
+  CANCELLED: "cancelled",
+  TIMEOUT: "timeout",
+  NONE_PENDING: "none_pending",
+} as const;
+
+export type QuestionStatus = (typeof STATUSES)[Exclude<keyof typeof STATUSES, "NONE_PENDING">];
+
+export interface Question {
+  id: string;
+  sessionId: string;
+  type: QuestionType;
+  config: BaseConfig;
+  status: QuestionStatus;
+  createdAt: Date;
+  answeredAt?: Date;
+  response?: Answer;
+  /** True if this answer was already returned via get_next_answer */
+  retrieved?: boolean;
+}
+
+export const QUESTIONS = {
+  PICK_ONE: "pick_one",
+  PICK_MANY: "pick_many",
+  CONFIRM: "confirm",
+  RANK: "rank",
+  RATE: "rate",
+  ASK_TEXT: "ask_text",
+  ASK_IMAGE: "ask_image",
+  ASK_FILE: "ask_file",
+  ASK_CODE: "ask_code",
+  SHOW_DIFF: "show_diff",
+  SHOW_PLAN: "show_plan",
+  SHOW_OPTIONS: "show_options",
+  REVIEW_SECTION: "review_section",
+  THUMBS: "thumbs",
+  EMOJI_REACT: "emoji_react",
+  SLIDER: "slider",
+} as const;
+
+export type QuestionType = (typeof QUESTIONS)[keyof typeof QUESTIONS];
+export const QUESTION_TYPES = Object.values(QUESTIONS);
+
+// --- Answer Types ---
+
+export interface PickOneAnswer {
+  selected: string;
+}
+
+export interface PickManyAnswer {
+  selected: string[];
+}
+
+export interface ConfirmAnswer {
+  choice: "yes" | "no" | "cancel";
+}
+
+export interface ThumbsAnswer {
+  choice: "up" | "down";
+}
+
+export interface EmojiReactAnswer {
+  emoji: string;
+}
+
+export interface AskTextAnswer {
+  text: string;
+}
+
+export interface SliderAnswer {
+  value: number;
+}
+
+export interface RankAnswer {
+  ranking: Array<{ id: string; rank: number }>;
+}
+
+export interface RateAnswer {
+  ratings: Record<string, number>;
+}
+
+export interface AskCodeAnswer {
+  code: string;
+}
+
+export interface AskImageAnswer {
+  images: Array<{ name: string; data: string; type: string }>;
+}
+
+export interface AskFileAnswer {
+  files: Array<{ name: string; data: string; type: string }>;
+}
+
+export interface ReviewAnswer {
+  decision: string;
+  feedback?: string;
+}
+
+export interface ShowOptionsAnswer {
+  selected: string;
+  feedback?: string;
+}
+
+export type Answer =
+  | PickOneAnswer
+  | PickManyAnswer
+  | ConfirmAnswer
+  | ThumbsAnswer
+  | EmojiReactAnswer
+  | AskTextAnswer
+  | SliderAnswer
+  | RankAnswer
+  | RateAnswer
+  | AskCodeAnswer
+  | AskImageAnswer
+  | AskFileAnswer
+  | ReviewAnswer
+  | ShowOptionsAnswer;
+
+export interface QuestionAnswers {
+  [QUESTIONS.PICK_ONE]: PickOneAnswer;
+  [QUESTIONS.PICK_MANY]: PickManyAnswer;
+  [QUESTIONS.CONFIRM]: ConfirmAnswer;
+  [QUESTIONS.THUMBS]: ThumbsAnswer;
+  [QUESTIONS.EMOJI_REACT]: EmojiReactAnswer;
+  [QUESTIONS.ASK_TEXT]: AskTextAnswer;
+  [QUESTIONS.SLIDER]: SliderAnswer;
+  [QUESTIONS.RANK]: RankAnswer;
+  [QUESTIONS.RATE]: RateAnswer;
+  [QUESTIONS.ASK_CODE]: AskCodeAnswer;
+  [QUESTIONS.ASK_IMAGE]: AskImageAnswer;
+  [QUESTIONS.ASK_FILE]: AskFileAnswer;
+  [QUESTIONS.SHOW_DIFF]: ReviewAnswer;
+  [QUESTIONS.SHOW_PLAN]: ReviewAnswer;
+  [QUESTIONS.REVIEW_SECTION]: ReviewAnswer;
+  [QUESTIONS.SHOW_OPTIONS]: ShowOptionsAnswer;
+}
+
+export type QuestionConfig =
+  | PickOneConfig
+  | PickManyConfig
+  | ConfirmConfig
+  | RankConfig
+  | RateConfig
+  | AskTextConfig
+  | AskImageConfig
+  | AskFileConfig
+  | AskCodeConfig
+  | ShowDiffConfig
+  | ShowPlanConfig
+  | ShowOptionsConfig
+  | ReviewSectionConfig
+  | ThumbsConfig
+  | EmojiReactConfig
+  | SliderConfig;
+
+/** Config type for transit - accepts both strict QuestionConfig and loose objects */
+export type BaseConfig =
+  | QuestionConfig
+  | {
+      question?: string;
+      context?: string;
+      [key: string]: unknown;
+    };
+
+export interface Session {
+  id: string;
+  title?: string;
+  port: number;
+  url: string;
+  createdAt: Date;
+  questions: Map<string, Question>;
+  wsConnected: boolean;
+  server?: ReturnType<typeof Bun.serve>;
+  wsClient?: ServerWebSocket<unknown>;
+}
+
+export interface InitialQuestion {
+  type: QuestionType;
+  config: BaseConfig;
+}
+
+export interface StartSessionInput {
+  title?: string;
+  /** Initial questions to display immediately when browser opens */
+  questions?: InitialQuestion[];
+}
+
+export interface StartSessionOutput {
+  session_id: string;
+  url: string;
+  /** IDs of initial questions if any were provided */
+  question_ids?: string[];
+}
+
+export interface EndSessionOutput {
+  ok: boolean;
+}
+
+export interface PushQuestionOutput {
+  question_id: string;
+}
+
+export interface GetAnswerInput {
+  question_id: string;
+  block?: boolean;
+  timeout?: number;
+}
+
+export interface GetAnswerOutput {
+  completed: boolean;
+  status: QuestionStatus;
+  response?: Answer;
+  reason?: "timeout" | "cancelled" | "pending";
+}
+
+export interface GetNextAnswerInput {
+  session_id: string;
+  block?: boolean;
+  timeout?: number;
+}
+
+export type AnswerStatus = (typeof STATUSES)[keyof typeof STATUSES];
+
+export interface GetNextAnswerOutput {
+  completed: boolean;
+  question_id?: string;
+  question_type?: QuestionType;
+  status: AnswerStatus;
+  response?: Answer;
+  reason?: typeof STATUSES.TIMEOUT | typeof STATUSES.NONE_PENDING;
+}
+
+export interface ListQuestionsOutput {
+  questions: Array<{
+    id: string;
+    type: QuestionType;
+    status: QuestionStatus;
+    createdAt: string;
+    answeredAt?: string;
+  }>;
+}
+
+// WebSocket message types
+export const WS_MESSAGES = {
+  QUESTION: "question",
+  CANCEL: "cancel",
+  END: "end",
+  RESPONSE: "response",
+  CONNECTED: "connected",
+} as const;
+
+export interface WsQuestionMessage {
+  type: "question";
+  id: string;
+  questionType: QuestionType;
+  config: BaseConfig;
+}
+
+export interface WsCancelMessage {
+  type: "cancel";
+  id: string;
+}
+
+export interface WsEndMessage {
+  type: "end";
+}
+
+export interface WsResponseMessage {
+  type: "response";
+  id: string;
+  answer: Answer;
+}
+
+export interface WsConnectedMessage {
+  type: "connected";
+}
+
+export type WsServerMessage = WsQuestionMessage | WsCancelMessage | WsEndMessage;
+export type WsClientMessage = WsResponseMessage | WsConnectedMessage;
diff --git a/src/octto/session/utils.ts b/src/octto/session/utils.ts
new file mode 100644
index 0000000..686664a
--- /dev/null
+++ b/src/octto/session/utils.ts
@@ -0,0 +1,25 @@
+// src/octto/session/utils.ts
+// ID generation utilities for octto sessions and questions
+
+const ID_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
+const ID_LENGTH = 8;
+
+function generateId(prefix: string): string {
+  let result = `${prefix}_`;
+  for (let i = 0; i < ID_LENGTH; i++) {
+    result += ID_CHARS.charAt(Math.floor(Math.random() * ID_CHARS.length));
+  }
+  return result;
+}
+
+export function generateSessionId(): string {
+  return generateId("ses");
+}
+
+export function generateQuestionId(): string {
+  return generateId("q");
+}
+
+export function generateBrainstormId(): string {
+  return generateId("bs");
+}
diff --git a/src/octto/session/waiter.ts b/src/octto/session/waiter.ts
new file mode 100644
index 0000000..f77d57e
--- /dev/null
+++ b/src/octto/session/waiter.ts
@@ -0,0 +1,132 @@
+// src/octto/session/waiter.ts
+// Immutable waiter management for async response handling
+
+export interface Waiters<K, T> {
+  register: (key: K, callback: (data: T) => void) => () => void;
+  notifyFirst: (key: K, data: T) => void;
+  notifyAll: (key: K, data: T) => void;
+  has: (key: K) => boolean;
+  count: (key: K) => number;
+  clear: (key: K) => void;
+}
+
+/**
+ * Create a waiter registry for async response handling.
+ * Each operation creates a new array rather than mutating in place.
+ *
+ * @typeParam K - Key type (e.g., string for question_id or session_id)
+ * @typeParam T - Data type passed to waiter callbacks
+ */
+export function createWaiters<K, T>(): Waiters<K, T> {
+  const waiters = new Map<K, Array<(data: T) => void>>();
+
+  return {
+    /**
+     * Register a waiter callback for a key.
+     * Returns a cleanup function to remove this specific waiter.
+     */
+    register(key: K, callback: (data: T) => void): () => void {
+      // Create new array with callback appended (immutable)
+      const current = waiters.get(key) || [];
+      waiters.set(key, [...current, callback]);
+
+      // Return cleanup function that removes this specific callback
+      return () => {
+        const callbacks = waiters.get(key);
+        if (!callbacks) return;
+
+        const idx = callbacks.indexOf(callback);
+        if (idx >= 0) {
+          // Create new array without this callback (immutable)
+          const remaining = [...callbacks.slice(0, idx), ...callbacks.slice(idx + 1)];
+          if (remaining.length === 0) {
+            waiters.delete(key);
+          } else {
+            waiters.set(key, remaining);
+          }
+        }
+      };
+    },
+
+    /**
+     * Notify only the first waiter for a key and remove it.
+     * Other waiters remain registered for subsequent notifications.
+     */
+    notifyFirst(key: K, data: T): void {
+      const callbacks = waiters.get(key);
+      if (!callbacks || callbacks.length === 0) return;
+
+      const [first, ...rest] = callbacks;
+      first(data);
+
+      // Set new array without first element (immutable)
+      if (rest.length === 0) {
+        waiters.delete(key);
+      } else {
+        waiters.set(key, rest);
+      }
+    },
+
+    /**
+     * Notify all waiters for a key and remove them all.
+     */
+    notifyAll(key: K, data: T): void {
+      const callbacks = waiters.get(key);
+      if (!callbacks) return;
+
+      for (const callback of callbacks) {
+        callback(data);
+      }
+
+      waiters.delete(key);
+    },
+
+    /**
+     * Check if there are any waiters for a key.
+     */
+    has(key: K): boolean {
+      const callbacks = waiters.get(key);
+      return callbacks !== undefined && callbacks.length > 0;
+    },
+
+    /**
+     * Get the number of waiters for a key.
+     */
+    count(key: K): number {
+      return waiters.get(key)?.length ?? 0;
+    },
+
+    /**
+     * Remove all waiters for a key without notifying them.
+     */
+    clear(key: K): void {
+      waiters.delete(key);
+    },
+  };
+}
+
+/**
+ * Result of waiting for a response
+ */
+export type WaitResult<T> = { ok: true; data: T } | { ok: false; reason: "timeout" };
+
+/**
+ * Wait for a response with timeout.
+ * Registers a waiter and returns a promise that resolves when notified or times out.
+ */
+export function waitForResponse<K, T>(waiters: Waiters<K, T>, key: K, timeoutMs: number): Promise<WaitResult<T>> {
+  return new Promise((resolve) => {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let cleanup: (() => void) | undefined;
+
+    cleanup = waiters.register(key, (data) => {
+      if (timeoutId) clearTimeout(timeoutId);
+      resolve({ ok: true, data });
+    });
+
+    timeoutId = setTimeout(() => {
+      if (cleanup) cleanup();
+      resolve({ ok: false, reason: "timeout" });
+    }, timeoutMs);
+  });
+}
diff --git a/src/octto/state/index.ts b/src/octto/state/index.ts
new file mode 100644
index 0000000..3381f48
--- /dev/null
+++ b/src/octto/state/index.ts
@@ -0,0 +1,5 @@
+// src/octto/state/index.ts
+
+export * from "./persistence";
+export * from "./store";
+export * from "./types";
diff --git a/src/octto/state/persistence.ts b/src/octto/state/persistence.ts
new file mode 100644
index 0000000..b3d0489
--- /dev/null
+++ b/src/octto/state/persistence.ts
@@ -0,0 +1,65 @@
+// src/octto/state/persistence.ts
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { STATE_DIR } from "../constants";
+import type { BrainstormState } from "./types";
+
+export interface StatePersistence {
+  save: (state: BrainstormState) => Promise<void>;
+  load: (sessionId: string) => Promise<BrainstormState | null>;
+  delete: (sessionId: string) => Promise<void>;
+  list: () => Promise<string[]>;
+}
+
+function validateSessionId(sessionId: string): void {
+  if (!/^[a-zA-Z0-9_-]+$/.test(sessionId)) {
+    throw new Error(`Invalid session ID: ${sessionId}`);
+  }
+}
+
+export function createStatePersistence(baseDir = STATE_DIR): StatePersistence {
+  function getFilePath(sessionId: string): string {
+    validateSessionId(sessionId);
+    return join(baseDir, `${sessionId}.json`);
+  }
+
+  function ensureDir(): void {
+    if (!existsSync(baseDir)) {
+      mkdirSync(baseDir, { recursive: true });
+    }
+  }
+
+  return {
+    async save(state: BrainstormState): Promise<void> {
+      ensureDir();
+      const filePath = getFilePath(state.session_id);
+      state.updated_at = Date.now();
+      await Bun.write(filePath, JSON.stringify(state, null, 2));
+    },
+
+    async load(sessionId: string): Promise<BrainstormState | null> {
+      const filePath = getFilePath(sessionId);
+      if (!existsSync(filePath)) {
+        return null;
+      }
+      const content = await Bun.file(filePath).text();
+      return JSON.parse(content) as BrainstormState;
+    },
+
+    async delete(sessionId: string): Promise<void> {
+      const filePath = getFilePath(sessionId);
+      if (existsSync(filePath)) {
+        rmSync(filePath);
+      }
+    },
+
+    async list(): Promise<string[]> {
+      if (!existsSync(baseDir)) {
+        return [];
+      }
+      const files = readdirSync(baseDir);
+      return files.filter((f) => f.endsWith(".json")).map((f) => f.replace(".json", ""));
+    },
+  };
+}
diff --git a/src/octto/state/store.ts b/src/octto/state/store.ts
new file mode 100644
index 0000000..68ad9ea
--- /dev/null
+++ b/src/octto/state/store.ts
@@ -0,0 +1,159 @@
+// src/octto/state/store.ts
+import type { Answer } from "../session";
+
+import { STATE_DIR } from "../constants";
+import { createStatePersistence } from "./persistence";
+import {
+  BRANCH_STATUSES,
+  type BrainstormState,
+  type Branch,
+  type BranchQuestion,
+  type CreateBranchInput,
+} from "./types";
+
+export interface StateStore {
+  createSession: (sessionId: string, request: string, branches: CreateBranchInput[]) => Promise<BrainstormState>;
+  getSession: (sessionId: string) => Promise<BrainstormState | null>;
+  setBrowserSessionId: (sessionId: string, browserSessionId: string) => Promise<void>;
+  addQuestionToBranch: (sessionId: string, branchId: string, question: BranchQuestion) => Promise<BranchQuestion>;
+  recordAnswer: (sessionId: string, questionId: string, answer: Answer) => Promise<void>;
+  completeBranch: (sessionId: string, branchId: string, finding: string) => Promise<void>;
+  getNextExploringBranch: (sessionId: string) => Promise<Branch | null>;
+  isSessionComplete: (sessionId: string) => Promise<boolean>;
+  deleteSession: (sessionId: string) => Promise<void>;
+}
+
+export function createStateStore(baseDir = STATE_DIR): StateStore {
+  const persistence = createStatePersistence(baseDir);
+
+  // Operation queue per session to prevent concurrent read-modify-write races
+  const operationQueues = new Map<string, Promise<void>>();
+
+  // Serialize operations for a given session
+  function withSessionLock<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+    const currentQueue = operationQueues.get(sessionId) ?? Promise.resolve();
+    const newOperation = currentQueue.then(operation, operation); // Run even if previous failed
+    operationQueues.set(
+      sessionId,
+      newOperation.then(
+        () => {},
+        () => {},
+      ),
+    ); // Ignore result for queue
+    return newOperation;
+  }
+
+  return {
+    async createSession(
+      sessionId: string,
+      request: string,
+      branchInputs: CreateBranchInput[],
+    ): Promise<BrainstormState> {
+      const branches: Record<string, Branch> = {};
+      const order: string[] = [];
+
+      for (const input of branchInputs) {
+        branches[input.id] = {
+          id: input.id,
+          scope: input.scope,
+          status: BRANCH_STATUSES.EXPLORING,
+          questions: [],
+          finding: null,
+        };
+        order.push(input.id);
+      }
+
+      const state: BrainstormState = {
+        session_id: sessionId,
+        browser_session_id: null,
+        request,
+        created_at: Date.now(),
+        updated_at: Date.now(),
+        branches,
+        branch_order: order,
+      };
+
+      await persistence.save(state);
+      return state;
+    },
+
+    async getSession(sessionId: string): Promise<BrainstormState | null> {
+      return persistence.load(sessionId);
+    },
+
+    async setBrowserSessionId(sessionId: string, browserSessionId: string): Promise<void> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+        state.browser_session_id = browserSessionId;
+        await persistence.save(state);
+      });
+    },
+
+    async addQuestionToBranch(sessionId: string, branchId: string, question: BranchQuestion): Promise<BranchQuestion> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+        if (!state.branches[branchId]) throw new Error(`Branch not found: ${branchId}`);
+
+        state.branches[branchId].questions.push(question);
+        await persistence.save(state);
+        return question;
+      });
+    },
+
+    async recordAnswer(sessionId: string, questionId: string, answer: Answer): Promise<void> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+
+        for (const branch of Object.values(state.branches)) {
+          const question = branch.questions.find((q) => q.id === questionId);
+          if (question) {
+            question.answer = answer;
+            question.answeredAt = Date.now();
+            await persistence.save(state);
+            return;
+          }
+        }
+        throw new Error(`Question not found: ${questionId}`);
+      });
+    },
+
+    async completeBranch(sessionId: string, branchId: string, finding: string): Promise<void> {
+      return withSessionLock(sessionId, async () => {
+        const state = await persistence.load(sessionId);
+        if (!state) throw new Error(`Session not found: ${sessionId}`);
+        if (!state.branches[branchId]) throw new Error(`Branch not found: ${branchId}`);
+
+        state.branches[branchId].status = BRANCH_STATUSES.DONE;
+        state.branches[branchId].finding = finding;
+        await persistence.save(state);
+      });
+    },
+
+    async getNextExploringBranch(sessionId: string): Promise<Branch | null> {
+      const state = await persistence.load(sessionId);
+      if (!state) return null;
+
+      for (const branchId of state.branch_order) {
+        const branch = state.branches[branchId];
+        if (branch.status === BRANCH_STATUSES.EXPLORING) {
+          return branch;
+        }
+      }
+      return null;
+    },
+
+    async isSessionComplete(sessionId: string): Promise<boolean> {
+      const state = await persistence.load(sessionId);
+      if (!state) return false;
+
+      return Object.values(state.branches).every((b) => b.status === BRANCH_STATUSES.DONE);
+    },
+
+    async deleteSession(sessionId: string): Promise<void> {
+      await persistence.delete(sessionId);
+    },
+  };
+}
diff --git a/src/octto/state/types.ts b/src/octto/state/types.ts
new file mode 100644
index 0000000..9ec5970
--- /dev/null
+++ b/src/octto/state/types.ts
@@ -0,0 +1,51 @@
+// src/octto/state/types.ts
+import type { Answer, BaseConfig, QuestionType } from "../session";
+
+export const BRANCH_STATUSES = {
+  EXPLORING: "exploring",
+  DONE: "done",
+} as const;
+
+export type BranchStatus = (typeof BRANCH_STATUSES)[keyof typeof BRANCH_STATUSES];
+
+export interface BranchQuestion {
+  id: string;
+  type: QuestionType;
+  text: string;
+  config: BaseConfig;
+  answer?: Answer;
+  answeredAt?: number;
+}
+
+export interface Branch {
+  id: string;
+  scope: string;
+  status: BranchStatus;
+  questions: BranchQuestion[];
+  finding: string | null;
+}
+
+export interface BrainstormState {
+  session_id: string;
+  browser_session_id: string | null;
+  request: string;
+  created_at: number;
+  updated_at: number;
+  branches: Record<string, Branch>;
+  branch_order: string[];
+}
+
+export interface CreateBranchInput {
+  id: string;
+  scope: string;
+}
+
+export interface BranchProbeResult {
+  done: boolean;
+  reason: string;
+  finding?: string;
+  question?: {
+    type: QuestionType;
+    config: BaseConfig;
+  };
+}
diff --git a/src/octto/types.ts b/src/octto/types.ts
new file mode 100644
index 0000000..a73f751
--- /dev/null
+++ b/src/octto/types.ts
@@ -0,0 +1,376 @@
+// src/octto/types.ts
+// Common types for all interactive tools
+
+export interface BaseConfig {
+  /** Window title */
+  title?: string;
+  /** Timeout in seconds (0 = no timeout) */
+  timeout?: number;
+  /** Theme preference */
+  theme?: "light" | "dark" | "auto";
+}
+
+export interface Option {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label: string;
+  /** Optional description */
+  description?: string;
+}
+
+export interface OptionWithPros extends Option {
+  /** Pros/advantages */
+  pros?: string[];
+  /** Cons/disadvantages */
+  cons?: string[];
+}
+
+export interface RatedOption extends Option {
+  /** User's rating (filled after response) */
+  rating?: number;
+}
+
+export interface RankedOption extends Option {
+  /** User's rank position (filled after response) */
+  rank?: number;
+}
+
+// Tool-specific configs
+
+export interface PickOneConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Available options */
+  options: Option[];
+  /** Recommended option id (highlighted) */
+  recommended?: string;
+  /** Allow custom "other" input */
+  allowOther?: boolean;
+}
+
+export interface PickManyConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Available options */
+  options: Option[];
+  /** Recommended option ids (highlighted) */
+  recommended?: string[];
+  /** Minimum selections required */
+  min?: number;
+  /** Maximum selections allowed */
+  max?: number;
+  /** Allow custom "other" input */
+  allowOther?: boolean;
+}
+
+export interface ConfirmConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Context/details to show */
+  context?: string;
+  /** Custom label for yes button */
+  yesLabel?: string;
+  /** Custom label for no button */
+  noLabel?: string;
+  /** Show cancel option */
+  allowCancel?: boolean;
+}
+
+export interface RankConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Items to rank */
+  options: Option[];
+  /** Context/instructions */
+  context?: string;
+}
+
+export interface RateConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Items to rate */
+  options: Option[];
+  /** Minimum rating value */
+  min?: number;
+  /** Maximum rating value */
+  max?: number;
+  /** Rating step (default 1) */
+  step?: number;
+  /** Labels for min/max */
+  labels?: { min?: string; max?: string };
+}
+
+export interface AskTextConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Context/instructions */
+  context?: string;
+  /** Multi-line input */
+  multiline?: boolean;
+  /** Minimum length */
+  minLength?: number;
+  /** Maximum length */
+  maxLength?: number;
+}
+
+export interface AskImageConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Context/instructions */
+  context?: string;
+  /** Allow multiple images */
+  multiple?: boolean;
+  /** Maximum number of images */
+  maxImages?: number;
+  /** Allowed mime types */
+  accept?: string[];
+}
+
+export interface AskFileConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Context/instructions */
+  context?: string;
+  /** Allow multiple files */
+  multiple?: boolean;
+  /** Maximum number of files */
+  maxFiles?: number;
+  /** Allowed file extensions or mime types */
+  accept?: string[];
+  /** Maximum file size in bytes */
+  maxSize?: number;
+}
+
+export interface AskCodeConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Context/instructions */
+  context?: string;
+  /** Programming language for syntax highlighting */
+  language?: string;
+  /** Placeholder code */
+  placeholder?: string;
+}
+
+export interface ShowDiffConfig extends BaseConfig {
+  /** Title/description of the change */
+  question: string;
+  /** Original content */
+  before: string;
+  /** Modified content */
+  after: string;
+  /** File path (for context) */
+  filePath?: string;
+  /** Language for syntax highlighting */
+  language?: string;
+}
+
+export interface PlanSection {
+  /** Section identifier */
+  id: string;
+  /** Section title */
+  title: string;
+  /** Section content (markdown) */
+  content: string;
+}
+
+export interface ShowPlanConfig extends BaseConfig {
+  /** Plan title */
+  question: string;
+  /** Plan sections */
+  sections: PlanSection[];
+  /** Full markdown (alternative to sections) */
+  markdown?: string;
+}
+
+export interface ShowOptionsConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Options with pros/cons */
+  options: OptionWithPros[];
+  /** Recommended option id */
+  recommended?: string;
+  /** Allow text feedback with selection */
+  allowFeedback?: boolean;
+}
+
+export interface ReviewSectionConfig extends BaseConfig {
+  /** Section title */
+  question: string;
+  /** Section content (markdown) */
+  content: string;
+  /** Context about what to review */
+  context?: string;
+}
+
+export interface ThumbsConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Context to show */
+  context?: string;
+}
+
+export interface EmojiReactConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Context to show */
+  context?: string;
+  /** Available emoji options (default: common set) */
+  emojis?: string[];
+}
+
+export interface SliderConfig extends BaseConfig {
+  /** Question/prompt to display */
+  question: string;
+  /** Context/instructions */
+  context?: string;
+  /** Minimum value */
+  min: number;
+  /** Maximum value */
+  max: number;
+  /** Step size */
+  step?: number;
+  /** Default value */
+  defaultValue?: number;
+  /** Labels for values */
+  labels?: { min?: string; max?: string; mid?: string };
+}
+
+// Response types
+
+export interface BaseResponse {
+  /** Whether the interaction completed (false if cancelled/timeout) */
+  completed: boolean;
+  /** Cancellation reason if not completed */
+  cancelReason?: "timeout" | "cancelled" | "closed";
+}
+
+export interface PickOneResponse extends BaseResponse {
+  /** Selected option id */
+  selected?: string;
+  /** Custom "other" value if provided */
+  other?: string;
+}
+
+export interface PickManyResponse extends BaseResponse {
+  /** Selected option ids */
+  selected: string[];
+  /** Custom "other" values if provided */
+  other?: string[];
+}
+
+export interface ConfirmResponse extends BaseResponse {
+  /** User's choice */
+  choice?: "yes" | "no" | "cancel";
+}
+
+export interface RankResponse extends BaseResponse {
+  /** Option ids in ranked order (first = highest) */
+  ranking: string[];
+}
+
+export interface RateResponse extends BaseResponse {
+  /** Ratings by option id */
+  ratings: Record<string, number>;
+}
+
+export interface AskTextResponse extends BaseResponse {
+  /** User's text input */
+  text?: string;
+}
+
+export interface AskImageResponse extends BaseResponse {
+  /** Image data */
+  images: Array<{
+    /** Original filename */
+    filename: string;
+    /** Mime type */
+    mimeType: string;
+    /** Base64 encoded data */
+    data: string;
+  }>;
+  /** File paths (if provided instead of upload) */
+  paths?: string[];
+}
+
+export interface AskFileResponse extends BaseResponse {
+  /** File data */
+  files: Array<{
+    /** Original filename */
+    filename: string;
+    /** Mime type */
+    mimeType: string;
+    /** Base64 encoded data */
+    data: string;
+  }>;
+  /** File paths (if provided instead of upload) */
+  paths?: string[];
+}
+
+export interface AskCodeResponse extends BaseResponse {
+  /** User's code input */
+  code?: string;
+  /** Detected/selected language */
+  language?: string;
+}
+
+export interface ShowDiffResponse extends BaseResponse {
+  /** User's decision */
+  decision?: "approve" | "reject" | "edit";
+  /** User's edited version (if decision is "edit") */
+  edited?: string;
+  /** Optional feedback */
+  feedback?: string;
+}
+
+export interface Annotation {
+  /** Annotation id */
+  id: string;
+  /** Section id or line range */
+  target: string;
+  /** Annotation type */
+  type: "comment" | "suggest" | "delete" | "approve";
+  /** Annotation content */
+  content?: string;
+}
+
+export interface ShowPlanResponse extends BaseResponse {
+  /** User's decision */
+  decision?: "approve" | "reject" | "revise";
+  /** User annotations */
+  annotations: Annotation[];
+  /** Overall feedback */
+  feedback?: string;
+}
+
+export interface ShowOptionsResponse extends BaseResponse {
+  /** Selected option id */
+  selected?: string;
+  /** Optional feedback text */
+  feedback?: string;
+}
+
+export interface ReviewSectionResponse extends BaseResponse {
+  /** User's decision */
+  decision?: "approve" | "revise";
+  /** Inline feedback/suggestions */
+  feedback?: string;
+}
+
+export interface ThumbsResponse extends BaseResponse {
+  /** User's choice */
+  choice?: "up" | "down";
+}
+
+export interface EmojiReactResponse extends BaseResponse {
+  /** Selected emoji */
+  emoji?: string;
+}
+
+export interface SliderResponse extends BaseResponse {
+  /** Selected value */
+  value?: number;
+}
diff --git a/src/octto/ui/bundle.ts b/src/octto/ui/bundle.ts
new file mode 100644
index 0000000..98c79ac
--- /dev/null
+++ b/src/octto/ui/bundle.ts
@@ -0,0 +1,1599 @@
+// src/octto/ui/bundle.ts
+
+/**
+ * Returns the bundled HTML for the octto UI.
+ * Uses nof1 design system - IBM Plex Mono, terminal aesthetic.
+ */
+export function getHtmlBundle(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Octto</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+  <style>
+    :root {
+      --background: #ffffff;
+      --surface: #ffffff;
+      --surface-elevated: #f8f9fa;
+      --surface-hover: #f1f3f4;
+      --foreground: #000000;
+      --foreground-muted: #333333;
+      --foreground-subtle: #666666;
+      --border: #000000;
+      --border-subtle: #cccccc;
+      --accent-success: #00aa00;
+      --accent-error: #ff0000;
+    }
+
+    *, *:before, *:after {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    html, body {
+      height: 100%;
+      background: var(--background);
+      color: var(--foreground);
+      font-family: 'IBM Plex Mono', monospace;
+      font-size: 14px;
+      line-height: 1.5;
+      letter-spacing: -0.02em;
+    }
+
+    body {
+      position: relative;
+    }
+
+    body::before {
+      content: "";
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noiseFilter'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.6' numOctaves='4' stitchTiles='stitch'/%3E%3CfeColorMatrix type='saturate' values='0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noiseFilter)' opacity='0.15'/%3E%3C/svg%3E");
+      background-size: 180px 180px;
+      pointer-events: none;
+      z-index: 1;
+    }
+
+    #root {
+      position: relative;
+      z-index: 2;
+      max-width: 640px;
+      margin: 0 auto;
+      padding: 2rem 1.5rem;
+      min-height: 100vh;
+    }
+
+    h1, h2, h3 {
+      font-weight: 700;
+      letter-spacing: 0.05em;
+      text-transform: uppercase;
+    }
+
+    .header {
+      text-align: center;
+      padding: 3rem 0;
+    }
+
+    .header h1 {
+      font-size: 1.5rem;
+      margin-bottom: 0.5rem;
+    }
+
+    .header p {
+      color: var(--foreground-subtle);
+      font-size: 0.875rem;
+    }
+
+    .spinner {
+      width: 24px;
+      height: 24px;
+      border: 2px solid var(--border-subtle);
+      border-top-color: var(--foreground);
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+      margin: 1.5rem auto 0;
+    }
+
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    .card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      padding: 1.5rem;
+      margin-bottom: 1rem;
+    }
+
+    .card-answered {
+      background: var(--surface-elevated);
+      border-color: var(--border-subtle);
+      opacity: 0.7;
+      padding: 1rem;
+      cursor: pointer;
+      transition: opacity 0.15s;
+    }
+
+    .card-answered:hover {
+      opacity: 0.85;
+    }
+
+    .card-answered.expanded {
+      opacity: 1;
+      cursor: default;
+    }
+
+    .card-answered .check {
+      color: var(--accent-success);
+      margin-right: 0.5rem;
+    }
+
+    .card-answered-header {
+      display: flex;
+      align-items: center;
+      cursor: pointer;
+    }
+
+    .card-answered-header .toggle {
+      margin-left: auto;
+      color: var(--foreground-subtle);
+      font-size: 0.75rem;
+    }
+
+    .card-answered-body {
+      margin-top: 1rem;
+      padding-top: 1rem;
+      border-top: 1px solid var(--border-subtle);
+    }
+
+    .readonly-answer {
+      background: var(--surface-hover);
+      padding: 0.75rem;
+      margin-top: 0.5rem;
+      font-size: 0.875rem;
+    }
+
+    .readonly-answer-label {
+      font-size: 0.6875rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: var(--foreground-subtle);
+      margin-bottom: 0.25rem;
+    }
+
+    .readonly-option {
+      padding: 0.5rem 0.75rem;
+      border: 1px solid var(--border-subtle);
+      margin-bottom: 0.25rem;
+      opacity: 0.6;
+    }
+
+    .readonly-option.selected {
+      opacity: 1;
+      border-color: var(--accent-success);
+      background: rgba(0, 170, 0, 0.05);
+    }
+
+    .readonly-option .check-mark {
+      color: var(--accent-success);
+      margin-right: 0.5rem;
+    }
+
+    .question-text {
+      font-size: 1rem;
+      font-weight: 600;
+      margin-bottom: 1.25rem;
+      line-height: 1.4;
+    }
+
+    .context {
+      color: var(--foreground-muted);
+      font-size: 0.875rem;
+      margin-bottom: 1rem;
+      padding-left: 1rem;
+      border-left: 2px solid var(--border-subtle);
+    }
+
+    .options {
+      display: flex;
+      flex-direction: column;
+      gap: 0.5rem;
+    }
+
+    .option {
+      display: flex;
+      align-items: flex-start;
+      gap: 0.75rem;
+      padding: 0.75rem;
+      border: 1px solid var(--border-subtle);
+      cursor: pointer;
+      transition: none;
+    }
+
+    .option:hover {
+      background: var(--surface-hover);
+      border-color: var(--border);
+    }
+
+    .option.recommended {
+      border-color: var(--border);
+      background: var(--surface-elevated);
+    }
+
+    .option input {
+      margin-top: 0.125rem;
+      accent-color: var(--foreground);
+    }
+
+    .option-content {
+      flex: 1;
+    }
+
+    .option-label {
+      font-weight: 500;
+    }
+
+    .option-desc {
+      font-size: 0.8125rem;
+      color: var(--foreground-subtle);
+      margin-top: 0.25rem;
+    }
+
+    .option-tag {
+      font-size: 0.6875rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: var(--foreground-muted);
+      margin-left: 0.5rem;
+    }
+
+    .btn {
+      display: inline-block;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      color: var(--foreground);
+      font-family: 'IBM Plex Mono', monospace;
+      font-weight: 500;
+      font-size: 0.75rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      padding: 0.5rem 1rem;
+      cursor: pointer;
+      transition: none;
+    }
+
+    .btn:hover {
+      background: var(--surface-hover);
+    }
+
+    .btn:active {
+      background: var(--foreground);
+      color: var(--background);
+    }
+
+    .btn-primary {
+      background: var(--foreground);
+      color: var(--background);
+    }
+
+    .btn-primary:hover {
+      opacity: 0.9;
+    }
+
+    .btn-success {
+      border-color: var(--accent-success);
+      color: var(--accent-success);
+    }
+
+    .btn-success:hover {
+      background: var(--accent-success);
+      color: var(--background);
+    }
+
+    .btn-danger {
+      border-color: var(--accent-error);
+      color: var(--accent-error);
+    }
+
+    .btn-danger:hover {
+      background: var(--accent-error);
+      color: var(--background);
+    }
+
+    .btn-group {
+      display: flex;
+      gap: 0.5rem;
+      margin-top: 1.25rem;
+    }
+
+    .input, .textarea {
+      width: 100%;
+      padding: 0.75rem;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      color: var(--foreground);
+      font-family: 'IBM Plex Mono', monospace;
+      font-size: 0.875rem;
+    }
+
+    .input:focus, .textarea:focus {
+      outline: none;
+      border-color: var(--foreground);
+    }
+
+    .textarea {
+      resize: vertical;
+      min-height: 100px;
+    }
+
+    .slider-container {
+      display: flex;
+      align-items: center;
+      gap: 1rem;
+    }
+
+    .slider-container input[type="range"] {
+      flex: 1;
+      height: 2px;
+      background: var(--border-subtle);
+      appearance: none;
+      -webkit-appearance: none;
+    }
+
+    .slider-container input[type="range"]::-webkit-slider-thumb {
+      appearance: none;
+      -webkit-appearance: none;
+      width: 16px;
+      height: 16px;
+      background: var(--foreground);
+      cursor: pointer;
+    }
+
+    .slider-value {
+      font-weight: 600;
+      min-width: 3rem;
+      text-align: center;
+      font-variant-numeric: tabular-nums;
+    }
+
+    .slider-labels {
+      color: var(--foreground-subtle);
+      font-size: 0.75rem;
+    }
+
+    .thumbs-container {
+      display: flex;
+      gap: 1rem;
+    }
+
+    .thumb-btn {
+      font-size: 2rem;
+      padding: 1rem 1.5rem;
+      border: 1px solid var(--border-subtle);
+      background: var(--surface);
+      cursor: pointer;
+    }
+
+    .thumb-btn:hover {
+      border-color: var(--border);
+      background: var(--surface-hover);
+    }
+
+    .queue-indicator {
+      text-align: center;
+      color: var(--foreground-subtle);
+      font-size: 0.75rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      margin-top: 1rem;
+    }
+
+    .branch-subtitle {
+      font-size: 0.75rem;
+      color: var(--foreground-subtle);
+      margin-top: 0.25rem;
+      margin-bottom: 0.75rem;
+    }
+
+    .thinking {
+      text-align: center;
+      padding: 2rem;
+      margin-top: 2rem;
+      margin-bottom: 2rem;
+      border: 1px dashed var(--border-subtle);
+    }
+
+    .thinking-text {
+      color: var(--foreground-subtle);
+      font-size: 0.75rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      margin-bottom: 1rem;
+    }
+
+    .thinking .spinner {
+      margin: 0 auto;
+    }
+
+    .review-content {
+      background: var(--surface-elevated);
+      border: 1px solid var(--border-subtle);
+      padding: 1rem;
+      margin-bottom: 1rem;
+      font-size: 0.875rem;
+      line-height: 1.6;
+      max-height: 400px;
+      overflow-y: auto;
+    }
+
+    .review-content h1, .review-content h2, .review-content h3,
+    .review-content h4, .review-content h5, .review-content h6 {
+      font-weight: 600;
+      margin: 1rem 0 0.5rem 0;
+    }
+
+    .review-content h1 { font-size: 1.25rem; }
+    .review-content h2 { font-size: 1.125rem; }
+    .review-content h3 { font-size: 1rem; }
+
+    .review-content p {
+      margin: 0.5rem 0;
+    }
+
+    .review-content ul, .review-content ol {
+      margin: 0.5rem 0;
+      padding-left: 1.5rem;
+    }
+
+    .review-content li {
+      margin: 0.25rem 0;
+    }
+
+    .review-content code {
+      background: var(--surface-hover);
+      padding: 0.125rem 0.25rem;
+      font-size: 0.8125rem;
+    }
+
+    .review-content pre {
+      background: var(--surface-hover);
+      padding: 0.75rem;
+      overflow-x: auto;
+      margin: 0.5rem 0;
+    }
+
+    .review-content pre code {
+      background: none;
+      padding: 0;
+    }
+
+    .review-content blockquote {
+      border-left: 2px solid var(--border);
+      padding-left: 1rem;
+      margin: 0.5rem 0;
+      color: var(--foreground-muted);
+    }
+
+    .feedback-input {
+      margin-top: 1rem;
+    }
+
+    .feedback-input label {
+      display: block;
+      font-size: 0.75rem;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: var(--foreground-subtle);
+      margin-bottom: 0.5rem;
+    }
+
+    .plan-section {
+      margin-bottom: 1.5rem;
+    }
+
+    .plan-section-title {
+      font-size: 1rem;
+      font-weight: 600;
+      margin-bottom: 0.5rem;
+      padding-bottom: 0.25rem;
+      border-bottom: 1px solid var(--border-subtle);
+    }
+
+    .session-ended {
+      text-align: center;
+      padding: 4rem 0;
+    }
+
+    .session-ended h1 {
+      margin-bottom: 0.5rem;
+    }
+
+    .session-ended p {
+      color: var(--foreground-subtle);
+    }
+
+    /* Show Options */
+    .options-with-pros {
+      display: flex;
+      flex-direction: column;
+      gap: 1rem;
+    }
+
+    .option-card {
+      border: 1px solid var(--border-subtle);
+      padding: 1rem;
+    }
+
+    .option-card.recommended {
+      border-color: var(--border);
+      background: var(--surface-elevated);
+    }
+
+    .option-header {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      margin-bottom: 0.5rem;
+    }
+
+    .pros, .cons {
+      font-size: 0.8125rem;
+      margin-top: 0.5rem;
+    }
+
+    .pros { color: var(--accent-success); }
+    .cons { color: var(--accent-error); }
+
+    .pros ul, .cons ul {
+      margin: 0.25rem 0 0 1rem;
+    }
+
+    /* Show Diff */
+    .diff-filepath {
+      font-size: 0.75rem;
+      color: var(--foreground-subtle);
+      margin-bottom: 0.5rem;
+      font-family: monospace;
+    }
+
+    .diff-container {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 0.5rem;
+      margin-bottom: 1rem;
+    }
+
+    .diff-side {
+      border: 1px solid var(--border-subtle);
+      overflow: auto;
+      max-height: 300px;
+    }
+
+    .diff-label {
+      font-size: 0.6875rem;
+      text-transform: uppercase;
+      padding: 0.25rem 0.5rem;
+      background: var(--surface-elevated);
+      border-bottom: 1px solid var(--border-subtle);
+    }
+
+    .diff-before .diff-label { color: var(--accent-error); }
+    .diff-after .diff-label { color: var(--accent-success); }
+
+    .diff-side pre {
+      margin: 0;
+      padding: 0.5rem;
+      font-size: 0.75rem;
+      white-space: pre-wrap;
+    }
+
+    /* Rank */
+    .rank-list {
+      display: flex;
+      flex-direction: column;
+      gap: 0.25rem;
+    }
+
+    .rank-item {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      padding: 0.5rem 0.75rem;
+      border: 1px solid var(--border-subtle);
+      background: var(--surface);
+      cursor: grab;
+    }
+
+    .rank-item:active, .rank-item.dragging {
+      cursor: grabbing;
+      opacity: 0.5;
+    }
+
+    .rank-handle {
+      color: var(--foreground-subtle);
+    }
+
+    .rank-num {
+      font-weight: 600;
+      min-width: 1.5rem;
+    }
+
+    /* Rate */
+    .rate-list {
+      display: flex;
+      flex-direction: column;
+      gap: 0.75rem;
+    }
+
+    .rate-item {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+
+    .rate-stars {
+      display: flex;
+      gap: 0.25rem;
+    }
+
+    .rate-star {
+      width: 2rem;
+      height: 2rem;
+      border: 1px solid var(--border-subtle);
+      background: var(--surface);
+      cursor: pointer;
+      font-size: 0.75rem;
+    }
+
+    .rate-star.selected {
+      background: var(--foreground);
+      color: var(--background);
+      border-color: var(--foreground);
+    }
+
+    /* Code Input */
+    .code-input {
+      font-family: 'IBM Plex Mono', monospace;
+      font-size: 0.8125rem;
+    }
+
+    .code-input-label {
+      font-size: 0.6875rem;
+      text-transform: uppercase;
+      color: var(--foreground-subtle);
+      margin-bottom: 0.25rem;
+    }
+
+    /* File Upload */
+    .file-upload {
+      margin-bottom: 1rem;
+    }
+
+    .file-upload input[type="file"] {
+      width: 100%;
+      padding: 0.5rem;
+      border: 1px dashed var(--border-subtle);
+    }
+
+    .image-preview {
+      display: flex;
+      flex-wrap: wrap;
+      margin-top: 0.5rem;
+    }
+
+    /* Emoji React */
+    .emoji-grid {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.5rem;
+    }
+
+    .emoji-btn {
+      font-size: 2rem;
+      padding: 0.75rem;
+      border: 1px solid var(--border-subtle);
+      background: var(--surface);
+      cursor: pointer;
+    }
+
+    .emoji-btn:hover {
+      background: var(--surface-hover);
+      border-color: var(--border);
+    }
+
+    /* Keyboard focus styles */
+    .thumb-btn:focus,
+    .emoji-btn:focus,
+    .rate-star:focus,
+    .btn:focus {
+      outline: 2px solid var(--foreground);
+      outline-offset: 2px;
+    }
+  </style>
+</head>
+<body>
+  <div id="root">
+    <div class="header">
+      <h1>Octto</h1>
+      <p>Connecting to session...</p>
+      <div class="spinner"></div>
+    </div>
+  </div>
+
+  <script>
+    const wsUrl = 'ws://' + window.location.host + '/ws';
+    let ws = null;
+    let questions = [];
+    let expandedAnswers = new Set();
+
+    function connect() {
+      ws = new WebSocket(wsUrl);
+
+      ws.onopen = () => {
+        ws.send(JSON.stringify({ type: 'connected' }));
+        render();
+      };
+
+      ws.onmessage = (event) => {
+        const msg = JSON.parse(event.data);
+        if (msg.type === 'question') {
+          questions.push(msg);
+          render();
+        } else if (msg.type === 'cancel') {
+          questions = questions.filter(q => q.id !== msg.id);
+          render();
+        } else if (msg.type === 'end') {
+          document.getElementById('root').innerHTML =
+            '<div class="session-ended"><h1>Session Ended</h1><p>You can close this window.</p></div>';
+        }
+      };
+
+      ws.onclose = () => {
+        setTimeout(connect, 2000);
+      };
+    }
+
+    function render() {
+      const root = document.getElementById('root');
+
+      if (questions.length === 0) {
+        root.innerHTML = '<div class="header"><h1>Octto</h1><p>Waiting for questions...</p></div>';
+        return;
+      }
+
+      const pending = questions.filter(q => !q.answered);
+      const answered = questions.filter(q => q.answered);
+
+      let html = '';
+
+      // Show remaining count at top
+      if (pending.length > 1) {
+        html += '<div class="queue-indicator" style="margin-top: 0; margin-bottom: 1rem;">' + (pending.length - 1) + ' more question(s) remaining</div>';
+      }
+
+      // Show current question
+      if (pending.length > 0) {
+        const q = pending[0];
+        html += renderQuestion(q);
+      } else if (answered.length > 0) {
+        // All answered, waiting for more questions
+        html += '<div class="thinking">';
+        html += '<div class="thinking-text">Thinking...</div>';
+        html += '<div class="spinner"></div>';
+        html += '</div>';
+      }
+
+      // Show answered questions at bottom (collapsed or expanded)
+      for (const q of answered) {
+        const isExpanded = expandedAnswers.has(q.id);
+        // Extract branch name from context
+        let branchName = '';
+        const ctx = q.config.context || '';
+        const branchMatch = ctx.match(/^\\[([^\\]]+)\\]/);
+        if (branchMatch) branchName = branchMatch[1];
+
+        html += '<div class="card card-answered' + (isExpanded ? ' expanded' : '') + '" data-qid="' + q.id + '">';
+        html += '<div class="card-answered-header" onclick="toggleAnswered(\\'' + q.id + '\\')">';
+        html += '<span class="check">[OK]</span>';
+        html += '<div style="flex: 1;">';
+        html += '<span>' + escapeHtml(q.config.question) + '</span>';
+        if (branchName) html += '<div class="branch-subtitle" style="margin-bottom: 0; margin-top: 0.125rem;">' + escapeHtml(branchName) + '</div>';
+        html += '</div>';
+        html += '<span class="toggle">' + (isExpanded ? '\\u25B2 collapse' : '\\u25BC view') + '</span>';
+        html += '</div>';
+        if (isExpanded) {
+          html += '<div class="card-answered-body">';
+          html += renderAnsweredQuestion(q);
+          html += '</div>';
+        }
+        html += '</div>';
+      }
+
+      root.innerHTML = html;
+      attachListeners();
+    }
+
+    function renderQuestion(q) {
+      const config = q.config;
+      let html = '<div class="card">';
+
+      // Extract branch from context if present: "[Branch Scope] rest of context"
+      let branchName = '';
+      let remainingContext = config.context || '';
+      const branchMatch = remainingContext.match(/^\\[([^\\]]+)\\]\\s*/);
+      if (branchMatch) {
+        branchName = branchMatch[1];
+        remainingContext = remainingContext.substring(branchMatch[0].length);
+      }
+
+      html += '<div class="question-text">' + escapeHtml(config.question) + '</div>';
+      if (branchName) {
+        html += '<div class="branch-subtitle">' + escapeHtml(branchName) + '</div>';
+      }
+      if (remainingContext) {
+        html += '<div class="context">' + escapeHtml(remainingContext) + '</div>';
+      }
+
+      switch (q.questionType) {
+        case 'pick_one':
+          html += renderPickOne(q);
+          break;
+        case 'pick_many':
+          html += renderPickMany(q);
+          break;
+        case 'confirm':
+          html += renderConfirm(q);
+          break;
+        case 'ask_text':
+          html += renderAskText(q);
+          break;
+        case 'thumbs':
+          html += renderThumbs(q);
+          break;
+        case 'slider':
+          html += renderSlider(q);
+          break;
+        case 'review_section':
+          html += renderReviewSection(q);
+          break;
+        case 'show_plan':
+          html += renderShowPlan(q);
+          break;
+        case 'show_options':
+          html += renderShowOptions(q);
+          break;
+        case 'show_diff':
+          html += renderShowDiff(q);
+          break;
+        case 'rank':
+          html += renderRank(q);
+          break;
+        case 'rate':
+          html += renderRate(q);
+          break;
+        case 'ask_code':
+          html += renderAskCode(q);
+          break;
+        case 'ask_image':
+          html += renderAskImage(q);
+          break;
+        case 'ask_file':
+          html += renderAskFile(q);
+          break;
+        case 'emoji_react':
+          html += renderEmojiReact(q);
+          break;
+        default:
+          html += '<p>Question type "' + q.questionType + '" not yet implemented.</p>';
+          html += '<div class="btn-group"><button onclick="submitAnswer(\\'' + q.id + '\\', {})" class="btn">Skip</button></div>';
+      }
+
+      html += '</div>';
+      return html;
+    }
+
+    function renderPickOne(q) {
+      const options = q.config.options || [];
+      let html = '<div class="options">';
+      for (const opt of options) {
+        const isRecommended = q.config.recommended === opt.id;
+        html += '<label class="option' + (isRecommended ? ' recommended' : '') + '">';
+        html += '<input type="radio" name="pick_' + q.id + '" value="' + opt.id + '">';
+        html += '<div class="option-content">';
+        html += '<div class="option-label">' + escapeHtml(opt.label);
+        if (isRecommended) html += '<span class="option-tag">(recommended)</span>';
+        html += '</div>';
+        if (opt.description) html += '<div class="option-desc">' + escapeHtml(opt.description) + '</div>';
+        html += '</div></label>';
+      }
+      html += '</div>';
+      html += '<div class="btn-group"><button onclick="submitPickOne(\\'' + q.id + '\\')" class="btn btn-primary">Submit</button></div>';
+      return html;
+    }
+
+    function renderPickMany(q) {
+      const options = q.config.options || [];
+      let html = '<div class="options">';
+      for (const opt of options) {
+        html += '<label class="option">';
+        html += '<input type="checkbox" name="pick_' + q.id + '" value="' + opt.id + '">';
+        html += '<div class="option-content">';
+        html += '<div class="option-label">' + escapeHtml(opt.label) + '</div>';
+        if (opt.description) html += '<div class="option-desc">' + escapeHtml(opt.description) + '</div>';
+        html += '</div></label>';
+      }
+      html += '</div>';
+      html += '<div class="btn-group"><button onclick="submitPickMany(\\'' + q.id + '\\')" class="btn btn-primary">Submit</button></div>';
+      return html;
+    }
+
+    function renderConfirm(q) {
+      const yesLabel = q.config.yesLabel || 'Yes';
+      const noLabel = q.config.noLabel || 'No';
+      let html = '<div class="btn-group">';
+      html += '<button onclick="submitAnswer(\\'' + q.id + '\\', {choice: \\'yes\\'})" class="btn btn-success">' + escapeHtml(yesLabel) + '</button>';
+      html += '<button onclick="submitAnswer(\\'' + q.id + '\\', {choice: \\'no\\'})" class="btn btn-danger">' + escapeHtml(noLabel) + '</button>';
+      if (q.config.allowCancel) {
+        html += '<button onclick="submitAnswer(\\'' + q.id + '\\', {choice: \\'cancel\\'})" class="btn">Cancel</button>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function renderAskText(q) {
+      const multiline = q.config.multiline;
+      let html = '';
+      if (multiline) {
+        html += '<textarea id="text_' + q.id + '" class="textarea" rows="4" placeholder="' + escapeHtml(q.config.placeholder || '') + '"></textarea>';
+      } else {
+        html += '<input type="text" id="text_' + q.id + '" class="input" placeholder="' + escapeHtml(q.config.placeholder || '') + '">';
+      }
+      html += '<div class="btn-group"><button onclick="submitText(\\'' + q.id + '\\')" class="btn btn-primary">Submit</button></div>';
+      return html;
+    }
+
+    function renderThumbs(q) {
+      let html = '<div class="thumbs-container">';
+      html += '<button onclick="submitAnswer(\\'' + q.id + '\\', {choice: \\'up\\'})" class="thumb-btn">\\uD83D\\uDC4D</button>';
+      html += '<button onclick="submitAnswer(\\'' + q.id + '\\', {choice: \\'down\\'})" class="thumb-btn">\\uD83D\\uDC4E</button>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderSlider(q) {
+      const min = q.config.min;
+      const max = q.config.max;
+      const step = q.config.step || 1;
+      const defaultVal = q.config.defaultValue || Math.floor((min + max) / 2);
+      let html = '<div class="slider-container">';
+      html += '<span class="slider-labels">' + min + '</span>';
+      html += '<input type="range" id="slider_' + q.id + '" min="' + min + '" max="' + max + '" step="' + step + '" value="' + defaultVal + '">';
+      html += '<span class="slider-labels">' + max + '</span>';
+      html += '<span id="slider_val_' + q.id + '" class="slider-value">' + defaultVal + '</span>';
+      html += '</div>';
+      html += '<div class="btn-group"><button onclick="submitSlider(\\'' + q.id + '\\')" class="btn btn-primary">Submit</button></div>';
+      return html;
+    }
+
+    function renderReviewSection(q) {
+      let html = '';
+      // Render markdown content
+      const markdownHtml = typeof marked !== 'undefined' ? marked.parse(q.config.content || '') : escapeHtml(q.config.content || '');
+      html += '<div class="review-content">' + markdownHtml + '</div>';
+      html += '<div class="feedback-input">';
+      html += '<label for="feedback_' + q.id + '">Feedback (optional)</label>';
+      html += '<textarea id="feedback_' + q.id + '" class="textarea" rows="3" placeholder="Any suggestions or changes..."></textarea>';
+      html += '</div>';
+      html += '<div class="btn-group">';
+      html += '<button onclick="submitReview(\\'' + q.id + '\\', \\'approve\\')" class="btn btn-success">Approve</button>';
+      html += '<button onclick="submitReview(\\'' + q.id + '\\', \\'revise\\')" class="btn btn-danger">Needs Revision</button>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderShowPlan(q) {
+      let html = '';
+
+      // Render sections if provided
+      if (q.config.sections && q.config.sections.length > 0) {
+        for (const section of q.config.sections) {
+          html += '<div class="plan-section">';
+          html += '<h3 class="plan-section-title">' + escapeHtml(section.title) + '</h3>';
+          const sectionHtml = typeof marked !== 'undefined' ? marked.parse(section.content || '') : escapeHtml(section.content || '');
+          html += '<div class="review-content">' + sectionHtml + '</div>';
+          html += '</div>';
+        }
+      } else if (q.config.markdown) {
+        // Fallback to raw markdown
+        const markdownHtml = typeof marked !== 'undefined' ? marked.parse(q.config.markdown) : escapeHtml(q.config.markdown);
+        html += '<div class="review-content">' + markdownHtml + '</div>';
+      }
+
+      html += '<div class="feedback-input">';
+      html += '<label for="feedback_' + q.id + '">Feedback (optional)</label>';
+      html += '<textarea id="feedback_' + q.id + '" class="textarea" rows="3" placeholder="Any suggestions or changes..."></textarea>';
+      html += '</div>';
+      html += '<div class="btn-group">';
+      html += '<button onclick="submitReview(\\'' + q.id + '\\', \\'approve\\')" class="btn btn-success">Approve Plan</button>';
+      html += '<button onclick="submitReview(\\'' + q.id + '\\', \\'revise\\')" class="btn btn-danger">Needs Changes</button>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderShowOptions(q) {
+      const options = q.config.options || [];
+      let html = '<div class="options-with-pros">';
+      for (const opt of options) {
+        const isRecommended = q.config.recommended === opt.id;
+        html += '<div class="option-card' + (isRecommended ? ' recommended' : '') + '" data-id="' + opt.id + '">';
+        html += '<div class="option-header">';
+        html += '<input type="radio" name="opt_' + q.id + '" value="' + opt.id + '">';
+        html += '<span class="option-label">' + escapeHtml(opt.label);
+        if (isRecommended) html += ' <span class="option-tag">(recommended)</span>';
+        html += '</span></div>';
+        if (opt.description) html += '<div class="option-desc">' + escapeHtml(opt.description) + '</div>';
+        if (opt.pros && opt.pros.length > 0) {
+          html += '<div class="pros"><strong>Pros:</strong><ul>';
+          for (const pro of opt.pros) html += '<li>' + escapeHtml(pro) + '</li>';
+          html += '</ul></div>';
+        }
+        if (opt.cons && opt.cons.length > 0) {
+          html += '<div class="cons"><strong>Cons:</strong><ul>';
+          for (const con of opt.cons) html += '<li>' + escapeHtml(con) + '</li>';
+          html += '</ul></div>';
+        }
+        html += '</div>';
+      }
+      html += '</div>';
+      if (q.config.allowFeedback) {
+        html += '<div class="feedback-input"><label>Feedback (optional)</label>';
+        html += '<textarea id="feedback_' + q.id + '" class="textarea" rows="2"></textarea></div>';
+      }
+      html += '<div class="btn-group"><button onclick="submitShowOptions(\\'' + q.id + '\\')" class="btn btn-primary">Select</button></div>';
+      return html;
+    }
+
+    function renderShowDiff(q) {
+      let html = '';
+      if (q.config.filePath) {
+        html += '<div class="diff-filepath">' + escapeHtml(q.config.filePath) + '</div>';
+      }
+      html += '<div class="diff-container">';
+      html += '<div class="diff-side diff-before"><div class="diff-label">Before</div><pre><code>' + escapeHtml(q.config.before || '') + '</code></pre></div>';
+      html += '<div class="diff-side diff-after"><div class="diff-label">After</div><pre><code>' + escapeHtml(q.config.after || '') + '</code></pre></div>';
+      html += '</div>';
+      html += '<div class="feedback-input"><label>Comments (optional)</label>';
+      html += '<textarea id="feedback_' + q.id + '" class="textarea" rows="2"></textarea></div>';
+      html += '<div class="btn-group">';
+      html += '<button onclick="submitDiff(\\'' + q.id + '\\', \\'approve\\')" class="btn btn-success">Approve</button>';
+      html += '<button onclick="submitDiff(\\'' + q.id + '\\', \\'reject\\')" class="btn btn-danger">Reject</button>';
+      html += '<button onclick="submitDiff(\\'' + q.id + '\\', \\'edit\\')" class="btn">Edit</button>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderRank(q) {
+      const options = q.config.options || [];
+      let html = '<div class="rank-list" id="rank_' + q.id + '">';
+      for (let i = 0; i < options.length; i++) {
+        const opt = options[i];
+        html += '<div class="rank-item" data-id="' + opt.id + '" draggable="true">';
+        html += '<span class="rank-handle">\\u2630</span>';
+        html += '<span class="rank-num">' + (i + 1) + '</span>';
+        html += '<span class="rank-label">' + escapeHtml(opt.label) + '</span>';
+        html += '</div>';
+      }
+      html += '</div>';
+      html += '<div class="btn-group"><button onclick="submitRank(\\'' + q.id + '\\')" class="btn btn-primary">Submit Ranking</button></div>';
+      return html;
+    }
+
+    function renderRate(q) {
+      const options = q.config.options || [];
+      const min = q.config.min || 1;
+      const max = q.config.max || 5;
+      let html = '<div class="rate-list">';
+      for (const opt of options) {
+        html += '<div class="rate-item">';
+        html += '<div class="rate-label">' + escapeHtml(opt.label) + '</div>';
+        html += '<div class="rate-stars" id="rate_' + q.id + '_' + opt.id + '">';
+        for (let i = min; i <= max; i++) {
+          html += '<button class="rate-star" data-value="' + i + '" onclick="setRating(\\'' + q.id + '\\', \\'' + opt.id + '\\', ' + i + ')">' + i + '</button>';
+        }
+        html += '</div></div>';
+      }
+      html += '</div>';
+      html += '<div class="btn-group"><button onclick="submitRate(\\'' + q.id + '\\')" class="btn btn-primary">Submit Ratings</button></div>';
+      return html;
+    }
+
+    function renderAskCode(q) {
+      let html = '';
+      const lang = q.config.language || 'plaintext';
+      html += '<div class="code-input-label">Language: ' + escapeHtml(lang) + '</div>';
+      html += '<textarea id="code_' + q.id + '" class="textarea code-input" rows="10" placeholder="' + escapeHtml(q.config.placeholder || 'Enter code here...') + '"></textarea>';
+      html += '<div class="btn-group"><button onclick="submitCode(\\'' + q.id + '\\')" class="btn btn-primary">Submit Code</button></div>';
+      return html;
+    }
+
+    function renderAskImage(q) {
+      let html = '';
+      const multiple = q.config.multiple ? 'multiple' : '';
+      html += '<div class="file-upload">';
+      html += '<input type="file" id="image_' + q.id + '" accept="image/*" ' + multiple + ' onchange="previewImages(\\'' + q.id + '\\')">';
+      html += '<div id="preview_' + q.id + '" class="image-preview"></div>';
+      html += '</div>';
+      html += '<div class="btn-group"><button onclick="submitImages(\\'' + q.id + '\\')" class="btn btn-primary">Upload</button></div>';
+      return html;
+    }
+
+    function renderAskFile(q) {
+      let html = '';
+      const multiple = q.config.multiple ? 'multiple' : '';
+      const accept = q.config.accept ? q.config.accept.join(',') : '';
+      html += '<div class="file-upload">';
+      html += '<input type="file" id="file_' + q.id + '" ' + (accept ? 'accept="' + accept + '"' : '') + ' ' + multiple + '>';
+      html += '<div id="filelist_' + q.id + '" class="file-list"></div>';
+      html += '</div>';
+      html += '<div class="btn-group"><button onclick="submitFiles(\\'' + q.id + '\\')" class="btn btn-primary">Upload</button></div>';
+      return html;
+    }
+
+    function renderEmojiReact(q) {
+      let html = '';
+      const emojis = q.config.emojis || ['\\uD83D\\uDC4D', '\\uD83D\\uDC4E', '\\u2764\\uFE0F', '\\uD83C\\uDF89', '\\uD83D\\uDE15', '\\uD83D\\uDE80'];
+      html += '<div class="emoji-grid">';
+      for (const emoji of emojis) {
+        html += '<button class="emoji-btn" onclick="submitAnswer(\\'' + q.id + '\\', {emoji: \\'' + emoji + '\\'})">' + emoji + '</button>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function attachListeners() {
+      document.querySelectorAll('input[type="range"]').forEach(slider => {
+        const id = slider.id.replace('slider_', 'slider_val_');
+        slider.oninput = () => {
+          document.getElementById(id).textContent = slider.value;
+        };
+      });
+    }
+
+    function submitAnswer(questionId, answer) {
+      const q = questions.find(q => q.id === questionId);
+      if (q) {
+        q.answered = true;
+        q.answer = answer;  // Store answer for read-only view
+        ws.send(JSON.stringify({ type: 'response', id: questionId, answer }));
+        render();
+      }
+    }
+
+    function showError(questionId, message) {
+      const existingError = document.getElementById('error_' + questionId);
+      if (existingError) existingError.remove();
+
+      const card = document.querySelector('[data-qid="' + questionId + '"]') || document.querySelector('.card:not(.card-answered)');
+      if (card) {
+        const errorDiv = document.createElement('div');
+        errorDiv.id = 'error_' + questionId;
+        errorDiv.style.cssText = 'color: var(--accent-error); font-size: 0.875rem; margin-top: 0.5rem;';
+        errorDiv.textContent = message;
+        const btnGroup = card.querySelector('.btn-group');
+        if (btnGroup) btnGroup.before(errorDiv);
+      }
+    }
+
+    function submitPickOne(questionId) {
+      const selected = document.querySelector('input[name="pick_' + questionId + '"]:checked');
+      if (!selected) {
+        showError(questionId, 'Please select an option');
+        return;
+      }
+      submitAnswer(questionId, { selected: selected.value });
+    }
+
+    function submitPickMany(questionId) {
+      const selected = Array.from(document.querySelectorAll('input[name="pick_' + questionId + '"]:checked')).map(el => el.value);
+      submitAnswer(questionId, { selected });
+    }
+
+    function submitText(questionId) {
+      const input = document.getElementById('text_' + questionId);
+      if (input) {
+        submitAnswer(questionId, { text: input.value });
+      }
+    }
+
+    function submitSlider(questionId) {
+      const slider = document.getElementById('slider_' + questionId);
+      if (slider) {
+        submitAnswer(questionId, { value: parseFloat(slider.value) });
+      }
+    }
+
+    function submitReview(questionId, decision) {
+      const feedbackEl = document.getElementById('feedback_' + questionId);
+      const feedback = feedbackEl ? feedbackEl.value : '';
+      submitAnswer(questionId, { decision, feedback: feedback || undefined });
+    }
+
+    function submitShowOptions(questionId) {
+      const selected = document.querySelector('input[name="opt_' + questionId + '"]:checked');
+      if (!selected) {
+        showError(questionId, 'Please select an option');
+        return;
+      }
+      const feedbackEl = document.getElementById('feedback_' + questionId);
+      const feedback = feedbackEl ? feedbackEl.value : '';
+      submitAnswer(questionId, { selected: selected.value, feedback: feedback || undefined });
+    }
+
+    function submitDiff(questionId, decision) {
+      const feedbackEl = document.getElementById('feedback_' + questionId);
+      const feedback = feedbackEl ? feedbackEl.value : '';
+      submitAnswer(questionId, { decision, feedback: feedback || undefined });
+    }
+
+    function submitRank(questionId) {
+      const container = document.getElementById('rank_' + questionId);
+      const items = container.querySelectorAll('.rank-item');
+      const ranking = Array.from(items).map((item, idx) => ({
+        id: item.dataset.id,
+        rank: idx + 1
+      }));
+      submitAnswer(questionId, { ranking });
+    }
+
+    function submitRate(questionId) {
+      const q = questions.find(q => q.id === questionId);
+      if (!q) return;
+      const ratings = {};
+      for (const opt of (q.config.options || [])) {
+        const container = document.getElementById('rate_' + questionId + '_' + opt.id);
+        const selected = container.querySelector('.rate-star.selected');
+        if (selected) {
+          ratings[opt.id] = parseInt(selected.dataset.value);
+        }
+      }
+      submitAnswer(questionId, { ratings });
+    }
+
+    function setRating(questionId, optId, value) {
+      const container = document.getElementById('rate_' + questionId + '_' + optId);
+      container.querySelectorAll('.rate-star').forEach(btn => {
+        btn.classList.toggle('selected', parseInt(btn.dataset.value) <= value);
+      });
+    }
+
+    function submitCode(questionId) {
+      const textarea = document.getElementById('code_' + questionId);
+      if (textarea) {
+        submitAnswer(questionId, { code: textarea.value });
+      }
+    }
+
+    function submitImages(questionId) {
+      const input = document.getElementById('image_' + questionId);
+      if (input && input.files.length > 0) {
+        // Convert to base64 for transport
+        const promises = Array.from(input.files).map(file => {
+          return new Promise((resolve) => {
+            const reader = new FileReader();
+            reader.onload = () => resolve({ name: file.name, type: file.type, data: reader.result });
+            reader.readAsDataURL(file);
+          });
+        });
+        Promise.all(promises).then(images => {
+          submitAnswer(questionId, { images });
+        });
+      }
+    }
+
+    function previewImages(questionId) {
+      const input = document.getElementById('image_' + questionId);
+      const preview = document.getElementById('preview_' + questionId);
+      preview.innerHTML = '';
+      for (const file of input.files) {
+        const img = document.createElement('img');
+        img.src = URL.createObjectURL(file);
+        img.style.maxWidth = '100px';
+        img.style.maxHeight = '100px';
+        img.style.margin = '4px';
+        preview.appendChild(img);
+      }
+    }
+
+    function submitFiles(questionId) {
+      const input = document.getElementById('file_' + questionId);
+      if (input && input.files.length > 0) {
+        const promises = Array.from(input.files).map(file => {
+          return new Promise((resolve) => {
+            const reader = new FileReader();
+            reader.onload = () => resolve({ name: file.name, type: file.type, size: file.size, data: reader.result });
+            reader.readAsDataURL(file);
+          });
+        });
+        Promise.all(promises).then(files => {
+          submitAnswer(questionId, { files });
+        });
+      }
+    }
+
+    // Drag and drop for ranking
+    document.addEventListener('dragstart', (e) => {
+      if (e.target.classList.contains('rank-item')) {
+        e.dataTransfer.setData('text/plain', e.target.dataset.id);
+        e.target.classList.add('dragging');
+      }
+    });
+    document.addEventListener('dragend', (e) => {
+      if (e.target.classList.contains('rank-item')) {
+        e.target.classList.remove('dragging');
+      }
+    });
+    document.addEventListener('dragover', (e) => {
+      e.preventDefault();
+      const dragging = document.querySelector('.rank-item.dragging');
+      const rankList = e.target.closest('.rank-list');
+      if (dragging && rankList) {
+        const siblings = [...rankList.querySelectorAll('.rank-item:not(.dragging)')];
+        const nextSibling = siblings.find(sibling => {
+          const rect = sibling.getBoundingClientRect();
+          return e.clientY < rect.top + rect.height / 2;
+        });
+        rankList.insertBefore(dragging, nextSibling);
+        // Update numbers
+        rankList.querySelectorAll('.rank-item').forEach((item, idx) => {
+          item.querySelector('.rank-num').textContent = idx + 1;
+        });
+      }
+    });
+
+    function toggleAnswered(questionId) {
+      if (expandedAnswers.has(questionId)) {
+        expandedAnswers.delete(questionId);
+      } else {
+        expandedAnswers.add(questionId);
+      }
+      render();
+    }
+
+    function renderAnsweredQuestion(q) {
+      const config = q.config;
+      const answer = q.answer || {};
+      let html = '';
+
+      switch (q.questionType) {
+        case 'pick_one':
+          html += renderAnsweredPickOne(q, answer);
+          break;
+        case 'pick_many':
+          html += renderAnsweredPickMany(q, answer);
+          break;
+        case 'confirm':
+          html += renderAnsweredConfirm(q, answer);
+          break;
+        case 'ask_text':
+          html += renderAnsweredText(q, answer);
+          break;
+        case 'thumbs':
+          html += renderAnsweredThumbs(q, answer);
+          break;
+        case 'slider':
+          html += renderAnsweredSlider(q, answer);
+          break;
+        case 'review_section':
+        case 'show_plan':
+          html += renderAnsweredReview(q, answer);
+          break;
+        case 'show_options':
+          html += renderAnsweredShowOptions(q, answer);
+          break;
+        case 'show_diff':
+          html += renderAnsweredDiff(q, answer);
+          break;
+        case 'rank':
+          html += renderAnsweredRank(q, answer);
+          break;
+        case 'rate':
+          html += renderAnsweredRate(q, answer);
+          break;
+        case 'ask_code':
+          html += renderAnsweredCode(q, answer);
+          break;
+        case 'ask_image':
+        case 'ask_file':
+          html += renderAnsweredFile(q, answer);
+          break;
+        case 'emoji_react':
+          html += renderAnsweredEmoji(q, answer);
+          break;
+        default:
+          html += '<div class="readonly-answer"><pre>' + escapeHtml(JSON.stringify(answer, null, 2)) + '</pre></div>';
+      }
+
+      return html;
+    }
+
+    function renderAnsweredPickOne(q, answer) {
+      const options = q.config.options || [];
+      let html = '<div class="options">';
+      for (const opt of options) {
+        const isSelected = answer.selected === opt.id;
+        html += '<div class="readonly-option' + (isSelected ? ' selected' : '') + '">';
+        if (isSelected) html += '<span class="check-mark">\\u2713</span>';
+        html += '<span>' + escapeHtml(opt.label) + '</span>';
+        html += '</div>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredPickMany(q, answer) {
+      const options = q.config.options || [];
+      const selected = answer.selected || [];
+      let html = '<div class="options">';
+      for (const opt of options) {
+        const isSelected = selected.includes(opt.id);
+        html += '<div class="readonly-option' + (isSelected ? ' selected' : '') + '">';
+        if (isSelected) html += '<span class="check-mark">\\u2713</span>';
+        html += '<span>' + escapeHtml(opt.label) + '</span>';
+        html += '</div>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredConfirm(q, answer) {
+      const choice = answer.choice;
+      const labels = { yes: q.config.yesLabel || 'Yes', no: q.config.noLabel || 'No', cancel: 'Cancel' };
+      let html = '<div class="readonly-answer">';
+      html += '<div class="readonly-answer-label">Answer</div>';
+      html += '<strong>' + escapeHtml(labels[choice] || choice) + '</strong>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredText(q, answer) {
+      let html = '<div class="readonly-answer">';
+      html += '<div class="readonly-answer-label">Response</div>';
+      html += '<div>' + escapeHtml(answer.text || '') + '</div>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredThumbs(q, answer) {
+      const emoji = answer.choice === 'up' ? '\\uD83D\\uDC4D' : '\\uD83D\\uDC4E';
+      let html = '<div class="readonly-answer">';
+      html += '<span style="font-size: 2rem;">' + emoji + '</span>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredSlider(q, answer) {
+      let html = '<div class="readonly-answer">';
+      html += '<div class="readonly-answer-label">Value</div>';
+      html += '<strong style="font-size: 1.25rem;">' + answer.value + '</strong>';
+      html += ' <span style="color: var(--foreground-subtle);">(range: ' + q.config.min + ' - ' + q.config.max + ')</span>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredReview(q, answer) {
+      let html = '<div class="readonly-answer">';
+      html += '<div class="readonly-answer-label">Decision</div>';
+      html += '<strong>' + (answer.decision === 'approve' ? '\\u2713 Approved' : '\\u2717 Needs Revision') + '</strong>';
+      if (answer.feedback) {
+        html += '<div style="margin-top: 0.5rem;"><em>Feedback:</em> ' + escapeHtml(answer.feedback) + '</div>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredShowOptions(q, answer) {
+      const options = q.config.options || [];
+      let html = '<div class="options">';
+      for (const opt of options) {
+        const isSelected = answer.selected === opt.id;
+        html += '<div class="readonly-option' + (isSelected ? ' selected' : '') + '">';
+        if (isSelected) html += '<span class="check-mark">\\u2713</span>';
+        html += '<span>' + escapeHtml(opt.label) + '</span>';
+        html += '</div>';
+      }
+      html += '</div>';
+      if (answer.feedback) {
+        html += '<div class="readonly-answer"><div class="readonly-answer-label">Feedback</div>' + escapeHtml(answer.feedback) + '</div>';
+      }
+      return html;
+    }
+
+    function renderAnsweredDiff(q, answer) {
+      let html = '<div class="readonly-answer">';
+      html += '<div class="readonly-answer-label">Decision</div>';
+      const decisions = { approve: '\\u2713 Approved', reject: '\\u2717 Rejected', edit: '\\u270E Edit Requested' };
+      html += '<strong>' + (decisions[answer.decision] || answer.decision) + '</strong>';
+      if (answer.feedback) {
+        html += '<div style="margin-top: 0.5rem;"><em>Comments:</em> ' + escapeHtml(answer.feedback) + '</div>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredRank(q, answer) {
+      const ranking = answer.ranking || [];
+      let html = '<div class="readonly-answer-label">Final Ranking</div>';
+      html += '<div class="options">';
+      for (const item of ranking) {
+        const opt = (q.config.options || []).find(o => o.id === item.id);
+        html += '<div class="readonly-option selected">';
+        html += '<strong>' + item.rank + '.</strong> ' + escapeHtml(opt ? opt.label : item.id);
+        html += '</div>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredRate(q, answer) {
+      const ratings = answer.ratings || {};
+      let html = '<div class="readonly-answer-label">Ratings</div>';
+      html += '<div class="options">';
+      for (const opt of (q.config.options || [])) {
+        const rating = ratings[opt.id];
+        html += '<div class="readonly-option' + (rating ? ' selected' : '') + '">';
+        html += '<span>' + escapeHtml(opt.label) + '</span>';
+        html += ' <strong style="margin-left: auto;">' + (rating || '-') + '</strong>';
+        html += '</div>';
+      }
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredCode(q, answer) {
+      let html = '<div class="readonly-answer">';
+      html += '<div class="readonly-answer-label">Code (' + escapeHtml(q.config.language || 'plaintext') + ')</div>';
+      html += '<pre style="margin: 0; white-space: pre-wrap;"><code>' + escapeHtml(answer.code || '') + '</code></pre>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredFile(q, answer) {
+      const files = answer.images || answer.files || [];
+      let html = '<div class="readonly-answer">';
+      html += '<div class="readonly-answer-label">Uploaded ' + files.length + ' file(s)</div>';
+      html += '<ul style="margin: 0.5rem 0 0 1rem;">';
+      for (const f of files) {
+        html += '<li>' + escapeHtml(f.name) + '</li>';
+      }
+      html += '</ul>';
+      html += '</div>';
+      return html;
+    }
+
+    function renderAnsweredEmoji(q, answer) {
+      let html = '<div class="readonly-answer">';
+      html += '<span style="font-size: 2rem;">' + (answer.emoji || '') + '</span>';
+      html += '</div>';
+      return html;
+    }
+
+    function escapeHtml(text) {
+      const div = document.createElement('div');
+      div.textContent = text;
+      return div.innerHTML;
+    }
+
+    connect();
+  </script>
+</body>
+</html>`;
+}
diff --git a/src/octto/ui/index.ts b/src/octto/ui/index.ts
new file mode 100644
index 0000000..4687435
--- /dev/null
+++ b/src/octto/ui/index.ts
@@ -0,0 +1,2 @@
+// src/octto/ui/index.ts
+export { getHtmlBundle } from "./bundle";
diff --git a/src/tools/octto/brainstorm.ts b/src/tools/octto/brainstorm.ts
new file mode 100644
index 0000000..f1e3d53
--- /dev/null
+++ b/src/tools/octto/brainstorm.ts
@@ -0,0 +1,325 @@
+// src/tools/octto/brainstorm.ts
+import { tool } from "@opencode-ai/plugin/tool";
+
+import type { ReviewAnswer, SessionStore } from "../../octto/session";
+import { QUESTION_TYPES, QUESTIONS, STATUSES } from "../../octto/session";
+import { BRANCH_STATUSES, type BrainstormState, createStateStore, type StateStore } from "../../octto/state";
+import { config } from "../../utils/config";
+import { log } from "../../utils/logger";
+
+import { formatBranchStatus, formatFindings, formatFindingsList, formatQASummary } from "./formatters";
+import { processAnswer } from "./processor";
+import type { OcttoTools, OpencodeClient } from "./types";
+import { generateSessionId } from "./utils";
+
+// --- Extracted helper functions ---
+
+interface CollectionResult {
+  state: BrainstormState | null;
+  allComplete: boolean;
+}
+
+async function collectAnswers(
+  stateStore: StateStore,
+  sessions: SessionStore,
+  sessionId: string,
+  browserSessionId: string,
+  client: OpencodeClient,
+): Promise<CollectionResult> {
+  const pendingProcessing: Promise<void>[] = [];
+
+  for (let i = 0; i < config.octto.maxIterations; i++) {
+    if (await stateStore.isSessionComplete(sessionId)) break;
+
+    const answer = await sessions.getNextAnswer({
+      session_id: browserSessionId,
+      block: true,
+      timeout: config.octto.answerTimeoutMs,
+    });
+
+    if (!answer.completed) {
+      if (answer.status === STATUSES.NONE_PENDING) {
+        await Promise.all(pendingProcessing);
+        pendingProcessing.length = 0;
+        continue;
+      }
+      if (answer.status === STATUSES.TIMEOUT) break;
+      continue;
+    }
+
+    const { question_id, response } = answer;
+    if (!question_id || response === undefined) continue;
+
+    const processing = processAnswer(
+      stateStore,
+      sessions,
+      sessionId,
+      browserSessionId,
+      question_id,
+      response,
+      client,
+    ).catch((error) => {
+      log.error("octto", `Error processing answer ${question_id}`, error);
+    });
+    pendingProcessing.push(processing);
+  }
+
+  await Promise.all(pendingProcessing);
+
+  const [state, allComplete] = await Promise.all([
+    stateStore.getSession(sessionId),
+    stateStore.isSessionComplete(sessionId),
+  ]);
+
+  return { state, allComplete };
+}
+
+interface ReviewSection {
+  id: string;
+  title: string;
+  content: string;
+}
+
+function buildReviewSections(state: BrainstormState): ReviewSection[] {
+  return [
+    {
+      id: "summary",
+      title: "Original Request",
+      content: state.request,
+    },
+    ...state.branch_order.map((id) => {
+      const b = state.branches[id];
+      const qaSummary = formatQASummary(b);
+      return {
+        id,
+        title: b.scope,
+        content: `**Finding:** ${b.finding || "No finding"}\n\n**Discussion:**\n${qaSummary || "(no questions answered)"}`,
+      };
+    }),
+  ];
+}
+
+interface ReviewResult {
+  approved: boolean;
+  feedback: string;
+}
+
+async function waitForReviewApproval(sessions: SessionStore, browserSessionId: string): Promise<ReviewResult> {
+  const result = await sessions.getNextAnswer({
+    session_id: browserSessionId,
+    block: true,
+    timeout: config.octto.reviewTimeoutMs,
+  });
+
+  if (!result.completed || !result.response) {
+    return { approved: false, feedback: "" };
+  }
+
+  const response = result.response as ReviewAnswer;
+  return {
+    approved: response.decision === "approve",
+    feedback: response.feedback ?? "",
+  };
+}
+
+// --- Format functions ---
+
+function formatInProgressResult(state: BrainstormState): string {
+  const branches = state.branch_order.map((id) => formatBranchStatus(state.branches[id])).join("\n");
+  return `<brainstorm_in_progress>
+  <request>${state.request}</request>
+  <branches>
+${branches}
+  </branches>
+  <next_action>Call await_brainstorm_complete again to continue</next_action>
+</brainstorm_in_progress>`;
+}
+
+function formatSkippedReviewResult(state: BrainstormState): string {
+  return `<brainstorm_complete status="review_skipped">
+  <request>${state.request}</request>
+  <branch_count>${state.branch_order.length}</branch_count>
+  <note>Browser session ended before review</note>
+  ${formatFindings(state)}
+  <next_action>Write the design document to docs/plans/</next_action>
+</brainstorm_complete>`;
+}
+
+function formatCompletionResult(state: BrainstormState, approved: boolean, feedback: string): string {
+  const feedbackXml = feedback ? `\n  <feedback>${feedback}</feedback>` : "";
+  const nextAction = approved
+    ? "Write the design document to docs/plans/"
+    : "Review feedback and discuss with user before proceeding";
+  return `<brainstorm_complete status="${approved ? "approved" : "changes_requested"}">
+  <request>${state.request}</request>
+  <branch_count>${state.branch_order.length}</branch_count>${feedbackXml}
+  ${formatFindings(state)}
+  <next_action>${nextAction}</next_action>
+</brainstorm_complete>`;
+}
+
+// --- Tool definitions ---
+
+export function createBrainstormTools(sessions: SessionStore, client: OpencodeClient): OcttoTools {
+  const store = createStateStore();
+
+  const create_brainstorm = tool({
+    description: "Create a new brainstorm session with exploration branches",
+    args: {
+      request: tool.schema.string().describe("The original user request"),
+      branches: tool.schema
+        .array(
+          tool.schema.object({
+            id: tool.schema.string(),
+            scope: tool.schema.string(),
+            initial_question: tool.schema.object({
+              type: tool.schema.enum(QUESTION_TYPES),
+              config: tool.schema.looseObject({
+                question: tool.schema.string().optional(),
+                context: tool.schema.string().optional(),
+              }),
+            }),
+          }),
+        )
+        .describe("Branches to explore"),
+    },
+    execute: async (args) => {
+      const sessionId = generateSessionId();
+
+      await store.createSession(
+        sessionId,
+        args.request,
+        args.branches.map((b) => ({ id: b.id, scope: b.scope })),
+      );
+
+      const initialQuestions = args.branches.map((b) => {
+        const { type, config } = b.initial_question;
+        const context = `[${b.scope}] ${config.context ?? ""}`.trim();
+        return {
+          type,
+          config: { ...config, context },
+        };
+      });
+
+      const browserSession = await sessions.startSession({
+        title: "Brainstorming Session",
+        questions: initialQuestions,
+      });
+
+      await store.setBrowserSessionId(sessionId, browserSession.session_id);
+
+      for (const [i, branch] of args.branches.entries()) {
+        const questionId = browserSession.question_ids?.[i];
+        if (!questionId) continue;
+
+        const { type, config } = branch.initial_question;
+        await store.addQuestionToBranch(sessionId, branch.id, {
+          id: questionId,
+          type,
+          text: config.question ?? "Question",
+          config,
+        });
+      }
+
+      const branchesXml = args.branches.map((b) => `    <branch id="${b.id}">${b.scope}</branch>`).join("\n");
+      return `<brainstorm_created>
+  <session_id>${sessionId}</session_id>
+  <browser_session>${browserSession.session_id}</browser_session>
+  <url>${browserSession.url}</url>
+  <branches>
+${branchesXml}
+  </branches>
+  <next_action>Call get_next_answer(session_id="${browserSession.session_id}", block=true)</next_action>
+</brainstorm_created>`;
+    },
+  });
+
+  const get_session_summary = tool({
+    description: "Get summary of all branches and their findings",
+    args: {
+      session_id: tool.schema.string().describe("Brainstorm session ID"),
+    },
+    execute: async (args) => {
+      const state = await store.getSession(args.session_id);
+      if (!state) return `<error>Session not found: ${args.session_id}</error>`;
+
+      const branches = state.branch_order.map((id) => formatBranchStatus(state.branches[id])).join("\n");
+      const allDone = Object.values(state.branches).every((b) => b.status === BRANCH_STATUSES.DONE);
+
+      return `<session_summary>
+  <request>${state.request}</request>
+  <status>${allDone ? "complete" : "in_progress"}</status>
+  <branches>
+${branches}
+  </branches>
+</session_summary>`;
+    },
+  });
+
+  const end_brainstorm = tool({
+    description: "End a brainstorm session and get final summary",
+    args: {
+      session_id: tool.schema.string().describe("Brainstorm session ID"),
+    },
+    execute: async (args) => {
+      const state = await store.getSession(args.session_id);
+      if (!state) return `<error>Session not found: ${args.session_id}</error>`;
+
+      if (state.browser_session_id) {
+        await sessions.endSession(state.browser_session_id);
+      }
+
+      const findings = formatFindingsList(state);
+      await store.deleteSession(args.session_id);
+
+      return `<brainstorm_ended>
+  <request>${state.request}</request>
+  ${findings}
+  <next_action>Write the design document based on these findings</next_action>
+</brainstorm_ended>`;
+    },
+  });
+
+  const await_brainstorm_complete = tool({
+    description: `Wait for brainstorm session to complete. Processes answers asynchronously as they arrive.
+Returns when all branches are done with their findings.
+This is the recommended way to run a brainstorm - just create_brainstorm then await_brainstorm_complete.`,
+    args: {
+      session_id: tool.schema.string().describe("Brainstorm session ID (state session)"),
+      browser_session_id: tool.schema.string().describe("Browser session ID (for collecting answers)"),
+    },
+    execute: async (args) => {
+      const { state, allComplete } = await collectAnswers(
+        store,
+        sessions,
+        args.session_id,
+        args.browser_session_id,
+        client,
+      );
+
+      if (!state) return "<error>Session lost</error>";
+      if (!allComplete) return formatInProgressResult(state);
+
+      const sections = buildReviewSections(state);
+
+      try {
+        sessions.pushQuestion(args.browser_session_id, QUESTIONS.SHOW_PLAN, {
+          question: "Review Design Plan",
+          sections,
+        });
+      } catch {
+        return formatSkippedReviewResult(state);
+      }
+
+      const { approved, feedback } = await waitForReviewApproval(sessions, args.browser_session_id);
+      return formatCompletionResult(state, approved, feedback);
+    },
+  });
+
+  return {
+    create_brainstorm,
+    get_session_summary,
+    end_brainstorm,
+    await_brainstorm_complete,
+  };
+}
diff --git a/src/tools/octto/extractor.ts b/src/tools/octto/extractor.ts
new file mode 100644
index 0000000..ce0be1c
--- /dev/null
+++ b/src/tools/octto/extractor.ts
@@ -0,0 +1,95 @@
+// src/tools/octto/extractor.ts
+// Utility functions for extracting answer summaries
+
+import type {
+  Answer,
+  AskCodeAnswer,
+  AskTextAnswer,
+  ConfirmAnswer,
+  EmojiReactAnswer,
+  PickManyAnswer,
+  PickOneAnswer,
+  QuestionType,
+  RankAnswer,
+  RateAnswer,
+  ReviewAnswer,
+  ShowOptionsAnswer,
+  SliderAnswer,
+  ThumbsAnswer,
+} from "../../octto/session";
+import { QUESTIONS } from "../../octto/session";
+
+const MAX_TEXT_LENGTH = 100;
+
+function truncateText(text: string): string {
+  return text.length > MAX_TEXT_LENGTH ? `${text.substring(0, MAX_TEXT_LENGTH)}...` : text;
+}
+
+export function extractAnswerSummary(type: QuestionType, answer: Answer): string {
+  switch (type) {
+    case QUESTIONS.PICK_ONE:
+      return (answer as PickOneAnswer).selected;
+
+    case QUESTIONS.PICK_MANY:
+      return (answer as PickManyAnswer).selected.join(", ");
+
+    case QUESTIONS.CONFIRM:
+      return (answer as ConfirmAnswer).choice;
+
+    case QUESTIONS.THUMBS:
+      return (answer as ThumbsAnswer).choice;
+
+    case QUESTIONS.EMOJI_REACT:
+      return (answer as EmojiReactAnswer).emoji;
+
+    case QUESTIONS.ASK_TEXT:
+      return truncateText((answer as AskTextAnswer).text);
+
+    case QUESTIONS.SLIDER:
+      return String((answer as SliderAnswer).value);
+
+    case QUESTIONS.RANK: {
+      const rankAnswer = answer as RankAnswer;
+      const sorted = [...rankAnswer.ranking].sort((a, b) => a.rank - b.rank);
+      return sorted.map((r) => r.id).join(" → ");
+    }
+
+    case QUESTIONS.RATE: {
+      const rateAnswer = answer as RateAnswer;
+      const entries = Object.entries(rateAnswer.ratings);
+      if (entries.length === 0) return "no ratings";
+      const sorted = entries.sort((a, b) => b[1] - a[1]);
+      return sorted
+        .slice(0, 3)
+        .map(([k, v]) => `${k}: ${v}`)
+        .join(", ");
+    }
+
+    case QUESTIONS.ASK_CODE:
+      return truncateText((answer as AskCodeAnswer).code);
+
+    case QUESTIONS.ASK_IMAGE:
+    case QUESTIONS.ASK_FILE:
+      return "file(s) uploaded";
+
+    case QUESTIONS.SHOW_DIFF:
+    case QUESTIONS.SHOW_PLAN:
+    case QUESTIONS.REVIEW_SECTION: {
+      const reviewAnswer = answer as ReviewAnswer;
+      return reviewAnswer.feedback
+        ? `${reviewAnswer.decision}: ${truncateText(reviewAnswer.feedback)}`
+        : reviewAnswer.decision;
+    }
+
+    case QUESTIONS.SHOW_OPTIONS: {
+      const optAnswer = answer as ShowOptionsAnswer;
+      return optAnswer.feedback ? `${optAnswer.selected}: ${truncateText(optAnswer.feedback)}` : optAnswer.selected;
+    }
+
+    default: {
+      // Exhaustiveness check - if we get here, we missed a case
+      const _exhaustive: never = type;
+      return String(_exhaustive);
+    }
+  }
+}
diff --git a/src/tools/octto/factory.ts b/src/tools/octto/factory.ts
new file mode 100644
index 0000000..066ecc4
--- /dev/null
+++ b/src/tools/octto/factory.ts
@@ -0,0 +1,84 @@
+// src/tools/octto/factory.ts
+
+import { tool } from "@opencode-ai/plugin/tool";
+
+import type { BaseConfig, QuestionType, SessionStore } from "../../octto/session";
+
+import type { OcttoTool, OcttoTools } from "./types";
+
+type ArgsSchema = Parameters<typeof tool>[0]["args"];
+
+interface QuestionToolConfig<T> {
+  type: QuestionType;
+  description: string;
+  args: ArgsSchema;
+  validate?: (args: T) => string | null;
+  toConfig: (args: T) => BaseConfig;
+}
+
+export function createQuestionToolFactory(sessions: SessionStore) {
+  return function createQuestionTool<T extends { session_id: string }>(config: QuestionToolConfig<T>): OcttoTool {
+    return tool({
+      description: `${config.description}
+Returns immediately with question_id. Use get_answer to retrieve response.`,
+      args: {
+        session_id: tool.schema.string().describe("Session ID from start_session"),
+        ...config.args,
+      },
+      execute: async (args) => {
+        const validationError = config.validate?.(args as unknown as T);
+        if (validationError) return `Failed: ${validationError}`;
+
+        try {
+          const questionConfig = config.toConfig(args as unknown as T);
+          const result = sessions.pushQuestion(args.session_id, config.type, questionConfig);
+          return `Question pushed: ${result.question_id}\nUse get_answer("${result.question_id}") to retrieve response.`;
+        } catch (error) {
+          return `Failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+      },
+    });
+  };
+}
+
+export function createPushQuestionTool(sessions: SessionStore): OcttoTools {
+  const push_question = tool({
+    description: `Push a question to the session queue. This is the generic tool for adding any question type.
+The question will appear in the browser for the user to answer.`,
+    args: {
+      session_id: tool.schema.string().describe("Session ID from start_session"),
+      type: tool.schema
+        .enum([
+          "pick_one",
+          "pick_many",
+          "confirm",
+          "ask_text",
+          "show_options",
+          "review_section",
+          "thumbs",
+          "slider",
+          "rank",
+          "rate",
+        ])
+        .describe("Question type"),
+      config: tool.schema
+        .looseObject({
+          question: tool.schema.string().optional(),
+          context: tool.schema.string().optional(),
+        })
+        .describe("Question configuration (varies by type)"),
+    },
+    execute: async (args) => {
+      try {
+        const result = sessions.pushQuestion(args.session_id, args.type, args.config);
+        return `Question pushed: ${result.question_id}
+Type: ${args.type}
+Use get_next_answer(session_id, block=true) to wait for the user's response.`;
+      } catch (error) {
+        return `Failed to push question: ${error instanceof Error ? error.message : String(error)}`;
+      }
+    },
+  });
+
+  return { push_question };
+}
diff --git a/src/tools/octto/formatters.ts b/src/tools/octto/formatters.ts
new file mode 100644
index 0000000..abfe4cd
--- /dev/null
+++ b/src/tools/octto/formatters.ts
@@ -0,0 +1,59 @@
+// src/tools/octto/formatters.ts
+
+import type { Answer } from "../../octto/session";
+import type { BrainstormState, Branch, BranchQuestion } from "../../octto/state";
+
+import { extractAnswerSummary } from "./extractor";
+
+function escapeXml(str: string): string {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export function formatBranchFinding(branch: Branch): string {
+  return `<branch id="${branch.id}">
+    <scope>${escapeXml(branch.scope)}</scope>
+    <finding>${escapeXml(branch.finding || "no finding")}</finding>
+  </branch>`;
+}
+
+export function formatBranchStatus(branch: Branch): string {
+  return `<branch id="${branch.id}" status="${branch.status}">
+    <scope>${escapeXml(branch.scope)}</scope>
+    <finding>${escapeXml(branch.finding || "pending")}</finding>
+  </branch>`;
+}
+
+export function formatFindings(state: BrainstormState): string {
+  const branches = state.branch_order.map((id) => formatBranchFinding(state.branches[id])).join("\n");
+  return `<findings>\n${branches}\n</findings>`;
+}
+
+export function formatFindingsList(state: BrainstormState): string {
+  const items = state.branch_order
+    .map((id) => {
+      const b = state.branches[id];
+      return `  <finding scope="${escapeXml(b.scope)}">${escapeXml(b.finding || "no finding")}</finding>`;
+    })
+    .join("\n");
+  return `<findings>\n${items}\n</findings>`;
+}
+
+export function formatQASummary(branch: Branch): string {
+  const answered = branch.questions.filter((q): q is BranchQuestion & { answer: Answer } => q.answer !== undefined);
+
+  if (answered.length === 0) {
+    return "<qa_summary>no questions answered</qa_summary>";
+  }
+
+  const qas = answered
+    .map((q) => {
+      const answerText = extractAnswerSummary(q.type, q.answer);
+      return `    <qa>
+      <question>${escapeXml(q.text)}</question>
+      <answer>${escapeXml(answerText)}</answer>
+    </qa>`;
+    })
+    .join("\n");
+
+  return qas;
+}
diff --git a/src/tools/octto/index.ts b/src/tools/octto/index.ts
new file mode 100644
index 0000000..dd4a224
--- /dev/null
+++ b/src/tools/octto/index.ts
@@ -0,0 +1,24 @@
+// src/tools/octto/index.ts
+
+import type { SessionStore } from "../../octto/session";
+
+import { createBrainstormTools } from "./brainstorm";
+import { createPushQuestionTool } from "./factory";
+import { createQuestionTools } from "./questions";
+import { createResponseTools } from "./responses";
+import { createSessionTools } from "./session";
+import type { OcttoTools, OpencodeClient } from "./types";
+
+export type { OcttoTools, OpencodeClient } from "./types";
+export type { SessionStore } from "../../octto/session";
+export { createSessionStore } from "../../octto/session";
+
+export function createOcttoTools(sessions: SessionStore, client: OpencodeClient): OcttoTools {
+  return {
+    ...createSessionTools(sessions),
+    ...createQuestionTools(sessions),
+    ...createResponseTools(sessions),
+    ...createPushQuestionTool(sessions),
+    ...createBrainstormTools(sessions, client),
+  };
+}
diff --git a/src/tools/octto/processor.ts b/src/tools/octto/processor.ts
new file mode 100644
index 0000000..cfe9a8f
--- /dev/null
+++ b/src/tools/octto/processor.ts
@@ -0,0 +1,165 @@
+// src/tools/octto/processor.ts
+
+import type { Answer, QuestionType, SessionStore } from "../../octto/session";
+import { BRANCH_STATUSES, type BrainstormState, type StateStore } from "../../octto/state";
+import { log } from "../../utils/logger";
+
+import type { OpencodeClient } from "./types";
+
+// Agent name constant - matches the agent exported from src/agents/probe.ts
+const PROBE_AGENT = "probe";
+
+interface ProbeResult {
+  done: boolean;
+  finding?: string;
+  question?: {
+    type: QuestionType;
+    config: Record<string, unknown>;
+  };
+}
+
+function formatBranchContext(state: BrainstormState, branchId: string): string {
+  const lines: string[] = [];
+
+  lines.push(`<original_request>${state.request}</original_request>`);
+  lines.push("");
+  lines.push("<branches>");
+
+  for (const [id, branch] of Object.entries(state.branches)) {
+    const isCurrent = id === branchId;
+    lines.push(`<branch id="${id}" scope="${branch.scope}"${isCurrent ? ' current="true"' : ""}>`);
+
+    for (const q of branch.questions) {
+      lines.push(`  <question type="${q.type}">${q.text}</question>`);
+      if (q.answer) {
+        lines.push(`  <answer>${JSON.stringify(q.answer)}</answer>`);
+      }
+    }
+
+    if (branch.status === BRANCH_STATUSES.DONE && branch.finding) {
+      lines.push(`  <finding>${branch.finding}</finding>`);
+    }
+
+    lines.push("</branch>");
+  }
+
+  lines.push("</branches>");
+  lines.push("");
+  lines.push(`Evaluate the branch "${branchId}" and decide: ask another question or complete with a finding.`);
+
+  return lines.join("\n");
+}
+
+async function runProbeAgent(client: OpencodeClient, state: BrainstormState, branchId: string): Promise<ProbeResult> {
+  const sessionResult = await client.session.create({
+    body: { title: `probe-${branchId}` },
+  });
+
+  if (!sessionResult.data) {
+    throw new Error("Failed to create probe session");
+  }
+
+  const probeSessionId = sessionResult.data.id;
+
+  try {
+    const promptResult = await client.session.prompt({
+      path: { id: probeSessionId },
+      body: {
+        agent: PROBE_AGENT,
+        tools: {},
+        parts: [{ type: "text", text: formatBranchContext(state, branchId) }],
+      },
+    });
+
+    if (!promptResult.data) {
+      throw new Error("Failed to get probe response");
+    }
+
+    let responseText = "";
+    for (const part of promptResult.data.parts) {
+      if (part.type === "text" && "text" in part) {
+        responseText += (part as { text: string }).text;
+      }
+    }
+
+    const jsonMatch = responseText.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      return { done: true, finding: "Could not parse probe response" };
+    }
+
+    return JSON.parse(jsonMatch[0]) as ProbeResult;
+  } finally {
+    await client.session.delete({ path: { id: probeSessionId } }).catch(() => {});
+  }
+}
+
+export async function processAnswer(
+  stateStore: StateStore,
+  sessions: SessionStore,
+  sessionId: string,
+  browserSessionId: string,
+  questionId: string,
+  answer: Answer,
+  client: OpencodeClient,
+): Promise<void> {
+  const state = await stateStore.getSession(sessionId);
+  if (!state) return;
+
+  // Find which branch this question belongs to
+  let branchId: string | null = null;
+  for (const [id, branch] of Object.entries(state.branches)) {
+    if (branch.questions.some((q) => q.id === questionId)) {
+      branchId = id;
+      break;
+    }
+  }
+
+  if (!branchId) return;
+  if (state.branches[branchId].status === BRANCH_STATUSES.DONE) return;
+
+  // Record the answer
+  try {
+    await stateStore.recordAnswer(sessionId, questionId, answer);
+  } catch (error) {
+    log.error("octto", `Failed to record answer for ${questionId}`, error);
+    throw error;
+  }
+
+  // Get fresh state after recording
+  const updatedState = await stateStore.getSession(sessionId);
+  if (!updatedState) return;
+
+  const branch = updatedState.branches[branchId];
+  if (!branch || branch.status === BRANCH_STATUSES.DONE) return;
+
+  // Evaluate branch using probe agent
+  const result = await runProbeAgent(client, updatedState, branchId);
+
+  if (result.done) {
+    await stateStore.completeBranch(sessionId, branchId, result.finding || "No finding");
+    return;
+  }
+
+  if (result.question) {
+    const config = result.question.config as { question?: string; context?: string };
+    const questionText = config.question ?? "Follow-up question";
+    const existingContext = config.context ?? "";
+    const configWithContext = {
+      ...config,
+      context: `[${branch.scope}] ${existingContext}`.trim(),
+    };
+
+    const { question_id: newQuestionId } = sessions.pushQuestion(
+      browserSessionId,
+      result.question.type,
+      configWithContext,
+    );
+
+    await stateStore.addQuestionToBranch(sessionId, branchId, {
+      id: newQuestionId,
+      type: result.question.type,
+      text: questionText,
+      config: configWithContext,
+    });
+  }
+}
diff --git a/src/tools/octto/questions.ts b/src/tools/octto/questions.ts
new file mode 100644
index 0000000..7df9422
--- /dev/null
+++ b/src/tools/octto/questions.ts
@@ -0,0 +1,488 @@
+// src/tools/octto/questions.ts
+import { tool } from "@opencode-ai/plugin/tool";
+
+import type { SessionStore } from "../../octto/session";
+import type { ConfirmConfig, PickManyConfig, PickOneConfig, RankConfig, RateConfig } from "../../octto/types";
+
+import { createQuestionToolFactory } from "./factory";
+import type { OcttoTools } from "./types";
+
+const optionsSchema = tool.schema
+  .array(
+    tool.schema.object({
+      id: tool.schema.string().describe("Unique option identifier"),
+      label: tool.schema.string().describe("Display label"),
+      description: tool.schema.string().optional().describe("Optional description"),
+    }),
+  )
+  .describe("Available options");
+
+function requireOptions(args: { options?: unknown[] }): string | null {
+  if (!args.options || args.options.length === 0) return "options array must not be empty";
+  return null;
+}
+
+export function createQuestionTools(sessions: SessionStore): OcttoTools {
+  const createTool = createQuestionToolFactory(sessions);
+
+  const pick_one = createTool<PickOneConfig & { session_id: string }>({
+    type: "pick_one",
+    description: `Ask user to select ONE option from a list.
+Response format: { selected: string } where selected is the chosen option id.`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      options: optionsSchema,
+      recommended: tool.schema.string().optional().describe("Recommended option id (highlighted)"),
+      allowOther: tool.schema.boolean().optional().describe("Allow custom 'other' input"),
+    },
+    validate: requireOptions,
+    toConfig: (args) => ({
+      question: args.question,
+      options: args.options,
+      recommended: args.recommended,
+      allowOther: args.allowOther,
+    }),
+  });
+
+  const pick_many = createTool<PickManyConfig & { session_id: string }>({
+    type: "pick_many",
+    description: `Ask user to select MULTIPLE options from a list.
+Response format: { selected: string[] } where selected is array of chosen option ids.`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      options: optionsSchema,
+      recommended: tool.schema.array(tool.schema.string()).optional().describe("Recommended option ids"),
+      min: tool.schema.number().optional().describe("Minimum selections required"),
+      max: tool.schema.number().optional().describe("Maximum selections allowed"),
+      allowOther: tool.schema.boolean().optional().describe("Allow custom 'other' input"),
+    },
+    validate: (args) => {
+      if (!args.options || args.options.length === 0) return "options array must not be empty";
+      if (args.min !== undefined && args.max !== undefined && args.min > args.max) {
+        return `min (${args.min}) cannot be greater than max (${args.max})`;
+      }
+      return null;
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      options: args.options,
+      recommended: args.recommended,
+      min: args.min,
+      max: args.max,
+      allowOther: args.allowOther,
+    }),
+  });
+
+  const confirm = createTool<ConfirmConfig & { session_id: string }>({
+    type: "confirm",
+    description: `Ask user for Yes/No confirmation.
+Response format: { choice: "yes" | "no" | "cancel" }`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      context: tool.schema.string().optional().describe("Additional context/details"),
+      yesLabel: tool.schema.string().optional().describe("Custom label for yes button"),
+      noLabel: tool.schema.string().optional().describe("Custom label for no button"),
+      allowCancel: tool.schema.boolean().optional().describe("Show cancel option"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      context: args.context,
+      yesLabel: args.yesLabel,
+      noLabel: args.noLabel,
+      allowCancel: args.allowCancel,
+    }),
+  });
+
+  const rank = createTool<RankConfig & { session_id: string }>({
+    type: "rank",
+    description: `Ask user to rank/order items by dragging.
+Response format: { ranked: string[] } where ranked is array of option ids in user's order (first = highest).`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      options: optionsSchema.describe("Items to rank"),
+      context: tool.schema.string().optional().describe("Instructions/context"),
+    },
+    validate: requireOptions,
+    toConfig: (args) => ({
+      question: args.question,
+      options: args.options,
+      context: args.context,
+    }),
+  });
+
+  const rate = createTool<RateConfig & { session_id: string }>({
+    type: "rate",
+    description: `Ask user to rate items on a numeric scale.
+Response format: { ratings: Record<string, number> } where key is option id, value is rating.`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      options: optionsSchema.describe("Items to rate"),
+      min: tool.schema.number().optional().describe("Minimum rating value (default: 1)"),
+      max: tool.schema.number().optional().describe("Maximum rating value (default: 5)"),
+      step: tool.schema.number().optional().describe("Rating step (default: 1)"),
+    },
+    validate: (args) => {
+      if (!args.options || args.options.length === 0) return "options array must not be empty";
+      const min = args.min ?? 1;
+      const max = args.max ?? 5;
+      if (min >= max) return `min (${min}) must be less than max (${max})`;
+      return null;
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      options: args.options,
+      min: args.min ?? 1,
+      max: args.max ?? 5,
+      step: args.step,
+    }),
+  });
+
+  // Import remaining tools from other files
+  const inputTools = createInputTools(sessions);
+  const presentationTools = createPresentationTools(sessions);
+  const quickTools = createQuickTools(sessions);
+
+  return {
+    pick_one,
+    pick_many,
+    confirm,
+    rank,
+    rate,
+    ...inputTools,
+    ...presentationTools,
+    ...quickTools,
+  };
+}
+
+// Input tools using factory
+function createInputTools(sessions: SessionStore): OcttoTools {
+  const createTool = createQuestionToolFactory(sessions);
+
+  interface TextConfig {
+    session_id: string;
+    question: string;
+    placeholder?: string;
+    context?: string;
+    multiline?: boolean;
+    minLength?: number;
+    maxLength?: number;
+  }
+
+  const ask_text = createTool<TextConfig>({
+    type: "ask_text",
+    description: `Ask user for text input (single or multi-line).
+Response format: { text: string }`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      placeholder: tool.schema.string().optional().describe("Placeholder text"),
+      context: tool.schema.string().optional().describe("Instructions/context"),
+      multiline: tool.schema.boolean().optional().describe("Multi-line input (default: false)"),
+      minLength: tool.schema.number().optional().describe("Minimum text length"),
+      maxLength: tool.schema.number().optional().describe("Maximum text length"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      placeholder: args.placeholder,
+      context: args.context,
+      multiline: args.multiline,
+      minLength: args.minLength,
+      maxLength: args.maxLength,
+    }),
+  });
+
+  interface ImageConfig {
+    session_id: string;
+    question: string;
+    context?: string;
+    multiple?: boolean;
+    maxImages?: number;
+  }
+
+  const ask_image = createTool<ImageConfig>({
+    type: "ask_image",
+    description: "Ask user to upload/paste image(s).",
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      context: tool.schema.string().optional().describe("Instructions/context"),
+      multiple: tool.schema.boolean().optional().describe("Allow multiple images"),
+      maxImages: tool.schema.number().optional().describe("Maximum number of images"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      context: args.context,
+      multiple: args.multiple,
+      maxImages: args.maxImages,
+    }),
+  });
+
+  interface FileConfig {
+    session_id: string;
+    question: string;
+    context?: string;
+    multiple?: boolean;
+    maxFiles?: number;
+    accept?: string[];
+    maxSize?: number;
+  }
+
+  const ask_file = createTool<FileConfig>({
+    type: "ask_file",
+    description: "Ask user to upload file(s).",
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      context: tool.schema.string().optional().describe("Instructions/context"),
+      multiple: tool.schema.boolean().optional().describe("Allow multiple files"),
+      maxFiles: tool.schema.number().optional().describe("Maximum number of files"),
+      accept: tool.schema.array(tool.schema.string()).optional().describe("Allowed file types"),
+      maxSize: tool.schema.number().optional().describe("Maximum file size in bytes"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      context: args.context,
+      multiple: args.multiple,
+      maxFiles: args.maxFiles,
+      accept: args.accept,
+      maxSize: args.maxSize,
+    }),
+  });
+
+  interface CodeConfig {
+    session_id: string;
+    question: string;
+    context?: string;
+    language?: string;
+    placeholder?: string;
+  }
+
+  const ask_code = createTool<CodeConfig>({
+    type: "ask_code",
+    description: "Ask user for code input with syntax highlighting.",
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      context: tool.schema.string().optional().describe("Instructions/context"),
+      language: tool.schema.string().optional().describe("Programming language for highlighting"),
+      placeholder: tool.schema.string().optional().describe("Placeholder code"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      context: args.context,
+      language: args.language,
+      placeholder: args.placeholder,
+    }),
+  });
+
+  return { ask_text, ask_image, ask_file, ask_code };
+}
+
+// Presentation tools using factory
+function createPresentationTools(sessions: SessionStore): OcttoTools {
+  const createTool = createQuestionToolFactory(sessions);
+
+  interface DiffConfig {
+    session_id: string;
+    question: string;
+    before: string;
+    after: string;
+    filePath?: string;
+    language?: string;
+  }
+
+  const show_diff = createTool<DiffConfig>({
+    type: "show_diff",
+    description: "Show a diff and ask user to approve/reject/edit.",
+    args: {
+      question: tool.schema.string().describe("Title/description of the change"),
+      before: tool.schema.string().describe("Original content"),
+      after: tool.schema.string().describe("Modified content"),
+      filePath: tool.schema.string().optional().describe("File path for context"),
+      language: tool.schema.string().optional().describe("Language for syntax highlighting"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      before: args.before,
+      after: args.after,
+      filePath: args.filePath,
+      language: args.language,
+    }),
+  });
+
+  const sectionSchema = tool.schema.array(
+    tool.schema.object({
+      id: tool.schema.string().describe("Section identifier"),
+      title: tool.schema.string().describe("Section title"),
+      content: tool.schema.string().describe("Section content (markdown)"),
+    }),
+  );
+
+  interface PlanConfig {
+    session_id: string;
+    question: string;
+    sections?: Array<{ id: string; title: string; content: string }>;
+    markdown?: string;
+  }
+
+  const show_plan = createTool<PlanConfig>({
+    type: "show_plan",
+    description: `Show a plan/document for user review with annotations.
+Response format: { approved: boolean, annotations?: Record<sectionId, string> }`,
+    args: {
+      question: tool.schema.string().describe("Plan title"),
+      sections: sectionSchema.optional().describe("Plan sections"),
+      markdown: tool.schema.string().optional().describe("Full markdown (alternative to sections)"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      sections: args.sections || [],
+      markdown: args.markdown,
+    }),
+  });
+
+  const prosConsOptionSchema = tool.schema.array(
+    tool.schema.object({
+      id: tool.schema.string().describe("Unique option identifier"),
+      label: tool.schema.string().describe("Display label"),
+      description: tool.schema.string().optional().describe("Optional description"),
+      pros: tool.schema.array(tool.schema.string()).optional().describe("Advantages"),
+      cons: tool.schema.array(tool.schema.string()).optional().describe("Disadvantages"),
+    }),
+  );
+
+  interface ShowOptionsConfig {
+    session_id: string;
+    question: string;
+    options: Array<{ id: string; label: string; description?: string; pros?: string[]; cons?: string[] }>;
+    recommended?: string;
+    allowFeedback?: boolean;
+  }
+
+  const show_options = createTool<ShowOptionsConfig>({
+    type: "show_options",
+    description: `Show options with pros/cons for user to select.
+Response format: { selected: string, feedback?: string } where selected is the chosen option id.`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      options: prosConsOptionSchema.describe("Options with pros/cons"),
+      recommended: tool.schema.string().optional().describe("Recommended option id"),
+      allowFeedback: tool.schema.boolean().optional().describe("Allow text feedback with selection"),
+    },
+    validate: (args) => {
+      if (!args.options || args.options.length === 0) return "options array must not be empty";
+      return null;
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      options: args.options,
+      recommended: args.recommended,
+      allowFeedback: args.allowFeedback,
+    }),
+  });
+
+  interface ReviewConfig {
+    session_id: string;
+    question: string;
+    content: string;
+    context?: string;
+  }
+
+  const review_section = createTool<ReviewConfig>({
+    type: "review_section",
+    description: "Show content section for user review with inline feedback.",
+    args: {
+      question: tool.schema.string().describe("Section title"),
+      content: tool.schema.string().describe("Section content (markdown)"),
+      context: tool.schema.string().optional().describe("Context about what to review"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      content: args.content,
+      context: args.context,
+    }),
+  });
+
+  return { show_diff, show_plan, show_options, review_section };
+}
+
+// Quick tools using factory
+function createQuickTools(sessions: SessionStore): OcttoTools {
+  const createTool = createQuestionToolFactory(sessions);
+
+  interface ThumbsConfig {
+    session_id: string;
+    question: string;
+    context?: string;
+  }
+
+  const thumbs = createTool<ThumbsConfig>({
+    type: "thumbs",
+    description: `Ask user for quick thumbs up/down feedback.
+Response format: { choice: "up" | "down" }`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      context: tool.schema.string().optional().describe("Context to show"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      context: args.context,
+    }),
+  });
+
+  interface EmojiConfig {
+    session_id: string;
+    question: string;
+    context?: string;
+    emojis?: string[];
+  }
+
+  const emoji_react = createTool<EmojiConfig>({
+    type: "emoji_react",
+    description: "Ask user to react with an emoji.",
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      context: tool.schema.string().optional().describe("Context to show"),
+      emojis: tool.schema.array(tool.schema.string()).optional().describe("Available emoji options"),
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      context: args.context,
+      emojis: args.emojis,
+    }),
+  });
+
+  interface SliderConfig {
+    session_id: string;
+    question: string;
+    min: number;
+    max: number;
+    step?: number;
+    defaultValue?: number;
+    context?: string;
+  }
+
+  const slider = createTool<SliderConfig>({
+    type: "slider",
+    description: `Ask user to select a value on a numeric slider.
+Response format: { value: number }`,
+    args: {
+      question: tool.schema.string().describe("Question to display"),
+      min: tool.schema.number().describe("Minimum value"),
+      max: tool.schema.number().describe("Maximum value"),
+      step: tool.schema.number().optional().describe("Step size (default: 1)"),
+      defaultValue: tool.schema.number().optional().describe("Default value"),
+      context: tool.schema.string().optional().describe("Instructions/context"),
+    },
+    validate: (args) => {
+      if (args.min >= args.max) return `min (${args.min}) must be less than max (${args.max})`;
+      return null;
+    },
+    toConfig: (args) => ({
+      question: args.question,
+      min: args.min,
+      max: args.max,
+      step: args.step,
+      defaultValue: args.defaultValue,
+      context: args.context,
+    }),
+  });
+
+  return { thumbs, emoji_react, slider };
+}
diff --git a/src/tools/octto/responses.ts b/src/tools/octto/responses.ts
new file mode 100644
index 0000000..ffea057
--- /dev/null
+++ b/src/tools/octto/responses.ts
@@ -0,0 +1,135 @@
+// src/tools/octto/responses.ts
+import { tool } from "@opencode-ai/plugin/tool";
+
+import { type SessionStore, STATUSES } from "../../octto/session";
+
+import type { OcttoTools } from "./types";
+
+export function createResponseTools(sessions: SessionStore): OcttoTools {
+  const get_answer = tool({
+    description: `Get the answer to a SPECIFIC question.
+By default returns immediately with current status.
+Set block=true to wait for user response (with optional timeout).
+NOTE: Prefer get_next_answer for better flow - it returns whichever question user answers first.`,
+    args: {
+      question_id: tool.schema.string().describe("Question ID from a question tool"),
+      block: tool.schema.boolean().optional().describe("Wait for response (default: false)"),
+      timeout: tool.schema
+        .number()
+        .optional()
+        .describe("Max milliseconds to wait if blocking (default: 300000 = 5 min)"),
+    },
+    execute: async (args) => {
+      const result = await sessions.getAnswer({
+        question_id: args.question_id,
+        block: args.block,
+        timeout: args.timeout,
+      });
+
+      if (result.completed) {
+        return `## Answer Received
+
+**Status:** ${result.status}
+
+**Response:**
+\`\`\`json
+${JSON.stringify(result.response, null, 2)}
+\`\`\``;
+      }
+
+      return `## Waiting for Answer
+
+**Status:** ${result.status}
+**Reason:** ${result.reason}
+
+${result.status === STATUSES.PENDING ? "User has not answered yet. Call again with block=true to wait." : ""}`;
+    },
+  });
+
+  const get_next_answer = tool({
+    description: `Wait for ANY question to be answered. Returns whichever question the user answers first.
+This is the PREFERRED way to get answers - lets user answer in any order.
+Push multiple questions, then call this repeatedly to get answers as they come.`,
+    args: {
+      session_id: tool.schema.string().describe("Session ID from start_session"),
+      block: tool.schema.boolean().optional().describe("Wait for response (default: false)"),
+      timeout: tool.schema
+        .number()
+        .optional()
+        .describe("Max milliseconds to wait if blocking (default: 300000 = 5 min)"),
+    },
+    execute: async (args) => {
+      const result = await sessions.getNextAnswer({
+        session_id: args.session_id,
+        block: args.block,
+        timeout: args.timeout,
+      });
+
+      if (result.completed) {
+        return `## Answer Received
+
+**Question ID:** ${result.question_id}
+**Question Type:** ${result.question_type}
+**Status:** ${result.status}
+
+**Response:**
+\`\`\`json
+${JSON.stringify(result.response, null, 2)}
+\`\`\``;
+      }
+
+      if (result.status === STATUSES.NONE_PENDING) {
+        return `## No Pending Questions
+
+All questions have been answered or there are no questions in the queue.
+Push more questions or end the session.`;
+      }
+
+      return `## Waiting for Answer
+
+**Status:** ${result.status}
+${result.reason === STATUSES.TIMEOUT ? "Timed out waiting for response." : "No answer yet."}`;
+    },
+  });
+
+  const list_questions = tool({
+    description: `List all questions and their status for a session.`,
+    args: {
+      session_id: tool.schema.string().optional().describe("Session ID (omit for all sessions)"),
+    },
+    execute: async (args) => {
+      const result = sessions.listQuestions(args.session_id);
+
+      if (result.questions.length === 0) {
+        return "No questions found.";
+      }
+
+      let output = "## Questions\n\n";
+      output += "| ID | Type | Status | Created | Answered |\n";
+      output += "|----|------|--------|---------|----------|\n";
+
+      for (const q of result.questions) {
+        output += `| ${q.id} | ${q.type} | ${q.status} | ${q.createdAt} | ${q.answeredAt || "-"} |\n`;
+      }
+
+      return output;
+    },
+  });
+
+  const cancel_question = tool({
+    description: `Cancel a pending question.
+The question will be removed from the user's queue.`,
+    args: {
+      question_id: tool.schema.string().describe("Question ID to cancel"),
+    },
+    execute: async (args) => {
+      const result = sessions.cancelQuestion(args.question_id);
+      if (result.ok) {
+        return `Question ${args.question_id} cancelled.`;
+      }
+      return `Could not cancel question ${args.question_id}. It may already be answered or not exist.`;
+    },
+  });
+
+  return { get_answer, get_next_answer, list_questions, cancel_question };
+}
diff --git a/src/tools/octto/session.ts b/src/tools/octto/session.ts
new file mode 100644
index 0000000..f70c5fd
--- /dev/null
+++ b/src/tools/octto/session.ts
@@ -0,0 +1,104 @@
+// src/tools/octto/session.ts
+import { tool } from "@opencode-ai/plugin/tool";
+
+import type { SessionStore } from "../../octto/session";
+
+import type { OcttoTools } from "./types";
+
+export function createSessionTools(sessions: SessionStore): OcttoTools {
+  const start_session = tool({
+    description: `Start an interactive octto session with initial questions.
+Opens a browser window with questions already displayed - no waiting.
+REQUIRED: You MUST provide at least 1 question. Will fail without questions.`,
+    args: {
+      title: tool.schema.string().optional().describe("Session title (shown in browser)"),
+      questions: tool.schema
+        .array(
+          tool.schema.object({
+            type: tool.schema
+              .enum([
+                "pick_one",
+                "pick_many",
+                "confirm",
+                "ask_text",
+                "show_options",
+                "review_section",
+                "thumbs",
+                "slider",
+              ])
+              .describe("Question type"),
+            config: tool.schema
+              .looseObject({
+                question: tool.schema.string().optional(),
+                context: tool.schema.string().optional(),
+              })
+              .describe("Question config (varies by type)"),
+          }),
+        )
+        .describe("REQUIRED: Initial questions to display when browser opens. Must have at least 1."),
+    },
+    execute: async (args) => {
+      // ENFORCE: questions are required
+      if (!args.questions || args.questions.length === 0) {
+        return `## ERROR: questions parameter is REQUIRED
+
+start_session MUST include questions. Browser should open with questions ready.
+
+Example:
+\`\`\`
+start_session(
+  title="Design Session",
+  questions=[
+    {type: "pick_one", config: {question: "What language?", options: [{id: "go", label: "Go"}]}},
+    {type: "ask_text", config: {question: "Any constraints?"}}
+  ]
+)
+\`\`\`
+
+Please call start_session again WITH your prepared questions.`;
+      }
+
+      try {
+        const result = await sessions.startSession({ title: args.title, questions: args.questions });
+
+        let output = `## Session Started
+
+| Field | Value |
+|-------|-------|
+| Session ID | ${result.session_id} |
+| URL | ${result.url} |
+`;
+
+        if (result.question_ids && result.question_ids.length > 0) {
+          output += `| Questions | ${result.question_ids.length} loaded |\n\n`;
+          output += `**Question IDs:** ${result.question_ids.join(", ")}\n\n`;
+          output += `Browser opened with ${result.question_ids.length} questions ready.\n`;
+          output += `Use get_next_answer(session_id, block=true) to get answers as user responds.`;
+        } else {
+          output += `\nBrowser opened. Use question tools to push questions.`;
+        }
+
+        return output;
+      } catch (error) {
+        return `Failed to start session: ${error instanceof Error ? error.message : String(error)}`;
+      }
+    },
+  });
+
+  const end_session = tool({
+    description: `End an interactive octto session.
+Closes the browser window and cleans up resources.`,
+    args: {
+      session_id: tool.schema.string().describe("Session ID to end"),
+    },
+    execute: async (args) => {
+      const result = await sessions.endSession(args.session_id);
+      if (result.ok) {
+        return `Session ${args.session_id} ended successfully.`;
+      }
+      return `Failed to end session ${args.session_id}. It may not exist.`;
+    },
+  });
+
+  return { start_session, end_session };
+}
diff --git a/src/tools/octto/types.ts b/src/tools/octto/types.ts
new file mode 100644
index 0000000..853eb98
--- /dev/null
+++ b/src/tools/octto/types.ts
@@ -0,0 +1,16 @@
+// src/tools/octto/types.ts
+
+import type { ToolContext } from "@opencode-ai/plugin/tool";
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+
+// Using `any` to avoid exposing zod types in declaration files.
+// The actual tools are typesafe via zod schemas.
+export interface OcttoTool {
+  description: string;
+  args: any;
+  execute: (args: any, context: ToolContext) => Promise<string>;
+}
+
+export type OcttoTools = Record<string, OcttoTool>;
+
+export type OpencodeClient = ReturnType<typeof createOpencodeClient>;
diff --git a/src/tools/octto/utils.ts b/src/tools/octto/utils.ts
new file mode 100644
index 0000000..fb181a6
--- /dev/null
+++ b/src/tools/octto/utils.ts
@@ -0,0 +1,4 @@
+// src/tools/octto/utils.ts
+// Re-export ID generation utilities from octto/session for convenience
+
+export { generateBrainstormId, generateQuestionId, generateSessionId } from "../../octto/session/utils";
diff --git a/src/utils/config.ts b/src/utils/config.ts
index 3414937..e47a2bf 100644
--- a/src/utils/config.ts
+++ b/src/utils/config.ts
@@ -100,4 +100,18 @@ export const config = {
     /** Max entries in context cache */
     contextCacheMaxSize: 100,
   },
+
+  /**
+   * Octto (browser-based brainstorming) settings
+   */
+  octto: {
+    /** Answer timeout (ms) - 5 minutes */
+    answerTimeoutMs: 5 * 60 * 1000,
+    /** Review timeout (ms) - 10 minutes */
+    reviewTimeoutMs: 10 * 60 * 1000,
+    /** Max iterations in brainstorm loop */
+    maxIterations: 50,
+    /** State directory for brainstorm sessions */
+    stateDir: "thoughts/brainstorms",
+  },
 } as const;

From 589263f472951bf88a5420e9339c71ae4fa46eb8 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sat, 17 Jan 2026 13:56:32 +0200
Subject: [PATCH 12/22] feat(indexing): add milestone artifact indexing

---
 src/indexing/milestone-artifact-classifier.ts |  26 +++
 src/indexing/milestone-artifact-ingest.ts     |  42 +++++
 src/tools/artifact-index/index.ts             | 155 +++++++++++++++++-
 src/tools/artifact-index/schema.sql           |  21 +++
 .../milestone-artifact-classifier.test.ts     |  28 ++++
 .../flows/milestone-error-paths.test.ts       |  55 +++++++
 tests/indexing/flows/milestone-ingest.test.ts |  47 ++++++
 .../indexing/search/milestone-search.test.ts  |  58 +++++++
 tests/tools/artifact-index-schema.test.ts     |   9 +-
 9 files changed, 437 insertions(+), 4 deletions(-)
 create mode 100644 src/indexing/milestone-artifact-classifier.ts
 create mode 100644 src/indexing/milestone-artifact-ingest.ts
 create mode 100644 tests/indexing/classifier/milestone-artifact-classifier.test.ts
 create mode 100644 tests/indexing/flows/milestone-error-paths.test.ts
 create mode 100644 tests/indexing/flows/milestone-ingest.test.ts
 create mode 100644 tests/indexing/search/milestone-search.test.ts

diff --git a/src/indexing/milestone-artifact-classifier.ts b/src/indexing/milestone-artifact-classifier.ts
new file mode 100644
index 0000000..0e96333
--- /dev/null
+++ b/src/indexing/milestone-artifact-classifier.ts
@@ -0,0 +1,26 @@
+export const MILESTONE_ARTIFACT_TYPES = {
+  FEATURE: "feature",
+  DECISION: "decision",
+  SESSION: "session",
+} as const;
+
+export type MilestoneArtifactType = (typeof MILESTONE_ARTIFACT_TYPES)[keyof typeof MILESTONE_ARTIFACT_TYPES];
+
+const FEATURE_HINTS = ["requirement", "implementation", "capability", "scope", "spec"];
+const DECISION_HINTS = ["decision", "decided", "trade-off", "rationale", "chosen"];
+const SESSION_HINTS = ["meeting", "status", "discussion", "notes", "update"];
+
+const matchesAny = (content: string, hints: string[]) => hints.some((hint) => content.includes(hint));
+
+export function classifyMilestoneArtifact(content: string): MilestoneArtifactType {
+  const normalized = content.toLowerCase();
+  const isFeature = matchesAny(normalized, FEATURE_HINTS);
+  const isDecision = matchesAny(normalized, DECISION_HINTS);
+  const isSession = matchesAny(normalized, SESSION_HINTS);
+
+  if (isFeature) return MILESTONE_ARTIFACT_TYPES.FEATURE;
+  if (isDecision) return MILESTONE_ARTIFACT_TYPES.DECISION;
+  if (isSession) return MILESTONE_ARTIFACT_TYPES.SESSION;
+
+  return MILESTONE_ARTIFACT_TYPES.SESSION;
+}
diff --git a/src/indexing/milestone-artifact-ingest.ts b/src/indexing/milestone-artifact-ingest.ts
new file mode 100644
index 0000000..7014603
--- /dev/null
+++ b/src/indexing/milestone-artifact-ingest.ts
@@ -0,0 +1,42 @@
+import { type ArtifactIndex, getArtifactIndex } from "../tools/artifact-index";
+import { log } from "../utils/logger";
+import {
+  classifyMilestoneArtifact,
+  MILESTONE_ARTIFACT_TYPES,
+  type MilestoneArtifactType,
+} from "./milestone-artifact-classifier";
+
+export interface MilestoneArtifactInput {
+  id: string;
+  milestoneId: string;
+  sourceSessionId?: string;
+  createdAt?: string;
+  tags?: string[];
+  payload: string;
+}
+
+export async function ingestMilestoneArtifact(
+  input: MilestoneArtifactInput,
+  index?: ArtifactIndex,
+  classifier: (content: string) => MilestoneArtifactType = classifyMilestoneArtifact,
+): Promise<void> {
+  const artifactIndex = index ?? (await getArtifactIndex());
+  let artifactType: MilestoneArtifactType;
+
+  try {
+    artifactType = classifier(input.payload);
+  } catch (error) {
+    log.error("milestone-ingest", "Failed to classify milestone artifact, defaulting to session", error);
+    artifactType = MILESTONE_ARTIFACT_TYPES.SESSION;
+  }
+
+  await artifactIndex.indexMilestoneArtifact({
+    id: input.id,
+    milestoneId: input.milestoneId,
+    artifactType,
+    sourceSessionId: input.sourceSessionId,
+    createdAt: input.createdAt,
+    tags: input.tags,
+    payload: input.payload,
+  });
+}
diff --git a/src/tools/artifact-index/index.ts b/src/tools/artifact-index/index.ts
index 94de30f..f9cbe14 100644
--- a/src/tools/artifact-index/index.ts
+++ b/src/tools/artifact-index/index.ts
@@ -1,9 +1,8 @@
 // src/tools/artifact-index/index.ts
 import { Database } from "bun:sqlite";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { mkdirSync, existsSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
 const DEFAULT_DB_DIR = join(homedir(), ".config", "opencode", "artifact-index");
 const DB_NAME = "context.db";
@@ -27,6 +26,16 @@ export interface LedgerRecord {
   filesModified?: string;
 }
 
+export interface MilestoneArtifactRecord {
+  id: string;
+  milestoneId: string;
+  artifactType: string;
+  sourceSessionId?: string;
+  createdAt?: string;
+  tags?: string[];
+  payload: string;
+}
+
 export interface SearchResult {
   type: "plan" | "ledger";
   id: string;
@@ -36,6 +45,18 @@ export interface SearchResult {
   score: number;
 }
 
+export interface MilestoneArtifactSearchResult {
+  type: "milestone";
+  id: string;
+  milestoneId: string;
+  artifactType: string;
+  sourceSessionId?: string;
+  createdAt?: string;
+  tags: string[];
+  payload: string;
+  score: number;
+}
+
 export class ArtifactIndex {
   private db: Database | null = null;
   private dbPath: string;
@@ -91,8 +112,26 @@ export class ArtifactIndex {
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
         indexed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
       );
+      CREATE TABLE IF NOT EXISTS milestone_artifacts (
+        id TEXT PRIMARY KEY,
+        milestone_id TEXT NOT NULL,
+        artifact_type TEXT NOT NULL,
+        source_session_id TEXT,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        tags TEXT,
+        payload TEXT NOT NULL,
+        indexed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      );
       CREATE VIRTUAL TABLE IF NOT EXISTS plans_fts USING fts5(id, title, overview, approach);
       CREATE VIRTUAL TABLE IF NOT EXISTS ledgers_fts USING fts5(id, session_name, goal, state_now, key_decisions);
+      CREATE VIRTUAL TABLE IF NOT EXISTS milestone_artifacts_fts USING fts5(
+        id,
+        milestone_id,
+        artifact_type,
+        payload,
+        tags,
+        source_session_id
+      );
     `;
   }
 
@@ -239,6 +278,116 @@ export class ArtifactIndex {
     return results.slice(0, limit);
   }
 
+  async indexMilestoneArtifact(record: MilestoneArtifactRecord): Promise<void> {
+    if (!this.db) throw new Error("Database not initialized");
+
+    const tags = JSON.stringify(record.tags ?? []);
+    const createdAt = record.createdAt ?? new Date().toISOString();
+    const existing = this.db.query("SELECT id FROM milestone_artifacts WHERE id = ?").get(record.id) as
+      | { id: string }
+      | undefined;
+
+    if (existing) {
+      this.db.run("DELETE FROM milestone_artifacts_fts WHERE id = ?", [existing.id]);
+    }
+
+    this.db.run(
+      `INSERT INTO milestone_artifacts (
+          id,
+          milestone_id,
+          artifact_type,
+          source_session_id,
+          created_at,
+          tags,
+          payload,
+          indexed_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(id) DO UPDATE SET
+          milestone_id = excluded.milestone_id,
+          artifact_type = excluded.artifact_type,
+          source_session_id = excluded.source_session_id,
+          created_at = excluded.created_at,
+          tags = excluded.tags,
+          payload = excluded.payload,
+          indexed_at = CURRENT_TIMESTAMP`,
+      [
+        record.id,
+        record.milestoneId,
+        record.artifactType,
+        record.sourceSessionId ?? null,
+        createdAt,
+        tags,
+        record.payload,
+      ],
+    );
+
+    this.db.run(
+      `INSERT INTO milestone_artifacts_fts (
+          id,
+          milestone_id,
+          artifact_type,
+          payload,
+          tags,
+          source_session_id
+        ) VALUES (?, ?, ?, ?, ?, ?)`,
+      [record.id, record.milestoneId, record.artifactType, record.payload, tags, record.sourceSessionId ?? ""],
+    );
+  }
+
+  async searchMilestoneArtifacts(
+    query: string,
+    options: { milestoneId?: string; artifactType?: string; limit?: number } = {},
+  ): Promise<MilestoneArtifactSearchResult[]> {
+    if (!this.db) throw new Error("Database not initialized");
+
+    const escapedQuery = this.escapeFtsQuery(query);
+    const milestoneId = options.milestoneId ?? null;
+    const artifactType = options.artifactType ?? null;
+    const limit = options.limit ?? 10;
+
+    const rows = this.db
+      .query(
+        `SELECT
+          milestone_artifacts.id,
+          milestone_artifacts.milestone_id,
+          milestone_artifacts.artifact_type,
+          milestone_artifacts.source_session_id,
+          milestone_artifacts.created_at,
+          milestone_artifacts.tags,
+          milestone_artifacts.payload,
+          milestone_artifacts_fts.rank
+        FROM milestone_artifacts_fts
+        JOIN milestone_artifacts ON milestone_artifacts.id = milestone_artifacts_fts.id
+        WHERE milestone_artifacts_fts MATCH ?
+          AND (? IS NULL OR milestone_artifacts.milestone_id = ?)
+          AND (? IS NULL OR milestone_artifacts.artifact_type = ?)
+        ORDER BY milestone_artifacts_fts.rank
+        LIMIT ?`,
+      )
+      .all(escapedQuery, milestoneId, milestoneId, artifactType, artifactType, limit) as Array<{
+      id: string;
+      milestone_id: string;
+      artifact_type: string;
+      source_session_id: string | null;
+      created_at: string | null;
+      tags: string | null;
+      payload: string;
+      rank: number;
+    }>;
+
+    return rows.map((row) => ({
+      type: "milestone",
+      id: row.id,
+      milestoneId: row.milestone_id,
+      artifactType: row.artifact_type,
+      sourceSessionId: row.source_session_id ?? undefined,
+      createdAt: row.created_at ?? undefined,
+      tags: row.tags ? JSON.parse(row.tags) : [],
+      payload: row.payload,
+      score: -row.rank,
+    }));
+  }
+
   private escapeFtsQuery(query: string): string {
     // Escape special FTS5 characters and wrap terms in quotes
     return query
diff --git a/src/tools/artifact-index/schema.sql b/src/tools/artifact-index/schema.sql
index 3e01735..2fa888f 100644
--- a/src/tools/artifact-index/schema.sql
+++ b/src/tools/artifact-index/schema.sql
@@ -27,6 +27,18 @@ CREATE TABLE IF NOT EXISTS ledgers (
     indexed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
 
+-- Milestone artifacts table
+CREATE TABLE IF NOT EXISTS milestone_artifacts (
+    id TEXT PRIMARY KEY,
+    milestone_id TEXT NOT NULL,
+    artifact_type TEXT NOT NULL,
+    source_session_id TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    tags TEXT,
+    payload TEXT NOT NULL,
+    indexed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
 -- FTS5 virtual tables for full-text search (standalone, manually synced)
 CREATE VIRTUAL TABLE IF NOT EXISTS plans_fts USING fts5(
     id,
@@ -42,3 +54,12 @@ CREATE VIRTUAL TABLE IF NOT EXISTS ledgers_fts USING fts5(
     state_now,
     key_decisions
 );
+
+CREATE VIRTUAL TABLE IF NOT EXISTS milestone_artifacts_fts USING fts5(
+    id,
+    milestone_id,
+    artifact_type,
+    payload,
+    tags,
+    source_session_id
+);
diff --git a/tests/indexing/classifier/milestone-artifact-classifier.test.ts b/tests/indexing/classifier/milestone-artifact-classifier.test.ts
new file mode 100644
index 0000000..12c3c92
--- /dev/null
+++ b/tests/indexing/classifier/milestone-artifact-classifier.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  classifyMilestoneArtifact,
+  MILESTONE_ARTIFACT_TYPES,
+} from "../../../src/indexing/milestone-artifact-classifier";
+
+describe("classifyMilestoneArtifact", () => {
+  it("classifies feature content", () => {
+    const content = "Requirement: add scoped implementation details for indexing.";
+    expect(classifyMilestoneArtifact(content)).toBe(MILESTONE_ARTIFACT_TYPES.FEATURE);
+  });
+
+  it("classifies decision content", () => {
+    const content = "Decision: we decided on SQLite storage because of reliability.";
+    expect(classifyMilestoneArtifact(content)).toBe(MILESTONE_ARTIFACT_TYPES.DECISION);
+  });
+
+  it("classifies session content", () => {
+    const content = "Meeting notes: status updates and discussion items.";
+    expect(classifyMilestoneArtifact(content)).toBe(MILESTONE_ARTIFACT_TYPES.SESSION);
+  });
+
+  it("prefers feature over decision over session", () => {
+    const content = "Decision: we decided on the implementation details and requirements.";
+    expect(classifyMilestoneArtifact(content)).toBe(MILESTONE_ARTIFACT_TYPES.FEATURE);
+  });
+});
diff --git a/tests/indexing/flows/milestone-error-paths.test.ts b/tests/indexing/flows/milestone-error-paths.test.ts
new file mode 100644
index 0000000..2875b59
--- /dev/null
+++ b/tests/indexing/flows/milestone-error-paths.test.ts
@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { MILESTONE_ARTIFACT_TYPES } from "../../../src/indexing/milestone-artifact-classifier";
+import { ingestMilestoneArtifact } from "../../../src/indexing/milestone-artifact-ingest";
+import { ArtifactIndex } from "../../../src/tools/artifact-index";
+
+describe("milestone artifact ingest error paths", () => {
+  let testDir: string;
+  let consoleErrorSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `milestone-error-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("falls back to session when classifier fails", async () => {
+    const index = new ArtifactIndex(testDir);
+    await index.initialize();
+
+    await ingestMilestoneArtifact(
+      {
+        id: "artifact-err",
+        milestoneId: "ms-err",
+        sourceSessionId: "session-err",
+        createdAt: "2026-01-16T13:00:00Z",
+        tags: ["error"],
+        payload: "Status update only.",
+      },
+      index,
+      () => {
+        throw new Error("classifier failure");
+      },
+    );
+
+    const results = await index.searchMilestoneArtifacts("status", {
+      milestoneId: "ms-err",
+      limit: 10,
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0].artifactType).toBe(MILESTONE_ARTIFACT_TYPES.SESSION);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+
+    await index.close();
+  });
+});
diff --git a/tests/indexing/flows/milestone-ingest.test.ts b/tests/indexing/flows/milestone-ingest.test.ts
new file mode 100644
index 0000000..8d03bcf
--- /dev/null
+++ b/tests/indexing/flows/milestone-ingest.test.ts
@@ -0,0 +1,47 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { ingestMilestoneArtifact } from "../../../src/indexing/milestone-artifact-ingest";
+import { ArtifactIndex } from "../../../src/tools/artifact-index";
+
+describe("milestone artifact ingest", () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `milestone-ingest-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("classifies and stores milestone artifacts", async () => {
+    const index = new ArtifactIndex(testDir);
+    await index.initialize();
+
+    await ingestMilestoneArtifact(
+      {
+        id: "artifact-3",
+        milestoneId: "ms-3",
+        sourceSessionId: "session-3",
+        createdAt: "2026-01-16T12:00:00Z",
+        tags: ["feature", "milestone"],
+        payload: "Implementation details for the indexing pipeline.",
+      },
+      index,
+    );
+
+    const results = await index.searchMilestoneArtifacts("implementation", {
+      milestoneId: "ms-3",
+      limit: 10,
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0].artifactType).toBe("feature");
+
+    await index.close();
+  });
+});
diff --git a/tests/indexing/search/milestone-search.test.ts b/tests/indexing/search/milestone-search.test.ts
new file mode 100644
index 0000000..4eca8b7
--- /dev/null
+++ b/tests/indexing/search/milestone-search.test.ts
@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+describe("milestone artifact search", () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `milestone-search-test-${Date.now()}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("filters by milestone metadata", async () => {
+    const { ArtifactIndex } = await import("../../../src/tools/artifact-index");
+    const index = new ArtifactIndex(testDir);
+    await index.initialize();
+
+    await index.indexMilestoneArtifact({
+      id: "artifact-1",
+      milestoneId: "ms-1",
+      artifactType: "feature",
+      sourceSessionId: "session-1",
+      createdAt: "2026-01-16T10:00:00Z",
+      tags: ["feature"],
+      payload: "Implementation details for milestone indexing.",
+    });
+
+    await index.indexMilestoneArtifact({
+      id: "artifact-2",
+      milestoneId: "ms-2",
+      artifactType: "decision",
+      sourceSessionId: "session-2",
+      createdAt: "2026-01-16T11:00:00Z",
+      tags: ["decision"],
+      payload: "Decision to store artifacts only in SQLite.",
+    });
+
+    const results = await index.searchMilestoneArtifacts("SQLite", {
+      milestoneId: "ms-2",
+      artifactType: "decision",
+      limit: 10,
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({
+      id: "artifact-2",
+      milestoneId: "ms-2",
+      artifactType: "decision",
+    });
+
+    await index.close();
+  });
+});
diff --git a/tests/tools/artifact-index-schema.test.ts b/tests/tools/artifact-index-schema.test.ts
index bb7c883..7391c54 100644
--- a/tests/tools/artifact-index-schema.test.ts
+++ b/tests/tools/artifact-index-schema.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 
 describe("artifact-index schema", () => {
   it("should not have handoff tables", async () => {
@@ -17,6 +17,13 @@ describe("artifact-index schema", () => {
     expect(schema).toContain("CREATE VIRTUAL TABLE IF NOT EXISTS plans_fts");
   });
 
+  it("should have milestone artifacts tables", async () => {
+    const fs = await import("node:fs/promises");
+    const schema = await fs.readFile("src/tools/artifact-index/schema.sql", "utf-8");
+    expect(schema).toContain("CREATE TABLE IF NOT EXISTS milestone_artifacts");
+    expect(schema).toContain("CREATE VIRTUAL TABLE IF NOT EXISTS milestone_artifacts_fts");
+  });
+
   it("should have files_read and files_modified columns in ledgers", async () => {
     const fs = await import("node:fs/promises");
     const schema = await fs.readFile("src/tools/artifact-index/schema.sql", "utf-8");

From 81ebd4a0b779c78dd29528d936e64e6cd6dec403 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sat, 17 Jan 2026 13:56:38 +0200
Subject: [PATCH 13/22] fix(agents): reduce confirmation prompts

---
 src/agents/brainstormer.ts | 124 ++++++++++++++++++++++++-------
 src/agents/commander.ts    |  37 +++++++++-
 src/agents/executor.ts     |  18 +++++
 src/agents/implementer.ts  |  19 ++++-
 src/agents/planner.ts      | 146 ++++++++++++++++++++++++++-----------
 src/agents/reviewer.ts     |  17 ++++-
 6 files changed, 290 insertions(+), 71 deletions(-)

diff --git a/src/agents/brainstormer.ts b/src/agents/brainstormer.ts
index 9f963b2..f013c93 100644
--- a/src/agents/brainstormer.ts
+++ b/src/agents/brainstormer.ts
@@ -20,6 +20,56 @@ Turn ideas into fully formed designs through natural collaborative dialogue.
 This is DESIGN ONLY. The planner agent handles detailed implementation plans.
 </purpose>
 
+<voice-and-tone>
+  <principle>Be a thoughtful colleague, not a formal document generator</principle>
+  <principle>Write like you're explaining to a smart peer over coffee</principle>
+  <principle>Show your thinking - "I'm leaning toward X because..." not just "X is the solution"</principle>
+  <principle>Use "we" and "our" - this is collaborative design</principle>
+  <principle>Be direct but warm - no corporate speak, no filler phrases</principle>
+</voice-and-tone>
+
+<formatting-rules priority="HIGH">
+  <rule>USE MARKDOWN FORMATTING - headers, bullets, bold, whitespace</rule>
+  <rule>NEVER write walls of text - break into digestible chunks</rule>
+  <rule>Each section gets a ## header</rule>
+  <rule>Use bullet points for lists of 3+ items</rule>
+  <rule>Use **bold** for key terms and important concepts</rule>
+  <rule>Add blank lines between sections for breathing room</rule>
+  <rule>Keep paragraphs to 2-3 sentences max</rule>
+
+  <good-example>
+## Architecture Overview
+
+The system treats **artifacts as first-class records** stored in SQLite, decoupled from files.
+
+**Key insight:** We're shifting from "file-backed" to "event-backed" artifacts. This means:
+- Artifacts survive even if source files are deleted
+- Search is always consistent with the database
+- We don't need to re-index when files move
+
+The milestone pipeline becomes the single source of truth.
+  </good-example>
+
+  <bad-example>
+Architecture Overview
+The redesigned artifact system treats artifacts as first‑class records stored only in SQLite, decoupled from plan or ledger files. Artifacts are created at milestones (design approved, plan complete, execution done) using a classification agent that chooses exactly one type: feature, decision, or session. The agent scores the milestone content against the agreed criteria, selects the highest‑confidence type, and resolves ties using the deterministic priority order feature → decision → session. Each artifact record includes the complete metadata set you requested...
+  </bad-example>
+
+  <section-template>
+## [Section Name]
+
+[1-2 sentence overview of what this section covers]
+
+**[Key concept 1]:** [Brief explanation]
+
+- [Detail point]
+- [Detail point]
+- [Detail point]
+
+[Optional: transition sentence to next section]
+  </section-template>
+</formatting-rules>
+
 <critical-rules>
   <rule priority="HIGHEST">ONE QUESTION AT A TIME: Ask exactly ONE question, then STOP and wait for the user's response. NEVER ask multiple questions in a single message. This is the most important rule.</rule>
   <rule>NO CODE: Never write code. Never provide code examples. Design only.</rule>
@@ -60,8 +110,7 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
 </phase>
 
 <phase name="presenting">
-  <rule>Break into sections of 200-300 words</rule>
-  <rule>Ask after EACH section: "Does this look right so far?"</rule>
+  <rule>Present ALL sections in ONE message - do not pause between sections</rule>
   <aspects>
     <aspect>Architecture overview</aspect>
     <aspect>Key components and responsibilities</aspect>
@@ -69,17 +118,14 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
     <aspect>Error handling strategy</aspect>
     <aspect>Testing approach</aspect>
   </aspects>
-  <rule>Don't proceed to next section until current one is validated</rule>
+  <rule>After presenting ALL sections, ask ONE question: "Does this design look right, or would you like changes to any section?"</rule>
+  <rule>If user says it looks good/yes/approved, proceed to finalizing immediately</rule>
 </phase>
 
-<phase name="finalizing">
+<phase name="finalizing" trigger="user approves design OR says it looks good">
   <action>Write validated design to thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md</action>
   <action>Commit the design document to git</action>
-  <action>Ask: "Ready for the planner to create a detailed implementation plan?"</action>
-</phase>
-
-<phase name="handoff" trigger="user approves design">
-  <action>When user says yes/approved/ready, IMMEDIATELY spawn the planner:</action>
+  <action>IMMEDIATELY spawn planner - do NOT ask "Ready for planner?"</action>
   <spawn>
     Task(
       subagent_type="planner",
@@ -87,16 +133,11 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
       description="Create implementation plan"
     )
   </spawn>
-  <rule>Do NOT ask again - if user approved, spawn planner immediately</rule>
-  <after-planner>
-    <action>Report: "Implementation plan created at thoughts/shared/plans/YYYY-MM-DD-{topic}.md"</action>
-    <action>Ask user: "Ready to execute the plan?"</action>
-    <rule>Wait for user response before proceeding</rule>
-  </after-planner>
 </phase>
 
-<phase name="execution" trigger="user approves execution">
-  <action>When user says yes/execute/go, spawn the executor:</action>
+<phase name="handoff" trigger="planner completes">
+  <action>Report: "Implementation plan created at thoughts/shared/plans/YYYY-MM-DD-{topic}.md"</action>
+  <action>IMMEDIATELY spawn executor - do NOT ask "Ready to execute?"</action>
   <spawn>
     Task(
       subagent_type="executor",
@@ -104,11 +145,13 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
       description="Execute implementation plan"
     )
   </spawn>
-  <after-execution>
-    <action>Report executor results to user</action>
-    <rule priority="CRITICAL">YOUR JOB IS DONE. STOP HERE.</rule>
-    <rule>Do NOT write any code yourself</rule>
-  </after-execution>
+  <rule>User approved the workflow when they approved the design - proceed without re-asking</rule>
+</phase>
+
+<phase name="execution" trigger="executor completes">
+  <action>Report executor results to user</action>
+  <rule priority="CRITICAL">YOUR JOB IS DONE. STOP HERE.</rule>
+  <rule>Do NOT write any code yourself</rule>
 </phase>
 </process>
 
@@ -116,15 +159,46 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
   <principle name="design-only">NO CODE. Describe components, not implementations. Planner writes code.</principle>
   <principle name="sync-subagents">Use Task tool for subagents. They complete before you continue.</principle>
   <principle name="parallel-research">Multiple Task calls in one message run in parallel</principle>
-  <principle name="one-question">Ask exactly ONE question per message. STOP after asking. Wait for user's answer before continuing. NEVER bundle multiple questions together.</principle>
+  <principle name="one-question">Ask exactly ONE question per message during exploration. STOP after asking. Wait for user's answer before continuing.</principle>
   <principle name="yagni">Remove unnecessary features from ALL designs</principle>
   <principle name="explore-alternatives">ALWAYS propose 2-3 approaches before settling</principle>
-  <principle name="incremental-validation">Present in sections, validate each before proceeding</principle>
-  <principle name="auto-handoff">When user approves design, IMMEDIATELY spawn planner - don't ask again</principle>
+  <principle name="batch-presentation">Present ALL design sections in ONE message, then ask for feedback once</principle>
+  <principle name="workflow-autonomy">When user approves design, execute entire workflow (plan + execute) without re-asking</principle>
 </principles>
 
+<confirmation-protocol>
+  <rule>ONLY pause for confirmation when there's a genuine decision to make</rule>
+  <rule>NEVER ask "Does this look right?" after each section - batch into single review</rule>
+  <rule>NEVER ask "Ready for X?" when user already approved the workflow</rule>
+  <rule>NEVER ask "Should I proceed?" - if direction is clear, proceed</rule>
+
+  <pause-for description="Situations that require user input">
+    <situation>Multiple valid approaches - user must choose</situation>
+    <situation>Clarifying ambiguous requirements</situation>
+    <situation>Design is complete and needs approval before implementation</situation>
+  </pause-for>
+
+  <do-not-pause-for description="Just do it">
+    <situation>Progress updates between sections</situation>
+    <situation>Next step in an approved workflow</situation>
+    <situation>Obvious follow-up actions</situation>
+  </do-not-pause-for>
+
+  <state-tracking>
+    <rule>Track what you've done to avoid repeating work</rule>
+    <rule>Before any action, check: "Have I already done this?"</rule>
+    <rule>If user says "you already did X" - acknowledge and move on</rule>
+  </state-tracking>
+</confirmation-protocol>
+
 <never-do>
+  <forbidden>NEVER write walls of text - use headers, bullets, whitespace</forbidden>
+  <forbidden>NEVER skip markdown formatting - ## headers, **bold**, bullet lists</forbidden>
+  <forbidden>NEVER write paragraphs longer than 3 sentences</forbidden>
   <forbidden>NEVER ask multiple questions in one message - this breaks the collaborative flow</forbidden>
+  <forbidden>NEVER ask "Does this look right?" after EACH section - present all, then ask once</forbidden>
+  <forbidden>NEVER ask "Ready for X?" or "Should I proceed?" when workflow is approved</forbidden>
+  <forbidden>NEVER repeat work you've already done - check state first</forbidden>
   <forbidden>Never write code snippets or examples</forbidden>
   <forbidden>Never provide file paths with line numbers</forbidden>
   <forbidden>Never specify exact function signatures</forbidden>
diff --git a/src/agents/commander.ts b/src/agents/commander.ts
index 8b16468..543148c 100644
--- a/src/agents/commander.ts
+++ b/src/agents/commander.ts
@@ -136,7 +136,42 @@ Just do it - including obvious follow-up actions.
 <rule>Use TodoWrite to track what you're doing</rule>
 <rule>Never discard tasks without explicit approval</rule>
 <rule>Use journal for insights, failed approaches, preferences</rule>
-</tracking>`;
+</tracking>
+
+<confirmation-protocol>
+  <rule>ONLY pause for confirmation when there's a genuine decision to make</rule>
+  <rule>NEVER ask "Does this look right?" for progress updates</rule>
+  <rule>NEVER ask "Ready for X?" when workflow is already approved</rule>
+  <rule>NEVER ask "Should I proceed?" - if direction is clear, proceed</rule>
+
+  <pause-for description="Situations that require user input">
+    <situation>Multiple valid approaches exist and choice matters</situation>
+    <situation>Would delete or significantly restructure existing code</situation>
+    <situation>Requirements are ambiguous and need clarification</situation>
+    <situation>Plan needs approval before implementation begins</situation>
+  </pause-for>
+
+  <do-not-pause-for description="Just do it">
+    <situation>Next step in an approved workflow</situation>
+    <situation>Obvious follow-up actions</situation>
+    <situation>Progress updates - report, don't ask</situation>
+    <situation>Spawning subagents for approved work</situation>
+  </do-not-pause-for>
+</confirmation-protocol>
+
+<state-tracking>
+  <rule>Track what you've done to avoid repeating work</rule>
+  <rule>Before any action, check: "Have I already done this?"</rule>
+  <rule>If user says "you already did X" - acknowledge and move on, don't redo</rule>
+  <rule>Check if design/plan files exist before creating them</rule>
+</state-tracking>
+
+<never-do>
+  <forbidden>NEVER ask "Does this look right?" after each step - batch updates</forbidden>
+  <forbidden>NEVER ask "Ready for X?" when user approved the workflow</forbidden>
+  <forbidden>NEVER repeat work you've already done</forbidden>
+  <forbidden>NEVER ask for permission to do obvious follow-up actions</forbidden>
+</never-do>`;
 
 export const primaryAgent: AgentConfig = {
   description: "Pragmatic orchestrator. Direct, honest, delegates to specialists.",
diff --git a/src/agents/executor.ts b/src/agents/executor.ts
index 61911f3..e9ab38e 100644
--- a/src/agents/executor.ts
+++ b/src/agents/executor.ts
@@ -182,7 +182,24 @@ spawn_agent(agent="reviewer", prompt="Review task 3 implementation", description
 </template>
 </output-format>
 
+<autonomy-rules>
+  <rule>You are a SUBAGENT - execute the entire plan without asking for confirmation</rule>
+  <rule>NEVER ask "Does this look right?" or "Should I continue?" - just execute</rule>
+  <rule>NEVER ask "Ready for next batch?" - if current batch is done, proceed to next</rule>
+  <rule>Report final results when ALL tasks are done, not after each task</rule>
+  <rule>If a task is blocked after 3 cycles, mark it blocked and continue with other tasks</rule>
+</autonomy-rules>
+
+<state-tracking>
+  <rule>Track which tasks have been completed to avoid re-executing</rule>
+  <rule>Track which review cycles have been done for each task</rule>
+  <rule>If resuming, check what's already done before starting</rule>
+  <rule>Before spawning an implementer, verify the task hasn't already been completed</rule>
+</state-tracking>
+
 <never-do>
+<forbidden>NEVER ask for confirmation - you're a subagent, just execute the plan</forbidden>
+<forbidden>NEVER ask "Does this look right?" or "Should I proceed?"</forbidden>
 <forbidden>NEVER implement tasks yourself - ALWAYS spawn implementer agents</forbidden>
 <forbidden>NEVER verify implementations yourself - ALWAYS spawn reviewer agents</forbidden>
 <forbidden>Never skip dependency analysis</forbidden>
@@ -190,5 +207,6 @@ spawn_agent(agent="reviewer", prompt="Review task 3 implementation", description
 <forbidden>Never skip reviewer for any task</forbidden>
 <forbidden>Never continue past 3 cycles for a single task</forbidden>
 <forbidden>Never report success if any task is blocked</forbidden>
+<forbidden>Never re-execute tasks that are already completed</forbidden>
 </never-do>`,
 };
diff --git a/src/agents/implementer.ts b/src/agents/implementer.ts
index e11731d..341f38c 100644
--- a/src/agents/implementer.ts
+++ b/src/agents/implementer.ts
@@ -94,11 +94,28 @@ Awaiting guidance.
 </template>
 </on-mismatch>
 
+<autonomy-rules>
+  <rule>You are a SUBAGENT - execute your task completely without asking for confirmation</rule>
+  <rule>NEVER ask "Does this look right?" or "Should I continue?" - just execute</rule>
+  <rule>NEVER ask for permission to proceed - if you have the task, do it</rule>
+  <rule>Report results when done (success or mismatch), don't ask questions along the way</rule>
+  <rule>If plan doesn't match reality, report MISMATCH and STOP - don't ask what to do</rule>
+</autonomy-rules>
+
+<state-tracking>
+  <rule>Before editing a file, check its current state</rule>
+  <rule>If the change is already applied, skip it and report already done</rule>
+  <rule>Track which files you've modified to avoid duplicate changes</rule>
+</state-tracking>
+
 <never-do>
-<forbidden>Don't guess when uncertain</forbidden>
+<forbidden>NEVER ask for confirmation - you're a subagent, just execute</forbidden>
+<forbidden>NEVER ask "Does this look right?" or "Should I proceed?"</forbidden>
+<forbidden>Don't guess when uncertain - report mismatch instead</forbidden>
 <forbidden>Don't add features not in plan</forbidden>
 <forbidden>Don't refactor adjacent code</forbidden>
 <forbidden>Don't "fix" things outside scope</forbidden>
 <forbidden>Don't skip verification steps</forbidden>
+<forbidden>Don't re-apply changes that are already done</forbidden>
 </never-do>`,
 };
diff --git a/src/agents/planner.ts b/src/agents/planner.ts
index e2cde6b..96f0228 100644
--- a/src/agents/planner.ts
+++ b/src/agents/planner.ts
@@ -19,20 +19,46 @@ Every task is bite-sized (2-5 minutes), with exact paths and complete code.
 
 <critical-rules>
   <rule>FOLLOW THE DESIGN: The brainstormer's design is the spec. Do not explore alternatives.</rule>
-  <rule>SUBAGENTS: Use spawn_agent tool to spawn subagents. They complete before you continue.</rule>
-  <rule>TOOLS (grep, read, etc.): Do NOT use directly - use subagents instead.</rule>
   <rule>Every code example MUST be complete - never write "add validation here"</rule>
   <rule>Every file path MUST be exact - never write "somewhere in src/"</rule>
   <rule>Follow TDD: failing test → verify fail → implement → verify pass → commit</rule>
+  <rule priority="HIGH">MINIMAL RESEARCH: Most plans need 0-3 subagent calls total. Use tools directly first.</rule>
 </critical-rules>
 
+<research-strategy>
+  <principle>READ THE DESIGN FIRST - it often contains everything you need</principle>
+  <principle>USE TOOLS DIRECTLY for simple lookups (read, grep, glob) - no subagent needed</principle>
+  <principle>SUBAGENTS are for complex analysis only - not simple file reads</principle>
+  <principle>MOST PLANS need zero subagent calls if design is detailed</principle>
+
+  <do-directly description="Use tools directly, no subagent">
+    <task>Read a specific file: use Read tool</task>
+    <task>Find files by name: use Glob tool</task>
+    <task>Search for a string: use Grep tool</task>
+    <task>Check if file exists: use Glob tool</task>
+    <task>Read the design doc: use Read tool</task>
+  </do-directly>
+
+  <use-subagent-for description="Only when truly needed">
+    <task>Deep analysis of complex module interactions</task>
+    <task>Finding non-obvious patterns across many files</task>
+    <task>Understanding unfamiliar architectural decisions</task>
+  </use-subagent-for>
+
+  <limits>
+    <rule>MAX 3-5 subagent calls per plan - if you need more, you're over-researching</rule>
+    <rule>Before spawning a subagent, ask: "Can I do this with a simple Read/Grep?"</rule>
+    <rule>ONE round of research - no iterative refinement loops</rule>
+  </limits>
+</research-strategy>
+
 <research-scope>
 Brainstormer did conceptual research (architecture, patterns, approaches).
 Your research is IMPLEMENTATION-LEVEL only:
-- Exact file paths and line numbers
-- Exact function signatures and types
-- Exact test file conventions
-- Exact import paths
+- Exact file paths and line numbers (use Glob/Read directly)
+- Exact function signatures and types (use Read directly)
+- Exact test file conventions (use Glob/Read directly)
+- Exact import paths (use Read directly)
 All research must serve the design - never second-guess design decisions.
 </research-scope>
 
@@ -42,23 +68,21 @@ All research must serve the design - never second-guess design decisions.
 <rule>Use these directly - no subagent needed for library research.</rule>
 </library-research>
 
-<available-subagents>
+<available-subagents description="USE SPARINGLY - most tasks don't need these">
   <subagent name="codebase-locator">
-    Find exact file paths needed for implementation.
-    Examples: "Find exact path to UserService", "Find test directory structure"
-    spawn_agent(agent="codebase-locator", prompt="Find exact path to UserService", description="Find UserService")
+    ONLY for: Finding files when you don't know the naming convention.
+    DON'T USE for: Finding a file you already know exists (use Glob instead).
   </subagent>
   <subagent name="codebase-analyzer">
-    Get exact signatures and types for code examples.
-    Examples: "Get function signature for createUser", "Get type definition for UserConfig"
-    spawn_agent(agent="codebase-analyzer", prompt="Get function signature for createUser", description="Get signature")
+    ONLY for: Understanding complex module interactions or unfamiliar code.
+    DON'T USE for: Reading a file (use Read instead).
   </subagent>
   <subagent name="pattern-finder">
-    Find exact patterns to copy in code examples.
-    Examples: "Find exact test setup pattern", "Find exact error handling in similar endpoint"
-    spawn_agent(agent="pattern-finder", prompt="Find test setup pattern", description="Find patterns")
+    ONLY for: Finding patterns across many files when you don't know where to look.
+    DON'T USE for: Reading an example file you already identified (use Read instead).
   </subagent>
-  <rule>Use spawn_agent tool to spawn subagents. Call multiple in ONE message for parallel execution.</rule>
+  <rule>MAX 3-5 subagent calls total. If you need more, you're over-researching.</rule>
+  <rule>If multiple needed, call in ONE message for parallel execution.</rule>
 </available-subagents>
 
 <inputs>
@@ -69,28 +93,30 @@ All research must serve the design - never second-guess design decisions.
 
 <process>
 <phase name="understand-design">
-  <action>Read the design document thoroughly</action>
+  <action>Read the design document using Read tool (NOT a subagent)</action>
   <action>Identify all components, files, and interfaces mentioned</action>
   <action>Note any constraints or decisions made by brainstormer</action>
+  <rule>The design doc often contains 80% of what you need - read it carefully</rule>
 </phase>
 
-<phase name="implementation-research">
-  <action>Spawn subagents using spawn_agent tool (they run synchronously):</action>
-  <parallel-research description="Launch independent research in a single message">
-    In a SINGLE message, call multiple spawn_agent tools in parallel:
-    - spawn_agent(agent="codebase-locator", prompt="Find exact path to [component]", description="Find [component]")
-    - spawn_agent(agent="codebase-analyzer", prompt="Get signature for [function]", description="Get signature")
-    - spawn_agent(agent="pattern-finder", prompt="Find test setup pattern", description="Find patterns")
-    - context7_resolve-library-id + context7_query-docs for API docs
-    - btca_ask for library internals when needed
-  </parallel-research>
-  <rule>Only research what's needed to implement the design</rule>
-  <rule>Never research alternatives to design decisions</rule>
+<phase name="minimal-research" description="ONLY if design doc is missing critical details">
+  <principle>MOST PLANS SKIP THIS PHASE - design doc is usually sufficient</principle>
+  <direct-tools description="Use these first - no subagent needed">
+    - Glob: Find files by pattern (e.g., "src/**/*.ts")
+    - Read: Read specific files the design mentions
+    - Grep: Search for specific strings
+  </direct-tools>
+  <subagents description="ONLY if direct tools aren't enough">
+    - MAX 3-5 calls total
+    - Call all needed subagents in ONE message (parallel)
+    - If you're spawning more than 5, STOP and reconsider
+  </subagents>
+  <rule>ONE round of research only - no iterative refinement</rule>
 </phase>
 
 <phase name="planning">
   <action>Break design into sequential tasks (2-5 minutes each)</action>
-  <action>For each task, determine exact file paths from research</action>
+  <action>For each task, determine exact file paths</action>
   <action>Write complete code examples following CODE_STYLE.md</action>
   <action>Include exact verification commands with expected output</action>
 </phase>
@@ -176,18 +202,33 @@ git commit -m "feat(scope): add specific feature"
 </output-format>
 
 <execution-example>
-<step name="research">
-// In a SINGLE message, spawn all research tasks in parallel:
-spawn_agent(agent="codebase-locator", prompt="Find UserService path", description="Find UserService")
-spawn_agent(agent="codebase-analyzer", prompt="Get createUser signature", description="Get signature")
-spawn_agent(agent="pattern-finder", prompt="Find test setup pattern", description="Find patterns")
-context7_resolve-library-id(libraryName="express")
-btca_ask(tech="express", question="middleware chain order")
-// All complete before next message - results available immediately
-</step>
-<step name="plan">
-// Use all collected results to write the implementation plan
-</step>
+<good-example description="Minimal research - most plans">
+// Step 1: Read the design doc directly
+Read(file_path="thoughts/shared/designs/2026-01-16-feature-design.md")
+
+// Step 2: Design mentions src/services/user.ts - read it directly
+Read(file_path="src/services/user.ts")
+
+// Step 3: Need to find test conventions - use Glob, not subagent
+Glob(pattern="tests/**/*.test.ts")
+
+// Step 4: Write the plan - no subagents needed!
+Write(file_path="thoughts/shared/plans/2026-01-16-feature.md", content="...")
+</good-example>
+
+<bad-example description="Over-researching - DON'T DO THIS">
+// WRONG: 18 subagent calls for a simple plan
+spawn_agent(agent="codebase-analyzer", prompt="Read src/hooks/...")  // Just use Read!
+spawn_agent(agent="codebase-locator", prompt="Find existing files under thoughts/...")  // Just use Glob!
+spawn_agent(agent="codebase-analyzer", prompt="Read thoughts/shared/designs/...")  // Just use Read!
+// ... 15 more unnecessary subagent calls
+</bad-example>
+
+<when-subagents-ok description="Rare cases where subagents add value">
+// Complex pattern discovery across unfamiliar codebase:
+spawn_agent(agent="pattern-finder", prompt="Find auth middleware patterns", description="Find auth patterns")
+// That's it - ONE subagent call, not 18
+</when-subagents-ok>
 </execution-example>
 
 <principles>
@@ -202,7 +243,26 @@ btca_ask(tech="express", question="middleware chain order")
   <principle name="dry">Extract duplication in code examples</principle>
 </principles>
 
+<autonomy-rules>
+  <rule>You are a SUBAGENT - execute your task completely without asking for confirmation</rule>
+  <rule>NEVER ask "Does this look right?" or "Should I continue?" - just do your job</rule>
+  <rule>NEVER ask "Ready for X?" - if you have the inputs, produce the outputs</rule>
+  <rule>Report results when done, don't ask for permission along the way</rule>
+  <rule>If you encounter a genuine blocker, report it clearly and stop - don't ask what to do</rule>
+</autonomy-rules>
+
+<state-tracking>
+  <rule>Before writing a file, check if it already exists with the expected content</rule>
+  <rule>Track what research you've done to avoid duplicate subagent calls</rule>
+  <rule>If the plan file already exists, read it first before overwriting</rule>
+</state-tracking>
+
 <never-do>
+  <forbidden>NEVER spawn a subagent to READ A FILE - use Read tool directly</forbidden>
+  <forbidden>NEVER spawn a subagent to FIND FILES - use Glob tool directly</forbidden>
+  <forbidden>NEVER spawn more than 5 subagents total - you're over-researching</forbidden>
+  <forbidden>NEVER ask for confirmation - you're a subagent, just execute</forbidden>
+  <forbidden>NEVER ask "Does this look right?" or "Should I proceed?"</forbidden>
   <forbidden>Never second-guess the design - brainstormer made those decisions</forbidden>
   <forbidden>Never propose alternative approaches - implement what's in the design</forbidden>
   <forbidden>Never write "add validation here" - write the actual validation</forbidden>
diff --git a/src/agents/reviewer.ts b/src/agents/reviewer.ts
index 506c10a..b3471e7 100644
--- a/src/agents/reviewer.ts
+++ b/src/agents/reviewer.ts
@@ -103,5 +103,20 @@ Check correctness and style. Be specific. Run code, don't just read.
 <priority order="3">Missing functionality</priority>
 <priority order="4">Test coverage</priority>
 <priority order="5">Style/readability</priority>
-</priority-order>`,
+</priority-order>
+
+<autonomy-rules>
+  <rule>You are a SUBAGENT - complete your review without asking for confirmation</rule>
+  <rule>NEVER ask "Does this look right?" or "Should I continue?" - just review</rule>
+  <rule>NEVER ask for permission to run tests or checks - just run them</rule>
+  <rule>Report APPROVED or CHANGES REQUESTED - don't ask what to do next</rule>
+  <rule>Make a decision and state it clearly - executor handles next steps</rule>
+</autonomy-rules>
+
+<never-do>
+<forbidden>NEVER ask for confirmation - you're a subagent, just review</forbidden>
+<forbidden>NEVER ask "Does this look right?" or "Should I proceed?"</forbidden>
+<forbidden>NEVER hedge your verdict - state APPROVED or CHANGES REQUESTED clearly</forbidden>
+<forbidden>Don't defer decisions to executor - make the call yourself</forbidden>
+</never-do>`,
 };

From 1e296467944cac19f1491742fc82de1a922048d2 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sat, 17 Jan 2026 15:15:22 +0200
Subject: [PATCH 14/22] fix(config): validate model overrides against
 opencode.json

- Read available models from opencode.json synchronously during init
- Validate user model overrides in micode.json against available models
- Invalid models fall back to opencode default with warning
- Remove hardcoded model from agents (use opencode default)
- Update @opencode-ai/plugin to 1.1.23
- Fix plugin entry point to use dist/index.js
---
 bun.lock                          | 32 ++++++++++++--
 package.json                      |  8 ++--
 src/agents/artifact-searcher.ts   |  1 -
 src/agents/bootstrapper.ts        |  1 -
 src/agents/brainstormer.ts        |  1 -
 src/agents/codebase-analyzer.ts   |  1 -
 src/agents/codebase-locator.ts    |  1 -
 src/agents/commander.ts           |  1 -
 src/agents/executor.ts            |  1 -
 src/agents/implementer.ts         |  1 -
 src/agents/ledger-creator.ts      |  1 -
 src/agents/octto.ts               |  1 -
 src/agents/pattern-finder.ts      |  1 -
 src/agents/planner.ts             |  1 -
 src/agents/probe.ts               |  1 -
 src/agents/project-initializer.ts |  1 -
 src/agents/reviewer.ts            |  1 -
 src/config-loader.ts              | 70 ++++++++++++++++++++++++++++---
 src/index.ts                      | 18 ++------
 19 files changed, 100 insertions(+), 43 deletions(-)

diff --git a/bun.lock b/bun.lock
index 4f6acef..a06c9af 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,12 +5,14 @@
     "": {
       "name": "@vtemian/opencode-config",
       "dependencies": {
-        "@opencode-ai/plugin": "1.1.6",
+        "@opencode-ai/plugin": "1.1.23",
         "bun-pty": "^0.4.5",
+        "valibot": "^1.2.0",
       },
       "devDependencies": {
         "@biomejs/biome": "^2.3.10",
         "bun-types": "latest",
+        "lefthook": "^2.0.13",
         "typescript": "^5.7.3",
       },
     },
@@ -34,9 +36,9 @@
 
     "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.3.10", "", { "os": "win32", "cpu": "x64" }, "sha512-pHEFgq7dUEsKnqG9mx9bXihxGI49X+ar+UBrEIj3Wqj3UCZp1rNgV+OoyjFgcXsjCWpuEAF4VJdkZr3TrWdCbQ=="],
 
-    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.1.6", "", { "dependencies": { "@opencode-ai/sdk": "1.1.6", "zod": "4.1.8" } }, "sha512-psGajIrj4V03gn85/7Xy5YXdPoCsRGwBsifruG5TfG63+7Jd1TENNufp+SxGb+xtlddDteDMGVHSnE98q9LbDw=="],
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.1.23", "", { "dependencies": { "@opencode-ai/sdk": "1.1.23", "zod": "4.1.8" } }, "sha512-O/iLSKOUuzD95UWhj9y/tEuycPEBv36de0suHXXqeYLWZLZ16DAUSKR+YG7rvRjJS0sbn4biVMw+k7XXk/oxiQ=="],
 
-    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.1.6", "", {}, "sha512-7Tiso9BExVgxz86VY6F807McCyOgu/SCaQJ87wwxxVSN8GpPpmUIYN5h6LH38EBNJWKXDjokasn/y9EkKxOisQ=="],
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.1.23", "", {}, "sha512-YjN9ogzkLol92s+/iARXRop9/5oFIezUkvWVay12u1IM6A/WJs50DeKl3oL0x4a68P1a5tI5gD98dLnk2+AlsA=="],
 
     "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="],
 
@@ -44,10 +46,34 @@
 
     "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
 
+    "lefthook": ["lefthook@2.0.15", "", { "optionalDependencies": { "lefthook-darwin-arm64": "2.0.15", "lefthook-darwin-x64": "2.0.15", "lefthook-freebsd-arm64": "2.0.15", "lefthook-freebsd-x64": "2.0.15", "lefthook-linux-arm64": "2.0.15", "lefthook-linux-x64": "2.0.15", "lefthook-openbsd-arm64": "2.0.15", "lefthook-openbsd-x64": "2.0.15", "lefthook-windows-arm64": "2.0.15", "lefthook-windows-x64": "2.0.15" }, "bin": { "lefthook": "bin/index.js" } }, "sha512-sl5rePO6UUOLKp6Ci+MMKOc86zicBaPUCvSw2Cq4gCAgTmxpxhIjhz7LOu2ObYerVRPpTq3gvzPTjI71UotjnA=="],
+
+    "lefthook-darwin-arm64": ["lefthook-darwin-arm64@2.0.15", "", { "os": "darwin", "cpu": "arm64" }, "sha512-ygAqG/NzOgY9bEiqeQtiOmCRTtp9AmOd3eyrpEaSrRB9V9f3RHRgWDrWbde9BiHSsCzcbeY9/X2NuKZ69eUsNA=="],
+
+    "lefthook-darwin-x64": ["lefthook-darwin-x64@2.0.15", "", { "os": "darwin", "cpu": "x64" }, "sha512-3wA30CzdSL5MFKD6dk7v8BMq7ScWQivpLbmIn3Pv67AaBavN57N/hcdGqOFnDDFI5WazVwDY7UqDfMIk5HZjEA=="],
+
+    "lefthook-freebsd-arm64": ["lefthook-freebsd-arm64@2.0.15", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-FbYBBLVbX8BjdO+icN1t/pC3TOW3FAvTKv/zggBKNihv6jHNn/3s/0j2xIS0k0Pw9oOE7MVmEni3qp2j5vqHrQ=="],
+
+    "lefthook-freebsd-x64": ["lefthook-freebsd-x64@2.0.15", "", { "os": "freebsd", "cpu": "x64" }, "sha512-udHMjh1E8TfC0Z7Y249XZMATJOyj1Jxlj9JoEinkoBvAsePFKDEQg5teuXuTGhjsHYpqVekfSvLNNfHKUUbbjw=="],
+
+    "lefthook-linux-arm64": ["lefthook-linux-arm64@2.0.15", "", { "os": "linux", "cpu": "arm64" }, "sha512-1HAPmdYhfcOlubv63sTnWtW2rFuC+kT1MvC3JvdrS5V6zrOImbBSnYZMJX/Dd3w4pm0x2ZJb9T+uef8a0jUQkg=="],
+
+    "lefthook-linux-x64": ["lefthook-linux-x64@2.0.15", "", { "os": "linux", "cpu": "x64" }, "sha512-Pho87mlNFH47zc4fPKzQSp8q9sWfIFW/KMMZfx/HZNmX25aUUTOqMyRwaXxtdAo/hNJ9FX4JeuZWq9Y3iyM5VA=="],
+
+    "lefthook-openbsd-arm64": ["lefthook-openbsd-arm64@2.0.15", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-pet03Edlj1QeFUgxcIK1xu8CeZA+ejYplvPgdfe//69+vQFGSDaEx3H2mVx8RqzWfmMbijM2/WfkZXR2EVw3bw=="],
+
+    "lefthook-openbsd-x64": ["lefthook-openbsd-x64@2.0.15", "", { "os": "openbsd", "cpu": "x64" }, "sha512-i+a364CcSAeIO5wQzLMHsthHt/v6n3XwhKmRq/VBzPOUv9KutNeF55yCE/6lvuvzwxpdEfBjh6cXPERC0yp98w=="],
+
+    "lefthook-windows-arm64": ["lefthook-windows-arm64@2.0.15", "", { "os": "win32", "cpu": "arm64" }, "sha512-69u5GdVOT4QIxc2TK5ce0cTXLzwB55Pk9ZnnJNFf1XsyZTGcg9bUWYYTyD12CIIXbVTa0RVXIIrbU9UgP8O1AQ=="],
+
+    "lefthook-windows-x64": ["lefthook-windows-x64@2.0.15", "", { "os": "win32", "cpu": "x64" }, "sha512-/zYEndCUgj8XK+4wvLYLRk3AcfKU6zWf2GHx+tcZ4K2bLaQdej4m+OqmQsVpUlF8N2tN9hfwlj1D50uz75LUuQ=="],
+
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
+    "valibot": ["valibot@1.2.0", "", { "peerDependencies": { "typescript": ">=5" }, "optionalPeers": ["typescript"] }, "sha512-mm1rxUsmOxzrwnX5arGS+U4T25RdvpPjPN4yR0u9pUBov9+zGVtO84tif1eY4r6zWxVxu3KzIyknJy3rxfRZZg=="],
+
     "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
   }
 }
diff --git a/package.json b/package.json
index cf159af..64904b3 100644
--- a/package.json
+++ b/package.json
@@ -2,8 +2,8 @@
   "name": "micode",
   "version": "0.8.4",
   "description": "OpenCode plugin with Brainstorm-Research-Plan-Implement workflow",
-  "module": "src/index.ts",
-  "main": "src/index.ts",
+  "module": "dist/index.js",
+  "main": "dist/index.js",
   "types": "src/index.ts",
   "type": "module",
   "files": [
@@ -12,7 +12,7 @@
   ],
   "scripts": {
     "prepare": "lefthook install",
-    "build": "tsc --noEmit",
+    "build": "bun build src/index.ts --outdir dist --target bun",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run typecheck",
     "test": "bun test",
@@ -39,7 +39,7 @@
     "url": "https://github.com/vtemian/micode/issues"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.6",
+    "@opencode-ai/plugin": "1.1.23",
     "bun-pty": "^0.4.5",
     "valibot": "^1.2.0"
   },
diff --git a/src/agents/artifact-searcher.ts b/src/agents/artifact-searcher.ts
index f51febd..52919cb 100644
--- a/src/agents/artifact-searcher.ts
+++ b/src/agents/artifact-searcher.ts
@@ -4,7 +4,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const artifactSearcherAgent: AgentConfig = {
   description: "Searches past handoffs, plans, and ledgers for relevant precedent",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.3,
   tools: {
     edit: false,
diff --git a/src/agents/bootstrapper.ts b/src/agents/bootstrapper.ts
index 301aae5..dd1e7d6 100644
--- a/src/agents/bootstrapper.ts
+++ b/src/agents/bootstrapper.ts
@@ -4,7 +4,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const bootstrapperAgent: AgentConfig = {
   description: "Analyzes a request and creates exploration branches with scopes for octto brainstorming",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.5,
   prompt: `<purpose>
 Analyze the user's request and create 2-4 exploration branches.
diff --git a/src/agents/brainstormer.ts b/src/agents/brainstormer.ts
index f013c93..7a9b411 100644
--- a/src/agents/brainstormer.ts
+++ b/src/agents/brainstormer.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const brainstormerAgent: AgentConfig = {
   description: "Refines rough ideas into fully-formed designs through collaborative questioning",
   mode: "primary",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.7,
   tools: {
     spawn_agent: false, // Primary agents use built-in Task tool, not spawn_agent
diff --git a/src/agents/codebase-analyzer.ts b/src/agents/codebase-analyzer.ts
index 1c37a06..dead595 100644
--- a/src/agents/codebase-analyzer.ts
+++ b/src/agents/codebase-analyzer.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const codebaseAnalyzerAgent: AgentConfig = {
   description: "Explains HOW code works with precise file:line references",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.2,
   tools: {
     write: false,
diff --git a/src/agents/codebase-locator.ts b/src/agents/codebase-locator.ts
index f7cf5f1..de64b7d 100644
--- a/src/agents/codebase-locator.ts
+++ b/src/agents/codebase-locator.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const codebaseLocatorAgent: AgentConfig = {
   description: "Finds WHERE files live in the codebase",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.1,
   tools: {
     write: false,
diff --git a/src/agents/commander.ts b/src/agents/commander.ts
index 543148c..abfb1eb 100644
--- a/src/agents/commander.ts
+++ b/src/agents/commander.ts
@@ -176,7 +176,6 @@ Just do it - including obvious follow-up actions.
 export const primaryAgent: AgentConfig = {
   description: "Pragmatic orchestrator. Direct, honest, delegates to specialists.",
   mode: "primary",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.2,
   thinking: {
     type: "enabled",
diff --git a/src/agents/executor.ts b/src/agents/executor.ts
index e9ab38e..f1f1a4e 100644
--- a/src/agents/executor.ts
+++ b/src/agents/executor.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const executorAgent: AgentConfig = {
   description: "Executes plan task-by-task with parallel execution where possible",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.2,
   prompt: `<environment>
 You are running as part of the "micode" OpenCode plugin (NOT Claude Code).
diff --git a/src/agents/implementer.ts b/src/agents/implementer.ts
index 341f38c..b158038 100644
--- a/src/agents/implementer.ts
+++ b/src/agents/implementer.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const implementerAgent: AgentConfig = {
   description: "Executes implementation tasks from a plan",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.1,
   prompt: `<environment>
 You are running as part of the "micode" OpenCode plugin (NOT Claude Code).
diff --git a/src/agents/ledger-creator.ts b/src/agents/ledger-creator.ts
index fe5b0bf..86d9d44 100644
--- a/src/agents/ledger-creator.ts
+++ b/src/agents/ledger-creator.ts
@@ -4,7 +4,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const ledgerCreatorAgent: AgentConfig = {
   description: "Creates and updates continuity ledgers for session state preservation",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.2,
   tools: {
     edit: false,
diff --git a/src/agents/octto.ts b/src/agents/octto.ts
index d6c6ddb..3bd5590 100644
--- a/src/agents/octto.ts
+++ b/src/agents/octto.ts
@@ -4,7 +4,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const octtoAgent: AgentConfig = {
   description: "Runs interactive browser-based brainstorming sessions using branch-based exploration",
   mode: "primary",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.7,
   prompt: `<environment>
 You are running as part of the "micode" OpenCode plugin (NOT Claude Code).
diff --git a/src/agents/pattern-finder.ts b/src/agents/pattern-finder.ts
index ff6da38..700d91e 100644
--- a/src/agents/pattern-finder.ts
+++ b/src/agents/pattern-finder.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const patternFinderAgent: AgentConfig = {
   description: "Finds existing patterns and examples to model after",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.2,
   tools: {
     write: false,
diff --git a/src/agents/planner.ts b/src/agents/planner.ts
index 96f0228..4cc7ff1 100644
--- a/src/agents/planner.ts
+++ b/src/agents/planner.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const plannerAgent: AgentConfig = {
   description: "Creates detailed implementation plans with exact file paths, complete code examples, and TDD steps",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.3,
   prompt: `<environment>
 You are running as part of the "micode" OpenCode plugin (NOT Claude Code).
diff --git a/src/agents/probe.ts b/src/agents/probe.ts
index c5b89eb..15fba0f 100644
--- a/src/agents/probe.ts
+++ b/src/agents/probe.ts
@@ -4,7 +4,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const probeAgent: AgentConfig = {
   description: "Evaluates octto branch Q&A and decides whether to ask more or complete with finding",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.5,
   prompt: `<purpose>
 You evaluate a brainstorming branch's Q&A history and decide:
diff --git a/src/agents/project-initializer.ts b/src/agents/project-initializer.ts
index 130e41b..a40ac3a 100644
--- a/src/agents/project-initializer.ts
+++ b/src/agents/project-initializer.ts
@@ -218,7 +218,6 @@ Available micode agents: codebase-locator, codebase-analyzer, pattern-finder.
 
 export const projectInitializerAgent: AgentConfig = {
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.3,
   maxTokens: 32000,
   prompt: PROMPT,
diff --git a/src/agents/reviewer.ts b/src/agents/reviewer.ts
index b3471e7..83829ca 100644
--- a/src/agents/reviewer.ts
+++ b/src/agents/reviewer.ts
@@ -3,7 +3,6 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 export const reviewerAgent: AgentConfig = {
   description: "Reviews implementation for correctness and style",
   mode: "subagent",
-  model: "openai/gpt-5.2-codex",
   temperature: 0.3,
   tools: {
     write: false,
diff --git a/src/config-loader.ts b/src/config-loader.ts
index 1fd48d9..8379ad4 100644
--- a/src/config-loader.ts
+++ b/src/config-loader.ts
@@ -1,7 +1,9 @@
 // src/config-loader.ts
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { homedir } from "node:os";
+import { join } from "node:path";
+
 import type { AgentConfig } from "@opencode-ai/sdk";
 
 // Minimal type for provider validation - only what we need
@@ -10,6 +12,35 @@ export interface ProviderInfo {
   models: Record<string, unknown>;
 }
 
+/**
+ * Load available models from opencode.json config file (synchronous)
+ * Returns a Set of "provider/model" strings
+ */
+export function loadAvailableModels(configDir?: string): Set<string> {
+  const availableModels = new Set<string>();
+  const baseDir = configDir ?? join(homedir(), ".config", "opencode");
+
+  try {
+    const configPath = join(baseDir, "opencode.json");
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content) as { provider?: Record<string, { models?: Record<string, unknown> }> };
+
+    if (config.provider) {
+      for (const [providerId, providerConfig] of Object.entries(config.provider)) {
+        if (providerConfig.models) {
+          for (const modelId of Object.keys(providerConfig.models)) {
+            availableModels.add(`${providerId}/${modelId}`);
+          }
+        }
+      }
+    }
+  } catch {
+    // Config doesn't exist or can't be parsed - return empty set
+  }
+
+  return availableModels;
+}
+
 // Safe properties that users can override
 const SAFE_AGENT_PROPERTIES = ["model", "temperature", "maxTokens"] as const;
 
@@ -66,26 +97,53 @@ export async function loadMicodeConfig(configDir?: string): Promise<MicodeConfig
 
 /**
  * Merge user config overrides into plugin agent configs
- * User overrides take precedence for safe properties only
+ * Model overrides are validated against available models from opencode.json
+ * Invalid models are logged and skipped (agent uses opencode default)
  */
 export function mergeAgentConfigs(
   pluginAgents: Record<string, AgentConfig>,
   userConfig: MicodeConfig | null,
+  availableModels?: Set<string>,
 ): Record<string, AgentConfig> {
   if (!userConfig?.agents) {
     return pluginAgents;
   }
 
+  // Load available models if not provided
+  const models = availableModels ?? loadAvailableModels();
+
   const merged: Record<string, AgentConfig> = {};
 
   for (const [name, agentConfig] of Object.entries(pluginAgents)) {
     const userOverride = userConfig.agents[name];
 
     if (userOverride) {
-      merged[name] = {
-        ...agentConfig,
-        ...userOverride,
-      };
+      // Validate model if specified
+      if (userOverride.model) {
+        if (models.has(userOverride.model)) {
+          // Model is valid - apply all overrides
+          merged[name] = {
+            ...agentConfig,
+            ...userOverride,
+          };
+        } else {
+          // Model is invalid - log warning and apply other overrides only
+          console.warn(
+            `[micode] Model "${userOverride.model}" for agent "${name}" is not available. Using opencode default.`,
+          );
+          const { model: _ignored, ...safeOverrides } = userOverride;
+          merged[name] = {
+            ...agentConfig,
+            ...safeOverrides,
+          };
+        }
+      } else {
+        // No model specified - apply all overrides
+        merged[name] = {
+          ...agentConfig,
+          ...userOverride,
+        };
+      }
     } else {
       merged[name] = agentConfig;
     }
diff --git a/src/index.ts b/src/index.ts
index fcdfbfb..9918bdb 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -4,7 +4,7 @@ import type { McpLocalConfig } from "@opencode-ai/sdk";
 // Agents
 import { agents, PRIMARY_AGENT_NAME } from "./agents";
 // Config loader
-import { loadMicodeConfig, mergeAgentConfigs, validateAgentModels } from "./config-loader";
+import { loadMicodeConfig, mergeAgentConfigs } from "./config-loader";
 import { createArtifactAutoIndexHook } from "./hooks/artifact-auto-index";
 // Hooks
 import { createAutoCompactHook } from "./hooks/auto-compact";
@@ -73,20 +73,8 @@ const OpenCodeConfigPlugin: Plugin = async (ctx) => {
     console.warn(`[micode] ${btcaStatus.message}`);
   }
 
-  // Load user config for model overrides
-  let userConfig = await loadMicodeConfig();
-
-  // Validate configured models against available providers
-  if (userConfig?.agents) {
-    try {
-      const providersResponse = await ctx.client.provider.list();
-      if (providersResponse.data?.all) {
-        userConfig = validateAgentModels(userConfig, providersResponse.data.all);
-      }
-    } catch (e) {
-      console.warn("[micode] Failed to validate model configuration:", e);
-    }
-  }
+  // Load user config for temperature/maxTokens overrides (model overrides not supported)
+  const userConfig = await loadMicodeConfig();
 
   // Think mode state per session
   const thinkModeState = new Map<string, boolean>();

From 06e113e9ba62d670195771e5223e7e5e6efcc59d Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sat, 17 Jan 2026 16:52:56 +0200
Subject: [PATCH 15/22] feat(task): update logger test to use ESM import

---
 tests/utils/logger.test.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/tests/utils/logger.test.ts b/tests/utils/logger.test.ts
index a9687c7..892616e 100644
--- a/tests/utils/logger.test.ts
+++ b/tests/utils/logger.test.ts
@@ -1,5 +1,5 @@
 // tests/utils/logger.test.ts
-import { describe, it, expect, spyOn, beforeEach, afterEach } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
 
 describe("logger utility", () => {
   let consoleLogSpy: ReturnType<typeof spyOn>;
@@ -68,9 +68,9 @@ describe("logger utility", () => {
     it("should log when DEBUG is set", async () => {
       process.env.DEBUG = "1";
       // Need fresh import to pick up env change
-      // Clear module cache
-      delete require.cache[require.resolve("../../src/utils/logger")];
-      const { log } = await import("../../src/utils/logger");
+      const moduleUrl = new URL("../../src/utils/logger", import.meta.url);
+      moduleUrl.searchParams.set("t", Date.now().toString());
+      const { log } = await import(moduleUrl.href);
       log.debug("my-module", "Debug info");
       expect(consoleLogSpy).toHaveBeenCalledWith("[my-module] Debug info");
     });

From c23e72038fbbdf22ced1a3b24d97dcf775b35bdf Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sat, 17 Jan 2026 16:53:07 +0200
Subject: [PATCH 16/22] fix(brainstormer): make agent decisive instead of
 question-seeking

Root cause: prompt had conflicting instructions - meta-rules said "be
proactive" but specific phase instructions said "ask ONE question" and
"wait for feedback". Models follow specific instructions over meta-rules.

Changes:
- Add <identity> section framing agent as senior engineer
- Rewrite exploring phase: "wait for feedback" -> "MAKE THE DECISION"
- Remove all "ask question" patterns throughout
- Update presenting phase to proceed without asking for approval
- Fix description: "collaborative questioning" -> "decisive collaboration"
---
 src/agents/brainstormer.ts | 74 +++++++++++++++++++++++++++-----------
 1 file changed, 54 insertions(+), 20 deletions(-)

diff --git a/src/agents/brainstormer.ts b/src/agents/brainstormer.ts
index 7a9b411..6b43dc9 100644
--- a/src/agents/brainstormer.ts
+++ b/src/agents/brainstormer.ts
@@ -1,7 +1,7 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
 
 export const brainstormerAgent: AgentConfig = {
-  description: "Refines rough ideas into fully-formed designs through collaborative questioning",
+  description: "Refines rough ideas into fully-formed designs through decisive collaboration",
   mode: "primary",
   temperature: 0.7,
   tools: {
@@ -19,6 +19,15 @@ Turn ideas into fully formed designs through natural collaborative dialogue.
 This is DESIGN ONLY. The planner agent handles detailed implementation plans.
 </purpose>
 
+<identity>
+You are a SENIOR ENGINEER, not a junior seeking approval.
+- Make decisions. Don't ask "what do you think?" - state "I'm doing X because Y."
+- State assumptions and proceed. User will correct you if wrong. This is faster than asking.
+- When you see a problem, propose a solution. Don't present problems without solutions.
+- Trust your judgment. You have context. Use it to make calls.
+- Disagreement is good. If user pushes back, discuss briefly, then execute their choice.
+</identity>
+
 <voice-and-tone>
   <principle>Be a thoughtful colleague, not a formal document generator</principle>
   <principle>Write like you're explaining to a smart peer over coffee</principle>
@@ -70,7 +79,9 @@ The redesigned artifact system treats artifacts as first‑class records stored
 </formatting-rules>
 
 <critical-rules>
-  <rule priority="HIGHEST">ONE QUESTION AT A TIME: Ask exactly ONE question, then STOP and wait for the user's response. NEVER ask multiple questions in a single message. This is the most important rule.</rule>
+  <rule priority="HIGHEST">BE PROACTIVE: When the user gives clear direction (e.g., "mark as solved", "fix this", "move to next"), EXECUTE IMMEDIATELY. Don't ask clarifying questions for clear instructions.</rule>
+  <rule>Gather requirements through STATEMENTS and PROPOSALS, not questions. "I'm assuming X" beats "What is X?"</rule>
+  <rule>CONTINUOUS WORKFLOW: When processing lists/items one-by-one, automatically move to the next item after completing each. Don't wait to be asked "what's next?"</rule>
   <rule>NO CODE: Never write code. Never provide code examples. Design only.</rule>
   <rule>TOOLS (grep, read, etc.): Do NOT use directly - use subagents instead.</rule>
   <rule>Use built-in Task tool to spawn subagents. NEVER use spawn_agent (that's for subagents only).</rule>
@@ -96,16 +107,17 @@ The redesigned artifact system treats artifacts as first‑class records stored
     Call multiple Task tools in ONE message for parallel execution.
     Results are available immediately - no polling needed.
   </workflow>
-  <rule>Do NOT proceed to questions until you have codebase context</rule>
+  <rule>Gather codebase context BEFORE forming your approach</rule>
   <focus>purpose, constraints, success criteria</focus>
 </phase>
 
 <phase name="exploring">
   <action>Propose 2-3 different approaches with trade-offs</action>
-  <action>Present options conversationally with your recommendation</action>
-  <rule>Lead with recommended option and explain WHY</rule>
+  <action>Lead with YOUR CHOSEN approach and explain WHY you chose it</action>
+  <action>Present alternatives briefly as "I considered X but rejected it because..."</action>
   <include>effort estimate, risks, dependencies</include>
-  <rule>Wait for feedback before proceeding</rule>
+  <rule>MAKE THE DECISION. State what you're going to do, then do it.</rule>
+  <rule>Only pause if you genuinely cannot choose between equally valid options</rule>
 </phase>
 
 <phase name="presenting">
@@ -117,11 +129,11 @@ The redesigned artifact system treats artifacts as first‑class records stored
     <aspect>Error handling strategy</aspect>
     <aspect>Testing approach</aspect>
   </aspects>
-  <rule>After presenting ALL sections, ask ONE question: "Does this design look right, or would you like changes to any section?"</rule>
-  <rule>If user says it looks good/yes/approved, proceed to finalizing immediately</rule>
+  <rule>After presenting, state: "I'm proceeding to create the design doc. Interrupt if you want changes."</rule>
+  <rule>Then IMMEDIATELY proceed to finalizing - don't wait for approval</rule>
 </phase>
 
-<phase name="finalizing" trigger="user approves design OR says it looks good">
+<phase name="finalizing" trigger="after presenting design">
   <action>Write validated design to thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md</action>
   <action>Commit the design document to git</action>
   <action>IMMEDIATELY spawn planner - do NOT ask "Ready for planner?"</action>
@@ -144,7 +156,7 @@ The redesigned artifact system treats artifacts as first‑class records stored
       description="Execute implementation plan"
     )
   </spawn>
-  <rule>User approved the workflow when they approved the design - proceed without re-asking</rule>
+  <rule>User approved the workflow when they started brainstorming - proceed without asking</rule>
 </phase>
 
 <phase name="execution" trigger="executor completes">
@@ -155,32 +167,52 @@ The redesigned artifact system treats artifacts as first‑class records stored
 </process>
 
 <principles>
+  <principle name="proactive-action">When user gives direction, EXECUTE it. Don't ask for confirmation on clear instructions.</principle>
+  <principle name="helper-mindset">Propose solutions, make recommendations, drive the conversation forward. You're a helper, not a stenographer.</principle>
+  <principle name="continuous-flow">When processing lists, automatically continue to next item after completing one. No "ready for next?"</principle>
   <principle name="design-only">NO CODE. Describe components, not implementations. Planner writes code.</principle>
   <principle name="sync-subagents">Use Task tool for subagents. They complete before you continue.</principle>
   <principle name="parallel-research">Multiple Task calls in one message run in parallel</principle>
-  <principle name="one-question">Ask exactly ONE question per message during exploration. STOP after asking. Wait for user's answer before continuing.</principle>
+  <principle name="state-assumptions">During exploration, STATE your assumptions and proceed. User will correct if wrong.</principle>
   <principle name="yagni">Remove unnecessary features from ALL designs</principle>
   <principle name="explore-alternatives">ALWAYS propose 2-3 approaches before settling</principle>
-  <principle name="batch-presentation">Present ALL design sections in ONE message, then ask for feedback once</principle>
-  <principle name="workflow-autonomy">When user approves design, execute entire workflow (plan + execute) without re-asking</principle>
+  <principle name="batch-presentation">Present ALL design sections in ONE message, then proceed immediately</principle>
+  <principle name="workflow-autonomy">Execute entire workflow (design + plan + execute) without pausing for approval</principle>
 </principles>
 
+<proactive-helper-mode>
+  <principle>You are a HELPER, not just a facilitator. Actively solve problems.</principle>
+  <principle>When user presents an issue, propose a concrete solution - don't just ask "what do you want to do?"</principle>
+  <principle>When reviewing items (bugs, comments, tasks), state your recommendation and execute it</principle>
+  <principle>Execute obvious actions without asking. "Mark as solved" = call the API. "Move to next" = show the next item.</principle>
+
+  <list-processing-workflow description="When going through lists one-by-one">
+    <step>Present current item with your analysis and recommendation</step>
+    <step>If user agrees or gives direction, EXECUTE immediately</step>
+    <step>After execution, AUTOMATICALLY present the next item - don't ask "ready for next?"</step>
+    <step>If user disagrees with your recommendation, discuss briefly then execute their choice</step>
+    <step>Track progress: "Done: 3/10. Moving to #4..."</step>
+  </list-processing-workflow>
+</proactive-helper-mode>
+
 <confirmation-protocol>
   <rule>ONLY pause for confirmation when there's a genuine decision to make</rule>
-  <rule>NEVER ask "Does this look right?" after each section - batch into single review</rule>
+  <rule>NEVER ask "Does this look right?" - present and proceed</rule>
   <rule>NEVER ask "Ready for X?" when user already approved the workflow</rule>
   <rule>NEVER ask "Should I proceed?" - if direction is clear, proceed</rule>
 
   <pause-for description="Situations that require user input">
-    <situation>Multiple valid approaches - user must choose</situation>
-    <situation>Clarifying ambiguous requirements</situation>
-    <situation>Design is complete and needs approval before implementation</situation>
+    <situation>Multiple valid approaches with significant trade-offs - user must choose</situation>
+    <situation>Destructive actions (deleting, major rewrites)</situation>
   </pause-for>
 
   <do-not-pause-for description="Just do it">
     <situation>Progress updates between sections</situation>
     <situation>Next step in an approved workflow</situation>
     <situation>Obvious follow-up actions</situation>
+    <situation>User gave clear direction - execute it</situation>
+    <situation>Moving to next item in a list</situation>
+    <situation>Marking items as done/resolved</situation>
   </do-not-pause-for>
 
   <state-tracking>
@@ -194,14 +226,16 @@ The redesigned artifact system treats artifacts as first‑class records stored
   <forbidden>NEVER write walls of text - use headers, bullets, whitespace</forbidden>
   <forbidden>NEVER skip markdown formatting - ## headers, **bold**, bullet lists</forbidden>
   <forbidden>NEVER write paragraphs longer than 3 sentences</forbidden>
-  <forbidden>NEVER ask multiple questions in one message - this breaks the collaborative flow</forbidden>
-  <forbidden>NEVER ask "Does this look right?" after EACH section - present all, then ask once</forbidden>
-  <forbidden>NEVER ask "Ready for X?" or "Should I proceed?" when workflow is approved</forbidden>
+  <forbidden>NEVER ask "Does this look right?" - present design and proceed</forbidden>
+  <forbidden>NEVER ask "Ready for X?" or "Should I proceed?" when workflow is approved or direction is clear</forbidden>
   <forbidden>NEVER repeat work you've already done - check state first</forbidden>
   <forbidden>Never write code snippets or examples</forbidden>
   <forbidden>Never provide file paths with line numbers</forbidden>
   <forbidden>Never specify exact function signatures</forbidden>
   <forbidden>Never jump to implementation details - stay at design level</forbidden>
+  <forbidden>NEVER be passive - if user needs help, HELP them. Don't just ask what they want.</forbidden>
+  <forbidden>NEVER wait to be asked "what's next?" when processing a list - continue automatically</forbidden>
+  <forbidden>NEVER ask "which comment number should we tackle next?" - just move to the next one</forbidden>
 </never-do>
 
 <output-format path="thoughts/shared/designs/YYYY-MM-DD-{topic}-design.md">

From ddc6f03f23450c6c4c0033762090aef6cd3b9e40 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sat, 17 Jan 2026 17:07:31 +0200
Subject: [PATCH 17/22] feat(octto): expand question schema support

---
 src/octto/types.ts           |  2 +-
 src/octto/ui/bundle.ts       | 63 ++++++++++++++++++++++++++++++++----
 src/tools/octto/factory.ts   |  7 +++-
 src/tools/octto/questions.ts | 24 ++++++++++++--
 src/tools/octto/session.ts   | 20 +++++++++---
 5 files changed, 101 insertions(+), 15 deletions(-)

diff --git a/src/octto/types.ts b/src/octto/types.ts
index a73f751..239ed35 100644
--- a/src/octto/types.ts
+++ b/src/octto/types.ts
@@ -181,7 +181,7 @@ export interface ShowPlanConfig extends BaseConfig {
   /** Plan title */
   question: string;
   /** Plan sections */
-  sections: PlanSection[];
+  sections?: PlanSection[];
   /** Full markdown (alternative to sections) */
   markdown?: string;
 }
diff --git a/src/octto/ui/bundle.ts b/src/octto/ui/bundle.ts
index 98c79ac..6fde3f8 100644
--- a/src/octto/ui/bundle.ts
+++ b/src/octto/ui/bundle.ts
@@ -974,16 +974,20 @@ export function getHtmlBundle(): string {
       const max = q.config.max;
       const step = q.config.step || 1;
       const defaultVal = q.config.defaultValue || Math.floor((min + max) / 2);
+      const labels = q.config.labels || {};
+      const minLabel = labels.min || String(min);
+      const maxLabel = labels.max || String(max);
       let html = '<div class="slider-container">';
-      html += '<span class="slider-labels">' + min + '</span>';
+      html += '<span class="slider-labels">' + escapeHtml(minLabel) + '</span>';
       html += '<input type="range" id="slider_' + q.id + '" min="' + min + '" max="' + max + '" step="' + step + '" value="' + defaultVal + '">';
-      html += '<span class="slider-labels">' + max + '</span>';
+      html += '<span class="slider-labels">' + escapeHtml(maxLabel) + '</span>';
       html += '<span id="slider_val_' + q.id + '" class="slider-value">' + defaultVal + '</span>';
       html += '</div>';
       html += '<div class="btn-group"><button onclick="submitSlider(\\'' + q.id + '\\')" class="btn btn-primary">Submit</button></div>';
       return html;
     }
 
+
     function renderReviewSection(q) {
       let html = '';
       // Render markdown content
@@ -1101,6 +1105,7 @@ export function getHtmlBundle(): string {
       const options = q.config.options || [];
       const min = q.config.min || 1;
       const max = q.config.max || 5;
+      const labels = q.config.labels || {};
       let html = '<div class="rate-list">';
       for (const opt of options) {
         html += '<div class="rate-item">';
@@ -1109,7 +1114,14 @@ export function getHtmlBundle(): string {
         for (let i = min; i <= max; i++) {
           html += '<button class="rate-star" data-value="' + i + '" onclick="setRating(\\'' + q.id + '\\', \\'' + opt.id + '\\', ' + i + ')">' + i + '</button>';
         }
-        html += '</div></div>';
+
+        html += '</div>';
+
+
+        if (labels.min || labels.max) {
+          html += '<div class="slider-labels">' + escapeHtml(labels.min || String(min)) + ' / ' + escapeHtml(labels.max || String(max)) + '</div>';
+        }
+        html += '</div>';
       }
       html += '</div>';
       html += '<div class="btn-group"><button onclick="submitRate(\\'' + q.id + '\\')" class="btn btn-primary">Submit Ratings</button></div>';
@@ -1128,14 +1140,16 @@ export function getHtmlBundle(): string {
     function renderAskImage(q) {
       let html = '';
       const multiple = q.config.multiple ? 'multiple' : '';
+      const accept = q.config.accept ? q.config.accept.join(',') : 'image/*';
       html += '<div class="file-upload">';
-      html += '<input type="file" id="image_' + q.id + '" accept="image/*" ' + multiple + ' onchange="previewImages(\\'' + q.id + '\\')">';
+      html += '<input type="file" id="image_' + q.id + '" accept="' + accept + '" ' + multiple + ' onchange="previewImages('' + q.id + '')">';
       html += '<div id="preview_' + q.id + '" class="image-preview"></div>';
       html += '</div>';
-      html += '<div class="btn-group"><button onclick="submitImages(\\'' + q.id + '\\')" class="btn btn-primary">Upload</button></div>';
+      html += '<div class="btn-group"><button onclick="submitImages('' + q.id + '')" class="btn btn-primary">Upload</button></div>';
       return html;
     }
 
+
     function renderAskFile(q) {
       let html = '';
       const multiple = q.config.multiple ? 'multiple' : '';
@@ -1299,11 +1313,36 @@ export function getHtmlBundle(): string {
       }
     }
 
+    function isAllowedFileType(file, allowed) {
+      if (!allowed || allowed.length === 0) return true;
+      const fileType = file.type || '';
+      const fileName = file.name || '';
+      return allowed.some(entry => {
+        if (!entry) return false;
+        if (entry.endsWith('/*')) {
+          const prefix = entry.slice(0, -1);
+          return fileType.startsWith(prefix);
+        }
+        if (entry.startsWith('.')) {
+          return fileName.toLowerCase().endsWith(entry.toLowerCase());
+        }
+        return fileType === entry || fileName.toLowerCase().endsWith(entry.toLowerCase());
+      });
+    }
+
     function previewImages(questionId) {
       const input = document.getElementById('image_' + questionId);
       const preview = document.getElementById('preview_' + questionId);
       preview.innerHTML = '';
+      const q = questions.find(q => q.id === questionId);
+      const allowed = q && q.config.accept ? q.config.accept : null;
       for (const file of input.files) {
+        if (allowed && allowed.length > 0 && !isAllowedFileType(file, allowed)) {
+          const warning = document.createElement('div');
+          warning.textContent = 'Warning: ' + file.name + ' does not match allowed types.';
+          warning.style.cssText = 'color: var(--accent-error); font-size: 0.75rem; margin: 0.25rem 0;';
+          preview.appendChild(warning);
+        }
         const img = document.createElement('img');
         img.src = URL.createObjectURL(file);
         img.style.maxWidth = '100px';
@@ -1481,10 +1520,13 @@ export function getHtmlBundle(): string {
     }
 
     function renderAnsweredSlider(q, answer) {
+      const labels = q.config.labels || {};
+      const minLabel = labels.min || String(q.config.min);
+      const maxLabel = labels.max || String(q.config.max);
       let html = '<div class="readonly-answer">';
       html += '<div class="readonly-answer-label">Value</div>';
       html += '<strong style="font-size: 1.25rem;">' + answer.value + '</strong>';
-      html += ' <span style="color: var(--foreground-subtle);">(range: ' + q.config.min + ' - ' + q.config.max + ')</span>';
+      html += ' <span style="color: var(--foreground-subtle);">(range: ' + escapeHtml(minLabel) + ' - ' + escapeHtml(maxLabel) + ')</span>';
       html += '</div>';
       return html;
     }
@@ -1545,6 +1587,9 @@ export function getHtmlBundle(): string {
 
     function renderAnsweredRate(q, answer) {
       const ratings = answer.ratings || {};
+      const labels = q.config.labels || {};
+      const minLabel = labels.min || String(q.config.min || 1);
+      const maxLabel = labels.max || String(q.config.max || 5);
       let html = '<div class="readonly-answer-label">Ratings</div>';
       html += '<div class="options">';
       for (const opt of (q.config.options || [])) {
@@ -1555,6 +1600,12 @@ export function getHtmlBundle(): string {
         html += '</div>';
       }
       html += '</div>';
+      if (labels.min || labels.max) {
+        html += '<div class="readonly-answer" style="margin-top: 0.5rem;">';
+        html += '<div class="readonly-answer-label">Scale</div>';
+        html += '<div>' + escapeHtml(minLabel) + ' → ' + escapeHtml(maxLabel) + '</div>';
+        html += '</div>';
+      }
       return html;
     }
 
diff --git a/src/tools/octto/factory.ts b/src/tools/octto/factory.ts
index 066ecc4..0381f4b 100644
--- a/src/tools/octto/factory.ts
+++ b/src/tools/octto/factory.ts
@@ -3,7 +3,6 @@
 import { tool } from "@opencode-ai/plugin/tool";
 
 import type { BaseConfig, QuestionType, SessionStore } from "../../octto/session";
-
 import type { OcttoTool, OcttoTools } from "./types";
 
 type ArgsSchema = Parameters<typeof tool>[0]["args"];
@@ -53,12 +52,18 @@ The question will appear in the browser for the user to answer.`,
           "pick_many",
           "confirm",
           "ask_text",
+          "ask_image",
+          "ask_file",
+          "ask_code",
+          "show_diff",
+          "show_plan",
           "show_options",
           "review_section",
           "thumbs",
           "slider",
           "rank",
           "rate",
+          "emoji_react",
         ])
         .describe("Question type"),
       config: tool.schema
diff --git a/src/tools/octto/questions.ts b/src/tools/octto/questions.ts
index 7df9422..0711fe8 100644
--- a/src/tools/octto/questions.ts
+++ b/src/tools/octto/questions.ts
@@ -3,7 +3,6 @@ import { tool } from "@opencode-ai/plugin/tool";
 
 import type { SessionStore } from "../../octto/session";
 import type { ConfirmConfig, PickManyConfig, PickOneConfig, RankConfig, RateConfig } from "../../octto/types";
-
 import { createQuestionToolFactory } from "./factory";
 import type { OcttoTools } from "./types";
 
@@ -120,6 +119,13 @@ Response format: { ratings: Record<string, number> } where key is option id, val
       min: tool.schema.number().optional().describe("Minimum rating value (default: 1)"),
       max: tool.schema.number().optional().describe("Maximum rating value (default: 5)"),
       step: tool.schema.number().optional().describe("Rating step (default: 1)"),
+      labels: tool.schema
+        .object({
+          min: tool.schema.string().optional().describe("Label for minimum value"),
+          max: tool.schema.string().optional().describe("Label for maximum value"),
+        })
+        .optional()
+        .describe("Optional labels for min/max"),
     },
     validate: (args) => {
       if (!args.options || args.options.length === 0) return "options array must not be empty";
@@ -134,6 +140,7 @@ Response format: { ratings: Record<string, number> } where key is option id, val
       min: args.min ?? 1,
       max: args.max ?? 5,
       step: args.step,
+      labels: args.labels,
     }),
   });
 
@@ -196,6 +203,7 @@ Response format: { text: string }`,
     context?: string;
     multiple?: boolean;
     maxImages?: number;
+    accept?: string[];
   }
 
   const ask_image = createTool<ImageConfig>({
@@ -206,12 +214,14 @@ Response format: { text: string }`,
       context: tool.schema.string().optional().describe("Instructions/context"),
       multiple: tool.schema.boolean().optional().describe("Allow multiple images"),
       maxImages: tool.schema.number().optional().describe("Maximum number of images"),
+      accept: tool.schema.array(tool.schema.string()).optional().describe("Allowed image types"),
     },
     toConfig: (args) => ({
       question: args.question,
       context: args.context,
       multiple: args.multiple,
       maxImages: args.maxImages,
+      accept: args.accept,
     }),
   });
 
@@ -332,7 +342,7 @@ Response format: { approved: boolean, annotations?: Record<sectionId, string> }`
     },
     toConfig: (args) => ({
       question: args.question,
-      sections: args.sections || [],
+      sections: args.sections,
       markdown: args.markdown,
     }),
   });
@@ -456,6 +466,7 @@ Response format: { choice: "up" | "down" }`,
     step?: number;
     defaultValue?: number;
     context?: string;
+    labels?: { min?: string; max?: string; mid?: string };
   }
 
   const slider = createTool<SliderConfig>({
@@ -469,6 +480,14 @@ Response format: { value: number }`,
       step: tool.schema.number().optional().describe("Step size (default: 1)"),
       defaultValue: tool.schema.number().optional().describe("Default value"),
       context: tool.schema.string().optional().describe("Instructions/context"),
+      labels: tool.schema
+        .object({
+          min: tool.schema.string().optional().describe("Label for minimum value"),
+          max: tool.schema.string().optional().describe("Label for maximum value"),
+          mid: tool.schema.string().optional().describe("Label for middle value"),
+        })
+        .optional()
+        .describe("Optional labels for the slider"),
     },
     validate: (args) => {
       if (args.min >= args.max) return `min (${args.min}) must be less than max (${args.max})`;
@@ -481,6 +500,7 @@ Response format: { value: number }`,
       step: args.step,
       defaultValue: args.defaultValue,
       context: args.context,
+      labels: args.labels,
     }),
   });
 
diff --git a/src/tools/octto/session.ts b/src/tools/octto/session.ts
index f70c5fd..c34a517 100644
--- a/src/tools/octto/session.ts
+++ b/src/tools/octto/session.ts
@@ -2,10 +2,9 @@
 import { tool } from "@opencode-ai/plugin/tool";
 
 import type { SessionStore } from "../../octto/session";
+import type { OcttoSessionTracker, OcttoTools } from "./types";
 
-import type { OcttoTools } from "./types";
-
-export function createSessionTools(sessions: SessionStore): OcttoTools {
+export function createSessionTools(sessions: SessionStore, tracker?: OcttoSessionTracker): OcttoTools {
   const start_session = tool({
     description: `Start an interactive octto session with initial questions.
 Opens a browser window with questions already displayed - no waiting.
@@ -21,12 +20,21 @@ REQUIRED: You MUST provide at least 1 question. Will fail without questions.`,
                 "pick_many",
                 "confirm",
                 "ask_text",
+                "ask_image",
+                "ask_file",
+                "ask_code",
+                "show_diff",
+                "show_plan",
                 "show_options",
                 "review_section",
                 "thumbs",
                 "slider",
+                "rank",
+                "rate",
+                "emoji_react",
               ])
               .describe("Question type"),
+
             config: tool.schema
               .looseObject({
                 question: tool.schema.string().optional(),
@@ -37,7 +45,7 @@ REQUIRED: You MUST provide at least 1 question. Will fail without questions.`,
         )
         .describe("REQUIRED: Initial questions to display when browser opens. Must have at least 1."),
     },
-    execute: async (args) => {
+    execute: async (args, context) => {
       // ENFORCE: questions are required
       if (!args.questions || args.questions.length === 0) {
         return `## ERROR: questions parameter is REQUIRED
@@ -60,6 +68,7 @@ Please call start_session again WITH your prepared questions.`;
 
       try {
         const result = await sessions.startSession({ title: args.title, questions: args.questions });
+        tracker?.onCreated?.(context.sessionID, result.session_id);
 
         let output = `## Session Started
 
@@ -91,9 +100,10 @@ Closes the browser window and cleans up resources.`,
     args: {
       session_id: tool.schema.string().describe("Session ID to end"),
     },
-    execute: async (args) => {
+    execute: async (args, context) => {
       const result = await sessions.endSession(args.session_id);
       if (result.ok) {
+        tracker?.onEnded?.(context.sessionID, args.session_id);
         return `Session ${args.session_id} ended successfully.`;
       }
       return `Failed to end session ${args.session_id}. It may not exist.`;

From f1718e0e50052927dd414b4c0c1d7e3a07e70169 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sun, 18 Jan 2026 00:06:40 +0200
Subject: [PATCH 18/22] fix(octto): address review feedback

---
 package.json                                  |   1 +
 src/config-loader.test.ts                     |  23 +++-
 src/config-loader.ts                          |   5 +
 src/index.ts                                  |  17 ++-
 src/octto/constants.ts                        |   2 +-
 src/octto/session/server.ts                   |   3 +-
 src/octto/session/sessions.ts                 |   6 +-
 src/octto/session/waiter.ts                   |  15 ++-
 src/octto/state/store.ts                      |   6 +-
 src/tools/octto/brainstorm.ts                 |  25 +++--
 src/tools/octto/formatters.ts                 |   8 +-
 src/tools/octto/index.ts                      |  15 ++-
 src/tools/octto/types.ts                      |   5 +
 src/utils/config.ts                           |   6 +
 .../flows/milestone-error-paths.test.ts       |  50 +++++----
 tests/indexing/flows/milestone-ingest.test.ts |  42 +++----
 .../indexing/search/milestone-search.test.ts  |  70 ++++++------
 tests/tools/artifact-index.test.ts            | 106 ++++++++++--------
 18 files changed, 246 insertions(+), 159 deletions(-)

diff --git a/package.json b/package.json
index 64904b3..60b0d1c 100644
--- a/package.json
+++ b/package.json
@@ -8,6 +8,7 @@
   "type": "module",
   "files": [
     "src",
+    "dist",
     "INSTALL_CLAUDE.md"
   ],
   "scripts": {
diff --git a/src/config-loader.test.ts b/src/config-loader.test.ts
index 7734bbc..7bf8cf9 100644
--- a/src/config-loader.test.ts
+++ b/src/config-loader.test.ts
@@ -1,7 +1,9 @@
 // src/config-loader.test.ts
 import { describe, expect, test } from "bun:test";
+
 import type { AgentConfig } from "@opencode-ai/sdk";
-import { validateAgentModels, type MicodeConfig, type ProviderInfo } from "./config-loader";
+
+import { type MicodeConfig, type ProviderInfo, validateAgentModels } from "./config-loader";
 
 // Helper to create a minimal ProviderInfo for testing
 function createProvider(id: string, modelIds: string[]): ProviderInfo {
@@ -157,8 +159,23 @@ describe("validateAgentModels", () => {
 
     const result = validateAgentModels(userConfig, providers);
 
-    // No providers available, model should be removed
-    expect(result.agents?.commander?.model).toBeUndefined();
+    // No providers available, config should remain unchanged
+    expect(result).toEqual(userConfig);
+  });
+
+  test("handles providers with no models", () => {
+    const userConfig: MicodeConfig = {
+      agents: {
+        commander: { model: "openai/gpt-4" },
+      },
+    };
+
+    const providers: ProviderInfo[] = [{ id: "openai", models: {} }];
+
+    const result = validateAgentModels(userConfig, providers);
+
+    // No provider models available, config should remain unchanged
+    expect(result).toEqual(userConfig);
   });
 
   test("validates multiple agents with mixed valid/invalid models", () => {
diff --git a/src/config-loader.ts b/src/config-loader.ts
index 8379ad4..504398b 100644
--- a/src/config-loader.ts
+++ b/src/config-loader.ts
@@ -161,6 +161,11 @@ export function validateAgentModels(userConfig: MicodeConfig, providers: Provide
     return userConfig;
   }
 
+  const hasAnyModels = providers.some((provider) => Object.keys(provider.models).length > 0);
+  if (!hasAnyModels) {
+    return userConfig;
+  }
+
   // Build lookup map for providers and their models
   const providerMap = new Map<string, Set<string>>();
   for (const provider of providers) {
diff --git a/src/index.ts b/src/index.ts
index 9918bdb..08afa5f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -99,11 +99,26 @@ const OpenCodeConfigPlugin: Plugin = async (ctx) => {
 
   // Octto (browser-based brainstorming) tools
   const octtoSessionStore = createSessionStore();
-  const octtoTools = createOcttoTools(octtoSessionStore, ctx.client);
 
   // Track octto sessions per opencode session for cleanup
   const octtoSessionsMap = new Map<string, Set<string>>();
 
+  const octtoTools = createOcttoTools(octtoSessionStore, ctx.client, {
+    onCreated: (parentSessionId, octtoSessionId) => {
+      const sessions = octtoSessionsMap.get(parentSessionId) ?? new Set<string>();
+      sessions.add(octtoSessionId);
+      octtoSessionsMap.set(parentSessionId, sessions);
+    },
+    onEnded: (parentSessionId, octtoSessionId) => {
+      const sessions = octtoSessionsMap.get(parentSessionId);
+      if (!sessions) return;
+      sessions.delete(octtoSessionId);
+      if (sessions.size === 0) {
+        octtoSessionsMap.delete(parentSessionId);
+      }
+    },
+  });
+
   return {
     // Tools
     tool: {
diff --git a/src/octto/constants.ts b/src/octto/constants.ts
index e016b67..6f35a29 100644
--- a/src/octto/constants.ts
+++ b/src/octto/constants.ts
@@ -8,7 +8,7 @@ import { config } from "../utils/config";
 export const DEFAULT_ANSWER_TIMEOUT_MS = config.octto.answerTimeoutMs;
 
 /** Default maximum number of follow-up questions per branch */
-export const DEFAULT_MAX_QUESTIONS = 15;
+export const DEFAULT_MAX_QUESTIONS = config.octto.maxQuestions;
 
 /** Default timeout for brainstorm review (10 minutes) */
 export const DEFAULT_REVIEW_TIMEOUT_MS = config.octto.reviewTimeoutMs;
diff --git a/src/octto/session/server.ts b/src/octto/session/server.ts
index ecde39e..cee99f9 100644
--- a/src/octto/session/server.ts
+++ b/src/octto/session/server.ts
@@ -1,8 +1,8 @@
 // src/octto/session/server.ts
 import type { Server, ServerWebSocket } from "bun";
 
+import { config } from "../../utils/config";
 import { getHtmlBundle } from "../ui";
-
 import type { SessionStore } from "./sessions";
 import type { WsClientMessage } from "./types";
 
@@ -18,6 +18,7 @@ export async function createServer(
 
   const server = Bun.serve<WsData>({
     port: 0, // Random available port
+    hostname: config.octto.allowRemoteBind ? config.octto.bindAddress : "127.0.0.1",
     fetch(req, server) {
       const url = new URL(req.url);
 
diff --git a/src/octto/session/sessions.ts b/src/octto/session/sessions.ts
index fac6f69..f93ddc4 100644
--- a/src/octto/session/sessions.ts
+++ b/src/octto/session/sessions.ts
@@ -2,7 +2,6 @@
 import type { ServerWebSocket } from "bun";
 
 import { DEFAULT_ANSWER_TIMEOUT_MS } from "../constants";
-import { generateQuestionId, generateSessionId } from "./utils";
 import { openBrowser } from "./browser";
 import { createServer } from "./server";
 import {
@@ -25,6 +24,7 @@ import {
   type WsClientMessage,
   type WsServerMessage,
 } from "./types";
+import { generateQuestionId, generateSessionId } from "./utils";
 import { createWaiters } from "./waiter";
 
 export interface SessionStoreOptions {
@@ -57,7 +57,8 @@ export function createSessionStore(options: SessionStoreOptions = {}): SessionSt
     async startSession(input: StartSessionInput): Promise<StartSessionOutput> {
       const sessionId = generateSessionId();
       const { server, port } = await createServer(sessionId, store);
-      const url = `http://localhost:${port}`;
+      const urlHost = server.hostname ?? "localhost";
+      const url = `http://${urlHost}:${port}`;
 
       const session: Session = {
         id: sessionId,
@@ -205,7 +206,6 @@ export function createSessionStore(options: SessionStoreOptions = {}): SessionSt
 
         timeoutId = setTimeout(() => {
           cleanup();
-          question.status = STATUSES.TIMEOUT;
           resolve({ completed: false, status: STATUSES.TIMEOUT, reason: STATUSES.TIMEOUT });
         }, timeout);
       });
diff --git a/src/octto/session/waiter.ts b/src/octto/session/waiter.ts
index f77d57e..108ef02 100644
--- a/src/octto/session/waiter.ts
+++ b/src/octto/session/waiter.ts
@@ -74,11 +74,18 @@ export function createWaiters<K, T>(): Waiters<K, T> {
       const callbacks = waiters.get(key);
       if (!callbacks) return;
 
-      for (const callback of callbacks) {
-        callback(data);
+      try {
+        for (const callback of callbacks) {
+          try {
+            callback(data);
+          } catch (error) {
+            console.error("Waiter notifyAll failed", error);
+            break;
+          }
+        }
+      } finally {
+        waiters.delete(key);
       }
-
-      waiters.delete(key);
     },
 
     /**
diff --git a/src/octto/state/store.ts b/src/octto/state/store.ts
index 68ad9ea..b129d54 100644
--- a/src/octto/state/store.ts
+++ b/src/octto/state/store.ts
@@ -1,7 +1,7 @@
 // src/octto/state/store.ts
-import type { Answer } from "../session";
 
 import { STATE_DIR } from "../constants";
+import type { Answer } from "../session";
 import { createStatePersistence } from "./persistence";
 import {
   BRANCH_STATUSES,
@@ -153,7 +153,9 @@ export function createStateStore(baseDir = STATE_DIR): StateStore {
     },
 
     async deleteSession(sessionId: string): Promise<void> {
-      await persistence.delete(sessionId);
+      await withSessionLock(sessionId, async () => {
+        await persistence.delete(sessionId);
+      });
     },
   };
 }
diff --git a/src/tools/octto/brainstorm.ts b/src/tools/octto/brainstorm.ts
index f1e3d53..fbdd426 100644
--- a/src/tools/octto/brainstorm.ts
+++ b/src/tools/octto/brainstorm.ts
@@ -6,10 +6,9 @@ import { QUESTION_TYPES, QUESTIONS, STATUSES } from "../../octto/session";
 import { BRANCH_STATUSES, type BrainstormState, createStateStore, type StateStore } from "../../octto/state";
 import { config } from "../../utils/config";
 import { log } from "../../utils/logger";
-
 import { formatBranchStatus, formatFindings, formatFindingsList, formatQASummary } from "./formatters";
 import { processAnswer } from "./processor";
-import type { OcttoTools, OpencodeClient } from "./types";
+import type { OcttoSessionTracker, OcttoTools, OpencodeClient } from "./types";
 import { generateSessionId } from "./utils";
 
 // --- Extracted helper functions ---
@@ -141,14 +140,14 @@ function formatSkippedReviewResult(state: BrainstormState): string {
   <branch_count>${state.branch_order.length}</branch_count>
   <note>Browser session ended before review</note>
   ${formatFindings(state)}
-  <next_action>Write the design document to docs/plans/</next_action>
+  <next_action>Write the design document to thoughts/shared/designs/</next_action>
 </brainstorm_complete>`;
 }
 
 function formatCompletionResult(state: BrainstormState, approved: boolean, feedback: string): string {
   const feedbackXml = feedback ? `\n  <feedback>${feedback}</feedback>` : "";
   const nextAction = approved
-    ? "Write the design document to docs/plans/"
+    ? "Write the design document to thoughts/shared/designs/"
     : "Review feedback and discuss with user before proceeding";
   return `<brainstorm_complete status="${approved ? "approved" : "changes_requested"}">
   <request>${state.request}</request>
@@ -160,7 +159,11 @@ function formatCompletionResult(state: BrainstormState, approved: boolean, feedb
 
 // --- Tool definitions ---
 
-export function createBrainstormTools(sessions: SessionStore, client: OpencodeClient): OcttoTools {
+export function createBrainstormTools(
+  sessions: SessionStore,
+  client: OpencodeClient,
+  tracker?: OcttoSessionTracker,
+): OcttoTools {
   const store = createStateStore();
 
   const create_brainstorm = tool({
@@ -183,7 +186,7 @@ export function createBrainstormTools(sessions: SessionStore, client: OpencodeCl
         )
         .describe("Branches to explore"),
     },
-    execute: async (args) => {
+    execute: async (args, context) => {
       const sessionId = generateSessionId();
 
       await store.createSession(
@@ -206,6 +209,7 @@ export function createBrainstormTools(sessions: SessionStore, client: OpencodeCl
         questions: initialQuestions,
       });
 
+      tracker?.onCreated?.(context.sessionID, browserSession.session_id);
       await store.setBrowserSessionId(sessionId, browserSession.session_id);
 
       for (const [i, branch] of args.branches.entries()) {
@@ -261,12 +265,15 @@ ${branches}
     args: {
       session_id: tool.schema.string().describe("Brainstorm session ID"),
     },
-    execute: async (args) => {
+    execute: async (args, context) => {
       const state = await store.getSession(args.session_id);
       if (!state) return `<error>Session not found: ${args.session_id}</error>`;
 
       if (state.browser_session_id) {
-        await sessions.endSession(state.browser_session_id);
+        const result = await sessions.endSession(state.browser_session_id);
+        if (result.ok) {
+          tracker?.onEnded?.(context.sessionID, state.browser_session_id);
+        }
       }
 
       const findings = formatFindingsList(state);
@@ -275,7 +282,7 @@ ${branches}
       return `<brainstorm_ended>
   <request>${state.request}</request>
   ${findings}
-  <next_action>Write the design document based on these findings</next_action>
+  <next_action>Write the design document based on these findings to thoughts/shared/designs/</next_action>
 </brainstorm_ended>`;
     },
   });
diff --git a/src/tools/octto/formatters.ts b/src/tools/octto/formatters.ts
index abfe4cd..c45a34d 100644
--- a/src/tools/octto/formatters.ts
+++ b/src/tools/octto/formatters.ts
@@ -2,11 +2,15 @@
 
 import type { Answer } from "../../octto/session";
 import type { BrainstormState, Branch, BranchQuestion } from "../../octto/state";
-
 import { extractAnswerSummary } from "./extractor";
 
 function escapeXml(str: string): string {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
 }
 
 export function formatBranchFinding(branch: Branch): string {
diff --git a/src/tools/octto/index.ts b/src/tools/octto/index.ts
index dd4a224..3562198 100644
--- a/src/tools/octto/index.ts
+++ b/src/tools/octto/index.ts
@@ -1,24 +1,27 @@
 // src/tools/octto/index.ts
 
 import type { SessionStore } from "../../octto/session";
-
 import { createBrainstormTools } from "./brainstorm";
 import { createPushQuestionTool } from "./factory";
 import { createQuestionTools } from "./questions";
 import { createResponseTools } from "./responses";
 import { createSessionTools } from "./session";
-import type { OcttoTools, OpencodeClient } from "./types";
+import type { OcttoSessionTracker, OcttoTools, OpencodeClient } from "./types";
 
-export type { OcttoTools, OpencodeClient } from "./types";
 export type { SessionStore } from "../../octto/session";
 export { createSessionStore } from "../../octto/session";
+export type { OcttoSessionTracker, OcttoTools, OpencodeClient } from "./types";
 
-export function createOcttoTools(sessions: SessionStore, client: OpencodeClient): OcttoTools {
+export function createOcttoTools(
+  sessions: SessionStore,
+  client: OpencodeClient,
+  tracker?: OcttoSessionTracker,
+): OcttoTools {
   return {
-    ...createSessionTools(sessions),
+    ...createSessionTools(sessions, tracker),
     ...createQuestionTools(sessions),
     ...createResponseTools(sessions),
     ...createPushQuestionTool(sessions),
-    ...createBrainstormTools(sessions, client),
+    ...createBrainstormTools(sessions, client, tracker),
   };
 }
diff --git a/src/tools/octto/types.ts b/src/tools/octto/types.ts
index 853eb98..5d5c252 100644
--- a/src/tools/octto/types.ts
+++ b/src/tools/octto/types.ts
@@ -14,3 +14,8 @@ export interface OcttoTool {
 export type OcttoTools = Record<string, OcttoTool>;
 
 export type OpencodeClient = ReturnType<typeof createOpencodeClient>;
+
+export interface OcttoSessionTracker {
+  onCreated?: (parentSessionId: string, octtoSessionId: string) => void;
+  onEnded?: (parentSessionId: string, octtoSessionId: string) => void;
+}
diff --git a/src/utils/config.ts b/src/utils/config.ts
index e47a2bf..b87b823 100644
--- a/src/utils/config.ts
+++ b/src/utils/config.ts
@@ -111,7 +111,13 @@ export const config = {
     reviewTimeoutMs: 10 * 60 * 1000,
     /** Max iterations in brainstorm loop */
     maxIterations: 50,
+    /** Max follow-up questions per branch */
+    maxQuestions: 15,
     /** State directory for brainstorm sessions */
     stateDir: "thoughts/brainstorms",
+    /** Bind address for brainstorm server */
+    bindAddress: "127.0.0.1",
+    /** Allow overriding bind address for remote access */
+    allowRemoteBind: false,
   },
 } as const;
diff --git a/tests/indexing/flows/milestone-error-paths.test.ts b/tests/indexing/flows/milestone-error-paths.test.ts
index 2875b59..6816bed 100644
--- a/tests/indexing/flows/milestone-error-paths.test.ts
+++ b/tests/indexing/flows/milestone-error-paths.test.ts
@@ -26,30 +26,32 @@ describe("milestone artifact ingest error paths", () => {
     const index = new ArtifactIndex(testDir);
     await index.initialize();
 
-    await ingestMilestoneArtifact(
-      {
-        id: "artifact-err",
+    try {
+      await ingestMilestoneArtifact(
+        {
+          id: "artifact-err",
+          milestoneId: "ms-err",
+          sourceSessionId: "session-err",
+          createdAt: "2026-01-16T13:00:00Z",
+          tags: ["error"],
+          payload: "Status update only.",
+        },
+        index,
+        () => {
+          throw new Error("classifier failure");
+        },
+      );
+
+      const results = await index.searchMilestoneArtifacts("status", {
         milestoneId: "ms-err",
-        sourceSessionId: "session-err",
-        createdAt: "2026-01-16T13:00:00Z",
-        tags: ["error"],
-        payload: "Status update only.",
-      },
-      index,
-      () => {
-        throw new Error("classifier failure");
-      },
-    );
-
-    const results = await index.searchMilestoneArtifacts("status", {
-      milestoneId: "ms-err",
-      limit: 10,
-    });
-
-    expect(results).toHaveLength(1);
-    expect(results[0].artifactType).toBe(MILESTONE_ARTIFACT_TYPES.SESSION);
-    expect(consoleErrorSpy).toHaveBeenCalled();
-
-    await index.close();
+        limit: 10,
+      });
+
+      expect(results).toHaveLength(1);
+      expect(results[0].artifactType).toBe(MILESTONE_ARTIFACT_TYPES.SESSION);
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    } finally {
+      await index.close();
+    }
   });
 });
diff --git a/tests/indexing/flows/milestone-ingest.test.ts b/tests/indexing/flows/milestone-ingest.test.ts
index 8d03bcf..ab52b55 100644
--- a/tests/indexing/flows/milestone-ingest.test.ts
+++ b/tests/indexing/flows/milestone-ingest.test.ts
@@ -22,26 +22,28 @@ describe("milestone artifact ingest", () => {
     const index = new ArtifactIndex(testDir);
     await index.initialize();
 
-    await ingestMilestoneArtifact(
-      {
-        id: "artifact-3",
+    try {
+      await ingestMilestoneArtifact(
+        {
+          id: "artifact-3",
+          milestoneId: "ms-3",
+          sourceSessionId: "session-3",
+          createdAt: "2026-01-16T12:00:00Z",
+          tags: ["feature", "milestone"],
+          payload: "Implementation details for the indexing pipeline.",
+        },
+        index,
+      );
+
+      const results = await index.searchMilestoneArtifacts("implementation", {
         milestoneId: "ms-3",
-        sourceSessionId: "session-3",
-        createdAt: "2026-01-16T12:00:00Z",
-        tags: ["feature", "milestone"],
-        payload: "Implementation details for the indexing pipeline.",
-      },
-      index,
-    );
-
-    const results = await index.searchMilestoneArtifacts("implementation", {
-      milestoneId: "ms-3",
-      limit: 10,
-    });
-
-    expect(results).toHaveLength(1);
-    expect(results[0].artifactType).toBe("feature");
-
-    await index.close();
+        limit: 10,
+      });
+
+      expect(results).toHaveLength(1);
+      expect(results[0].artifactType).toBe("feature");
+    } finally {
+      await index.close();
+    }
   });
 });
diff --git a/tests/indexing/search/milestone-search.test.ts b/tests/indexing/search/milestone-search.test.ts
index 4eca8b7..02a810d 100644
--- a/tests/indexing/search/milestone-search.test.ts
+++ b/tests/indexing/search/milestone-search.test.ts
@@ -20,39 +20,41 @@ describe("milestone artifact search", () => {
     const index = new ArtifactIndex(testDir);
     await index.initialize();
 
-    await index.indexMilestoneArtifact({
-      id: "artifact-1",
-      milestoneId: "ms-1",
-      artifactType: "feature",
-      sourceSessionId: "session-1",
-      createdAt: "2026-01-16T10:00:00Z",
-      tags: ["feature"],
-      payload: "Implementation details for milestone indexing.",
-    });
-
-    await index.indexMilestoneArtifact({
-      id: "artifact-2",
-      milestoneId: "ms-2",
-      artifactType: "decision",
-      sourceSessionId: "session-2",
-      createdAt: "2026-01-16T11:00:00Z",
-      tags: ["decision"],
-      payload: "Decision to store artifacts only in SQLite.",
-    });
-
-    const results = await index.searchMilestoneArtifacts("SQLite", {
-      milestoneId: "ms-2",
-      artifactType: "decision",
-      limit: 10,
-    });
-
-    expect(results).toHaveLength(1);
-    expect(results[0]).toMatchObject({
-      id: "artifact-2",
-      milestoneId: "ms-2",
-      artifactType: "decision",
-    });
-
-    await index.close();
+    try {
+      await index.indexMilestoneArtifact({
+        id: "artifact-1",
+        milestoneId: "ms-1",
+        artifactType: "feature",
+        sourceSessionId: "session-1",
+        createdAt: "2026-01-16T10:00:00Z",
+        tags: ["feature"],
+        payload: "Implementation details for milestone indexing.",
+      });
+
+      await index.indexMilestoneArtifact({
+        id: "artifact-2",
+        milestoneId: "ms-2",
+        artifactType: "decision",
+        sourceSessionId: "session-2",
+        createdAt: "2026-01-16T11:00:00Z",
+        tags: ["decision"],
+        payload: "Decision to store artifacts only in SQLite.",
+      });
+
+      const results = await index.searchMilestoneArtifacts("SQLite", {
+        milestoneId: "ms-2",
+        artifactType: "decision",
+        limit: 10,
+      });
+
+      expect(results).toHaveLength(1);
+      expect(results[0]).toMatchObject({
+        id: "artifact-2",
+        milestoneId: "ms-2",
+        artifactType: "decision",
+      });
+    } finally {
+      await index.close();
+    }
   });
 });
diff --git a/tests/tools/artifact-index.test.ts b/tests/tools/artifact-index.test.ts
index 1f72a9e..d6d89ba 100644
--- a/tests/tools/artifact-index.test.ts
+++ b/tests/tools/artifact-index.test.ts
@@ -1,8 +1,8 @@
 // tests/tools/artifact-index.test.ts
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import { mkdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 describe("ArtifactIndex", () => {
   let testDir: string;
@@ -21,10 +21,12 @@ describe("ArtifactIndex", () => {
     const index = new ArtifactIndex(testDir);
     await index.initialize();
 
-    const dbPath = join(testDir, "context.db");
-    expect(Bun.file(dbPath).size).toBeGreaterThan(0);
-
-    await index.close();
+    try {
+      const dbPath = join(testDir, "context.db");
+      expect(Bun.file(dbPath).size).toBeGreaterThan(0);
+    } finally {
+      await index.close();
+    }
   });
 
   it("should index and search plans", async () => {
@@ -32,19 +34,21 @@ describe("ArtifactIndex", () => {
     const index = new ArtifactIndex(testDir);
     await index.initialize();
 
-    await index.indexPlan({
-      id: "plan-1",
-      title: "API Refactoring Plan",
-      filePath: "/path/to/plan.md",
-      overview: "Refactor REST API to GraphQL",
-      approach: "Incremental migration with adapter layer",
-    });
-
-    const results = await index.search("GraphQL migration");
-    expect(results.length).toBeGreaterThan(0);
-    expect(results[0].type).toBe("plan");
-
-    await index.close();
+    try {
+      await index.indexPlan({
+        id: "plan-1",
+        title: "API Refactoring Plan",
+        filePath: "/path/to/plan.md",
+        overview: "Refactor REST API to GraphQL",
+        approach: "Incremental migration with adapter layer",
+      });
+
+      const results = await index.search("GraphQL migration");
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].type).toBe("plan");
+    } finally {
+      await index.close();
+    }
   });
 
   it("should index and search ledgers", async () => {
@@ -52,22 +56,24 @@ describe("ArtifactIndex", () => {
     const index = new ArtifactIndex(testDir);
     await index.initialize();
 
-    await index.indexLedger({
-      id: "ledger-1",
-      sessionName: "database-migration",
-      filePath: "/path/to/ledger.md",
-      goal: "Migrate from MySQL to PostgreSQL",
-      stateNow: "Schema conversion in progress",
-      keyDecisions: "Use pgloader for data migration",
-      filesRead: "src/db/schema.ts,src/db/migrations/001.sql",
-      filesModified: "src/db/config.ts",
-    });
-
-    const results = await index.search("PostgreSQL migration");
-    expect(results.length).toBeGreaterThan(0);
-    expect(results[0].type).toBe("ledger");
-
-    await index.close();
+    try {
+      await index.indexLedger({
+        id: "ledger-1",
+        sessionName: "database-migration",
+        filePath: "/path/to/ledger.md",
+        goal: "Migrate from MySQL to PostgreSQL",
+        stateNow: "Schema conversion in progress",
+        keyDecisions: "Use pgloader for data migration",
+        filesRead: "src/db/schema.ts,src/db/migrations/001.sql",
+        filesModified: "src/db/config.ts",
+      });
+
+      const results = await index.search("PostgreSQL migration");
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].type).toBe("ledger");
+    } finally {
+      await index.close();
+    }
   });
 
   it("should index ledger with file operations", async () => {
@@ -75,19 +81,21 @@ describe("ArtifactIndex", () => {
     const index = new ArtifactIndex(testDir);
     await index.initialize();
 
-    await index.indexLedger({
-      id: "ledger-2",
-      sessionName: "feature-work",
-      filePath: "/path/to/ledger2.md",
-      goal: "Implement new feature",
-      filesRead: "src/a.ts,src/b.ts",
-      filesModified: "src/c.ts",
-    });
-
-    // Verify it was indexed (search should find it)
-    const results = await index.search("feature");
-    expect(results.length).toBeGreaterThan(0);
-
-    await index.close();
+    try {
+      await index.indexLedger({
+        id: "ledger-2",
+        sessionName: "feature-work",
+        filePath: "/path/to/ledger2.md",
+        goal: "Implement new feature",
+        filesRead: "src/a.ts,src/b.ts",
+        filesModified: "src/c.ts",
+      });
+
+      // Verify it was indexed (search should find it)
+      const results = await index.search("feature");
+      expect(results.length).toBeGreaterThan(0);
+    } finally {
+      await index.close();
+    }
   });
 });

From fd73d1d22aba09f2a8a53d5433467b3428107659 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sun, 18 Jan 2026 00:08:04 +0200
Subject: [PATCH 19/22] fix(config): clean up model validation tests

---
 src/config-loader.test.ts | 46 ---------------------------------------
 1 file changed, 46 deletions(-)

diff --git a/src/config-loader.test.ts b/src/config-loader.test.ts
index 7bf8cf9..ff65d09 100644
--- a/src/config-loader.test.ts
+++ b/src/config-loader.test.ts
@@ -1,8 +1,6 @@
 // src/config-loader.test.ts
 import { describe, expect, test } from "bun:test";
 
-import type { AgentConfig } from "@opencode-ai/sdk";
-
 import { type MicodeConfig, type ProviderInfo, validateAgentModels } from "./config-loader";
 
 // Helper to create a minimal ProviderInfo for testing
@@ -14,14 +12,6 @@ function createProvider(id: string, modelIds: string[]): ProviderInfo {
   return { id, models };
 }
 
-// Helper to create minimal AgentConfig
-function createAgentConfig(model: string): AgentConfig {
-  return {
-    model,
-    systemPrompt: "test",
-  } as AgentConfig;
-}
-
 describe("validateAgentModels", () => {
   test("returns config unchanged when all models are valid", () => {
     const userConfig: MicodeConfig = {
@@ -36,11 +26,6 @@ describe("validateAgentModels", () => {
       createProvider("anthropic", ["claude-3", "claude-2"]),
     ];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-3.5"),
-      brainstormer: createAgentConfig("anthropic/claude-2"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     expect(result.agents?.commander?.model).toBe("openai/gpt-4");
@@ -56,10 +41,6 @@ describe("validateAgentModels", () => {
 
     const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-4"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     // Model should be removed, falling back to default
@@ -75,10 +56,6 @@ describe("validateAgentModels", () => {
 
     const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4", "gpt-3.5"])];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-4"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     // Model should be removed, falling back to default
@@ -98,10 +75,6 @@ describe("validateAgentModels", () => {
 
     const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-4"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     // Model removed but other properties preserved
@@ -115,10 +88,6 @@ describe("validateAgentModels", () => {
 
     const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-4"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     expect(result).toEqual({});
@@ -133,10 +102,6 @@ describe("validateAgentModels", () => {
 
     const providers: ProviderInfo[] = [createProvider("openai", ["gpt-4"])];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-4"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     // No model to validate, config unchanged
@@ -153,10 +118,6 @@ describe("validateAgentModels", () => {
 
     const providers: ProviderInfo[] = [];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-4"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     // No providers available, config should remain unchanged
@@ -193,13 +154,6 @@ describe("validateAgentModels", () => {
       createProvider("anthropic", ["claude-3"]),
     ];
 
-    const defaultAgents: Record<string, AgentConfig> = {
-      commander: createAgentConfig("openai/gpt-3.5"),
-      brainstormer: createAgentConfig("openai/gpt-3.5"),
-      planner: createAgentConfig("openai/gpt-3.5"),
-      reviewer: createAgentConfig("anthropic/claude-3"),
-    };
-
     const result = validateAgentModels(userConfig, providers);
 
     expect(result.agents?.commander?.model).toBe("openai/gpt-4");

From 976875edb3f5755e22541ba28a7ae1d2b79b03fe Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sun, 18 Jan 2026 09:21:21 +0200
Subject: [PATCH 20/22] fix(config): relax model validation

---
 src/agents/index.ts   | 49 ++++++++++++++++++++++---------------------
 src/agents/planner.ts |  2 +-
 src/config-loader.ts  |  8 +++----
 3 files changed, 30 insertions(+), 29 deletions(-)

diff --git a/src/agents/index.ts b/src/agents/index.ts
index 99cb308..c3e6766 100644
--- a/src/agents/index.ts
+++ b/src/agents/index.ts
@@ -1,36 +1,37 @@
 import type { AgentConfig } from "@opencode-ai/sdk";
-import { brainstormerAgent } from "./brainstormer";
+
+import { artifactSearcherAgent } from "./artifact-searcher";
 import { bootstrapperAgent } from "./bootstrapper";
-import { codebaseLocatorAgent } from "./codebase-locator";
+import { brainstormerAgent } from "./brainstormer";
 import { codebaseAnalyzerAgent } from "./codebase-analyzer";
-import { patternFinderAgent } from "./pattern-finder";
-import { plannerAgent } from "./planner";
-import { implementerAgent } from "./implementer";
-import { reviewerAgent } from "./reviewer";
+import { codebaseLocatorAgent } from "./codebase-locator";
+import { PRIMARY_AGENT_NAME, primaryAgent } from "./commander";
 import { executorAgent } from "./executor";
-import { primaryAgent, PRIMARY_AGENT_NAME } from "./commander";
-import { projectInitializerAgent } from "./project-initializer";
+import { implementerAgent } from "./implementer";
 import { ledgerCreatorAgent } from "./ledger-creator";
-import { artifactSearcherAgent } from "./artifact-searcher";
 import { octtoAgent } from "./octto";
+import { patternFinderAgent } from "./pattern-finder";
+import { plannerAgent } from "./planner";
 import { probeAgent } from "./probe";
+import { projectInitializerAgent } from "./project-initializer";
+import { reviewerAgent } from "./reviewer";
 
 export const agents: Record<string, AgentConfig> = {
-  [PRIMARY_AGENT_NAME]: primaryAgent,
-  brainstormer: brainstormerAgent,
-  bootstrapper: bootstrapperAgent,
-  "codebase-locator": codebaseLocatorAgent,
-  "codebase-analyzer": codebaseAnalyzerAgent,
-  "pattern-finder": patternFinderAgent,
-  planner: plannerAgent,
-  implementer: implementerAgent,
-  reviewer: reviewerAgent,
-  executor: executorAgent,
-  "project-initializer": projectInitializerAgent,
-  "ledger-creator": ledgerCreatorAgent,
-  "artifact-searcher": artifactSearcherAgent,
-  octto: octtoAgent,
-  probe: probeAgent,
+  [PRIMARY_AGENT_NAME]: { ...primaryAgent, model: "openai/gpt-5.2-codex" },
+  brainstormer: { ...brainstormerAgent, model: "openai/gpt-5.2-codex" },
+  bootstrapper: { ...bootstrapperAgent, model: "openai/gpt-5.2-codex" },
+  "codebase-locator": { ...codebaseLocatorAgent, model: "openai/gpt-5.2-codex" },
+  "codebase-analyzer": { ...codebaseAnalyzerAgent, model: "openai/gpt-5.2-codex" },
+  "pattern-finder": { ...patternFinderAgent, model: "openai/gpt-5.2-codex" },
+  planner: { ...plannerAgent, model: "openai/gpt-5.2-codex" },
+  implementer: { ...implementerAgent, model: "openai/gpt-5.2-codex" },
+  reviewer: { ...reviewerAgent, model: "openai/gpt-5.2-codex" },
+  executor: { ...executorAgent, model: "openai/gpt-5.2-codex" },
+  "project-initializer": { ...projectInitializerAgent, model: "openai/gpt-5.2-codex" },
+  "ledger-creator": { ...ledgerCreatorAgent, model: "openai/gpt-5.2-codex" },
+  "artifact-searcher": { ...artifactSearcherAgent, model: "openai/gpt-5.2-codex" },
+  octto: { ...octtoAgent, model: "openai/gpt-5.2-codex" },
+  probe: { ...probeAgent, model: "openai/gpt-5.2-codex" },
 };
 
 export {
diff --git a/src/agents/planner.ts b/src/agents/planner.ts
index 4cc7ff1..2e53de7 100644
--- a/src/agents/planner.ts
+++ b/src/agents/planner.ts
@@ -6,7 +6,7 @@ export const plannerAgent: AgentConfig = {
   temperature: 0.3,
   prompt: `<environment>
 You are running as part of the "micode" OpenCode plugin (NOT Claude Code).
-You are a SUBAGENT - use spawn_agent tool (not Task tool) to spawn other subagents.
+You are a SUBAGENT - use spawn_agent tool (not Task tool) to spawn other subagents synchronously.
 Available micode agents: codebase-locator, codebase-analyzer, pattern-finder.
 </environment>
 
diff --git a/src/config-loader.ts b/src/config-loader.ts
index 504398b..e9e0f3d 100644
--- a/src/config-loader.ts
+++ b/src/config-loader.ts
@@ -109,8 +109,8 @@ export function mergeAgentConfigs(
     return pluginAgents;
   }
 
-  // Load available models if not provided
-  const models = availableModels ?? loadAvailableModels();
+  const models = availableModels ?? new Set<string>();
+  const shouldValidateModels = availableModels !== undefined && models.size > 0;
 
   const merged: Record<string, AgentConfig> = {};
 
@@ -120,8 +120,8 @@ export function mergeAgentConfigs(
     if (userOverride) {
       // Validate model if specified
       if (userOverride.model) {
-        if (models.has(userOverride.model)) {
-          // Model is valid - apply all overrides
+        if (!shouldValidateModels || models.has(userOverride.model)) {
+          // Model is valid (or validation unavailable) - apply all overrides
           merged[name] = {
             ...agentConfig,
             ...userOverride,

From 5d56e0fe6cb4a8d7cc523aebf296e55ed1925c86 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sun, 18 Jan 2026 10:15:01 +0200
Subject: [PATCH 21/22] test(config): cover model validation

---
 src/config-loader.ts                    |  4 ++--
 tests/config-loader-integration.test.ts | 13 +++++++++----
 tests/config-loader.test.ts             | 13 ++++++++-----
 3 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/src/config-loader.ts b/src/config-loader.ts
index e9e0f3d..5e987c9 100644
--- a/src/config-loader.ts
+++ b/src/config-loader.ts
@@ -109,8 +109,8 @@ export function mergeAgentConfigs(
     return pluginAgents;
   }
 
-  const models = availableModels ?? new Set<string>();
-  const shouldValidateModels = availableModels !== undefined && models.size > 0;
+  const models = availableModels ?? loadAvailableModels();
+  const shouldValidateModels = models.size > 0;
 
   const merged: Record<string, AgentConfig> = {};
 
diff --git a/tests/config-loader-integration.test.ts b/tests/config-loader-integration.test.ts
index ebd9512..6d9b5e2 100644
--- a/tests/config-loader-integration.test.ts
+++ b/tests/config-loader-integration.test.ts
@@ -1,7 +1,8 @@
 // tests/config-loader-integration.test.ts
-import { describe, it, expect } from "bun:test";
-import { loadMicodeConfig, mergeAgentConfigs } from "../src/config-loader";
+import { describe, expect, it } from "bun:test";
+
 import { agents } from "../src/agents";
+import { loadMicodeConfig, mergeAgentConfigs } from "../src/config-loader";
 
 describe("config-loader integration", () => {
   it("should have all agents defined in agents/index.ts", () => {
@@ -35,7 +36,9 @@ describe("config-loader integration", () => {
       },
     };
 
-    const merged = mergeAgentConfigs(agents, userConfig);
+    const availableModels = new Set(["openai/gpt-4o", "openai/gpt-5.2-codex"]);
+
+    const merged = mergeAgentConfigs(agents, userConfig, availableModels);
 
     // Check project-initializer was merged correctly
     expect(merged["project-initializer"]).toBeDefined();
@@ -54,7 +57,9 @@ describe("config-loader integration", () => {
       },
     };
 
-    const merged = mergeAgentConfigs(agents, userConfig);
+    const availableModels = new Set(["openai/gpt-4o", "openai/gpt-5.2-codex"]);
+
+    const merged = mergeAgentConfigs(agents, userConfig, availableModels);
 
     const pi = merged["project-initializer"];
     expect(pi.model).toBe("openai/gpt-4o");
diff --git a/tests/config-loader.test.ts b/tests/config-loader.test.ts
index 6168046..ab32e2f 100644
--- a/tests/config-loader.test.ts
+++ b/tests/config-loader.test.ts
@@ -1,8 +1,9 @@
 // tests/config-loader.test.ts
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
-import { mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 import { loadMicodeConfig, mergeAgentConfigs } from "../src/config-loader";
 
 describe("config-loader", () => {
@@ -149,8 +150,9 @@ describe("mergeAgentConfigs", () => {
         commander: { model: "openai/gpt-4o", temperature: 0.5 },
       },
     };
+    const availableModels = new Set(["openai/gpt-4o", "anthropic/claude-opus-4-5"]);
 
-    const merged = mergeAgentConfigs(pluginAgents, userConfig);
+    const merged = mergeAgentConfigs(pluginAgents, userConfig, availableModels);
 
     expect(merged.commander.model).toBe("openai/gpt-4o");
     expect(merged.commander.temperature).toBe(0.5);
@@ -176,8 +178,9 @@ describe("mergeAgentConfigs", () => {
         commander: { model: "openai/gpt-4o" },
       },
     };
+    const availableModels = new Set(["openai/gpt-4o", "anthropic/claude-opus-4-5"]);
 
-    const merged = mergeAgentConfigs(pluginAgents, userConfig);
+    const merged = mergeAgentConfigs(pluginAgents, userConfig, availableModels);
 
     expect(merged.commander.model).toBe("openai/gpt-4o");
     expect(merged.brainstormer.model).toBe("anthropic/claude-opus-4-5");

From ec46a3abe1639b429665b2158585e98b9cce1f88 Mon Sep 17 00:00:00 2001
From: Vlad Temian <vladtemian@gmail.com>
Date: Sun, 18 Jan 2026 10:15:17 +0200
Subject: [PATCH 22/22] test(config): clean lint warnings

---
 tests/config-loader-integration.test.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/config-loader-integration.test.ts b/tests/config-loader-integration.test.ts
index 6d9b5e2..f6b2b65 100644
--- a/tests/config-loader-integration.test.ts
+++ b/tests/config-loader-integration.test.ts
@@ -2,7 +2,7 @@
 import { describe, expect, it } from "bun:test";
 
 import { agents } from "../src/agents";
-import { loadMicodeConfig, mergeAgentConfigs } from "../src/config-loader";
+import { mergeAgentConfigs } from "../src/config-loader";
 
 describe("config-loader integration", () => {
   it("should have all agents defined in agents/index.ts", () => {
@@ -47,7 +47,7 @@ describe("config-loader integration", () => {
     expect(merged["project-initializer"].prompt).toBeDefined();
 
     // Check other agents still have defaults
-    expect(merged["commander"].model).toBe("openai/gpt-5.2-codex");
+    expect(merged.commander.model).toBe("openai/gpt-5.2-codex");
   });
 
   it("should preserve all agent properties when merging", () => {