agy-plugin-porter 0.1.0 → 0.2.0

package/scripts/hook-shim.mjs

@@ -11,9 +11,9 @@
 //   the script decided something.
 // - SessionStart / Stop / PostToolUse: stdout must be a JSON object.
 import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { sep } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 // agy tool name -> source tool name and arg renames. Arg names are the agy CLI's
 // as seen live; the IDE-named tools reuse them unverified. Unknown args pass through.
@@ -56,7 +56,35 @@ const renameKeys = (obj, renames) => Object.fromEntries(
   Object.entries(obj ?? {}).map(([k, v]) => [renames[k] ?? k, v]));
 const invert = (renames) => Object.fromEntries(Object.entries(renames).map(([k, v]) => [v, k]));
 
-export function toSourceTool(toolCall, dialect) {
+export function toSourceTool(toolCall, dialect, matcher) {
+  if ((toolCall?.name === 'call_mcp_tool' || toolCall?.name === 'mcp_tool') && toolCall?.args) {
+    const server = toolCall.args.ServerName ?? toolCall.args.server_name ?? '';
+    const tool = toolCall.args.ToolName ?? toolCall.args.tool_name ?? '';
+    const rawArgs = toolCall.args.Arguments ?? toolCall.args.arguments ?? {};
+    return {
+      tool_name: server && tool ? `mcp__${server}__${tool}` : toolCall.name,
+      tool_input: typeof rawArgs === 'string' ? (parseJson(rawArgs.trim()) ?? {}) : (rawArgs ?? {}),
+    };
+  }
+  if (dialect !== 'gemini' && typeof toolCall?.name === 'string' && toolCall.name.startsWith('mcp_') && toolCall.name !== 'mcp_tool') {
+    const rest = toolCall.name.slice(4);
+    if (typeof matcher === 'string') {
+      for (const m of matcher.matchAll(/mcp__([A-Za-z0-9._-]+)__/g)) {
+        const srv = m[1];
+        const normSrv = srv.replace(/-/g, '_');
+        if (rest.startsWith(`${srv}_`)) {
+          return { tool_name: `mcp__${srv}__${rest.slice(srv.length + 1)}`, tool_input: toolCall.args ?? {} };
+        }
+        if (rest.startsWith(`${normSrv}_`)) {
+          return { tool_name: `mcp__${srv}__${rest.slice(normSrv.length + 1)}`, tool_input: toolCall.args ?? {} };
+        }
+      }
+    }
+    const idx = rest.indexOf('_');
+    if (idx > 0) {
+      return { tool_name: `mcp__${rest.slice(0, idx)}__${rest.slice(idx + 1)}`, tool_input: toolCall.args ?? {} };
+    }
+  }
   const [name, renames] = REVERSE[dialect]?.[toolCall?.name] ?? [toolCall?.name ?? '', {}];
   return { tool_name: name, tool_input: renameKeys(toolCall?.args, renames) };
 }
@@ -73,10 +101,10 @@ export function toSourcePayload(entry, payload) {
   else base.permission_mode = 'default';
   switch (entry.event) {
     case 'PreToolUse':
-      return { ...base, ...toSourceTool(payload.toolCall, entry.dialect) };
+      return { ...base, ...toSourceTool(payload.toolCall, entry.dialect, entry.matcher) };
     case 'PostToolUse':
-      if (entry.sourceEvent === 'PostToolUseFailure') return { ...base, ...toSourceTool(payload.toolCall, entry.dialect), error: payload.error ?? '' };
-      return { ...base, ...toSourceTool(payload.toolCall, entry.dialect), tool_response: payload.error ? { error: payload.error } : {} };
+      if (entry.sourceEvent === 'PostToolUseFailure') return { ...base, ...toSourceTool(payload.toolCall, entry.dialect, entry.matcher), error: payload.error ?? '' };
+      return { ...base, ...toSourceTool(payload.toolCall, entry.dialect, entry.matcher), tool_response: payload.error ? { error: payload.error } : {} };
     case 'SessionStart':
       return { ...base, source: 'startup' };
     case 'Stop':
@@ -88,23 +116,89 @@ export function toSourcePayload(entry, payload) {
 
 // Expands the plugin-path variables Claude Code and Gemini CLI provide, so the
 // command works under cmd.exe too. Unknown variables are left to the shell.
-export function expandCommand(command, vars) {
-  const values = { ...vars, '/': sep };
-  return command.replace(/\$\{([A-Za-z_]\w*|\/)\}|\$([A-Za-z_]\w*)/g, (whole, braced, bare) => {
-    const name = braced ?? bare;
-    return Object.hasOwn(values, name) ? values[name] : whole;
+export function expandCommand(command, vars, { posix = false } = {}) {
+  const slash = posix ? '/' : sep;
+  const norm = (v) => (posix && typeof v === 'string' ? v.replace(/\\/g, '/') : v);
+  const values = { ...Object.fromEntries(Object.entries(vars ?? {}).map(([k, v]) => [k, norm(v)])), '/': slash };
+  const VAR_RE = /\$\{([A-Za-z_]\w*|\/)\}|\$([A-Za-z_]\w*)/g;
+  return command.replace(/"[^"]*"|'[^']*'|\S+/g, (token) => {
+    let expandedAny = false;
+    const expanded = token.replace(VAR_RE, (whole, braced, bare) => {
+      const name = braced ?? bare;
+      if (Object.hasOwn(values, name)) {
+        if (name !== '/') expandedAny = true;
+        return values[name];
+      }
+      return whole;
+    });
+    const isQuoted = (token.startsWith('"') && token.endsWith('"')) || (token.startsWith("'") && token.endsWith("'"));
+    if (expandedAny && !isQuoted && !token.includes('"') && /\s/.test(expanded)) {
+      return `"${expanded}"`;
+    }
+    return expanded;
   });
 }
 
 const NO_OPINION = { PreToolUse: '' };
 export const noOpinion = (event) => NO_OPINION[event] ?? '{}';
 
+function splitTopLevelAlternatives(raw) {
+  const out = [];
+  let bracket = false;
+  let paren = 0;
+  let start = 0;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === '\\') { i++; continue; }
+    if (ch === '[' && !bracket) bracket = true;
+    else if (ch === ']' && bracket) bracket = false;
+    else if (!bracket && ch === '(') paren++;
+    else if (!bracket && ch === ')') paren = Math.max(0, paren - 1);
+    else if (!bracket && paren === 0 && ch === '|') {
+      out.push(raw.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  out.push(raw.slice(start).trim());
+  return out.filter(Boolean);
+}
+
+function matchesSourceMatcher(matcher, toolName, rawToolName) {
+  if (!matcher || matcher === '*' || matcher === '.*') return true;
+  const effectiveRaw = (rawToolName === 'call_mcp_tool' || rawToolName === 'mcp_tool') && toolName !== rawToolName
+    ? ''
+    : (rawToolName ?? '');
+  if (matcher === toolName || (effectiveRaw && matcher === effectiveRaw)) return true;
+  try {
+    for (const alt of splitTopLevelAlternatives(matcher)) {
+      if (alt === '*' || alt === '.*' || alt === toolName || (effectiveRaw && alt === effectiveRaw)) return true;
+      const hasAnchor = /^\(*\^/.test(alt) || /\$\)*$/.test(alt);
+      const isMcpPrefix = /^\^?mcp__.*__$/.test(alt);
+      const re = hasAnchor
+        ? new RegExp(alt)
+        : isMcpPrefix
+          ? new RegExp(`^(?:${alt})`)
+          : new RegExp(`^(?:${alt})$`);
+      if (re.test(toolName) || (effectiveRaw && re.test(effectiveRaw))) return true;
+    }
+    return false;
+  } catch {
+    return true;
+  }
+}
+
 // agy has one PostToolUse with `error` set when the tool failed (empty on
 // success, live-tested). Claude splits it: PostToolUse runs on success only,
 // PostToolUseFailure on failure only.
 export function shouldRun(entry, payload) {
-  if (entry.event !== 'PostToolUse' || entry.dialect !== 'claude') return true;
-  return Boolean(payload.error) === (entry.sourceEvent === 'PostToolUseFailure');
+  if (entry.event === 'PostToolUse' && entry.dialect === 'claude') {
+    if (Boolean(payload.error) !== (entry.sourceEvent === 'PostToolUseFailure')) return false;
+  }
+  if ((entry.event === 'PreToolUse' || entry.event === 'PostToolUse') && entry.matcher) {
+    const { tool_name } = toSourceTool(payload?.toolCall, entry.dialect, entry.matcher);
+    if (!matchesSourceMatcher(entry.matcher, tool_name, payload?.toolCall?.name)) return false;
+  }
+  return true;
 }
 
 function parseJson(text) {
@@ -132,10 +226,10 @@ export function translateResult(entry, result) {
     const reasonOr = (r, fallback) => (typeof r === 'string' && r.trim() ? r.trim() : fallback);
     if (blocked) return { stdout: JSON.stringify({ decision: 'deny', reason: reasonOr(stderr, 'Blocked by hook') }) };
     if (!json) return { stdout: '' };
-    let decision = ['allow', 'deny', 'ask'].includes(specific.permissionDecision) ? specific.permissionDecision : null;
+    let decision = ['allow', 'deny', 'ask', 'force_ask'].includes(specific.permissionDecision) ? specific.permissionDecision : null;
     let reason = specific.permissionDecisionReason;
     if (!decision && typeof json.decision === 'string') {
-      decision = { block: 'deny', deny: 'deny', approve: 'allow', allow: 'allow', ask: 'ask' }[json.decision] ?? null;
+      decision = { block: 'deny', deny: 'deny', approve: 'allow', allow: 'allow', ask: 'ask', force_ask: 'force_ask' }[json.decision] ?? null;
       reason = json.reason;
     }
     if (!decision && json.continue === false) {
@@ -147,8 +241,18 @@ export function translateResult(entry, result) {
     if (decision === 'deny') out.reason = reasonOr(reason, 'Blocked by hook');
     else if (typeof reason === 'string' && reason) out.reason = reason;
     if (decision !== 'deny' && specific.updatedInput && typeof specific.updatedInput === 'object') {
-      const renames = REVERSE[entry.dialect]?.[entry.toolName]?.[1] ?? {};
-      out.overwrite = renameKeys(specific.updatedInput, invert(renames));
+      if (entry.toolName === 'call_mcp_tool' || entry.toolName === 'mcp_tool') {
+        const rawArgs = entry.toolArgs && typeof entry.toolArgs === 'object' ? entry.toolArgs : {};
+        const argKey = 'Arguments' in rawArgs ? 'Arguments' : ('arguments' in rawArgs ? 'arguments' : 'Arguments');
+        const wasString = typeof rawArgs[argKey] === 'string';
+        out.overwrite = {
+          ...rawArgs,
+          [argKey]: wasString ? JSON.stringify(specific.updatedInput) : specific.updatedInput,
+        };
+      } else {
+        const renames = REVERSE[entry.dialect]?.[entry.toolName]?.[1] ?? {};
+        out.overwrite = renameKeys(specific.updatedInput, invert(renames));
+      }
     }
     return { stdout: JSON.stringify(out) };
   }
@@ -170,6 +274,59 @@ export function translateResult(entry, result) {
   return { stdout: '{}', ...(feedback ? { warning: `PostToolUse feedback dropped (agy has no channel for it): ${feedback}` } : {}) };
 }
 
+const POSIX_SHELL_RE = /\b(?:bash|sh)\s+|\.sh\b|\$\(|\/dev\/null\b|\bexport\s+[A-Za-z_]\w*=|^\s*\[[\s!]/;
+
+function hasPosixShebang(command, cwd) {
+  const m = /^\s*(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(command ?? '');
+  const token = m?.[1] ?? m?.[2] ?? m?.[3];
+  if (!token || /\.(?:exe|cmd|bat|ps1)$/i.test(token)) return false;
+  const candidate = isAbsolute(token) ? token : (cwd ? resolve(cwd, token) : token);
+  try {
+    if (!existsSync(candidate)) return false;
+    const head = readFileSync(candidate, 'utf8').slice(0, 128);
+    return /^#!\s*\//m.test(head);
+  } catch {
+    return false;
+  }
+}
+
+function findGitBash() {
+  const candidates = [
+    process.env.AGY_GIT_BASH,
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+    process.env.LOCALAPPDATA && resolve(process.env.LOCALAPPDATA, 'Programs\\Git\\bin\\bash.exe'),
+  ].filter(Boolean);
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+export function resolveHookSpawn(command, platform = process.platform, cwd = process.cwd()) {
+  if (platform === 'win32' && (POSIX_SHELL_RE.test(command) || hasPosixShebang(command, cwd))) {
+    const gitBash = findGitBash();
+    if (gitBash) {
+      return { file: gitBash, args: ['-c', command], shell: false };
+    }
+  }
+  return { file: command, args: [], shell: true };
+}
+
+function killProcessTree(child) {
+  if (!child?.pid) return;
+  try { child.stdout?.destroy(); } catch {}
+  try { child.stderr?.destroy(); } catch {}
+  try { child.stdin?.destroy(); } catch {}
+  if (process.platform === 'win32') {
+    try {
+      const tk = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+      tk.on('error', () => { try { child.kill(); } catch {} });
+      tk.unref();
+      return;
+    } catch {}
+  }
+  try { child.kill(); } catch {}
+}
+
 export function runCommand(command, { cwd, env, input, timeoutMs }) {
   return new Promise((resolve) => {
     let stdout = '';
@@ -182,9 +339,12 @@ export function runCommand(command, { cwd, env, input, timeoutMs }) {
       clearTimeout(timer);
       resolve({ stdout, stderr, ...extra });
     };
-    const timer = setTimeout(() => { child?.kill(); finish({ timedOut: true }); }, timeoutMs);
+    const timer = setTimeout(() => { killProcessTree(child); finish({ timedOut: true }); }, timeoutMs);
     try {
-      child = spawn(command, { cwd, env, shell: true, windowsHide: true });
+      const spec = resolveHookSpawn(command, process.platform, cwd);
+      child = spec.shell
+        ? spawn(spec.file, { cwd, env, shell: true, windowsHide: true })
+        : spawn(spec.file, spec.args, { cwd, env, windowsHide: true });
     } catch (err) {
       finish({ spawnError: err.message });
       return;
@@ -226,13 +386,16 @@ async function main() {
     const vars = entry.dialect === 'gemini'
       ? { extensionPath: pluginRoot, GEMINI_PROJECT_DIR: projectDir, CLAUDE_PROJECT_DIR: projectDir }
       : { CLAUDE_PLUGIN_ROOT: pluginRoot, CLAUDE_PROJECT_DIR: projectDir };
-    const result = await runCommand(expandCommand(entry.command, vars), {
+    const probeSpec = resolveHookSpawn(expandCommand(entry.command, vars, { posix: true }), process.platform, pluginRoot);
+    const usePosix = process.platform === 'win32' && !probeSpec.shell;
+    const envVars = usePosix ? Object.fromEntries(Object.entries(vars).map(([k, v]) => [k, v.replace(/\\/g, '/')])) : vars;
+    const result = await runCommand(expandCommand(entry.command, vars, { posix: usePosix }), {
       cwd: pluginRoot,
-      env: { ...process.env, ...vars },
+      env: { ...process.env, ...envVars },
       input: JSON.stringify(toSourcePayload(entry, payload)),
       timeoutMs: (entry.timeout ?? 60) * 1000,
     });
-    const translated = translateResult({ ...entry, toolName: payload.toolCall?.name }, result);
+    const translated = translateResult({ ...entry, toolName: payload.toolCall?.name, toolArgs: payload.toolCall?.args }, result);
     out = translated.stdout;
     if (translated.warning) warn(translated.warning);
   } catch (err) {
@@ -241,4 +404,15 @@ async function main() {
   process.stdout.write(out, () => process.exit(0));
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
+// Node resolves symlinks in the main module's URL but not in argv[1], so compare
+// real paths. Otherwise a plugin reached through a symlink (macOS's /var, a linked
+// home or .gemini) never runs its hooks.
+function isMain() {
+  try {
+    return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMain()) main();

package/scripts/mod-runtime/claude-code.mjs

@@ -0,0 +1,20 @@
+// Stand-in for the 'claude-code' module a TSX mod imports. Atoms live in the
+// conversation's $.state (engine.mjs), so they are per conversation, like Claude
+// Code's per-session state. derive and memberOf aren't used by the spike's mods.
+const key = (ref) => `${ref.plugin}/${ref.key}${ref.id === undefined ? '' : `#${ref.id}`}`;
+
+export const atom = (ref, initial, options) => Object.freeze({ ref: Object.freeze({ ...ref }), initial, shape: options?.shape });
+
+export async function read($, a) {
+  const value = await $.state.get(key(a.ref));
+  return value === undefined ? a.initial : value;
+}
+
+export async function update($, a, fn) {
+  const next = fn(await read($, a));
+  await $.state.set(key(a.ref), next);
+  return next;
+}
+
+export function derive() { throw new Error('derive is not available in the Antigravity port yet'); }
+export function memberOf() { throw new Error('memberOf is not available in the Antigravity port yet'); }

package/scripts/mod-runtime/elements.mjs

@@ -0,0 +1,35 @@
+// Element trees for a ported Claude Code mod. Mods compile against bare `h` and
+// `Fragment` (esbuild's classic JSX runtime), and get components from $.ui.resolve(e).
+// The view (ui-draw.js) decides how each element name is drawn.
+const normalize = (c) => (c == null || typeof c === 'boolean' ? [] : Array.isArray(c) ? c.flatMap(normalize)
+  : typeof c === 'number' ? [String(c)] : [c]);
+
+export const element = (type, props) => {
+  const { children, ...rest } = props ?? {};
+  return { type, props: rest, children: normalize(children) };
+};
+
+export function installJsxGlobals() {
+  globalThis.h = (tag, props, ...children) => {
+    const all = { ...(props ?? {}) };
+    if (children.length) all.children = children;
+    return typeof tag === 'function' ? tag(all) : element(String(tag), all);
+  };
+  globalThis.Fragment = (props) => element('Box', { flexDirection: 'column', ...props });
+}
+
+// $.ui.resolve(e): every element name is a constructor.
+export const ELEMENTS = new Proxy({}, {
+  get: (_, name) => (typeof name === 'string' && name !== 'then' ? (props) => element(name, props) : undefined),
+});
+
+// A tree as JSON for the view. Functions (onPress, onSubmit, ...) become {$cb: id}.
+export function serialize(node, cb) {
+  if (node == null || typeof node === 'boolean') return null;
+  if (typeof node === 'string' || typeof node === 'number') return String(node);
+  const kids = (list) => list.map((c) => serialize(c, cb)).filter((c) => c !== null);
+  if (Array.isArray(node)) return { type: 'Box', props: { flexDirection: 'column' }, children: kids(node) };
+  const props = {};
+  for (const [k, v] of Object.entries(node.props ?? {})) props[k] = typeof v === 'function' ? { $cb: cb(v) } : v;
+  return { type: node.type, props, children: kids(node.children ?? []) };
+}

package/scripts/mod-runtime/engine.mjs

@@ -0,0 +1,129 @@
+// Hosts a ported Claude Code mod for every Antigravity conversation: one Instance
+// per conversation, agy hook events mapped to the mod's events (plan §5.4), and the
+// MCP side (the mod's $.tool.register tools plus one slash_<name> tool per command).
+import { readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { installJsxGlobals } from './elements.mjs';
+import { Instance } from './instance.mjs';
+
+installJsxGlobals();
+
+export class Engine {
+  constructor({ mod, modUrl, dataDir, emit, visibleViews, log, preToolWaitMs = 1500, pendingMaxMs = 15 * 60_000 }) {
+    Object.assign(this, { mod, modUrl, emit, visibleViews, log, preToolWaitMs, pendingMaxMs });
+    this.options = mod.options ?? {};
+    this.instances = new Map();
+    const file = join(dataDir, 'store.json');
+    let data = {};
+    try { data = JSON.parse(readFileSync(file, 'utf8')); } catch {}
+    this.store = {
+      data: Object.assign(Object.create(null), data),
+      save() {
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        const payload = JSON.stringify(this.data, null, 2);
+        writeFileSync(tmp, payload);
+        try {
+          renameSync(tmp, file);
+        } catch {
+          try { writeFileSync(file, payload); } catch {}
+          try { rmSync(tmp, { force: true }); } catch {}
+        }
+      },
+    };
+  }
+
+  // The conversation's instance, loaded on first use. A cwd learned later reruns
+  // session.start, as a Claude Code reload does (live, Phase 2.5A).
+  async get(conv, cwd) {
+    // Hooks report C:\..., the view's workspace URI gives C:/...: use one spelling.
+    if (cwd && /^[A-Za-z]:[\\/]/.test(cwd)) cwd = cwd.replace(/\//g, '\\');
+    let entry = this.instances.get(conv);
+    if (!entry) {
+      const inst = new Instance(this, conv, cwd);
+      entry = { inst, ready: inst.load() };
+      this.instances.set(conv, entry);
+      this.log('instance', { conv, cwd: cwd ?? '' });
+    }
+    await entry.ready;
+    const { inst } = entry;
+    if (cwd && !inst.cwd) {
+      inst.cwd = cwd;
+      entry.ready = inst.dispatch('session.start', { cwd, source: 'resume' }, () => ({}));
+      await entry.ready;
+      inst.scheduleRender();
+    }
+    return inst;
+  }
+
+  // agy hook events, forwarded by hook.mjs. Returns what the hook prints.
+  async hook(event, payload) {
+    const inst = await this.get(typeof payload?.conversationId === 'string' ? payload.conversationId : '', payload?.workspacePaths?.[0]);
+    switch (event) {
+      case 'PreInvocation': {
+        // PreInvocation runs before every model call: only the first one of a turn
+        // starts it, and only that one adds prompt.context.
+        if (inst.inTurn) return { stdout: '{}' };
+        inst.inTurn = true;
+        await inst.dispatch('turn.start', {}, () => undefined);
+        return { stdout: await this.promptContext(inst) };
+      }
+      case 'PreToolUse': {
+        const { decision, path } = await inst.preToolUse(payload);
+        return { stdout: decision ? JSON.stringify(decision) : '', path };
+      }
+      case 'PostToolUse':
+        return { stdout: '{}', path: inst.postToolUse(payload) };
+      case 'Stop':
+        inst.dropPending('no PostToolUse before Stop');
+        await new Promise((r) => setImmediate(r));
+        inst.inTurn = false;
+        await inst.dispatch('turn.complete', { agentId: undefined }, () => undefined);
+        return { stdout: '{}' };
+      default:
+        return { stdout: '{}' };
+    }
+  }
+
+  // Only the systemMessage step is proven live. A step type agy doesn't know ends
+  // the whole agent turn (live: hookEphemeralMessage), so nothing else is emitted.
+  async promptContext(inst) {
+    if (!inst.has('prompt.context')) return '{}';
+    const r = await inst.dispatch('prompt.context', { blocks: [] }, (x) => ({ blocks: x.blocks }));
+    const text = (Array.isArray(r?.blocks) ? r.blocks : []).map((b) => b?.text).filter((t) => typeof t === 'string' && t).join('\n\n');
+    return text ? JSON.stringify({ injectSteps: [{ systemMessage: { systemMessage: text } }] }) : '{}';
+  }
+
+  async listTools() {
+    const inst = await this.get('');
+    const tools = [];
+    for (const t of inst.tools.values()) {
+      const full = `mcp__${this.mod.mcpServer}__${t.name}`;
+      const d = await inst.dispatch('tool.describe', { tool: full, description: t.description ?? '', inputSchema: t.inputSchema },
+        (x) => ({ description: x.description, inputSchema: x.inputSchema }));
+      tools.push({ name: t.name, description: d?.description ?? t.description ?? '', inputSchema: d?.inputSchema ?? t.inputSchema ?? { type: 'object', properties: {} } });
+    }
+    for (const c of inst.commands.values()) tools.push(commandTool(c));
+    return tools;
+  }
+
+  async callTool(conv, name, args) {
+    const inst = await this.get(conv ?? '');
+    if (name.startsWith('slash_')) return this.runCommand(inst, name.slice(6), args?.args ?? '', 'mcp');
+    const full = `mcp__${this.mod.mcpServer}__${name}`;
+    const r = await inst.dispatch('tool.call', { tool: full, ...args }, () => ({ deny: `${name} has no handler in this mod` }));
+    if (r?.deny) return { isError: true, text: String(r.deny) };
+    return { isError: false, text: typeof r?.result === 'string' ? r.result : JSON.stringify(r?.result ?? null) };
+  }
+
+  async runCommand(inst, command, args, from) {
+    const r = await inst.dispatch('command.run', { command, args: String(args ?? ''), from }, () => ({ text: `Unknown command /${command}` }));
+    return { isError: false, text: typeof r?.text === 'string' ? r.text : '' };
+  }
+}
+
+export const commandTool = (c) => ({
+  name: `slash_${c.name}`,
+  description: `Runs the /${c.name} command: ${c.description ?? ''}`.trim(),
+  inputSchema: { type: 'object', properties: { args: { type: 'string', description: `What follows /${c.name}${c.argumentHint ? ` (${c.argumentHint})` : ''}; empty for none.` } } },
+});

package/scripts/mod-runtime/hook.mjs

@@ -0,0 +1,24 @@
+// agy hook -> sidecar: `agy-node sidecars/<id>/hook.mjs <Event>`, cwd = plugin root
+// (live, Phase 2.5A). Prints what the sidecar answers. Fails open: if the sidecar is
+// down, slow or broken, it prints "no opinion" (nothing for PreToolUse, `{}`
+// otherwise) and exits 0, since agy fails a tool call on any nonzero PreToolUse exit
+// and reads `{}` from PreToolUse as a deny (live, agy-baseline.md).
+import { callSidecar } from './locate.mjs';
+
+const event = process.argv[2] || 'PreToolUse';
+const noOpinion = event === 'PreToolUse' ? '' : '{}';
+const finish = (out) => process.stdout.write(out, () => process.exit(0));
+process.on('uncaughtException', () => finish(noOpinion));
+setTimeout(() => finish(noOpinion), 4000).unref();
+
+let raw = '';
+for await (const chunk of process.stdin) raw += chunk;
+let payload = {};
+try { payload = JSON.parse(raw.replace(/^/, '') || '{}'); } catch {}
+try {
+  const r = await callSidecar('/api/hook', { event, payload });
+  finish(typeof r.stdout === 'string' ? r.stdout : noOpinion);
+} catch (err) {
+  process.stderr.write(`agy-porter mod hook: ${err.message}; not blocking\n`);
+  finish(noOpinion);
+}