@bldg-7/cc-plugin-loader 0.1.0 → 0.2.0

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@bldg-7/cc-plugin-loader",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
-  "files": ["src"],
+  "files": [
+    "src"
+  ],
   "publishConfig": {
     "access": "public"
   },

package/src/constants.ts

@@ -12,9 +12,18 @@ export const TOOL_NAME_MAP: Record<string, string> = {
   WebFetch: "webfetch",
   WebSearch: "websearch",
   Agent: "agent",
-  NotebookEdit: "notebookedit",
+  TodoWrite: "todowrite",
+  Task: "task",
+  LS: "ls",
+  Skill: "skill",
 };
 
+/** OpenCode tool name → Claude Code tool name (reverse of TOOL_NAME_MAP) */
+export const REVERSE_TOOL_NAME_MAP: Record<string, string> =
+  Object.fromEntries(
+    Object.entries(TOOL_NAME_MAP).map(([cc, oc]) => [oc, cc]),
+  );
+
 /** Claude Code model alias → OpenCode model ID */
 export const MODEL_MAP: Record<string, string> = {
   sonnet: "anthropic/claude-sonnet-4-6",

package/src/hooks/bridge-executor.ts

@@ -0,0 +1,99 @@
+import { spawn } from "child_process";
+import type { HookStdinPayload, HookStdoutResult } from "./bridge-types.js";
+
+const DEFAULT_TIMEOUT = 10_000;
+
+/**
+ * Execute a hook command as a subprocess.
+ *
+ * - Writes `payload` as JSON to stdin
+ * - Parses stdout as JSON
+ * - Kills process on timeout
+ * - Returns null on any error (non-zero exit, parse failure, timeout)
+ */
+export async function executeHookCommand(
+  command: string,
+  payload: HookStdinPayload,
+  timeout: number = DEFAULT_TIMEOUT,
+  env?: Record<string, string>,
+): Promise<HookStdoutResult | null> {
+  return new Promise((resolve) => {
+    const child = spawn("sh", ["-c", command], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+      cwd: payload.cwd,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        child.kill("SIGKILL");
+        console.warn(
+          `[cc-plugin-loader] Hook command timed out after ${timeout}ms: ${command}`,
+        );
+        resolve(null);
+      }
+    }, timeout);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("error", (err) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        console.warn(
+          `[cc-plugin-loader] Hook command failed to spawn: ${command}`,
+          err.message,
+        );
+        resolve(null);
+      }
+    });
+
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+
+      if (code !== 0) {
+        console.warn(
+          `[cc-plugin-loader] Hook command exited with code ${code}: ${command}`,
+          stderr || "(no stderr)",
+        );
+        resolve(null);
+        return;
+      }
+
+      const trimmed = stdout.trim();
+      if (!trimmed) {
+        // Empty stdout is valid — treat as { continue: true }
+        resolve({ continue: true });
+        return;
+      }
+
+      try {
+        const result = JSON.parse(trimmed) as HookStdoutResult;
+        resolve(result);
+      } catch {
+        console.warn(
+          `[cc-plugin-loader] Hook command returned invalid JSON: ${command}`,
+          trimmed,
+        );
+        resolve(null);
+      }
+    });
+
+    // Write payload to stdin and close
+    child.stdin.write(JSON.stringify(payload));
+    child.stdin.end();
+  });
+}

package/src/hooks/bridge-loader.ts

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+import type {
+  HooksConfig,
+  HookEventName,
+  ResolvedHookEntry,
+} from "./bridge-types.js";
+
+const DEFAULT_TIMEOUT = 10;
+
+/**
+ * Load hooks.json from a plugin's hooks/ directory.
+ * Returns resolved hook entries with ${CLAUDE_PLUGIN_ROOT} expanded.
+ * Filters to command-type hooks only.
+ */
+export async function loadHooks(
+  installPath: string,
+  pluginName: string,
+): Promise<ResolvedHookEntry[]> {
+  const hooksPath = join(installPath, "hooks", "hooks.json");
+
+  let raw: string;
+  try {
+    raw = await readFile(hooksPath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  let config: HooksConfig;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    console.warn(
+      `[cc-plugin-loader] Failed to parse hooks.json in ${pluginName}`,
+    );
+    return [];
+  }
+
+  const entries: ResolvedHookEntry[] = [];
+
+  for (const [eventName, rules] of Object.entries(config)) {
+    if (!rules || !Array.isArray(rules)) continue;
+
+    for (const rule of rules) {
+      if (!rule.hooks || !Array.isArray(rule.hooks)) continue;
+
+      for (const action of rule.hooks) {
+        // Phase 2: command type only
+        if (action.type !== "command") continue;
+        if (!action.command) continue;
+
+        // Expand ${CLAUDE_PLUGIN_ROOT}
+        const command = action.command.replaceAll(
+          "${CLAUDE_PLUGIN_ROOT}",
+          installPath,
+        );
+
+        entries.push({
+          pluginName,
+          installPath,
+          event: eventName as HookEventName,
+          matcher: rule.matcher,
+          command,
+          timeout: (action.timeout ?? DEFAULT_TIMEOUT) * 1000,
+        });
+      }
+    }
+  }
+
+  return entries;
+}

package/src/hooks/bridge-matcher.ts

@@ -0,0 +1,23 @@
+import type { HookEventName, ResolvedHookEntry } from "./bridge-types.js";
+
+/**
+ * Filter resolved hook entries by event name and optional tool name.
+ *
+ * Rules:
+ * - Entry must match the given event
+ * - If the entry has no matcher, it matches all tool names (wildcard)
+ * - Matcher "*" also matches all tool names
+ * - Otherwise, matcher must equal toolName exactly (case-sensitive)
+ */
+export function matchHooks(
+  entries: ResolvedHookEntry[],
+  event: HookEventName,
+  toolName?: string,
+): ResolvedHookEntry[] {
+  return entries.filter((entry) => {
+    if (entry.event !== event) return false;
+    if (!entry.matcher || entry.matcher === "*") return true;
+    if (!toolName) return false;
+    return entry.matcher === toolName;
+  });
+}

package/src/hooks/bridge-state.ts

@@ -0,0 +1,25 @@
+/**
+ * Tracks "once" hook executions to prevent re-running.
+ * Key format: `${pluginName}:${event}:${command}`
+ */
+const executed = new Set<string>();
+
+export function makeKey(
+  pluginName: string,
+  event: string,
+  command: string,
+): string {
+  return `${pluginName}:${event}:${command}`;
+}
+
+export function hasRun(key: string): boolean {
+  return executed.has(key);
+}
+
+export function markRun(key: string): void {
+  executed.add(key);
+}
+
+export function reset(): void {
+  executed.clear();
+}

package/src/hooks/bridge-types.ts

@@ -0,0 +1,61 @@
+// ── Claude Code Hooks Protocol Types ──
+
+/** Supported hook event names from Claude Code */
+export type HookEventName =
+  | "PreToolUse"
+  | "PostToolUse"
+  | "PermissionRequest"
+  | "UserPromptSubmit"
+  | "PreCompact";
+
+/** A single hook action within a hook rule */
+export interface HookAction {
+  type: "command" | "prompt" | "agent" | "http";
+  command?: string;
+  timeout?: number;
+}
+
+/** A hook rule: event matcher + list of actions */
+export interface HookRule {
+  matcher?: string;
+  hooks: HookAction[];
+}
+
+/** The shape of hooks.json */
+export type HooksConfig = Partial<Record<HookEventName, HookRule[]>>;
+
+/** A resolved hook entry ready for execution */
+export interface ResolvedHookEntry {
+  pluginName: string;
+  installPath: string;
+  event: HookEventName;
+  matcher?: string;
+  command: string;
+  timeout: number;
+}
+
+// ── stdin/stdout protocol types ──
+
+/** JSON written to hook subprocess stdin */
+export interface HookStdinPayload {
+  session_id: string;
+  cwd: string;
+  hook_event_name: HookEventName;
+  tool_name?: string;
+  tool_input?: unknown;
+  transcript_path: string;
+}
+
+/** hookSpecificOutput in subprocess stdout */
+export interface HookSpecificOutput {
+  hookEventName?: string;
+  permissionDecision?: "allow" | "deny";
+  updatedInput?: Record<string, unknown>;
+  additionalContext?: string;
+}
+
+/** JSON parsed from hook subprocess stdout */
+export interface HookStdoutResult {
+  continue: boolean;
+  hookSpecificOutput?: HookSpecificOutput;
+}

package/src/hooks/bridge.ts

@@ -0,0 +1,187 @@
+import type { Hooks } from "@opencode-ai/plugin";
+import type { ParsedPlugin } from "../types.js";
+import type {
+  HookEventName,
+  HookStdinPayload,
+  ResolvedHookEntry,
+} from "./bridge-types.js";
+import { REVERSE_TOOL_NAME_MAP } from "../constants.js";
+import { matchHooks } from "./bridge-matcher.js";
+import { executeHookCommand } from "./bridge-executor.js";
+
+/**
+ * Create OpenCode hook callbacks from resolved hook entries across all plugins.
+ */
+export function createBridgeHooks(plugins: ParsedPlugin[]): Partial<Hooks> {
+  const allEntries = plugins.flatMap((p) => p.hookEntries);
+  if (!allEntries.length) return {};
+
+  const hooks: Partial<Hooks> = {};
+
+  // Check which events have entries
+  const eventSet = new Set(allEntries.map((e) => e.event));
+
+  if (eventSet.has("PreToolUse")) {
+    hooks["tool.execute.before"] = async (input, output) => {
+      const ccToolName = REVERSE_TOOL_NAME_MAP[input.tool] ?? input.tool;
+      const matched = matchHooks(allEntries, "PreToolUse", ccToolName);
+      if (!matched.length) return;
+
+      const payload = buildPayload(
+        "PreToolUse",
+        input.sessionID,
+        ccToolName,
+        output.args,
+      );
+
+      for (const entry of matched) {
+        const result = await executeHookCommand(
+          entry.command,
+          payload,
+          entry.timeout,
+        );
+        if (!result) continue;
+
+        if (!result.continue) {
+          console.warn(
+            `[cc-plugin-loader] Hook "${entry.command}" returned continue:false, ` +
+              `but OpenCode tool.execute.before cannot cancel execution. ` +
+              `Consider using permission.ask instead.`,
+          );
+        }
+
+        if (result.hookSpecificOutput?.updatedInput) {
+          Object.assign(output.args, result.hookSpecificOutput.updatedInput);
+          // Update payload for chaining
+          payload.tool_input = output.args;
+        }
+      }
+    };
+  }
+
+  if (eventSet.has("PostToolUse")) {
+    hooks["tool.execute.after"] = async (input, output) => {
+      const ccToolName = REVERSE_TOOL_NAME_MAP[input.tool] ?? input.tool;
+      const matched = matchHooks(allEntries, "PostToolUse", ccToolName);
+      if (!matched.length) return;
+
+      const payload = buildPayload(
+        "PostToolUse",
+        input.sessionID,
+        ccToolName,
+        input.args,
+      );
+
+      for (const entry of matched) {
+        const result = await executeHookCommand(
+          entry.command,
+          payload,
+          entry.timeout,
+        );
+        if (!result) continue;
+
+        if (result.hookSpecificOutput?.additionalContext) {
+          output.output += "\n" + result.hookSpecificOutput.additionalContext;
+        }
+      }
+    };
+  }
+
+  if (eventSet.has("PermissionRequest")) {
+    hooks["permission.ask"] = async (input, output) => {
+      const matched = matchHooks(
+        allEntries,
+        "PermissionRequest",
+        input.type,
+      );
+      if (!matched.length) return;
+
+      const payload = buildPayload(
+        "PermissionRequest",
+        input.sessionID,
+        input.type,
+      );
+
+      for (const entry of matched) {
+        const result = await executeHookCommand(
+          entry.command,
+          payload,
+          entry.timeout,
+        );
+        if (!result) continue;
+
+        const decision = result.hookSpecificOutput?.permissionDecision;
+        if (decision === "allow") {
+          output.status = "allow";
+        } else if (decision === "deny") {
+          output.status = "deny";
+        }
+      }
+    };
+  }
+
+  if (eventSet.has("UserPromptSubmit")) {
+    hooks["chat.message"] = async (input, output) => {
+      const matched = matchHooks(allEntries, "UserPromptSubmit");
+      if (!matched.length) return;
+
+      const payload = buildPayload("UserPromptSubmit", input.sessionID);
+
+      for (const entry of matched) {
+        const result = await executeHookCommand(
+          entry.command,
+          payload,
+          entry.timeout,
+        );
+        if (!result) continue;
+
+        if (result.hookSpecificOutput?.additionalContext) {
+          output.parts.push({
+            type: "text",
+            text: result.hookSpecificOutput.additionalContext,
+          } as never);
+        }
+      }
+    };
+  }
+
+  if (eventSet.has("PreCompact")) {
+    hooks["experimental.session.compacting"] = async (input, output) => {
+      const matched = matchHooks(allEntries, "PreCompact");
+      if (!matched.length) return;
+
+      const payload = buildPayload("PreCompact", input.sessionID);
+
+      for (const entry of matched) {
+        const result = await executeHookCommand(
+          entry.command,
+          payload,
+          entry.timeout,
+        );
+        if (!result) continue;
+
+        if (result.hookSpecificOutput?.additionalContext) {
+          output.context.push(result.hookSpecificOutput.additionalContext);
+        }
+      }
+    };
+  }
+
+  return hooks;
+}
+
+function buildPayload(
+  event: HookEventName,
+  sessionId: string,
+  toolName?: string,
+  toolInput?: unknown,
+): HookStdinPayload {
+  return {
+    session_id: sessionId,
+    cwd: process.cwd(),
+    hook_event_name: event,
+    tool_name: toolName,
+    tool_input: toolInput,
+    transcript_path: "",
+  };
+}

package/src/hooks/config.ts

@@ -2,15 +2,41 @@ import type { Config } from "@opencode-ai/sdk";
 import { TOOL_NAME_MAP, MODEL_MAP } from "../constants.js";
 import type { ParsedPlugin } from "../types.js";
 
+/** Claude Code tool names that have no OpenCode equivalent — silently dropped */
+const UNMAPPABLE_TOOLS = new Set([
+  "NotebookEdit",
+  "NotebookRead",
+  "KillShell",
+  "BashOutput",
+  "AskUserQuestion",
+]);
+
+/**
+ * Map Claude Code tool names to OpenCode tool names.
+ * - Exact match in TOOL_NAME_MAP takes priority
+ * - Scoped patterns like "Bash(git:*)" → "bash"
+ * - Tools with no OpenCode equivalent are dropped
+ */
 function mapTools(tools: string[]): Record<string, boolean> {
   const result: Record<string, boolean> = {};
   for (const tool of tools) {
-    const mapped = TOOL_NAME_MAP[tool] || tool.toLowerCase();
+    // Handle scoped patterns like "Bash(git:*)"
+    const baseMatch = tool.match(/^(\w+)\(/);
+    const baseName = baseMatch ? baseMatch[1] : tool;
+
+    if (UNMAPPABLE_TOOLS.has(baseName)) continue;
+
+    const mapped = TOOL_NAME_MAP[baseName] || baseName.toLowerCase();
     result[mapped] = true;
   }
   return result;
 }
 
+function mapModel(model: string): string | undefined {
+  if (model === "inherit") return undefined; // let OpenCode use parent model
+  return MODEL_MAP[model] || model;
+}
+
 export function createConfigHook(plugins: ParsedPlugin[]) {
   return async (config: Config): Promise<void> => {
     if (!config.agent) config.agent = {};
@@ -21,18 +47,21 @@ export function createConfigHook(plugins: ParsedPlugin[]) {
       // Register agents
       for (const agent of plugin.agents) {
         const key = `${plugin.name}-${agent.name}`;
+        const model = agent.model ? mapModel(agent.model) : undefined;
         config.agent[key] = {
           description: agent.description,
           mode: "subagent",
           prompt: agent.prompt,
           tools: mapTools(agent.tools),
-          ...(agent.model && { model: MODEL_MAP[agent.model] || agent.model }),
+          ...(model && { model }),
           ...(agent.maxTurns && { maxSteps: agent.maxTurns }),
+          ...(agent.color && { color: agent.color }),
         };
       }
 
-      // Register MCP servers
+      // Register MCP servers (skip if already configured natively)
       for (const mcp of plugin.mcpServers) {
+        if (config.mcp[mcp.qualifiedName]) continue;
         config.mcp[mcp.qualifiedName] = {
           type: "local" as const,
           command: [mcp.command, ...mcp.args],

package/src/index.ts

@@ -5,6 +5,7 @@ import { createConfigHook } from "./hooks/config.js";
 import { createSystemHook } from "./hooks/system.js";
 import { createCommandHook } from "./hooks/command.js";
 import { createEnvHook } from "./hooks/env.js";
+import { createBridgeHooks } from "./hooks/bridge.js";
 import type { ParsedPlugin } from "./types.js";
 
 const plugin: Plugin = async (input) => {
@@ -37,6 +38,7 @@ const plugin: Plugin = async (input) => {
     "experimental.chat.system.transform": createSystemHook(plugins),
     "command.execute.before": createCommandHook(plugins),
     "shell.env": createEnvHook(plugins),
+    ...createBridgeHooks(plugins),
   };
 };
 

package/src/loader.ts

@@ -14,6 +14,7 @@ import type {
   ParsedCommand,
   ParsedMcp,
 } from "./types.js";
+import { loadHooks } from "./hooks/bridge-loader.js";
 
 async function readFileSafe(path: string): Promise<string | null> {
   try {
@@ -57,13 +58,15 @@ export async function loadPlugin(
 
   const pluginName = manifest.name;
 
-  const [claudeMd, skills, agents, commands, mcpServers] = await Promise.all([
-    readFileSafe(join(installPath, "CLAUDE.md")),
-    loadSkills(installPath, pluginName),
-    loadAgents(installPath, pluginName),
-    loadCommands(installPath, pluginName),
-    loadMcpServers(installPath, pluginName),
-  ]);
+  const [claudeMd, skills, agents, commands, mcpServers, hookEntries] =
+    await Promise.all([
+      readFileSafe(join(installPath, "CLAUDE.md")),
+      loadSkills(installPath, pluginName),
+      loadAgents(installPath, pluginName),
+      loadCommands(installPath, pluginName),
+      loadMcpServers(installPath, pluginName),
+      loadHooks(installPath, pluginName),
+    ]);
 
   return {
     name: pluginName,
@@ -73,6 +76,7 @@ export async function loadPlugin(
     agents,
     commands,
     mcpServers,
+    hookEntries,
   };
 }
 
@@ -146,6 +150,7 @@ async function loadAgents(
         model: frontmatter.model,
         tools: normalizeTools(frontmatter),
         maxTurns: frontmatter.maxTurns,
+        color: frontmatter.color,
         prompt,
       });
     } catch (e) {
@@ -219,11 +224,15 @@ async function loadMcpServers(
 
   const servers: ParsedMcp[] = [];
   for (const [serverName, server] of Object.entries(config.mcpServers)) {
-    // Expand env variables
+    // Expand env variables — omit unresolved vars so the MCP server
+    // can inherit them from the parent process environment
     const env: Record<string, string> = {};
     if (server.env) {
       for (const [k, v] of Object.entries(server.env)) {
-        env[k] = expandEnv(v);
+        const expanded = expandEnv(v);
+        if (expanded !== null) {
+          env[k] = expanded;
+        }
       }
     }
 
@@ -240,15 +249,27 @@ async function loadMcpServers(
   return servers;
 }
 
-function expandEnv(value: string): string {
-  return value.replace(/\$\{([^}]+)\}/g, (_match, varName) => {
+function expandEnv(value: string): string | null {
+  let hasUnresolved = false;
+  const result = value.replace(/\$\{([^}]+)\}/g, (_match, varExpr) => {
+    // Support ${VAR:-default} syntax
+    const colonIdx = varExpr.indexOf(":-");
+    const varName = colonIdx >= 0 ? varExpr.slice(0, colonIdx) : varExpr;
+    const fallback = colonIdx >= 0 ? varExpr.slice(colonIdx + 2) : undefined;
+
     const val = process.env[varName];
-    if (val === undefined) {
-      console.warn(
-        `[cc-plugin-loader] Environment variable ${varName} is not set`,
-      );
-      return "";
-    }
-    return val;
+    if (val !== undefined) return val;
+    if (fallback !== undefined) return fallback;
+
+    console.warn(
+      `[cc-plugin-loader] Environment variable ${varName} not set, omitting from MCP config`,
+    );
+    hasUnresolved = true;
+    return "";
   });
+
+  // If the entire value was a single unresolved ${VAR}, omit it
+  // so the MCP server can inherit from parent environment
+  if (hasUnresolved && result === "") return null;
+  return result;
 }

package/src/parser.ts

@@ -18,17 +18,22 @@ export function parseFrontmatter<T>(content: string): Parsed<T> {
 }
 
 /**
- * Normalize tools from either `allowed-tools` (YAML array) or `tools` (comma-separated string).
+ * Normalize tools from either `allowed-tools` (YAML array) or `tools` (array or comma-separated string).
  */
 export function normalizeTools(fm: {
   "allowed-tools"?: string[];
-  tools?: string;
+  tools?: string | string[];
 }): string[] {
   if (fm["allowed-tools"] && Array.isArray(fm["allowed-tools"])) {
     return fm["allowed-tools"];
   }
-  if (fm.tools && typeof fm.tools === "string") {
-    return fm.tools.split(",").map((t) => t.trim()).filter(Boolean);
+  if (fm.tools) {
+    if (Array.isArray(fm.tools)) {
+      return fm.tools;
+    }
+    if (typeof fm.tools === "string") {
+      return fm.tools.split(",").map((t) => t.trim()).filter(Boolean);
+    }
   }
   return [];
 }

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { ResolvedHookEntry } from "./hooks/bridge-types.js";
+
 // ── Source types (Claude Code plugin format) ──
 
 /** V1: each plugin key maps to a single entry (no scope, no array) */
@@ -45,7 +47,7 @@ export interface SkillFrontmatter {
   name?: string;
   description?: string;
   "allowed-tools"?: string[];
-  tools?: string;
+  tools?: string | string[];
 }
 
 export interface AgentFrontmatter {
@@ -53,8 +55,9 @@ export interface AgentFrontmatter {
   description: string;
   model?: string;
   "allowed-tools"?: string[];
-  tools?: string;
+  tools?: string | string[];
   maxTurns?: number;
+  color?: string;
 }
 
 export interface CommandFrontmatter {
@@ -92,6 +95,7 @@ export interface ParsedAgent {
   model?: string;
   tools: string[];
   maxTurns?: number;
+  color?: string;
   prompt: string;
 }
 
@@ -121,4 +125,7 @@ export interface ParsedPlugin {
   agents: ParsedAgent[];
   commands: ParsedCommand[];
   mcpServers: ParsedMcp[];
+  hookEntries: ResolvedHookEntry[];
 }
+
+export type { ResolvedHookEntry };