@jmylchreest/aide-plugin 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "aide plugin for OpenCode — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",

package/src/cli/config.ts

@@ -95,7 +95,7 @@ export function addAideToConfig(
     if (!mcp[MCP_SERVER_NAME]) {
       mcp[MCP_SERVER_NAME] = {
         type: "local",
-        command: ["npx", "-y", "-p", PLUGIN_NAME, "aide-wrapper", "mcp"],
+        command: ["npx", "-y", PLUGIN_NAME, "mcp"],
         environment: {
           AIDE_CODE_WATCH: "1",
           AIDE_CODE_WATCH_DELAY: "30s",

package/src/cli/index.ts

@@ -6,11 +6,13 @@
  *   bunx @jmylchreest/aide-plugin install   # Install globally for OpenCode
  *   bunx @jmylchreest/aide-plugin uninstall  # Remove from OpenCode config
  *   bunx @jmylchreest/aide-plugin status     # Show current installation status
+ *   bunx @jmylchreest/aide-plugin mcp        # Start MCP server (used by OpenCode)
  */
 
 import { install } from "./install.js";
 import { uninstall } from "./uninstall.js";
 import { status } from "./status.js";
+import { mcp } from "./mcp.js";
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -22,6 +24,7 @@ Usage:
   aide-plugin install     Install aide plugin globally for OpenCode
   aide-plugin uninstall   Remove aide plugin from OpenCode config
   aide-plugin status      Show current installation status
+  aide-plugin mcp         Start MCP server (delegates to aide-wrapper)
   aide-plugin --help      Show this help message
 
 Options:
@@ -49,6 +52,9 @@ async function main(): Promise<void> {
     case "status":
       await status();
       break;
+    case "mcp":
+      await mcp(args.slice(1));
+      break;
     case "--help":
     case "-h":
     case "help":

package/src/cli/install.ts

@@ -1,5 +1,8 @@
 /**
  * Install command — registers aide plugin and MCP server in OpenCode config.
+ *
+ * On reinstall, detects and upgrades stale MCP command configurations
+ * (e.g. old `aide-wrapper` commands) to the current format.
  */
 
 import {
@@ -10,6 +13,7 @@ import {
   readConfig,
   writeConfig,
   PLUGIN_NAME,
+  MCP_SERVER_NAME,
 } from "./config.js";
 
 export interface InstallFlags {
@@ -17,6 +21,32 @@ export interface InstallFlags {
   noMcp?: boolean;
 }
 
+/**
+ * Check if an existing MCP config has the current expected command format.
+ * Returns false if the command is missing, empty, or uses an outdated format.
+ */
+function isMcpCommandCurrent(config: ReturnType<typeof readConfig>): boolean {
+  const mcpConfig = config.mcp?.[MCP_SERVER_NAME];
+  if (!mcpConfig?.command || mcpConfig.command.length === 0) {
+    return false;
+  }
+
+  const cmd = mcpConfig.command;
+
+  // Current format: ["npx", "-y", "@jmylchreest/aide-plugin", "mcp"]
+  if (
+    cmd.length === 4 &&
+    cmd[0] === "npx" &&
+    cmd[1] === "-y" &&
+    cmd[2] === PLUGIN_NAME &&
+    cmd[3] === "mcp"
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
 export async function install(flags: InstallFlags): Promise<void> {
   const configPath = flags.project
     ? getProjectConfigPath()
@@ -29,7 +59,11 @@ export async function install(flags: InstallFlags): Promise<void> {
   const existing = readConfig(configPath);
   const before = isAideConfigured(existing);
 
-  if (before.plugin && before.mcp) {
+  // Check if MCP command needs updating (stale format from older versions)
+  const mcpNeedsUpdate =
+    !flags.noMcp && before.mcp && !isMcpCommandCurrent(existing);
+
+  if (before.plugin && before.mcp && !mcpNeedsUpdate) {
     console.log(`aide is already configured in ${configPath}`);
     console.log("  plugin: registered");
     console.log("  mcp:    registered");
@@ -37,6 +71,11 @@ export async function install(flags: InstallFlags): Promise<void> {
     return;
   }
 
+  // If MCP config is stale, remove it so addAideToConfig will write the current version
+  if (mcpNeedsUpdate && existing.mcp) {
+    delete existing.mcp[MCP_SERVER_NAME];
+  }
+
   // Apply changes
   const updated = addAideToConfig(existing, { noMcp: flags.noMcp });
   writeConfig(configPath, updated);
@@ -52,7 +91,9 @@ export async function install(flags: InstallFlags): Promise<void> {
   }
 
   if (!flags.noMcp) {
-    if (!before.mcp && after.mcp) {
+    if (mcpNeedsUpdate) {
+      console.log(`  ~ Updated "aide" MCP server command (was outdated)`);
+    } else if (!before.mcp && after.mcp) {
       console.log(`  + Added "aide" MCP server`);
     } else if (before.mcp) {
       console.log(`  = MCP server already registered`);

package/src/cli/mcp.ts

@@ -0,0 +1,63 @@
+/**
+ * MCP subcommand — delegates to aide-wrapper.sh to start the MCP server.
+ *
+ * This is the entry point used by OpenCode's MCP config:
+ *   "command": ["npx", "-y", "@jmylchreest/aide-plugin", "mcp"]
+ *
+ * The wrapper handles binary discovery/download, then exec's `aide mcp`.
+ */
+
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Find the aide-wrapper.sh script relative to this CLI module.
+ *
+ * Resolution: this file lives at <plugin-root>/src/cli/mcp.ts,
+ * so the wrapper is at <plugin-root>/bin/aide-wrapper.sh.
+ */
+function findWrapper(): string {
+  // __dirname equivalent for ESM
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  // src/cli -> src -> plugin-root
+  const pluginRoot = resolve(thisDir, "..", "..");
+  const wrapper = join(pluginRoot, "bin", "aide-wrapper.sh");
+
+  if (!existsSync(wrapper)) {
+    throw new Error(
+      `aide-wrapper.sh not found at ${wrapper}\n` +
+        `Expected plugin root: ${pluginRoot}\n` +
+        `Ensure the package is installed correctly.`,
+    );
+  }
+
+  return wrapper;
+}
+
+/**
+ * Start the MCP server by exec'ing aide-wrapper.sh with "mcp" + any extra args.
+ * This replaces the current process so stdio is inherited directly.
+ */
+export async function mcp(extraArgs: string[]): Promise<void> {
+  const wrapper = findWrapper();
+  const args = ["mcp", ...extraArgs];
+
+  // Use execFileSync with stdio inherit so the MCP JSON-RPC protocol
+  // flows directly between OpenCode and the aide binary.
+  // The wrapper will exec() into the aide binary, replacing itself.
+  try {
+    execFileSync(wrapper, args, {
+      stdio: "inherit",
+      env: process.env,
+    });
+  } catch (err: unknown) {
+    // execFileSync throws on non-zero exit. If the process was killed
+    // by a signal (e.g. OpenCode shutting down), exit cleanly.
+    if (err && typeof err === "object" && "status" in err) {
+      process.exit((err as { status: number }).status ?? 1);
+    }
+    throw err;
+  }
+}

package/src/core/comment-checker.ts

@@ -0,0 +1,354 @@
+/**
+ * Comment checker logic — platform-agnostic.
+ *
+ * Detects excessive or obvious comments in code written by AI agents.
+ * Injected as a warning after Write/Edit tool calls to nudge the agent
+ * toward cleaner, human-quality code output.
+ *
+ * Used by both Claude Code hooks (PostToolUse) and OpenCode plugin (tool.execute.after).
+ *
+ * Philosophy: LLMs over-comment because training data rewards explanation.
+ * The single most visible "AI slop" tell is unnecessary comments like
+ * "// Initialize the variable" above `let x = 0`. This checker catches
+ * those and nudges the agent to remove them without blocking the tool call.
+ */
+
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "comment-checker";
+
+/** File extensions we know how to check for comments */
+const CHECKABLE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".go",
+  ".py",
+  ".rs",
+  ".java",
+  ".c",
+  ".cpp",
+  ".h",
+  ".hpp",
+  ".cs",
+  ".rb",
+  ".swift",
+  ".kt",
+  ".scala",
+  ".php",
+  ".vue",
+  ".svelte",
+]);
+
+/** Extensions that use # for comments */
+const HASH_COMMENT_EXTENSIONS = new Set([".py", ".rb", ".sh", ".yaml", ".yml"]);
+
+/** Comment patterns to SKIP (not flag) — these are legitimate */
+const LEGITIMATE_PATTERNS = [
+  // Directives and pragmas
+  /^\s*\/\/\s*(eslint|prettier|ts-ignore|ts-expect-error|ts-nocheck|@ts-|TODO|FIXME|HACK|BUG|XXX|NOTE|IMPORTANT|WARNING)/i,
+  /^\s*\/\/\s*noinspection/i,
+  /^\s*\/\*\s*(eslint|prettier|global|jshint)/i,
+  /^\s*#\s*(type:\s*ignore|noqa|pragma|pylint|mypy)/i,
+  /^\s*\/\/\s*region\b/i,
+  /^\s*\/\/\s*endregion\b/i,
+  // Shebangs
+  /^\s*#!/,
+  // License/copyright headers
+  /^\s*\/\/\s*(copyright|license|SPDX)/i,
+  /^\s*#\s*(copyright|license|SPDX)/i,
+  // Encoding declarations
+  /^\s*#.*coding[:=]/,
+  // BDD/test descriptions (describe, it, test blocks in comments)
+  /^\s*\/\/\s*(describe|it|test|expect|should|given|when|then)\b/i,
+  // JSDoc/docstring openings (/** and """)
+  /^\s*\/\*\*/,
+  /^\s*"""/,
+  /^\s*'''/,
+  // Go build tags
+  /^\s*\/\/go:build/,
+  /^\s*\/\/\+build/,
+  // Rust attributes in comments
+  /^\s*\/\/!/,
+  /^\s*\/\/\s*#\[/,
+];
+
+/** Patterns that indicate an OBVIOUS/UNNECESSARY comment */
+const OBVIOUS_PATTERNS = [
+  // Restating the code in English
+  /^\s*\/\/\s*(initialize|initialise|set|create|declare|define|assign|update|increment|decrement|return|import|export|get|fetch|call|invoke|add|remove|delete|check|validate)\s+(the\s+)?\w+/i,
+  /^\s*#\s*(initialize|initialise|set|create|declare|define|assign|update|increment|decrement|return|import|export|get|fetch|call|invoke|add|remove|delete|check|validate)\s+(the\s+)?\w+/i,
+  // Section dividers that add no info
+  /^\s*\/\/\s*[-=*]{3,}\s*$/,
+  /^\s*#\s*[-=*]{3,}\s*$/,
+  // Empty comments
+  /^\s*\/\/\s*$/,
+  /^\s*#\s*$/,
+  // Repeating the function/variable name
+  /^\s*\/\/\s*(function|method|class|interface|type|const|let|var|def|func)\s+/i,
+  /^\s*#\s*(function|method|class|interface|type|const|let|var|def|func)\s+/i,
+];
+
+export interface CommentCheckResult {
+  /** Whether excessive comments were detected */
+  hasExcessiveComments: boolean;
+  /** Warning message to inject (empty if no issues) */
+  warning: string;
+  /** Number of suspicious comments found */
+  suspiciousCount: number;
+  /** Total comments found */
+  totalComments: number;
+  /** The suspicious comment lines */
+  examples: string[];
+}
+
+/**
+ * Extract the file extension from a path
+ */
+function getExtension(filePath: string): string {
+  const lastDot = filePath.lastIndexOf(".");
+  if (lastDot === -1) return "";
+  return filePath.slice(lastDot).toLowerCase();
+}
+
+/**
+ * Check if a line is a legitimate comment (should be kept)
+ */
+function isLegitimateComment(line: string): boolean {
+  return LEGITIMATE_PATTERNS.some((p) => p.test(line));
+}
+
+/**
+ * Check if a line is an obvious/unnecessary comment
+ */
+function isObviousComment(line: string): boolean {
+  return OBVIOUS_PATTERNS.some((p) => p.test(line));
+}
+
+/**
+ * Extract comment lines from code content.
+ * Returns only single-line comments (// or #), not block comments or docstrings.
+ */
+function extractCommentLines(
+  content: string,
+  ext: string,
+): { line: string; lineNumber: number }[] {
+  const lines = content.split("\n");
+  const comments: { line: string; lineNumber: number }[] = [];
+  const usesHash = HASH_COMMENT_EXTENSIONS.has(ext);
+  let inBlockComment = false;
+  let inDocstring = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+
+    // Track block comments (/* ... */)
+    if (!inDocstring) {
+      if (trimmed.startsWith("/*")) {
+        inBlockComment = true;
+        // Single-line block comments
+        if (trimmed.includes("*/")) {
+          inBlockComment = false;
+        }
+        continue;
+      }
+      if (inBlockComment) {
+        if (trimmed.includes("*/")) {
+          inBlockComment = false;
+        }
+        continue;
+      }
+    }
+
+    // Track Python/Ruby docstrings
+    if (ext === ".py" || ext === ".rb") {
+      const tripleQuoteCount = (trimmed.match(/"""|'''/g) || []).length;
+      if (tripleQuoteCount === 1) {
+        inDocstring = !inDocstring;
+        continue;
+      }
+      if (inDocstring) continue;
+    }
+
+    // Single-line comments
+    if (trimmed.startsWith("//")) {
+      comments.push({ line: lines[i], lineNumber: i + 1 });
+    } else if (
+      usesHash &&
+      trimmed.startsWith("#") &&
+      !trimmed.startsWith("#!")
+    ) {
+      comments.push({ line: lines[i], lineNumber: i + 1 });
+    }
+  }
+
+  return comments;
+}
+
+/**
+ * Check code content for excessive or obvious comments.
+ *
+ * @param filePath - Path to the file being written/edited
+ * @param content - The full file content after the write/edit, OR the new content being written
+ * @param isNewContent - If true, content is only the new/changed portion (Edit newString)
+ */
+export function checkComments(
+  filePath: string,
+  content: string,
+  isNewContent = false,
+): CommentCheckResult {
+  const ext = getExtension(filePath);
+
+  // Skip non-checkable files
+  if (!CHECKABLE_EXTENSIONS.has(ext)) {
+    return {
+      hasExcessiveComments: false,
+      warning: "",
+      suspiciousCount: 0,
+      totalComments: 0,
+      examples: [],
+    };
+  }
+
+  const comments = extractCommentLines(content, ext);
+  const suspicious: { line: string; lineNumber: number }[] = [];
+
+  for (const comment of comments) {
+    // Skip legitimate comments
+    if (isLegitimateComment(comment.line)) continue;
+
+    // Flag obvious/unnecessary comments
+    if (isObviousComment(comment.line)) {
+      suspicious.push(comment);
+    }
+  }
+
+  // For full file content: also check comment density
+  // (>30% comment lines in non-test files is suspicious)
+  const totalLines = content
+    .split("\n")
+    .filter((l) => l.trim().length > 0).length;
+  const isTestFile =
+    filePath.includes(".test.") ||
+    filePath.includes(".spec.") ||
+    filePath.includes("__tests__") ||
+    filePath.includes("_test.");
+  const commentRatio = totalLines > 0 ? comments.length / totalLines : 0;
+  const highDensity =
+    !isNewContent && !isTestFile && commentRatio > 0.3 && comments.length > 5;
+
+  const hasExcessiveComments = suspicious.length >= 2 || highDensity;
+
+  if (!hasExcessiveComments) {
+    return {
+      hasExcessiveComments: false,
+      warning: "",
+      suspiciousCount: suspicious.length,
+      totalComments: comments.length,
+      examples: [],
+    };
+  }
+
+  // Build warning message
+  const examples = suspicious.slice(0, 5).map((s) => s.line.trim());
+  const parts: string[] = [
+    `[aide:comment-checker] Detected ${suspicious.length} potentially unnecessary comment${suspicious.length === 1 ? "" : "s"} in ${filePath}.`,
+  ];
+
+  if (highDensity) {
+    parts.push(
+      `Comment density is ${Math.round(commentRatio * 100)}% (${comments.length}/${totalLines} non-empty lines).`,
+    );
+  }
+
+  if (examples.length > 0) {
+    parts.push("Examples:");
+    for (const ex of examples) {
+      parts.push(`  ${ex}`);
+    }
+  }
+
+  parts.push("");
+  parts.push(
+    "Clean code should be self-documenting. Remove comments that merely restate the code. " +
+      "Keep only: TODOs, complex logic explanations, non-obvious workarounds, API docs, and regulatory/compliance notes.",
+  );
+
+  return {
+    hasExcessiveComments: true,
+    warning: parts.join("\n"),
+    suspiciousCount: suspicious.length,
+    totalComments: comments.length,
+    examples,
+  };
+}
+
+/**
+ * Determine if a tool call is a write/edit that should be checked.
+ * Returns the file path if checkable, null otherwise.
+ */
+export function getCheckableFilePath(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+): string | null {
+  const toolLower = toolName.toLowerCase();
+  if (
+    toolLower !== "write" &&
+    toolLower !== "edit" &&
+    toolLower !== "multiedit" &&
+    toolLower !== "notebookedit"
+  ) {
+    return null;
+  }
+
+  const filePath =
+    (toolInput.filePath as string) ||
+    (toolInput.file_path as string) ||
+    (toolInput.path as string);
+
+  if (!filePath) return null;
+
+  const ext = getExtension(filePath);
+  if (!CHECKABLE_EXTENSIONS.has(ext)) return null;
+
+  return filePath;
+}
+
+/**
+ * Get the content to check from a tool's input.
+ * For Write: the full content. For Edit: the newString.
+ * Returns [content, isNewContent] tuple.
+ */
+export function getContentToCheck(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+): [string, boolean] | null {
+  const toolLower = toolName.toLowerCase();
+
+  if (toolLower === "write") {
+    const content = toolInput.content as string;
+    return content ? [content, false] : null;
+  }
+
+  if (toolLower === "edit") {
+    const newString = (toolInput.newString || toolInput.new_string) as string;
+    return newString ? [newString, true] : null;
+  }
+
+  if (toolLower === "multiedit") {
+    // Concatenate all new strings for checking
+    const edits = toolInput.edits as
+      | Array<{ new_string?: string; newString?: string }>
+      | undefined;
+    if (!edits || edits.length === 0) return null;
+    const combined = edits
+      .map((e) => e.new_string || e.newString || "")
+      .join("\n");
+    return combined ? [combined, true] : null;
+  }
+
+  return null;
+}
+
+debug(SOURCE, "Comment checker core loaded");

package/src/core/persistence-logic.ts

@@ -11,6 +11,10 @@ import {
   MAX_PERSISTENCE_ITERATIONS,
   type PersistenceMode,
 } from "./types.js";
+import { fetchTodosFromAide, checkTodos } from "./todo-checker.js";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "persistence-logic";
 
 /**
  * Check if a persistence mode is active
@@ -27,32 +31,49 @@ export function getActiveMode(
 }
 
 /**
- * Build a reinforcement message for the persistence mode
+ * Build a reinforcement message for the persistence mode.
+ * If a todo summary is provided, it's appended to give the agent
+ * precise visibility into which tasks are still incomplete.
  */
-export function buildReinforcement(mode: string, iteration: number): string {
+export function buildReinforcement(
+  mode: string,
+  iteration: number,
+  todoSummary?: string,
+): string {
   if (iteration > MAX_PERSISTENCE_ITERATIONS) {
     return `Maximum reinforcements (${MAX_PERSISTENCE_ITERATIONS}) reached. Releasing ${mode} mode.`;
   }
 
-  return `**${mode.toUpperCase()} MODE ACTIVE** (iteration ${iteration}/${MAX_PERSISTENCE_ITERATIONS})
-
-You attempted to stop but work may be incomplete.
+  const parts: string[] = [
+    `**${mode.toUpperCase()} MODE ACTIVE** (iteration ${iteration}/${MAX_PERSISTENCE_ITERATIONS})`,
+    "",
+    "You attempted to stop but work may be incomplete.",
+  ];
 
-Before stopping, verify:
-- All tasks in your todo list are marked complete
-- All requested functionality is implemented
-- Tests pass (if applicable)
-- No errors remain unaddressed
+  if (todoSummary) {
+    parts.push("");
+    parts.push(todoSummary);
+  } else {
+    parts.push("");
+    parts.push("Before stopping, verify:");
+    parts.push("- All tasks in your todo list are marked complete");
+    parts.push("- All requested functionality is implemented");
+    parts.push("- Tests pass (if applicable)");
+    parts.push("- No errors remain unaddressed");
+  }
 
-If ANY item is incomplete, CONTINUE WORKING.
+  parts.push("");
+  parts.push("If ANY item is incomplete, CONTINUE WORKING.");
 
-Use TaskList to check your progress.`;
+  return parts.join("\n");
 }
 
 /**
  * Check persistence and return block decision.
  *
  * Returns null if stop is allowed, or { reason } if stop should be blocked.
+ * When a persistence mode is active and todos exist, the reinforcement
+ * message includes the specific incomplete tasks.
  */
 export function checkPersistence(
   binary: string,
@@ -73,5 +94,21 @@ export function checkPersistence(
     return null;
   }
 
-  return { reason: buildReinforcement(mode, iteration) };
+  // Fetch todos and build a specific continuation message if incomplete tasks exist
+  let todoSummary: string | undefined;
+  try {
+    const todos = fetchTodosFromAide(binary, cwd);
+    const todoResult = checkTodos(todos);
+    if (todoResult.hasIncomplete) {
+      todoSummary = todoResult.message;
+      debug(
+        SOURCE,
+        `Found ${todoResult.incompleteCount} incomplete todos for persistence reinforcement`,
+      );
+    }
+  } catch (err) {
+    debug(SOURCE, `Failed to fetch todos for persistence (non-fatal): ${err}`);
+  }
+
+  return { reason: buildReinforcement(mode, iteration, todoSummary) };
 }

package/src/core/todo-checker.ts

@@ -0,0 +1,138 @@
+/**
+ * Todo continuation checker — platform-agnostic.
+ *
+ * Reads the agent's todo list and checks for incomplete items.
+ * Used to enhance persistence-logic.ts with precise todo-aware blocking:
+ * instead of a generic "verify your work is complete", we list the
+ * specific incomplete todos.
+ *
+ * For Claude Code: reads todos from the transcript (TodoWrite tool outputs)
+ *   or from aide task list.
+ * For OpenCode: reads todos via client.session.todo() API.
+ *
+ * This module provides the platform-agnostic core. Platform hooks
+ * call it with however they obtained the todo list.
+ */
+
+import { runAide } from "./aide-client.js";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "todo-checker";
+
+export interface TodoItem {
+  id: string;
+  content: string;
+  status: "pending" | "in_progress" | "completed" | "cancelled";
+  priority?: string;
+}
+
+export interface TodoCheckResult {
+  /** Whether there are incomplete todos */
+  hasIncomplete: boolean;
+  /** Number of incomplete items */
+  incompleteCount: number;
+  /** Total items */
+  totalCount: number;
+  /** The incomplete items */
+  incompleteItems: TodoItem[];
+  /** Formatted message for injection */
+  message: string;
+}
+
+/**
+ * Check a list of todos for incomplete items and build a continuation message.
+ */
+export function checkTodos(todos: TodoItem[]): TodoCheckResult {
+  if (!todos || todos.length === 0) {
+    return {
+      hasIncomplete: false,
+      incompleteCount: 0,
+      totalCount: 0,
+      incompleteItems: [],
+      message: "",
+    };
+  }
+
+  const incomplete = todos.filter(
+    (t) => t.status !== "completed" && t.status !== "cancelled",
+  );
+
+  if (incomplete.length === 0) {
+    return {
+      hasIncomplete: false,
+      incompleteCount: 0,
+      totalCount: todos.length,
+      incompleteItems: [],
+      message: "",
+    };
+  }
+
+  const completedCount = todos.length - incomplete.length;
+  const lines: string[] = [
+    `**TODO CONTINUATION** — ${incomplete.length} of ${todos.length} tasks incomplete (${completedCount} done)`,
+    "",
+    "Remaining tasks:",
+  ];
+
+  for (const item of incomplete) {
+    const statusIcon = item.status === "in_progress" ? ">" : " ";
+    lines.push(`  [${statusIcon}] ${item.content}`);
+  }
+
+  lines.push("");
+  lines.push(
+    "You stopped but have unfinished tasks. Continue working on the next incomplete item.",
+  );
+
+  return {
+    hasIncomplete: true,
+    incompleteCount: incomplete.length,
+    totalCount: todos.length,
+    incompleteItems: incomplete,
+    message: lines.join("\n"),
+  };
+}
+
+/**
+ * Parse todo items from aide task list output.
+ *
+ * Output format from `aide task list`:
+ *   [status] id: content
+ *   e.g.: [pending] abc123: Implement feature X
+ */
+export function parseTodosFromAide(output: string): TodoItem[] {
+  const todos: TodoItem[] = [];
+  const lines = output.split("\n");
+
+  for (const line of lines) {
+    const match = line.match(
+      /\[(pending|in_progress|completed|cancelled)\]\s+(\S+):\s+(.+)/,
+    );
+    if (match) {
+      todos.push({
+        status: match[1] as TodoItem["status"],
+        id: match[2],
+        content: match[3].trim(),
+      });
+    }
+  }
+
+  return todos;
+}
+
+/**
+ * Fetch todos from aide binary task list.
+ * Returns empty array if binary unavailable or no tasks.
+ */
+export function fetchTodosFromAide(binary: string, cwd: string): TodoItem[] {
+  try {
+    const output = runAide(binary, cwd, ["task", "list"], { timeout: 5000 });
+    if (!output) return [];
+    return parseTodosFromAide(output);
+  } catch (err) {
+    debug(SOURCE, `Failed to fetch todos from aide: ${err}`);
+    return [];
+  }
+}
+
+debug(SOURCE, "Todo checker core loaded");

package/src/core/write-guard.ts

@@ -0,0 +1,105 @@
+/**
+ * Write-existing-file guard logic — platform-agnostic.
+ *
+ * Prevents the Write tool from being used on files that already exist.
+ * When a file exists, the agent should use Edit instead, which is surgical
+ * and preserves content the agent may have forgotten about.
+ *
+ * Using Write on existing files is one of the most common destructive
+ * failure modes: the agent rewrites the entire file from memory and
+ * drops functions, imports, or sections it forgot about.
+ *
+ * Used by both Claude Code hooks (PreToolUse) and OpenCode plugin (tool.execute.before).
+ */
+
+import { existsSync } from "fs";
+import { resolve, isAbsolute, normalize } from "path";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "write-guard";
+
+/** Paths that are allowed to be overwritten via Write even if they exist */
+const WRITE_ALLOWED_PATTERNS = [
+  // aide internal state files
+  /\/.aide\//,
+  // dotfiles that are typically fully rewritten
+  /\/\.[^/]+rc$/,
+  /\/\.env/,
+  /\/\.gitignore$/,
+  // Lock files (often fully generated)
+  /\/package-lock\.json$/,
+  /\/bun\.lock$/,
+  /\/yarn\.lock$/,
+  /\/pnpm-lock\.yaml$/,
+  /\/go\.sum$/,
+  /\/Cargo\.lock$/,
+  // Generated config that's typically overwritten whole
+  /\/tsconfig\.json$/,
+];
+
+export interface WriteGuardResult {
+  /** Whether the Write should be allowed */
+  allowed: boolean;
+  /** Message explaining why the Write was blocked */
+  message?: string;
+}
+
+/**
+ * Check whether a Write tool call should be allowed.
+ *
+ * @param toolName - The tool being called (only "Write" is checked)
+ * @param toolInput - The tool's input arguments
+ * @param cwd - Working directory to resolve relative paths
+ * @returns Whether the write is allowed and an explanatory message if blocked
+ */
+export function checkWriteGuard(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  cwd: string,
+): WriteGuardResult {
+  // Only guard the Write tool
+  if (toolName.toLowerCase() !== "write") {
+    return { allowed: true };
+  }
+
+  const filePath =
+    (toolInput.filePath as string) ||
+    (toolInput.file_path as string) ||
+    (toolInput.path as string);
+
+  if (!filePath) {
+    return { allowed: true };
+  }
+
+  // Resolve the full path
+  const resolvedPath = normalize(
+    isAbsolute(filePath) ? filePath : resolve(cwd, filePath),
+  );
+
+  // Check if file exists
+  if (!existsSync(resolvedPath)) {
+    // File doesn't exist — Write is the correct tool for new files
+    return { allowed: true };
+  }
+
+  // Check if this path is in the allowed-overwrite list
+  for (const pattern of WRITE_ALLOWED_PATTERNS) {
+    if (pattern.test(resolvedPath)) {
+      debug(
+        SOURCE,
+        `Allowing Write to existing file (matches allow pattern): ${filePath}`,
+      );
+      return { allowed: true };
+    }
+  }
+
+  // File exists and isn't in the allowed list — block with guidance
+  debug(SOURCE, `Blocking Write to existing file: ${filePath}`);
+  return {
+    allowed: false,
+    message:
+      `File "${filePath}" already exists. Use the Edit tool instead of Write to make changes to existing files. ` +
+      `The Edit tool makes surgical replacements and preserves content you haven't explicitly changed. ` +
+      `Write overwrites the entire file, which risks losing code you forgot to include.`,
+  };
+}

package/src/opencode/hooks.ts

@@ -45,6 +45,12 @@ import {
 import { trackToolUse, updateToolStats } from "../core/tool-tracking.js";
 import { evaluateToolUse, isToolDenied } from "../core/tool-enforcement.js";
 import { checkPersistence, getActiveMode } from "../core/persistence-logic.js";
+import { checkWriteGuard } from "../core/write-guard.js";
+import {
+  checkComments,
+  getCheckableFilePath,
+  getContentToCheck,
+} from "../core/comment-checker.js";
 import { getState, setState } from "../core/aide-client.js";
 import { saveStateSnapshot } from "../core/pre-compact-logic.js";
 import { cleanupSession } from "../core/cleanup.js";
@@ -395,6 +401,28 @@ function createToolBeforeHandler(
   output: { args: Record<string, unknown> },
 ) => Promise<void> {
   return async (input, _output) => {
+    // Write guard: block Write tool on existing files
+    try {
+      const guardResult = checkWriteGuard(
+        input.tool,
+        _output.args || {},
+        state.cwd,
+      );
+      if (!guardResult.allowed) {
+        debug(SOURCE, `Write guard blocked: ${guardResult.message}`);
+        throw new Error(guardResult.message);
+      }
+    } catch (err) {
+      // Re-throw write guard errors (they're intentional blocks)
+      if (
+        err instanceof Error &&
+        err.message?.includes("already exists. Use the Edit tool")
+      ) {
+        throw err;
+      }
+      debug(SOURCE, `Write guard check failed (non-fatal): ${err}`);
+    }
+
     // Tool enforcement: check agent restrictions
     // OpenCode doesn't have named agent types like Claude Code, but
     // we still evaluate in case agent_name is passed via tool args or state
@@ -410,8 +438,6 @@ function createToolBeforeHandler(
             SOURCE,
             `Tool ${input.tool} denied for agent ${agentName}: ${enforcement.denyMessage}`,
           );
-          // OpenCode doesn't support blocking tool execution from hooks yet,
-          // but we log the violation for visibility
         }
       }
     } catch (err) {
@@ -443,6 +469,31 @@ function createToolAfterHandler(
     if (!state.binary) return;
 
     updateToolStats(state.binary, state.cwd, input.tool, input.sessionID);
+
+    // Comment checker: detect excessive comments in Write/Edit output
+    try {
+      const toolArgs = (_output.metadata?.args || {}) as Record<
+        string,
+        unknown
+      >;
+      const filePath = getCheckableFilePath(input.tool, toolArgs);
+      if (filePath) {
+        const contentResult = getContentToCheck(input.tool, toolArgs);
+        if (contentResult) {
+          const [content, isNewContent] = contentResult;
+          const result = checkComments(filePath, content, isNewContent);
+          if (result.hasExcessiveComments) {
+            debug(
+              SOURCE,
+              `Comment checker: ${result.suspiciousCount} suspicious comments in ${filePath}`,
+            );
+            _output.output += "\n\n" + result.warning;
+          }
+        }
+      }
+    } catch (err) {
+      debug(SOURCE, `Comment checker failed (non-fatal): ${err}`);
+    }
   };
 }
 

package/src/opencode/index.ts

@@ -16,7 +16,7 @@
  *   "mcp": {
  *     "aide": {
  *       "type": "local",
- *       "command": ["npx", "-y", "-p", "@jmylchreest/aide-plugin", "aide-wrapper", "mcp"],
+ *       "command": ["npx", "-y", "@jmylchreest/aide-plugin", "mcp"],
  *       "environment": { "AIDE_CODE_WATCH": "1", "AIDE_CODE_WATCH_DELAY": "30s" },
  *       "enabled": true
  *     }