opencode-ai-cli 1.17.0

package/src/subagent/agents/reviewer.md

@@ -0,0 +1,35 @@
+---
+name: reviewer
+description: Code review specialist for quality and security analysis
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+---
+
+You are a senior code reviewer. Analyze code for quality, security, and maintainability.
+
+Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
+Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
+
+Strategy:
+1. Run `git diff` to see recent changes (if applicable)
+2. Read the modified files
+3. Check for bugs, security issues, code smells
+
+Output format:
+
+## Files Reviewed
+- `path/to/file.ts` (lines X-Y)
+
+## Critical (must fix)
+- `file.ts:42` - Issue description
+
+## Warnings (should fix)
+- `file.ts:100` - Issue description
+
+## Suggestions (consider)
+- `file.ts:150` - Improvement idea
+
+## Summary
+Overall assessment in 2-3 sentences.
+
+Be specific with file paths and line numbers.

package/src/subagent/agents/scout.md

@@ -0,0 +1,49 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff to other agents
+tools: read_file, grep, find, ls
+openai_model: gpt-4o-mini
+gemini_model: gemini-2.5-flash
+---
+
+You are a scout. Investigate the codebase and return structured findings that another agent can use without re-reading everything.
+
+Your output will be passed to an agent who has NOT seen the files you explored.
+
+Default thoroughness is repository-aware medium: map the project shape first, then inspect the files relevant to the user's request. Do not stop after listing files.
+
+Strategy:
+1. EXTREME SPEED: Do NOT attempt to read every file in the project. You must be fast.
+2. Use `ls` and `find` to locate the 1 or 2 files most relevant to the user's request.
+3. Read ONLY those 1 or 2 critical files using `read_file`.
+4. DO NOT follow deep import chains. If you see an import, note it, but do not read the imported file unless absolutely necessary.
+5. SURGICAL READS: Request only the line ranges you need. Do NOT dump entire files.
+6. MAXIMUM 3 READS: You are strictly limited to reading a maximum of 3 files per scout mission.
+7. Once you have the gist of the architecture and the relevant file, immediately output your report.
+
+Output format:
+
+## Files Retrieved
+List with exact line ranges:
+1. `path/to/file.ts` (lines 10-50) - Description of what's here
+2. `path/to/other.ts` (lines 100-150) - Description
+3. ...
+
+## Key Snippets
+ONLY include critical types, interfaces, or logic (MAX 20 lines per snippet):
+
+```typescript
+// path/to/file.ts lines 10-25
+interface Example {
+  ...
+}
+```
+
+## Architecture
+Brief explanation (2-3 sentences) of how the pieces connect.
+
+## Start Here
+Which file to look at first and why.
+
+## Gaps
+Anything relevant you could not verify.

package/src/subagent/agents/worker.md

@@ -0,0 +1,29 @@
+---
+name: worker
+description: General-purpose subagent with full capabilities, isolated context
+model: claude-sonnet-4-5
+---
+
+You are a worker agent with full capabilities. You operate in an isolated context window to handle delegated tasks without polluting the main conversation.
+
+Work autonomously to complete the assigned task. Use all available tools as needed.
+
+- MANDATORY: When using mutating tools (`write_file`, `edit_file`, `bash`), you MUST explicitly describe your action.
+  - For `edit_file`, clearly state what is being removed and what is being added, and identify the affected lines.
+  - For `write_file`, state that you are creating/overwriting a file at a specific path.
+  - For `bash`, state exactly what command you are running and its purpose.
+
+Output format when finished:
+
+## Completed
+What was done.
+
+## Files Changed
+- `path/to/file.ts` - what changed
+
+## Notes (if any)
+Anything the main agent should know.
+
+If handing off to another agent (e.g. reviewer), include:
+- Exact file paths changed
+- Key functions/types touched (short list)

package/src/subagent/agents.ts

@@ -0,0 +1,89 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  tools?: string[];
+  model?: string;
+  openai_model?: string;
+  gemini_model?: string;
+  systemPrompt: string;
+  source: "user" | "project";
+  filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+  agents: AgentConfig[];
+  projectAgentsDir: string | null;
+}
+
+// Simple built-in frontmatter parser
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+  const parts = content.split("---");
+  if (parts.length < 3) return { frontmatter: {}, body: content };
+
+  const fmStr = parts[1];
+  const body = parts.slice(2).join("---").trim();
+  const frontmatter: Record<string, string> = {};
+
+  fmStr.split("\n").forEach((line) => {
+    const [key, ...rest] = line.split(":");
+    if (key && rest.length) frontmatter[key.trim()] = rest.join(":").trim();
+  });
+
+  return { frontmatter, body };
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+  const agents: AgentConfig[] = [];
+  if (!fs.existsSync(dir)) return agents;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return agents;
+  }
+
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    const filePath = path.join(dir, entry.name);
+    let content: string;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    if (!frontmatter.name || !frontmatter.description) continue;
+
+    const tools = frontmatter.tools
+      ?.split(",")
+      .map((t: string) => t.trim())
+      .filter(Boolean);
+
+    agents.push({
+      name: frontmatter.name,
+      description: frontmatter.description,
+      tools: tools && tools.length > 0 ? tools : undefined,
+      model: frontmatter.model,
+      openai_model: frontmatter.openai_model,
+      gemini_model: frontmatter.gemini_model,
+      systemPrompt: body,
+      source,
+      filePath,
+    });
+  }
+  return agents;
+}
+
+export function discoverAgents(cwd: string): AgentDiscoveryResult {
+  const localAgentsDir = path.join(cwd, "src", "subagent", "agents");
+  const agents = loadAgentsFromDir(localAgentsDir, "project");
+
+  return { agents, projectAgentsDir: localAgentsDir };
+}

package/src/subagent/index.ts

@@ -0,0 +1,224 @@
+import { runAgentLoop } from "../engine/agentLoop";
+import { AuthStorage } from "../core/auth-storage";
+import { getAllTools } from "../tools/index";
+import { discoverAgents, AgentConfig } from "./agents";
+import chalk from "chalk";
+import { AgentMessage } from "../engine/type";
+import { AgentTool, AgentToolResult } from "../types";
+
+async function runSingleAgent(
+  agent: AgentConfig,
+  task: string,
+  cwd: string,
+): Promise<{ output: string; usage: { promptTokens: number; completionTokens: number; totalTokens: number } }> {
+  const activeProvider = AuthStorage.getAuthenticatedProviders()[0] ?? "openai";
+  const activeKey = AuthStorage.getApiKey(activeProvider);
+
+  if (!activeKey) throw new Error("No API key available for subagent.");
+
+  // DYNAMIC MODEL SELECTION
+  let selectedModel = agent.model; // global fallback
+  if (activeProvider === "openai" && agent.openai_model) {
+    selectedModel = agent.openai_model;
+  } else if (activeProvider === "gemini" && agent.gemini_model) {
+    selectedModel = agent.gemini_model;
+  }
+
+  const allAvailableTools = getAllTools();
+  const toolAliases: Record<string, string> = {
+    read: "read_file",
+  };
+  const requestedToolNames = agent.tools?.map(
+    (toolName) => toolAliases[toolName] ?? toolName,
+  );
+  const agentTools =
+    requestedToolNames && requestedToolNames.length > 0
+      ? allAvailableTools.filter((t) => requestedToolNames.includes(t.name))
+      : allAvailableTools;
+
+  const initialMessages: AgentMessage[] = [
+    { role: "system", content: agent.systemPrompt },
+    { role: "user", content: task },
+  ];
+
+  const results = await runAgentLoop(
+    initialMessages,
+    {
+      cwd: cwd,
+      messages: [],
+      activeToolNames: agentTools.map((t) => t.name),
+      tools: agentTools,
+    },
+    {
+      provider: activeProvider,
+      apiKey: activeKey,
+      model: selectedModel,
+      maxTurns: 15,
+    },
+    (event) => {
+      if (event.type === "tool_execution_start") {
+        console.log(
+          chalk.dim(`  [${agent.name}] running ${event.toolName}...`),
+        );
+      }
+    },
+  );
+
+  const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+  results.forEach((msg) => {
+    if (msg.role === "assistant" && msg.usage) {
+      usage.promptTokens += msg.usage.promptTokens;
+      usage.completionTokens += msg.usage.completionTokens;
+      usage.totalTokens += msg.usage.totalTokens;
+    }
+  });
+
+  const lastMessage = results[results.length - 1];
+  let output = "(no output)";
+  if (lastMessage && lastMessage.role === "assistant") {
+    output = lastMessage.content
+      .filter((p: any) => p.type === "text")
+      .map((p: any) => p.text)
+      .join("");
+  }
+  return { output, usage };
+}
+
+export const nativeSubagentTool: AgentTool = {
+  name: "subagent",
+  label: "Subagent",
+  description:
+    "Delegate tasks to specialized subagents (scout, planner, worker). Supports single {agent, task}, chain [{agent, task...}], or parallel tasks [{agent, task}].",
+  schema: {
+    type: "function",
+    function: {
+      name: "subagent",
+      description:
+        "Delegate to subagents. Provide exactly one mode: agent/task (single), chain (array), or tasks (parallel).",
+      parameters: {
+        type: "object",
+        properties: {
+          agent: { type: "string", description: "Agent name (Single mode)" },
+          task: { type: "string", description: "Task (Single mode)" },
+          chain: {
+            type: "array",
+            description: "Sequential chain of agents",
+            items: {
+              type: "object",
+              properties: {
+                agent: { type: "string" },
+                task: {
+                  type: "string",
+                  description: "Use {previous} to inject previous step output.",
+                },
+              },
+              required: ["agent", "task"],
+            },
+          },
+          tasks: {
+            type: "array",
+            description: "Parallel tasks",
+            items: {
+              type: "object",
+              properties: {
+                agent: { type: "string" },
+                task: { type: "string" },
+              },
+              required: ["agent", "task"],
+            },
+          },
+        },
+      },
+    },
+  },
+  execute: async (args: any): Promise<AgentToolResult> => {
+    const cwd = process.cwd();
+    const { agents } = discoverAgents(cwd);
+
+    // CHAIN MODE
+    if (args.chain && args.chain.length > 0) {
+      console.log(
+        chalk.bold.blue(
+          `\n[Sub-Agent] Starting Chain workflow (${args.chain.length} steps)...`,
+        ),
+      );
+      let previousOutput = "";
+      let finalReport = "";
+      const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+
+      for (let i = 0; i < args.chain.length; i++) {
+        const step = args.chain[i];
+        const agent = agents.find((a) => a.name === step.agent);
+        if (!agent) throw new Error(`Agent ${step.agent} not found.`);
+
+        const taskWithContext = step.task.replace(
+          /\{previous\}/g,
+          previousOutput,
+        );
+        console.log(chalk.blue(`-> Step ${i + 1}: ${step.agent}`));
+
+        const { output, usage } = await runSingleAgent(agent, taskWithContext, cwd);
+        previousOutput = output;
+        totalUsage.promptTokens += usage.promptTokens;
+        totalUsage.completionTokens += usage.completionTokens;
+        totalUsage.totalTokens += usage.totalTokens;
+        finalReport += `### Step ${i + 1}: ${step.agent}\n${previousOutput}\n\n`;
+      }
+      return {
+        content: [{ type: "text", text: finalReport }],
+        terminate: false,
+        usage: totalUsage,
+      };
+    }
+
+    // PARALLEL MODE
+    if (args.tasks && args.tasks.length > 0) {
+      console.log(
+        chalk.bold.blue(
+          `\n[Sub-Agent] Starting Parallel workflow (${args.tasks.length} tasks)...`,
+        ),
+      );
+      const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+      const promises = args.tasks.map(async (t: any) => {
+        const agent = agents.find((a) => a.name === t.agent);
+        if (!agent) return `### ${t.agent} (NOT FOUND)`;
+        try {
+          const { output, usage } = await runSingleAgent(agent, t.task, cwd);
+          totalUsage.promptTokens += usage.promptTokens;
+          totalUsage.completionTokens += usage.completionTokens;
+          totalUsage.totalTokens += usage.totalTokens;
+          return `### ${t.agent}\n${output}`;
+        } catch (error: any) {
+          console.log(chalk.red(`  [${t.agent}] failed: ${error.message}`));
+          return `### ${t.agent} (FAILED)\nError: ${error.message}`;
+        }
+      });
+
+      const results = await Promise.all(promises);
+      return {
+        content: [{ type: "text", text: results.join("\n\n") }],
+        terminate: false,
+        usage: totalUsage,
+      };
+    }
+
+    // SINGLE MODE
+    if (args.agent && args.task) {
+      console.log(
+        chalk.bold.blue(`\n[Sub-Agent] Starting Single task: ${args.agent}...`),
+      );
+      const agent = agents.find((a) => a.name === args.agent);
+      if (!agent)
+        return {
+          content: [{ type: "text", text: `Agent ${args.agent} not found.` }],
+        };
+
+      const { output, usage } = await runSingleAgent(agent, args.task, cwd);
+      return { content: [{ type: "text", text: output }], terminate: false, usage };
+    }
+
+    return {
+      content: [{ type: "text", text: "Invalid subagent parameters." }],
+    };
+  },
+};

package/src/subagent/prompts/implement-and-review.md

@@ -0,0 +1,10 @@
+---
+description: Worker implements, reviewer reviews, worker applies feedback
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "worker" agent to implement: $@
+2. Then, use the "reviewer" agent to review the implementation from the previous step (use {previous} placeholder)
+3. Finally, use the "worker" agent to apply the feedback from the review (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

package/src/subagent/prompts/implement.md

@@ -0,0 +1,10 @@
+---
+description: Full implementation workflow - scout gathers context, planner creates plan, worker implements
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "scout" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+3. Finally, use the "worker" agent to implement the plan from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}.

package/src/subagent/prompts/scout-and-plan.md

@@ -0,0 +1,9 @@
+---
+description: Scout gathers context, planner creates implementation plan (no implementation)
+---
+Use the subagent tool with the chain parameter to execute this workflow:
+
+1. First, use the "scout" agent to find all code relevant to: $@
+2. Then, use the "planner" agent to create an implementation plan for "$@" using the context from the previous step (use {previous} placeholder)
+
+Execute this as a chain, passing output between steps via {previous}. Do NOT implement - just return the plan.

package/src/tools/bash-tool.ts

@@ -0,0 +1,44 @@
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import { AgentTool, AgentToolResult } from "../types";
+
+const execAsync = promisify(exec);
+
+export const bashTool: AgentTool = {
+  name: "bash",
+  label: "Bash Command",
+  description: "Execute a bash command in the terminal. Use this for installing packages, running tests, or git operations.",
+  schema: {
+    type: "function",
+    function: {
+      name: "bash",
+      description: "Execute a shell command.",
+      parameters: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: "The bash command to execute.",
+          },
+        },
+        required: ["command"],
+      },
+    },
+  },
+  execute: async (args: any): Promise<AgentToolResult> => {
+    try {
+      const { stdout, stderr } = await execAsync(args.command, { cwd: process.cwd() });
+      const output = stdout + (stderr ? `\nErrors:\n${stderr}` : "");
+      return {
+        content: [{ type: "text", text: output.trim() || "Command executed successfully with no output." }],
+        terminate: false,
+      };
+    } catch (error: any) {
+      return {
+        content: [{ type: "text", text: `Command failed: ${error.message}\n${error.stdout || ""}\n${error.stderr || ""}` }],
+        terminate: false,
+      };
+    }
+  },
+};

package/src/tools/edit-tool.ts

@@ -0,0 +1,85 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { AgentTool, AgentToolResult } from "../types";
+
+export const editTool: AgentTool = {
+  name: "edit_file",
+  label: "Edit File",
+  description:
+    "Surgically replace text in an existing file. Provide the EXACT old string you want to replace, and the EXACT new string.",
+  schema: {
+    type: "function",
+    function: {
+      name: "edit_file",
+      description: "Replace a specific string of text within a file.",
+      parameters: {
+        type: "object",
+        properties: {
+          file_path: {
+            type: "string",
+            description: "The path to the file to edit.",
+          },
+          old_string: {
+            type: "string",
+            description:
+              "The EXACT literal text currently in the file that you want to replace.",
+          },
+          new_string: {
+            type: "string",
+            description: "The literal text to replace it with.",
+          },
+        },
+        required: ["file_path", "old_string", "new_string"],
+      },
+    },
+  },
+  execute: async (args: any): Promise<AgentToolResult> => {
+    try {
+      const fullPath = path.resolve(process.cwd(), args.file_path);
+      const content = await fs.readFile(fullPath, "utf-8");
+
+      if (!content.includes(args.old_string)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Edit failed: Could not find the exact 'old_string' in ${args.file_path}. Make sure whitespace and indentation match perfectly.`,
+            },
+          ],
+          terminate: false,
+        };
+      }
+
+      // Check for multiple occurrences to warn the agent
+      const occurrences = content.split(args.old_string).length - 1;
+      if (occurrences > 1) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Edit failed: 'old_string' was found ${occurrences} times. Your old_string must be unique to avoid accidental replacements.`,
+            },
+          ],
+          terminate: false,
+        };
+      }
+
+      const newContent = content.replace(args.old_string, args.new_string);
+      await fs.writeFile(fullPath, newContent, "utf-8");
+
+      return {
+        content: [
+          { type: "text", text: `Successfully edited ${args.file_path}` },
+        ],
+        terminate: false,
+      };
+    } catch (error: any) {
+      return {
+        content: [
+          { type: "text", text: `Failed to edit file: ${error.message}` },
+        ],
+        terminate: false,
+      };
+    }
+  },
+};

package/src/tools/find-tool.ts

@@ -0,0 +1,81 @@
+import { glob } from "glob";
+import { AgentTool } from "../types";
+
+export const findTool: AgentTool = {
+  name: "find",
+  label: "find files",
+  description: "The BEST tool for recursively finding files by extension (e.g. '**/*.ts') or searching deep directory trees. Always use this instead of 'ls' when looking for specific files.",
+  schema: {
+    type: "function",
+    function: {
+      name: "find",
+      description:
+        "The BEST tool for recursively finding files by extension (e.g. '**/*.ts') or searching deep directory trees. Always use this instead of 'ls' when looking for specific files.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: {
+            type: "string",
+            description:
+              "Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.ts'",
+          },
+          dirPath: {
+            type: "string",
+            description:
+              "Directory to search in (default: current directory '.')",
+          },
+        },
+        required: ["pattern"],
+      },
+    },
+  },
+
+  execute: async (args: any) => {
+    try {
+      const pattern = args.pattern;
+      const targetPath = args.dirPath || ".";
+
+      console.log(
+        `\n system runing 'find for pattern ${pattern} in ${targetPath}`,
+      );
+
+      const files = await glob(pattern, {
+        cwd: targetPath,
+        ignore: ["**/node_modules/**", "**/.git/**"],
+        nodir: true, // Only return files not the folders
+      });
+
+      if (files.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No files found by matching this pattern ${pattern}`,
+            },
+          ],
+          details: {},
+        };
+      }
+
+      const limit = 100;
+
+      let output = files.slice(0, limit).join("\n");
+
+      if (files.length > limit) {
+        output += `\n\n[Warning: Output truncated. ${files.length} total results found, showing first ${limit}.]`;
+      }
+      return {
+        content: [{ type: "text", text: output }],
+        details: {},
+      };
+    } catch (error: any) {
+      console.error(`find tool error ${error.message}`);
+      return {
+        content: [
+          { type: "text", text: `Failed to excuate find: ${error.message}` },
+        ],
+        details: {},
+      };
+    }
+  },
+};