@opengsd/gsd-core 1.7.0-rc.1 → 1.7.0-rc.2

package/.opencode/plugins/gsd-core.js

@@ -0,0 +1,711 @@
+/**
+ * GSD plugin for OpenCode.ai  (CommonJS)
+ *
+ * Architecture: SUBPROCESS REUSE. Instead of re-implementing hook logic inside
+ * the plugin, this file is a thin adapter that spawns the existing Claude Code
+ * hook scripts under hooks/ as child processes. The hooks speak a stable
+ * protocol (JSON on stdin, JSON + exit code on stdout); this adapter:
+ *   1. Translates OpenCode plugin events into Claude Code hook payloads
+ *   2. Spawns `node <HOOKS_DIR>/<hook>.js` with the payload on stdin
+ *   3. Translates hook output back into OpenCode semantics
+ *      - block  → throw Error (OpenCode returns the error to the model)
+ *      - advisory → output.metadata + console.error (best-effort surfacing)
+ *
+ * Namespace conversion (/gsd:xxx → /gsd-xxx) reuses scripts/fix-slash-commands.cjs
+ * via require(), keeping the single source of truth.
+ *
+ * ── Two distribution shapes, one adapter (issue #1914) ─────────────────────
+ * This single file serves both distribution paths, distinguished at load time
+ * by REPO_ROOT (path.resolve(__dirname, "../..")):
+ *
+ *   • Option 1 — file copy (the supported GSD path). `bin/install.js` copies
+ *     this file to <opencodeConfigDir>/plugins/gsd-core.js, so REPO_ROOT is the
+ *     OpenCode config dir. GSD's own install already stages `hooks/*.js` and
+ *     `gsd-core/` there (ADR-857 skips hook *registration* for OpenCode, not the
+ *     file copy), so the hook bridge and content rewriting resolve natively.
+ *     Commands/agents/skills are ALREADY registered by GSD's native file copy in
+ *     this mode, so the plugin's own config-hook registration is redundant and is
+ *     SKIPPED (see IS_PACKAGE_TREE) to avoid double-registration.
+ *
+ *   • Option 2 — package / git-spec. When loaded from the package tree (npm
+ *     `main`, or an OpenCode git-spec install), REPO_ROOT is the package root and
+ *     the source layout (commands/gsd/, agents/, skills/) is present. Here the
+ *     plugin IS the sole registrar, so it registers commands/agents/skills too.
+ *
+ * IS_PACKAGE_TREE keys off the presence of the SOURCE command layout
+ * (commands/gsd/), which only exists in the package tree — never in an installed
+ * config dir (that uses the flattened command/ layout). The hook bridge and
+ * Read-time content rewriting run in BOTH modes; only the config-hook
+ * registration of commands/agents/skills is gated.
+ *
+ * Runtime-specific hooks are deliberately excluded:
+ *   - gsd-statusline.js / gsd-update-banner.js (Claude Code statusline)
+ *   - gsd-cursor-*.js (Cursor-specific)
+ *   - *.sh scripts (invoked directly by commands/agents, not hook events)
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const { spawnSync } = require("child_process");
+
+// Resolve REPO_ROOT to the directory that actually holds the GSD payload
+// (hooks/ + gsd-core/). This must work across three physical layouts because a
+// single adapter file serves both distribution shapes (see header):
+//   • package/git-spec tree:  <root>/.opencode/plugins/gsd-core.js   → <root>
+//   • global file-copy:       ~/.config/opencode/plugins/gsd-core.js → ~/.config/opencode
+//   • local file-copy:        <proj>/.opencode/plugins/gsd-core.js   → <proj>/.opencode
+// A fixed "../.." only works for the first; the copied layouts sit one level
+// shallower. Walking up to the first ancestor containing BOTH payload markers
+// resolves all three deterministically. Falls back to the package-tree
+// assumption ("../..") if no ancestor matches (keeps graceful degradation).
+function resolveRepoRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 6; i++) {
+    if (
+      fs.existsSync(path.join(dir, "hooks")) &&
+      fs.existsSync(path.join(dir, "gsd-core"))
+    ) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  // No ancestor carried both markers (broken/partial layout — the plugin can't
+  // function regardless). Fall back to the package-tree assumption ("../.."),
+  // matching the historical fixed-depth behavior and the .opencode/plugins/
+  // source layout.
+  return path.resolve(startDir, "../..");
+}
+
+// CJS: __dirname is a global, no need to derive from import.meta.url
+const REPO_ROOT = resolveRepoRoot(__dirname);
+const HOOKS_DIR = path.join(REPO_ROOT, "hooks");
+const COMMANDS = path.join(REPO_ROOT, "commands", "gsd");
+const AGENTS = path.join(REPO_ROOT, "agents");
+const SKILLS = path.join(REPO_ROOT, "skills");
+const GSD_CORE = path.join(REPO_ROOT, "gsd-core");
+
+// True only when loaded from the package/source tree (Option 2), detected by the
+// presence of the SOURCE command layout (commands/gsd/). In an installed OpenCode
+// config dir (Option 1) this directory is absent — the flattened command/ layout
+// is used instead — so the plugin skips its own command/agent/skill registration
+// and lets GSD's native file copy own that surface (avoids double-registration).
+const IS_PACKAGE_TREE = fs.existsSync(COMMANDS);
+
+// ---------------------------------------------------------------------------
+// Namespace conversion — reuse the single source of truth
+// ---------------------------------------------------------------------------
+
+let _cmdNames = null;
+let _transformFn = null;
+
+/**
+ * Lazily load scripts/fix-slash-commands.cjs and cache the transform function
+ * + command name list. Returns null if the module is unavailable (the plugin
+ * still works, just without namespace conversion).
+ */
+function getNamespaceConverter() {
+  if (_transformFn) return _transformFn;
+  try {
+    const mod = require(
+      path.join(REPO_ROOT, "scripts", "fix-slash-commands.cjs"),
+    );
+    _cmdNames = mod.readCmdNames();
+    _transformFn = mod.transformContentToHyphen;
+    return _transformFn;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session state — tracked across plugin hook invocations
+// ---------------------------------------------------------------------------
+
+let currentSessionId = null;
+let currentCwd = process.cwd();
+
+// ---------------------------------------------------------------------------
+// Tool name / argument mapping  (OpenCode ↔ Claude Code)
+// ---------------------------------------------------------------------------
+
+const TOOL_NAME_MAP = {
+  read: "Read",
+  write: "Write",
+  edit: "Edit",
+  apply_patch: "MultiEdit",
+  multi_edit: "MultiEdit",
+  bash: "Bash",
+  webfetch: "WebFetch",
+  web_search: "WebSearch",
+  websearch: "WebSearch",
+  task: "Task",
+  subagent: "Task",
+};
+
+function mapToolName(tool) {
+  if (!tool) return "";
+  return TOOL_NAME_MAP[String(tool).toLowerCase()] || tool;
+}
+
+// Build a Claude-style `tool_input` object from OpenCode's `output.args`.
+function mapToolInput(args) {
+  const input = {};
+  if (!args || typeof args !== "object") return input;
+
+  // File-path keys (OpenCode uses filePath/path; Claude uses file_path)
+  const filePath = args.filePath || args.path || args.file_path;
+  if (filePath) input.file_path = filePath;
+
+  // Content for Write
+  if (args.content !== undefined) input.content = args.content;
+
+  // Edit patch fields
+  if (args.new_string !== undefined) input.new_string = args.new_string;
+  if (args.newString !== undefined) input.new_string = args.newString;
+  if (args.old_string !== undefined) input.old_string = args.old_string;
+  if (args.oldString !== undefined) input.old_string = args.oldString;
+
+  // Bash command
+  if (args.command !== undefined) input.command = args.command;
+
+  // Web
+  if (args.url !== undefined) input.url = args.url;
+  if (args.query !== undefined) input.query = args.query;
+
+  return input;
+}
+
+// ---------------------------------------------------------------------------
+// Hook subprocess runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn a Claude Code hook script and pipe a JSON payload to its stdin.
+ *
+ * Hooks follow the convention:
+ *   - stdout: JSON object (decision/advisory) or empty
+ *   - exit 0: allow (with optional advisory JSON on stdout)
+ *   - exit 2: block (Claude convention; reason in stdout JSON)
+ *   - any error: exit 0 silently (hooks swallow their own errors)
+ *
+ * @param {string} hookFile  filename under hooks/, e.g. "gsd-prompt-guard.js"
+ * @param {object} payload   stdin JSON (hook_event_name, tool_name, ...)
+ * @param {object} [opts]
+ * @param {number} [opts.timeout=8000] spawn timeout in ms
+ * @param {string} [opts.cwd]         working directory for the child
+ * @returns {{ stdout: string, exitCode: number, timedOut: boolean }}
+ */
+function runHook(hookFile, payload, opts = {}) {
+  const hookPath = path.join(HOOKS_DIR, hookFile);
+  if (!fs.existsSync(hookPath)) {
+    return { stdout: "", exitCode: 0, timedOut: false };
+  }
+  const timeout = opts.timeout ?? 8000;
+  let result;
+  try {
+    result = spawnSync(process.execPath, [hookPath], {
+      input: JSON.stringify(payload),
+      encoding: "utf8",
+      timeout,
+      cwd: opts.cwd || currentCwd,
+      windowsHide: true,
+    });
+  } catch {
+    // Spawn failure — never break the tool call
+    return { stdout: "", exitCode: 0, timedOut: false };
+  }
+
+  const stdout = (result.stdout || "").trim();
+  const exitCode = result.status == null ? 0 : result.status;
+  return { stdout, exitCode, timedOut: result.signal === "SIGTERM" };
+}
+
+// ---------------------------------------------------------------------------
+// Hook output translation → OpenCode semantics
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a hook's stdout and apply its effect to the OpenCode output object.
+ *
+ * - Block   → throw Error(parsed.reason) so OpenCode aborts the tool call
+ * - Advisory→ append to output.metadata._gsdAdvisory[] and log to stderr
+ * - Silent  → no-op
+ *
+ * @param {{ stdout: string, exitCode: number }} hookResult
+ * @param {object} [output]  OpenCode mutable output object (optional)
+ */
+function handleHookResult(hookResult, output) {
+  const { stdout, exitCode } = hookResult;
+  if (!stdout && exitCode !== 2) return; // silent allow
+
+  let parsed = null;
+  if (stdout) {
+    try {
+      parsed = JSON.parse(stdout);
+    } catch {
+      // Non-JSON stdout (e.g. a stray log) — treat exit 2 as hard block, else allow
+    }
+  }
+
+  // Block: explicit decision OR Claude exit-code-2 convention
+  const isBlock = exitCode === 2 || (parsed && parsed.decision === "block");
+  if (isBlock) {
+    const reason =
+      (parsed && parsed.reason) || "Blocked by GSD hook (no reason provided).";
+    throw new Error(reason);
+  }
+
+  // Advisory: inject additionalContext into metadata + log
+  const advisory =
+    parsed &&
+    parsed.hookSpecificOutput &&
+    parsed.hookSpecificOutput.additionalContext;
+  if (advisory) {
+    if (output) {
+      output.metadata = output.metadata || {};
+      // Accumulate: a single tool call can run several advisory hooks in
+      // sequence (prompt guard, read guard, worktree guard, workflow guard).
+      // Storing a scalar would let a later advisory clobber an earlier one, so
+      // collect them all.
+      if (!Array.isArray(output.metadata._gsdAdvisory)) {
+        output.metadata._gsdAdvisory = [];
+      }
+      output.metadata._gsdAdvisory.push(advisory);
+    }
+    // Best-effort visibility when metadata isn't surfaced to the model
+    console.error(advisory);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter helpers (for config registration)
+// ---------------------------------------------------------------------------
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return { frontmatter: {}, body: content };
+  const fm = {};
+  for (const line of m[1].split("\n")) {
+    const i = line.indexOf(":");
+    if (i > 0) {
+      let v = line.slice(i + 1).trim();
+      if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+      fm[line.slice(0, i).trim()] = v;
+    }
+  }
+  return { frontmatter: fm, body: m[2] };
+}
+
+// Rewrite @~/.claude/ includes to point at the repo root.
+// Also applies /gsd:xxx → /gsd-xxx namespace conversion via the shared
+// transform from scripts/fix-slash-commands.cjs (single source of truth).
+function rewriteRefs(content) {
+  let out = content.replace(/@~\/\.claude\//g, `@${REPO_ROOT}/`);
+  const transform = getNamespaceConverter();
+  if (transform && _cmdNames && _cmdNames.length) {
+    out = transform(out, _cmdNames);
+  }
+  return out;
+}
+
+function loadDir(dir, keyFn, valFn) {
+  const result = {};
+  if (!fs.existsSync(dir)) return result;
+  for (const f of fs.readdirSync(dir).filter((f) => f.endsWith(".md"))) {
+    const raw = fs.readFileSync(path.join(dir, f), "utf8");
+    const { frontmatter, body } = parseFrontmatter(raw);
+    result[keyFn(f)] = valFn(body, frontmatter, f);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime content transform — for Read tool results on GSD-managed files
+// ---------------------------------------------------------------------------
+
+// Directories whose .md files may contain ~/.claude/ paths and gsd: namespace
+// refs. When the model reads these via the Read tool, we transparently rewrite
+// both so OpenCode sees correct paths and hyphen-form command names.
+const GSD_MANAGED_DIRS = [
+  path.join(GSD_CORE, "workflows"),
+  path.join(GSD_CORE, "references"),
+  path.join(GSD_CORE, "templates"),
+  path.join(GSD_CORE, "contexts"),
+  COMMANDS,
+  AGENTS,
+  SKILLS,
+];
+
+function isGsdManagedFile(filePath) {
+  if (!filePath) return false;
+  const resolved = path.resolve(filePath);
+  return GSD_MANAGED_DIRS.some(
+    (dir) => resolved === dir || resolved.startsWith(dir + path.sep),
+  );
+}
+
+// Rewrite content for OpenCode consumption:
+//   1. @-include paths:  @~/.claude/  →  @<REPO_ROOT>/
+//   2. plain-text paths: ~/.claude/gsd-core/  →  <GSD_CORE>/
+//   3. namespace:        gsd:xxx  →  gsd-xxx  (via fix-slash-commands.cjs)
+function rewriteContent(content) {
+  let out = content;
+  out = out.replace(/@~\/\.claude\//g, `@${REPO_ROOT}/`);
+  out = out.replace(/~\/\.claude\/gsd-core\//g, `${GSD_CORE}/`);
+  const transform = getNamespaceConverter();
+  if (transform && _cmdNames && _cmdNames.length) {
+    out = transform(out, _cmdNames);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Skills cache — copy SKILL.md files with rewritten @-include paths
+// ---------------------------------------------------------------------------
+//
+// OpenCode's skill loader reads SKILL.md files directly from disk and resolves
+// @-includes internally — this bypasses our tool.execute hooks. To make
+// @~/.claude/gsd-core/... includes resolve, we copy all SKILL.md files to a
+// cache directory with paths rewritten to the actual GSD_CORE location.
+//
+// Only used in package-tree mode (Option 2). In an installed OpenCode config
+// dir (Option 1) skills are already staged + registered by GSD's native file
+// copy, so we never register skills from the plugin (see IS_PACKAGE_TREE).
+
+const SKILLS_CACHE = path.join(
+  os.homedir(),
+  ".cache",
+  "opencode",
+  "gsd-skills",
+);
+
+function prepareSkillsCache() {
+  if (!fs.existsSync(SKILLS)) return null;
+  fs.mkdirSync(SKILLS_CACHE, { recursive: true });
+  for (const dir of fs.readdirSync(SKILLS)) {
+    const srcFile = path.join(SKILLS, dir, "SKILL.md");
+    if (!fs.existsSync(srcFile)) continue;
+    const raw = fs.readFileSync(srcFile, "utf8");
+    // Rewrite @-include paths only; namespace conversion is handled at
+    // Read-time via tool.execute.after for workflow/reference files.
+    const rewritten = raw
+      .replace(/@~\/\.claude\/gsd-core\//g, `@${GSD_CORE}/`)
+      .replace(/~\/\.claude\/gsd-core\//g, `${GSD_CORE}/`);
+    const destDir = path.join(SKILLS_CACHE, dir);
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.writeFileSync(path.join(destDir, "SKILL.md"), rewritten);
+  }
+  return SKILLS_CACHE;
+}
+
+// ===========================================================================
+// Plugin entry
+// ===========================================================================
+
+const GsdCorePlugin = async ({ directory } = {}) => {
+  if (directory) currentCwd = directory;
+
+  return {
+    // ── Config: register commands / agents / skills paths ──────────────
+    // Only in package-tree mode (Option 2). In an installed config dir
+    // (Option 1) GSD's native file copy already registered these, so the
+    // plugin stays out of registration to avoid double-registering.
+    config: async (config) => {
+      if (!IS_PACKAGE_TREE) return;
+
+      // Commands (commands/gsd/*.md → gsd-<name>)
+      config.command = config.command || {};
+      const cmds = loadDir(
+        COMMANDS,
+        (f) => "gsd-" + f.slice(0, -3),
+        (body, fm, name) => ({
+          template: rewriteRefs(body.trim()),
+          description: fm.description || `GSD ${name.slice(0, -3)} command`,
+        }),
+      );
+      for (const [k, v] of Object.entries(cmds)) {
+        if (!config.command[k]) config.command[k] = v;
+      }
+
+      // Agents (agents/*.md)
+      config.agent = config.agent || {};
+      const agents = loadDir(
+        AGENTS,
+        (f) => f.slice(0, -3),
+        (body, fm, name) => ({
+          prompt: rewriteRefs(body.trim()),
+          description: fm.description || `GSD ${name.slice(0, -3)} agent`,
+          mode: fm.mode || "subagent",
+        }),
+      );
+      for (const [k, v] of Object.entries(agents)) {
+        if (!config.agent[k]) config.agent[k] = v;
+      }
+
+      // Skills — copy SKILL.md files to cache with rewritten @-include paths,
+      // then register the cache directory. OpenCode's skill loader reads
+      // SKILL.md from disk and resolves @-includes internally (bypassing our
+      // tool.execute hooks), so we must pre-process the files.
+      const skillsCache = prepareSkillsCache();
+      config.skills = config.skills || {};
+      config.skills.paths = config.skills.paths || [];
+      const skillsPath = skillsCache || SKILLS;
+      if (!config.skills.paths.includes(skillsPath)) {
+        config.skills.paths.push(skillsPath);
+      }
+    },
+
+    // ── shell.env ───────────────────────────────────────────────────────
+    "shell.env": async (_input, output) => {
+      output.env = output.env || {};
+      output.env.GSD_DIR = GSD_CORE;
+    },
+
+    // ── tool.execute.before — PreToolUse hooks ─────────────────────────
+    "tool.execute.before": async (input, output) => {
+      const claudeTool = mapToolName(input.tool);
+      const toolInput = mapToolInput(output.args || {});
+      const cwd = currentCwd;
+
+      // 0. Read path rewrite — redirect ~/.claude/gsd-core/ to actual GSD_CORE
+      //    so the model can read workflow/reference/template files that SKILL.md
+      //    and command templates reference via the canonical Claude path.
+      if (claudeTool === "Read" && toolInput.file_path) {
+        const original = toolInput.file_path;
+        const rewritten = original
+          .replace(/^~\/\.claude\/gsd-core\//, GSD_CORE + "/")
+          .replace(/(?:.*)\/\.claude\/gsd-core\//, GSD_CORE + "/");
+        if (rewritten !== original) {
+          const args = output.args || {};
+          if (args.filePath) args.filePath = rewritten;
+          else if (args.path) args.path = rewritten;
+          else if (args.file_path) args.file_path = rewritten;
+          else args.filePath = rewritten;
+        }
+      }
+
+      const basePayload = {
+        hook_event_name: "PreToolUse",
+        cwd,
+      };
+      // NOTE: session_id intentionally omitted for PreToolUse hooks.
+      // gsd-read-guard.js treats a non-empty session_id as a Claude Code
+      // session and skips its advisory. On OpenCode we WANT the advisory.
+      const prePayload = (overrides = {}) => ({
+        ...basePayload,
+        tool_name: claudeTool,
+        tool_input: toolInput,
+        ...overrides,
+      });
+
+      const isWriteLike = ["Write", "Edit", "MultiEdit"].includes(claudeTool);
+
+      // 1. gsd-prompt-guard.js — injection scan on .planning/ writes
+      if (claudeTool === "Write" || claudeTool === "Edit") {
+        const r = runHook("gsd-prompt-guard.js", prePayload());
+        handleHookResult(r, output);
+      }
+
+      // 2. gsd-read-guard.js — read-before-edit advisory
+      if (claudeTool === "Write" || claudeTool === "Edit") {
+        const r = runHook("gsd-read-guard.js", prePayload());
+        handleHookResult(r, output);
+      }
+
+      // 3. gsd-worktree-path-guard.js — hard-block edits outside worktree
+      if (isWriteLike) {
+        const r = runHook("gsd-worktree-path-guard.js", prePayload());
+        handleHookResult(r, output);
+      }
+
+      // 4. gsd-workflow-guard.js — workflow advisory + git-force-add block
+      //    (covers Write/Edit/MultiEdit AND Bash force-add detection)
+      if (isWriteLike || claudeTool === "Bash") {
+        const r = runHook("gsd-workflow-guard.js", prePayload());
+        handleHookResult(r, output);
+      }
+    },
+
+    // ── tool.execute.after — PostToolUse hooks ─────────────────────────
+    "tool.execute.after": async (input, output) => {
+      const claudeTool = mapToolName(input.tool);
+      // NOTE: In the `after` hook, `args` lives on `input` (not `output`).
+      // The `output` object only has { title, output, metadata }.
+      const toolInput = mapToolInput(input.args || {});
+      const cwd = currentCwd;
+
+      // GSD content transform — rewrite paths + namespace in Read results
+      // BEFORE injection scanning so the scanner sees the final content.
+      if (
+        claudeTool === "Read" &&
+        output.output &&
+        isGsdManagedFile(toolInput.file_path)
+      ) {
+        const content =
+          typeof output.output === "string"
+            ? output.output
+            : String(output.output);
+        output.output = rewriteContent(content);
+      }
+
+      // gsd-read-injection-scanner.js — scan Read/WebFetch/WebSearch results
+      if (
+        claudeTool === "Read" ||
+        claudeTool === "WebFetch" ||
+        claudeTool === "WebSearch"
+      ) {
+        const payload = {
+          hook_event_name: "PostToolUse",
+          tool_name: claudeTool,
+          tool_input: toolInput,
+          tool_response: output.output,
+          cwd,
+        };
+        const r = runHook("gsd-read-injection-scanner.js", payload);
+        handleHookResult(r, output);
+        return;
+      }
+
+      // gsd-context-monitor.js — context usage warnings (Bash/Edit/Write/Task/...)
+      // Only meaningful when a session_id is tracked (writes metrics sentinel).
+      if (currentSessionId) {
+        const payload = {
+          hook_event_name: "PostToolUse",
+          tool_name: claudeTool,
+          tool_input: toolInput,
+          session_id: currentSessionId,
+          cwd,
+        };
+        const r = runHook("gsd-context-monitor.js", payload);
+        handleHookResult(r, output);
+      }
+    },
+
+    // ── experimental.session.compacting — PreCompact ───────────────────
+    "experimental.session.compacting": async (_input, output) => {
+      if (!currentSessionId) return;
+      const payload = {
+        hook_event_name: "PreCompact",
+        session_id: currentSessionId,
+        cwd: currentCwd,
+      };
+      const r = runHook("gsd-context-monitor.js", payload);
+      handleHookResult(r, output);
+
+      // Also inject a GSD compaction breadcrumb (mirrors the original plugin)
+      output.context = output.context || [];
+      output.context.push(
+        `[GSD] Active session: ${currentSessionId}. Preserve any in-flight phase/plan state.`,
+      );
+    },
+
+    // ── General event subscriptions ─────────────────────────────────────
+    event: async ({ event }) => {
+      // session.created → SessionStart hooks
+      if (event.type === "session.created") {
+        // Track session for context-monitor payloads.
+        // SDK type EventSessionCreated: { properties: { info: Session } }
+        // Session has `id` and `directory` (not `cwd`).
+        const info = event.properties?.info;
+        currentSessionId =
+          info?.id || event.sessionID || event.session_id || null;
+        if (info?.directory) currentCwd = info.directory;
+
+        // gsd-ensure-canonical-path.js — no stdin dependency; silent
+        runHook("gsd-ensure-canonical-path.js", {
+          hook_event_name: "SessionStart",
+          session_id: currentSessionId,
+          cwd: currentCwd,
+        });
+        // gsd-check-update.js — spawns its own background worker; no stdin
+        runHook("gsd-check-update.js", {
+          hook_event_name: "SessionStart",
+          session_id: currentSessionId,
+          cwd: currentCwd,
+        });
+        return;
+      }
+
+      // file.edited → FileChanged hook (config.json reload)
+      if (event.type === "file.edited") {
+        // SDK type EventFileEdited: { properties: { file: string } }
+        const filePath = event.properties?.file || event.filePath || "";
+        if (!filePath.endsWith("config.json")) return;
+        const cwd = event.properties?.cwd || currentCwd;
+        const expected = path.join(cwd, ".planning", "config.json");
+        if (path.resolve(filePath) !== path.resolve(expected)) return;
+
+        const payload = {
+          hook_event_name: "FileChanged",
+          file_path: filePath,
+          event: "change",
+          cwd,
+        };
+        const r = runHook("gsd-config-reload.js", payload);
+        // Advisory-only (additionalContext); surface to logs
+        handleHookResult(r);
+        return;
+      }
+
+      // session.idle ↔ Claude Stop lifecycle point (#1682 Slice 1b/c).
+      // OpenCode fires session.idle when the run quiesces. GSD maps it to the
+      // Stop equivalent — the opencode-subset lifecycle peer of compaction
+      // (compaction preserves state across context-window summarization; idle
+      // marks end-of-turn). No-op sentinel today (GSD state is already
+      // persisted to .planning/), but it MUST be recognized so the declared
+      // opencode-subset surface is fully wired and a future Stop-class hook can
+      // attach without a plugin change.
+      if (event.type === "session.idle") {
+        return;
+      }
+    },
+  };
+};
+
+// Export shape — verified against OpenCode's plugin loader source
+// (packages/opencode/src/plugin). The loader imports this module and runs
+// `for (const entry of Object.values(mod)) { getServerPlugin(entry) }`, where
+// `getServerPlugin` accepts a bare function OR an object exposing a `.server`
+// function, and THROWS `TypeError("Plugin export is not a function")` for
+// anything else. So EVERY enumerable value the loader iterates must be a
+// function or an object with `.server`.
+//
+// The subtlety: depending on how OpenCode's runtime (Node or Bun) imports a
+// CommonJS file, `mod` may be the raw `module.exports` OR an ESM namespace of
+// the form `{ default: module.exports, ...syntheticNamedExports }`. A plain
+// `module.exports = { id: "gsd-core", server }` literal risks a string `id`
+// appearing in `Object.values(mod)` (as a raw property, or as a lexer-
+// synthesized named export) — which would trip the throw. Two defenses:
+//   1. `id` is defined NON-ENUMERABLE, so it never appears in Object.values yet
+//      stays readable (via property access) for the loader's identity/dedup.
+//   2. `module.exports` is assigned from a VARIABLE (not an object literal), so
+//      cjs-module-lexer cannot statically synthesize named exports from it —
+//      only `default` is exposed under ESM/Bun interop.
+// Result: raw-CJS `Object.values` = `[server]`; ESM `Object.values` =
+// `[{server, <id non-enum>}]` — both fully extractable. Test-only helpers hang
+// off the `server` FUNCTION (`server._internals`), never as a sibling export.
+GsdCorePlugin._internals = {
+  REPO_ROOT,
+  IS_PACKAGE_TREE,
+  mapToolName,
+  mapToolInput,
+  parseFrontmatter,
+  rewriteContent,
+  isGsdManagedFile,
+  handleHookResult,
+  GsdCorePlugin,
+};
+
+const gsdCorePluginExport = { server: GsdCorePlugin };
+Object.defineProperty(gsdCorePluginExport, "id", {
+  value: "gsd-core",
+  enumerable: false,
+  writable: false,
+  configurable: false,
+});
+module.exports = gsdCorePluginExport;