claude-all-hands 1.0.39 → 1.0.41

package/.claude/commands/address-pr-review.md

@@ -0,0 +1,28 @@
+---
+description: Address PR review comments
+---
+
+<objective>
+Process unresolved PR review comments for the current feature branch, prioritize them, and address each based on user direction.
+</objective>
+
+<process>
+1. Read all unresolved review comments from the current feature branch's PR
+2. Group any duplicative review feedback
+3. Order concerns by priority using P1/P2/P3 indicators based on review indicators and your judgement
+4. For EACH grouped concern, use AskUserQuestion to present it separately:
+   - Include P<N> priority indicator
+   - Describe the concern and proposed resolution action
+   - Offer multichoice options: approve, decline, or "say something" (provide specific instructions)
+5. Execute on user's feedback for each concern
+6. Commit and push changes with an inferred commit message
+7. Resolve PR comments related to addressed issues (skip declined concerns)
+8. If any comments remain unresolved, briefly summarize and ask user what to do next
+</process>
+
+<success_criteria>
+- Each concern presented as separate AskUserQuestion with multichoice options
+- Only approved/instructed concerns addressed
+- Declined concerns left untouched in PR
+- Changes committed and pushed
+</success_criteria>

package/.claude/envoy/package-lock.json

@@ -10,6 +10,7 @@
       "hasInstallScript": true,
       "dependencies": {
         "@google/genai": "^0.14.0",
+        "@opencode-ai/sdk": "^1.1.14",
         "@upstash/context7-sdk": "^0.3.0",
         "@visheratin/tokenizers-node": "0.1.5",
         "@visheratin/web-ai-node": "^1.4.5",
@@ -498,6 +499,12 @@
         "node": ">=18.0.0"
       }
     },
+    "node_modules/@opencode-ai/sdk": {
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/@opencode-ai/sdk/-/sdk-1.1.14.tgz",
+      "integrity": "sha512-PJFu2QPxnOk0VZzlPm+IxhD1wSA41PJyCG6gkxAMI767gfAO96A0ukJJN7VK/gO6MbxLF5oTFaxBX5rAGcBRVw==",
+      "license": "MIT"
+    },
     "node_modules/@pinojs/redact": {
       "version": "0.4.0",
       "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",

package/.claude/envoy/package.json

@@ -14,6 +14,7 @@
   },
   "dependencies": {
     "@google/genai": "^0.14.0",
+    "@opencode-ai/sdk": "^1.1.14",
     "@upstash/context7-sdk": "^0.3.0",
     "@visheratin/tokenizers-node": "0.1.5",
     "@visheratin/web-ai-node": "^1.4.5",

package/.claude/envoy/src/commands/knowledge.ts

@@ -2,21 +2,39 @@
  * Knowledge commands - semantic search and indexing for docs/ documentation.
  *
  * Commands:
- *   envoy knowledge search <query> [--metadata-only]
+ *   envoy knowledge search <query> [--metadata-only] [--force-aggregate] [--no-aggregate]
  *   envoy knowledge reindex-all
  *   envoy knowledge reindex-from-changes [--files <json_array>]
  */
 
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import { Command } from "commander";
 import { spawnSync } from "child_process";
 import { BaseCommand, CommandResult } from "./base.js";
 import { KnowledgeService, type FileChange } from "../lib/knowledge.js";
+import {
+  AgentRunner,
+  type AggregatorOutput,
+  type SearchResult,
+} from "../lib/agents/index.js";
 import { getBaseBranch } from "../lib/git.js";
 
 const getProjectRoot = (): string => {
   return process.env.PROJECT_ROOT || process.cwd();
 };
 
+// Load aggregator prompt from file
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGGREGATOR_PROMPT_PATH = join(__dirname, "../lib/agents/prompts/knowledge-aggregator.md");
+
+const getAggregatorPrompt = (): string => {
+  return readFileSync(AGGREGATOR_PROMPT_PATH, "utf-8");
+};
+
+const DEFAULT_TOKEN_THRESHOLD = 3500;
+
 /**
  * Auto-detect doc file changes since branch diverged from base.
  * Returns FileChange[] for docs/ files only.
@@ -70,37 +88,119 @@ function getDocChangesFromGit(): FileChange[] {
 }
 
 /**
- * Search command - semantic search against docs index
+ * Search command - semantic search against docs index with hybrid aggregation
  */
 class SearchCommand extends BaseCommand {
   readonly name = "search";
-  readonly description = "Semantic search docs (use descriptive phrases, not keywords)";
+  readonly description = "Semantic search docs (aggregates large results automatically)";
 
   defineArguments(cmd: Command): void {
     cmd
       .argument("<query>", "Descriptive phrase (e.g. 'how to handle API authentication' not 'auth')")
-      .option("--metadata-only", "Return only file paths and descriptions (no full content)");
+      .option("--metadata-only", "Return only file paths and descriptions (no full content)")
+      .option("--force-aggregate", "Force aggregation even below threshold")
+      .option("--no-aggregate", "Disable aggregation entirely");
   }
 
   async execute(args: Record<string, unknown>): Promise<CommandResult> {
     const query = args.query as string;
     const metadataOnly = !!args.metadataOnly;
+    const forceAggregate = !!args.forceAggregate;
+    const noAggregate = !!args.noAggregate;
 
     if (!query) {
       return this.error("validation_error", "query is required");
     }
 
+    const projectRoot = getProjectRoot();
+
     try {
-      const service = new KnowledgeService(getProjectRoot());
+      const service = new KnowledgeService(projectRoot);
       const results = await service.search(query, 50, metadataOnly);
 
-      return this.success({
-        message: "Search completed",
-        query,
-        metadata_only: metadataOnly,
-        results,
-        result_count: results.length,
-      });
+      // Skip aggregation if metadata-only or explicitly disabled
+      if (metadataOnly || noAggregate) {
+        return this.success({
+          query,
+          metadata_only: metadataOnly,
+          results,
+          result_count: results.length,
+        });
+      }
+
+      // Calculate total tokens
+      const totalTokens = results.reduce((sum, r) => sum + r.token_count, 0);
+      const parsedThreshold = parseInt(
+        process.env.KNOWLEDGE_AGGREGATOR_TOKEN_THRESHOLD ?? String(DEFAULT_TOKEN_THRESHOLD),
+        10
+      );
+      const threshold = Number.isNaN(parsedThreshold) ? DEFAULT_TOKEN_THRESHOLD : parsedThreshold;
+
+      // Skip aggregation if below threshold
+      if (totalTokens < threshold && !forceAggregate) {
+        return this.success({
+          aggregated: false,
+          total_tokens: totalTokens,
+          threshold,
+          results,
+          result_count: results.length,
+        });
+      }
+
+      // Separate full vs minimized results
+      const fullResults = results.filter((r) => r.full_resource_context) as SearchResult[];
+      const minimizedResults = results
+        .filter((r) => !r.full_resource_context)
+        .map((r) => ({
+          resource_path: r.resource_path,
+          similarity: r.similarity,
+          token_count: r.token_count,
+          description: r.description,
+          relevant_files: r.relevant_files,
+        })) as SearchResult[];
+
+      // Run aggregator agent
+      try {
+        const runner = new AgentRunner(projectRoot);
+        const input = this.formatAggregatorInput(query, fullResults, minimizedResults);
+
+        const result = await runner.run<AggregatorOutput>(
+          {
+            name: "knowledge-aggregator",
+            systemPrompt: getAggregatorPrompt(),
+            timeoutMs: 60000,
+          },
+          input
+        );
+
+        if (!result.success || !result.data) {
+          // Fallback to raw results on aggregation failure
+          return this.success({
+            aggregated: false,
+            aggregation_error: result.error ?? "Unknown aggregation error",
+            total_tokens: totalTokens,
+            results,
+            result_count: results.length,
+          });
+        }
+
+        return this.success({
+          aggregated: true,
+          insight: result.data.insight,
+          references: result.data.references,
+          design_notes: result.data.design_notes,
+          metadata: result.metadata,
+        });
+      } catch (e) {
+        // Fallback to raw results on any error
+        return this.success({
+          aggregated: false,
+          aggregation_error: e instanceof Error ? e.message : String(e),
+          total_tokens: totalTokens,
+          results,
+          result_count: results.length,
+        });
+      }
     } catch (e) {
       return this.error(
         "search_error",
@@ -108,6 +208,36 @@ class SearchCommand extends BaseCommand {
       );
     }
   }
+
+  private formatAggregatorInput(
+    query: string,
+    fullResults: SearchResult[],
+    minimizedResults: SearchResult[]
+  ): string {
+    return `## Query
+${query}
+
+## Full Results (${fullResults.length} documents with complete content)
+
+${fullResults.map((r) => `### ${r.resource_path}
+- Similarity: ${r.similarity.toFixed(3)}
+- Tokens: ${r.token_count}
+- Description: ${r.description}
+
+Content:
+\`\`\`
+${r.full_resource_context}
+\`\`\`
+`).join("\n")}
+
+## Minimized Results (${minimizedResults.length} documents - request expansion if needed)
+
+${minimizedResults.map((r) => `- **${r.resource_path}** (similarity: ${r.similarity.toFixed(3)}, ${r.token_count} tokens)
+  ${r.description}
+`).join("\n")}
+
+Please analyze and provide your response as JSON.`;
+  }
 }
 
 /**

package/.claude/envoy/src/lib/agents/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Sub-agent infrastructure for envoy.
+ * Uses OpenCode SDK to spawn agents for specialized tasks.
+ */
+
+// Agent configuration
+export interface AgentConfig {
+  name: string;
+  systemPrompt: string;
+  model?: string;
+  timeoutMs?: number;
+}
+
+// Agent execution result
+export interface AgentResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  metadata?: {
+    model: string;
+    tokens_used?: number;
+    duration_ms: number;
+  };
+}
+
+// Search result type (mirrors KnowledgeService.SearchResult)
+export interface SearchResult {
+  resource_path: string;
+  similarity: number;
+  token_count: number;
+  description: string;
+  relevant_files: string[];
+  full_resource_context?: string;
+}
+
+// Knowledge aggregator input
+export interface AggregatorInput {
+  query: string;
+  full_results: SearchResult[];
+  minimized_results: SearchResult[];
+}
+
+// Knowledge aggregator output
+export interface AggregatorOutput {
+  insight: string;
+  references: Array<{
+    file: string;
+    symbol: string | null;
+    why: string;
+  }>;
+  design_notes?: string[];
+}
+
+export { AgentRunner } from "./runner.js";

package/.claude/envoy/src/lib/agents/prompts/knowledge-aggregator.md

@@ -0,0 +1,67 @@
+# Knowledge Aggregator
+
+You synthesize documentation into codebase-grounded answers. The caller is exploring a codebase - they need to understand **what exists**, **why it was built that way**, and **where to look**.
+
+## Core Principle
+
+Never answer generically. Every insight must reference concrete codebase implementations:
+- BAD: "An agent is a specialized execution context..."
+- GOOD: "Agents in this codebase are defined in `.claude/agents/` with configs that scope their tools - see `curator.md` for the pattern of restricting WebSearch to specific agent types"
+
+## Input Format
+
+You receive:
+1. A user query about the codebase
+2. Full results: Docs with complete content (high similarity)
+3. Minimized results: Docs with metadata only (may need expansion)
+
+## Expansion Protocol
+
+Need content from a minimized result? Output:
+```
+EXPAND: <resource_path>
+```
+
+You'll receive the content. Max 3 expansions. Only expand if description suggests direct relevance.
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "insight": "Codebase-grounded answer: what pattern exists, why it was chosen, how it's used. Include best practices if query implies implementation intent. 2-4 sentences max.",
+  "references": [
+    {
+      "file": "path/to/implementation.ts",
+      "symbol": "functionOrClassName",
+      "why": "Brief reason main agent should check this"
+    }
+  ],
+  "design_notes": ["Relevant architectural decisions or tradeoffs from docs"]
+}
+```
+
+## Field Guidelines
+
+**insight**:
+- Ground every statement in the codebase
+- If query implies they want to implement something, include the recommended approach
+- Mention specific files/patterns by name
+- Include "best practice: X" when docs encode conventions
+
+**references** (max 5, ranked by relevance):
+- `file`: Path to code file (from doc's `relevant_files` or inline references like `[ref:path:symbol:hash]`)
+- `symbol`: Function/class/variable name if known from doc references, null otherwise
+- `why`: One sentence - why should they look here? What will they find?
+
+**design_notes** (optional, max 2):
+- Only include if docs explicitly discuss design rationale
+- Format: "[Decision]: [Rationale]" e.g. "Least-privilege tooling: agents receive only tools for their function to prevent cross-domain actions"
+
+## Anti-patterns
+
+- Generic definitions not tied to this codebase
+- Listing every file mentioned (keep only most relevant)
+- Excerpts without actionability
+- Restating the query as the answer

package/.claude/envoy/src/lib/agents/runner.ts

@@ -0,0 +1,251 @@
+/**
+ * AgentRunner - Spawns and manages sub-agents via OpenCode SDK.
+ * Each run spawns a fresh server instance, executes the agent, and cleans up.
+ */
+
+import { existsSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { createOpencode } from "@opencode-ai/sdk";
+import type { AgentConfig, AgentResult } from "./index.js";
+import { logCommandComplete, logCommandStart } from "../observability.js";
+
+const MAX_EXPANSIONS = 3;
+const EXPANSION_PATTERN = /^EXPAND:\s*(.+)$/gm;
+const DEFAULT_TIMEOUT_MS = 60000;
+
+export class AgentRunner {
+  private readonly projectRoot: string;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+  }
+
+  /**
+   * Execute an agent with given config and user message.
+   * Spawns server, creates session, sends message, handles expansions, cleans up.
+   */
+  async run<T>(config: AgentConfig, userMessage: string): Promise<AgentResult<T>> {
+    const startTime = Date.now();
+    logCommandStart("agent.run", { agent: config.name });
+
+    let server: { close: () => void } | null = null;
+
+    try {
+      const { client, server: srv } = await createOpencode({
+        timeout: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        config: config.model ? { model: config.model } : undefined,
+      });
+      server = srv;
+
+      const session = await client.session.create({
+        body: { title: config.name },
+      });
+
+      if (!session.data?.id) {
+        throw new Error("Failed to create session");
+      }
+
+      // Send system prompt as context
+      await client.session.prompt({
+        path: { id: session.data.id },
+        body: {
+          noReply: true,
+          parts: [{ type: "text", text: config.systemPrompt }],
+        },
+      });
+
+      // Send user message and get response
+      let response = await client.session.prompt({
+        path: { id: session.data.id },
+        body: {
+          parts: [{ type: "text", text: userMessage }],
+        },
+      });
+
+      let responseText = this.extractResponseText(response);
+      let expansionCount = 0;
+
+      // Handle expansion requests
+      while (this.hasExpansionRequest(responseText) && expansionCount < MAX_EXPANSIONS) {
+        const paths = this.extractExpansionPaths(responseText);
+        const contents = this.readFiles(paths);
+        const expansionMessage = this.formatExpansionResponse(contents);
+
+        response = await client.session.prompt({
+          path: { id: session.data.id },
+          body: {
+            parts: [{ type: "text", text: expansionMessage }],
+          },
+        });
+
+        responseText = this.extractResponseText(response);
+        expansionCount++;
+      }
+
+      const durationMs = Date.now() - startTime;
+      const parsed = this.parseStructuredOutput<T>(responseText);
+
+      if (!parsed) {
+        // Retry once asking for JSON
+        response = await client.session.prompt({
+          path: { id: session.data.id },
+          body: {
+            parts: [{ type: "text", text: "Please format your response as valid JSON matching the required schema." }],
+          },
+        });
+
+        responseText = this.extractResponseText(response);
+        const retryParsed = this.parseStructuredOutput<T>(responseText);
+
+        if (!retryParsed) {
+          throw new Error("Failed to parse agent response as JSON");
+        }
+
+        logCommandComplete("agent.run", "success", Date.now() - startTime, {
+          agent: config.name,
+          expansions: expansionCount,
+          retry: true,
+        });
+
+        return {
+          success: true,
+          data: retryParsed,
+          metadata: {
+            model: config.model ?? "default",
+            duration_ms: Date.now() - startTime,
+          },
+        };
+      }
+
+      logCommandComplete("agent.run", "success", durationMs, {
+        agent: config.name,
+        expansions: expansionCount,
+      });
+
+      return {
+        success: true,
+        data: parsed,
+        metadata: {
+          model: config.model ?? "default",
+          duration_ms: durationMs,
+        },
+      };
+    } catch (error) {
+      const durationMs = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      logCommandComplete("agent.run", "error", durationMs, {
+        agent: config.name,
+        error: errorMessage,
+      });
+
+      return {
+        success: false,
+        error: errorMessage,
+        metadata: {
+          model: config.model ?? "default",
+          duration_ms: durationMs,
+        },
+      };
+    } finally {
+      if (server) {
+        server.close();
+      }
+    }
+  }
+
+  private extractResponseText(response: unknown): string {
+    // Navigate SDK response structure to get text content
+    const resp = response as {
+      data?: {
+        parts?: Array<{ type: string; text?: string }>;
+      };
+    };
+
+    if (!resp.data?.parts) {
+      return "";
+    }
+
+    return resp.data.parts
+      .filter((p) => p.type === "text" && p.text)
+      .map((p) => p.text)
+      .join("\n");
+  }
+
+  private hasExpansionRequest(text: string): boolean {
+    const regex = new RegExp(EXPANSION_PATTERN.source, EXPANSION_PATTERN.flags);
+    return regex.test(text);
+  }
+
+  private extractExpansionPaths(text: string): string[] {
+    const paths: string[] = [];
+    const regex = new RegExp(EXPANSION_PATTERN.source, "gm");
+    let match;
+
+    while ((match = regex.exec(text)) !== null) {
+      paths.push(match[1].trim());
+    }
+
+    return paths;
+  }
+
+  private readFiles(paths: string[]): Map<string, string | null> {
+    const contents = new Map<string, string | null>();
+    const MAX_FILE_SIZE = 1024 * 1024; // 1MB
+
+    for (const path of paths) {
+      const fullPath = join(this.projectRoot, path);
+      if (existsSync(fullPath)) {
+        try {
+          const stats = statSync(fullPath);
+          if (stats.size > MAX_FILE_SIZE) {
+            const partial = readFileSync(fullPath, "utf-8").slice(0, MAX_FILE_SIZE);
+            contents.set(path, `${partial}\n\n[TRUNCATED: file exceeds 1MB limit]`);
+          } else {
+            contents.set(path, readFileSync(fullPath, "utf-8"));
+          }
+        } catch {
+          contents.set(path, null);
+        }
+      } else {
+        contents.set(path, null);
+      }
+    }
+
+    return contents;
+  }
+
+  private formatExpansionResponse(contents: Map<string, string | null>): string {
+    const parts: string[] = ["Here are the expanded file contents:\n"];
+
+    for (const [path, content] of contents) {
+      if (content !== null) {
+        parts.push(`## ${path}\n\`\`\`\n${content}\n\`\`\`\n`);
+      } else {
+        parts.push(`## ${path}\n[File not found or unreadable]\n`);
+      }
+    }
+
+    parts.push("\nPlease continue your analysis and provide the final JSON response.");
+    return parts.join("\n");
+  }
+
+  private parseStructuredOutput<T>(text: string): T | null {
+    // Try to extract JSON from code block
+    const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (codeBlockMatch) {
+      try {
+        return JSON.parse(codeBlockMatch[1].trim()) as T;
+      } catch {
+        // Fall through to try raw parse
+      }
+    }
+
+    // Try raw JSON parse
+    try {
+      return JSON.parse(text.trim()) as T;
+    } catch {
+      return null;
+    }
+  }
+}

package/.claude/envoy/src/lib/index.ts

@@ -114,3 +114,13 @@ export {
 } from "./notification.js";
 export type { NotifyOptions } from "./notification.js";
 
+// Agent infrastructure
+export { AgentRunner } from "./agents/index.js";
+export type {
+  AgentConfig,
+  AgentResult,
+  AggregatorInput,
+  AggregatorOutput,
+  SearchResult,
+} from "./agents/index.js";
+

package/.claude/settings.json

@@ -5,6 +5,7 @@
     "SEARCH_SIMILARITY_THRESHOLD": "0.65",
     "SEARCH_FULL_CONTEXT_SIMILARITY_THRESHOLD": "0.82",
     "SEARCH_CONTEXT_TOKEN_LIMIT": "5000",
+    "KNOWLEDGE_AGGREGATOR_TOKEN_THRESHOLD": "3500",
     "MAX_LOGS_TOKENS": "10000",
     "BASH_MAX_TIMEOUT_MS": "3600000",
     "BASE_BRANCH": "main",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-all-hands",
-  "version": "1.0.39",
+  "version": "1.0.41",
   "description": "CLI for syncing Claude agent configurations to all-hands repository",
   "type": "module",
   "bin": {