@workit-dev/core 0.0.1 → 1.0.0

package/src/hooks/hosts/cursor.ts

@@ -0,0 +1,419 @@
+// Cursor: command hooks (hooks/hooks-cursor.json) mapped onto the protocol.
+import fs from "node:fs";
+import path from "node:path";
+import type { HostDescriptor } from "../descriptor";
+import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
+import { existingDirectory, isRecord, isWriteTool, nonEmpty, writeTargets } from "./fields";
+
+export type CursorHookEvent =
+  | "sessionStart"
+  | "preToolUse"
+  | "beforeShellExecution"
+  | "subagentStart"
+  | "subagentStop"
+  | "preCompact"
+  | "stop";
+
+export type CursorHookInput = {
+  hook_event_name: CursorHookEvent;
+  conversation_id?: string;
+  session_id?: string;
+  workspace_roots: string[];
+  tool_name?: string;
+  tool_input?: unknown;
+  command?: string;
+  cwd?: string;
+  subagent_id?: string;
+  subagent_type?: string;
+  parent_conversation_id?: string;
+  task?: string;
+  status?: "completed" | "error" | "aborted";
+  loop_count?: number;
+  transcript_path?: string;
+};
+
+export type CursorParseResult = { ok: true; data: CursorHookInput } | { ok: false; error: string };
+
+const undocumented = { support: "undocumented", native: null } as const;
+const none = { support: "none", native: null } as const;
+
+export const CURSOR_DESCRIPTOR: HostDescriptor = {
+  host: "cursor",
+  label: "Cursor",
+  verifiedAgainst: "Cursor hooks docs; payloads in test/fixtures/hooks/cursor",
+  docs: ["https://cursor.com/docs/agent/hooks"],
+  transport: "hook-process",
+  events: {
+    "session.start": { support: "native", native: "sessionStart" },
+    "context.turn": none,
+    "shell.pre": { support: "native", native: "beforeShellExecution" },
+    "tool.pre": { support: "native", native: "preToolUse" },
+    // preToolUse write tools; the file path is read from tool_input when present.
+    "write.pre": { support: "partial", native: "preToolUse" },
+    "shell.post": undocumented,
+    "subagent.start": { support: "native", native: "subagentStart" },
+    // subagentStop carries no stable child identity.
+    "subagent.stop": { support: "partial", native: "subagentStop" },
+    "prompt.submit": undocumented,
+    // preCompact can only show a user message.
+    "compact.pre": { support: "partial", native: "preCompact" },
+    // stop (cursor-agent 2026.09.26): `{"followup_message"}` queues one more
+    // user turn; the input carries loop_count and transcript_path, not the
+    // last message (read from transcript_path). Registered with
+    // `loop_limit: 1`, so the continuation's own stop never runs the hook.
+    stop: { support: "native", native: "stop" },
+  },
+  // Fails open like every host: a payload Workit cannot parse (a renamed
+  // field in a Cursor release) must not block every shell command.
+  shellPolicy: { deny: "native", channel: "exit2+json", failClosed: false, rewrite: "none" },
+  context: {
+    sessionStart: "native",
+    perTurn: "none",
+    afterCompact: "partial",
+    task: "single-active",
+    turnResend: "every-turn",
+  },
+  subagents: {
+    identity: "native",
+    parentBinding: "native",
+    blockStart: "native",
+    worktreeIsolation: "undocumented",
+    maxConcurrency: "undocumented",
+    agentPrefix: "workit-",
+  },
+  provenance: {
+    sessionId: "native",
+    agentIdOnTool: "undocumented",
+    postToolObserve: "undocumented",
+  },
+  interaction: { questions: "none", writeBoundary: "partial" },
+  stopControl: "native",
+  shellAvailable: "native",
+  // Hooks run the plugin's launcher against a local runtime (bundled dist or a
+  // global bin); only an install with neither falls back to a pinned,
+  // --prefer-offline npx.
+  perEventCost: "low",
+  capabilities: [
+    {
+      name: "known_product_writes",
+      surface: "preToolUse",
+      refs: ["preToolUse"],
+      requires: [],
+      assurance: "unavailable",
+      reason:
+        "file writes are host-policy; the Cursor hook no longer gates write tools or shell commands",
+    },
+    {
+      name: "native_subagents",
+      surface: "subagentStart/subagentStop",
+      refs: ["subagentStart", "subagentStop"],
+      requires: ["event:subagent.start", "event:subagent.stop"],
+      observed: ["subagent.start", "subagent.stop"],
+      assurance: "agent_guided",
+      reason:
+        "reviewer/investigator starts are bounded; Cursor implementer delegation is unavailable and subagentStop lacks a stable child identity",
+      unavailableReason: "Cursor native subagent lifecycle hooks are incomplete",
+    },
+    {
+      name: "native_subagent_start",
+      surface: "subagentStart",
+      refs: ["subagentStart"],
+      requires: ["event:subagent.start", "subagents.blockStart"],
+      observed: ["subagent.start"],
+      assurance: "enforced",
+      reason:
+        "Cursor subagentStart enforces explicit reviewer/investigator markers; implementer delegation is unavailable",
+      unavailableReason: "Cursor subagentStart is absent",
+    },
+    {
+      name: "fresh-context-review",
+      surface: "subagentStart",
+      refs: ["subagentStart"],
+      requires: ["event:subagent.start"],
+      observed: ["subagent.start"],
+      assurance: "agent_guided",
+      reason:
+        "independent review runs as a bounded reviewer subagent; stops lack stable identity, so reviewer exclusivity is evaluated from recorded evidence",
+      unavailableReason: "Cursor subagentStart is unavailable for independent review",
+    },
+    {
+      name: "arbitrary_shell_write",
+      surface: "unobservable_shell",
+      refs: ["beforeShellExecution"],
+      requires: [],
+      assurance: "unavailable",
+      reason:
+        "Only explicitly parsed shell targets are interceptable; arbitrary shell writes are not provable",
+    },
+    {
+      name: "compact_context",
+      surface: "sessionStart/preCompact",
+      refs: ["sessionStart", "preCompact"],
+      requires: ["context.sessionStart"],
+      observed: ["session.start"],
+      assurance: "agent_guided",
+      reason: "sessionStart injects context; preCompact can only show a bounded user reminder",
+    },
+  ],
+};
+
+const EVENTS: Record<CursorHookEvent, HookEventKind> = {
+  sessionStart: "session.start",
+  preToolUse: "tool.pre",
+  beforeShellExecution: "shell.pre",
+  subagentStart: "subagent.start",
+  subagentStop: "subagent.stop",
+  preCompact: "compact.pre",
+  stop: "stop",
+};
+
+/** Validate the keys each Cursor event needs; unknown keys are ignored. */
+export const parseCursorHookInput = (value: unknown): CursorParseResult => {
+  if (!isRecord(value) || !Object.hasOwn(EVENTS, String(value.hook_event_name)))
+    return { ok: false, error: "hook_event_name is required" };
+  const roots = value.workspace_roots;
+  if (!Array.isArray(roots) || roots.length === 0 || !roots.every(nonEmpty))
+    return { ok: false, error: "a workspace root is required" };
+  const canonical = roots.map(existingDirectory);
+  if (!canonical.every((root): root is string => root !== null))
+    return { ok: false, error: "workspace roots must be existing absolute paths" };
+  const event = value.hook_event_name as CursorHookEvent;
+  const conversationId = nonEmpty(value.conversation_id) ? value.conversation_id : undefined;
+  const sessionId = nonEmpty(value.session_id) ? value.session_id : undefined;
+  if (conversationId && sessionId && conversationId !== sessionId)
+    return { ok: false, error: "conversation_id and session_id must match" };
+  if (event !== "preCompact" && !nonEmpty(conversationId ?? sessionId))
+    return { ok: false, error: "conversation/session identity is required" };
+  if (
+    (event === "preToolUse" || event === "beforeShellExecution") &&
+    !nonEmpty(value.tool_name ?? value.command)
+  )
+    return { ok: false, error: "tool or command is required" };
+  if (
+    event === "subagentStart" &&
+    (!nonEmpty(value.subagent_id) || !nonEmpty(value.parent_conversation_id))
+  )
+    return { ok: false, error: "subagent identity and parent session are required" };
+  return {
+    ok: true,
+    data: {
+      hook_event_name: event,
+      workspace_roots: canonical,
+      ...(nonEmpty(value.conversation_id) ? { conversation_id: value.conversation_id } : {}),
+      ...(nonEmpty(value.session_id) ? { session_id: value.session_id } : {}),
+      ...(nonEmpty(value.tool_name) ? { tool_name: value.tool_name } : {}),
+      ...(value.tool_input !== undefined ? { tool_input: value.tool_input } : {}),
+      ...(nonEmpty(value.command) ? { command: value.command } : {}),
+      ...(nonEmpty(value.cwd) ? { cwd: value.cwd } : {}),
+      ...(event === "subagentStart" && nonEmpty(value.subagent_id)
+        ? { subagent_id: value.subagent_id }
+        : {}),
+      ...(event === "subagentStart" && nonEmpty(value.subagent_type)
+        ? { subagent_type: value.subagent_type }
+        : {}),
+      ...(event === "subagentStart" && nonEmpty(value.parent_conversation_id)
+        ? { parent_conversation_id: value.parent_conversation_id }
+        : {}),
+      ...(event === "subagentStart" && nonEmpty(value.task) ? { task: value.task } : {}),
+      ...(event === "stop"
+        ? {
+            ...(nonEmpty(value.status)
+              ? { status: value.status as CursorHookInput["status"] }
+              : {}),
+            ...(typeof value.loop_count === "number" ? { loop_count: value.loop_count } : {}),
+            ...(nonEmpty(value.transcript_path) ? { transcript_path: value.transcript_path } : {}),
+          }
+        : {}),
+    },
+  };
+};
+
+const protocolEvent = (input: CursorHookInput): HookEvent => {
+  switch (input.hook_event_name) {
+    case "sessionStart":
+      // Cursor reports no start source; every sessionStart is a fresh conversation.
+      return { kind: "session.start", source: "startup" };
+    case "beforeShellExecution":
+      // Branch policy reads the command alone; the shell's cwd does not change
+      // which branch name it targets.
+      return { kind: "shell.pre", command: input.command ?? "", toolUseId: null };
+    case "preToolUse":
+      return isWriteTool(input.tool_name)
+        ? {
+            kind: "write.pre",
+            tool: input.tool_name ?? "",
+            paths: writeTargets(input.tool_input),
+            toolUseId: null,
+          }
+        : { kind: "tool.pre", tool: input.tool_name ?? "", toolUseId: null };
+    case "subagentStart":
+      return {
+        kind: "subagent.start",
+        agentId: input.subagent_id!,
+        agentType: input.subagent_type ?? "",
+        task: input.task ?? null,
+      };
+    case "subagentStop":
+      return {
+        kind: "subagent.stop",
+        agentId: null,
+        agentType: null,
+        lastMessage: null,
+        stopHookActive: false,
+      };
+    case "preCompact":
+      return { kind: "compact.pre", trigger: "auto" };
+    case "stop":
+      return {
+        kind: "stop",
+        // Only a completed turn is continued; an aborted or failed one stops.
+        lastMessage:
+          (input.status ?? "completed") === "completed"
+            ? lastAssistantText(input.transcript_path)
+            : null,
+        // A followup_message turn reports loop_count > 0: one continue per turn.
+        stopHookActive: (input.loop_count ?? 0) > 0,
+      };
+  }
+};
+
+/** The transcript tail read for the last assistant message. */
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+/**
+ * The text of the last assistant entry in a Cursor agent transcript
+ * (`{"role":"assistant","message":{"content":[{"type":"text","text":…}]}}`
+ * per line), or null when it cannot be read.
+ */
+export const lastAssistantText = (file: string | null | undefined): string | null => {
+  if (!file || !path.isAbsolute(file)) return null;
+  try {
+    const size = fs.statSync(file).size;
+    const start = Math.max(0, size - TRANSCRIPT_TAIL_BYTES);
+    const buffer = Buffer.alloc(size - start);
+    const fd = fs.openSync(file, "r");
+    try {
+      fs.readSync(fd, buffer, 0, buffer.length, start);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const lines = buffer.toString("utf8").split("\n");
+    for (let index = lines.length - 1; index >= 0; index--) {
+      let entry: unknown;
+      try {
+        entry = JSON.parse(lines[index]);
+      } catch {
+        continue;
+      }
+      if (!isRecord(entry) || entry.role !== "assistant") continue;
+      const content = isRecord(entry.message) ? entry.message.content : entry.content;
+      if (typeof content === "string") return content;
+      if (!Array.isArray(content)) return null;
+      const text = content
+        .filter((part) => isRecord(part) && part.type === "text" && typeof part.text === "string")
+        .map((part) => (part as { text: string }).text)
+        .join("\n");
+      return text || null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+const within = (root: string, dir: string) =>
+  dir === root || dir.startsWith(root.endsWith(path.sep) ? root : `${root}${path.sep}`);
+
+/**
+ * Where a hook acts. Shell policy follows the command's own `cwd` (in a
+ * multi-root workspace each root is its own repository); everything else
+ * uses the workspace root that contains `cwd`, else the first root.
+ */
+const hookCwd = (input: CursorHookInput): string => {
+  const cwd = existingDirectory(input.cwd);
+  if (cwd && input.hook_event_name === "beforeShellExecution") return cwd;
+  return cursorWorkspaceRoot(input);
+};
+
+/** The workspace root that contains the payload `cwd`, else the first root. */
+export const cursorWorkspaceRoot = (input: CursorHookInput): string => {
+  const cwd = existingDirectory(input.cwd);
+  return (
+    (cwd && input.workspace_roots.find((root) => within(root, cwd))) || input.workspace_roots[0]
+  );
+};
+
+/** Cursor's documented deny payload; blocking events also exit 2. */
+export const cursorDeny = (reason: string) => ({
+  permission: "deny" as const,
+  user_message: "Workit blocked this action",
+  agent_message: reason,
+});
+const BLOCKING = new Set(["preToolUse", "beforeShellExecution", "subagentStart"]);
+
+const render = (decision: HookDecision, native: string | null) => {
+  if (decision.kind === "deny")
+    return {
+      json: cursorDeny(decision.reason),
+      exitCode: native !== null && BLOCKING.has(native) ? 2 : 0,
+    };
+  if (decision.kind === "ask" && native !== null && BLOCKING.has(native))
+    return {
+      json: { permission: "ask", user_message: decision.reason, agent_message: decision.reason },
+      exitCode: 0,
+    };
+  // beforeShellExecution has no context channel: a raw-git nudge rides on
+  // agent_message with no permission answer, so Cursor's own permissions
+  // decide the command (#635).
+  if (decision.kind === "context" && native === "beforeShellExecution")
+    return { json: { agent_message: decision.text }, exitCode: 0 };
+  if (decision.kind === "context")
+    return { json: { additional_context: decision.text }, exitCode: 0 };
+  if (decision.kind === "notice")
+    return { json: { user_message: decision.userMessage }, exitCode: 0 };
+  if (decision.kind === "continue" && native === "stop")
+    return { json: { followup_message: decision.reason }, exitCode: 0 };
+  // Workit answers only what it decides (deny, ask); anything else omits
+  // `permission`, which cursor-agent (2026.09.26) treats like no hook at all
+  // and the user's allowlist and auto-run settings decide (#635).
+  return { json: {}, exitCode: 0 };
+};
+
+export const cursorAdapter: HostAdapter = {
+  descriptor: CURSOR_DESCRIPTOR,
+  parse(raw) {
+    const parsed = parseCursorHookInput(raw);
+    if (!parsed.ok) {
+      const native =
+        isRecord(raw) && Object.hasOwn(EVENTS, String(raw.hook_event_name))
+          ? (raw.hook_event_name as CursorHookEvent)
+          : null;
+      return { ok: false, error: parsed.error, native, event: native ? EVENTS[native] : null };
+    }
+    const input = parsed.data;
+    return {
+      ok: true,
+      native: input.hook_event_name,
+      input: {
+        host: "cursor",
+        cwd: hookCwd(input),
+        session: {
+          id: input.session_id ?? input.conversation_id ?? "",
+          agentId: input.subagent_id ?? null,
+          agentType: input.subagent_type ?? null,
+          parentId: input.parent_conversation_id ?? null,
+        },
+        permissionMode: null,
+        transcriptPath: null,
+        event: protocolEvent(input),
+      },
+    };
+  },
+  render,
+  // Cursor's shell carries no conversation id (sessionStart env reaches hooks
+  // only), so the agent is told the id its `workit` calls should act as.
+  addendum: (input) =>
+    input.session.id
+      ? `<workit-session>Cursor puts no session id in the shell: start workit commands that record authorship with the global flag \`--session ${input.session.id}\` (e.g. \`workit --session ${input.session.id} git commit -m …\`; a leading env assignment can miss the \`Shell(workit)\` allowlist). A verifier uses its own id, never this one.</workit-session>`
+      : null,
+};

package/src/hooks/hosts/fields.ts

@@ -0,0 +1,98 @@
+// Lenient field readers for native hook payloads (D17): unknown keys are
+// ignored, and only the keys a mapping needs are checked.
+import { existsSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const nonEmpty = (value: unknown): value is string =>
+  typeof value === "string" && value.trim() !== "";
+
+export const optionalText = (value: unknown): string | null =>
+  typeof value === "string" ? value : null;
+
+/** The canonical path of an existing absolute directory, or null. */
+export const existingDirectory = (value: unknown): string | null => {
+  if (!nonEmpty(value) || !path.isAbsolute(value) || !existsSync(value)) return null;
+  try {
+    return statSync(value).isDirectory() ? realpathSync(value) : null;
+  } catch {
+    return null;
+  }
+};
+
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "pwsh", "powershell", "cmd"]);
+/** `-c`, `-lc`, `-ec`…, PowerShell `-Command`, and cmd `/c`. */
+const SCRIPT_FLAG = /^(?:-\w*c|-command|\/c)$/i;
+const quoteArg = (arg: string) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : JSON.stringify(arg));
+
+/**
+ * A shell command as one string. Hosts send either a string or an argv array.
+ * For a shell wrapper (`[bash, -e, -c, script]`, `[powershell.exe, -Command,
+ * script]`, `[cmd, /c, script]`) the script after the first script flag is
+ * the command; other arrays are joined with quoting so one argument never splits.
+ */
+export const commandText = (value: unknown): string | null => {
+  if (nonEmpty(value)) return value;
+  if (!Array.isArray(value) || value.length === 0) return null;
+  const argv: unknown[] = value;
+  if (!argv.every((arg): arg is string => typeof arg === "string")) return null;
+  const shell =
+    argv[0]
+      .split(/[\\/]/)
+      .at(-1)
+      ?.replace(/\.exe$/i, "")
+      .toLowerCase() ?? "";
+  if (SHELLS.has(shell))
+    for (let index = 1; index < argv.length - 1; index++) {
+      if (SCRIPT_FLAG.test(argv[index])) return nonEmpty(argv[index + 1]) ? argv[index + 1] : null;
+      // Other options may precede the script flag; a positional ends the scan.
+      if (!/^[-/]/.test(argv[index])) break;
+    }
+  const joined = argv.map(quoteArg).join(" ");
+  return nonEmpty(joined) ? joined : null;
+};
+
+const WRITE_TOOLS = new Set([
+  "write",
+  "edit",
+  "multiedit",
+  "notebookedit",
+  "applypatch",
+  "patch",
+  "delete",
+  "remove",
+  "rename",
+  "mkdir",
+  "mv",
+  "cp",
+  "touch",
+  "strreplace",
+  "searchreplace",
+  "editfile",
+  "writefile",
+]);
+/** A host tool that writes files (Claude Edit/Write, Cursor Write/Delete, apply_patch…). */
+export const isWriteTool = (name: unknown): boolean =>
+  typeof name === "string" && WRITE_TOOLS.has(name.toLowerCase().replace(/[_-]/g, ""));
+
+const PATH_KEYS = ["file_path", "filePath", "notebook_path", "path", "target_file", "file"];
+/** apply_patch file headers. Codex trims patch lines, so an indented header still applies. */
+const PATCH_HEADER = /^[ \t]*\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$/gm;
+
+/** The files a write tool names: its path fields, or the files of an apply_patch body. */
+export const writePaths = (input: unknown): string[] => {
+  if (!isRecord(input)) return [];
+  const paths = PATH_KEYS.map((key) => input[key]).filter(nonEmpty);
+  for (const value of Object.values(input))
+    if (typeof value === "string")
+      for (const match of value.matchAll(PATCH_HEADER)) paths.push(match[1].trim());
+  return [...new Set(paths)];
+};
+
+/** A write tool's targets for the before-write gate: null (unknown, so gated) when none parse. */
+export const writeTargets = (input: unknown): string[] | null => {
+  const paths = writePaths(input);
+  return paths.length > 0 ? paths : null;
+};

package/src/hooks/hosts/opencode.ts

@@ -0,0 +1,79 @@
+// OpenCode V2: an in-process plugin; hooks call core/hooks functions directly.
+import type { HostDescriptor } from "../descriptor";
+
+export const OPENCODE_DESCRIPTOR: HostDescriptor = {
+  host: "opencode",
+  label: "OpenCode",
+  verifiedAgainst: "@opencode/plugin 2.0.18",
+  docs: ["https://opencode.ai/v2/docs/build/plugins/"],
+  transport: "in-process-plugin",
+  events: {
+    // No separate start event: context is injected on every agent-loop call.
+    "session.start": { support: "none", native: null },
+    "context.turn": { support: "native", native: 'session.hook("context")' },
+    "shell.pre": { support: "native", native: 'permission.hook("evaluate")' },
+    "tool.pre": { support: "native", native: 'tool.hook("execute.before")' },
+    "write.pre": { support: "native", native: 'permission.hook("evaluate")' },
+    "shell.post": { support: "native", native: 'tool.hook("execute.after")' },
+    "subagent.start": { support: "native", native: 'tool.hook("execute.before") subagent' },
+    "subagent.stop": { support: "native", native: 'tool.hook("execute.after") subagent' },
+    "prompt.submit": { support: "undocumented", native: null },
+    "compact.pre": { support: "native", native: 'session.hook("compaction")' },
+    // No stop hook: the plugin's event subscription sees session.idle and
+    // resumes the session with `ctx.session.synthetic({resume: true})`
+    // (@opencode/client 2.0.18). Partial: the continuation lands after the
+    // session went idle, and resume semantics are inferred from the schema.
+    stop: { support: "partial", native: 'event("session.idle")' },
+  },
+  shellPolicy: { deny: "native", channel: "effect", failClosed: false, rewrite: "native" },
+  context: {
+    sessionStart: "none",
+    perTurn: "native",
+    afterCompact: "native",
+    task: "session-bound",
+    // The context hook rebuilds the system prompt on every agent-loop call.
+    turnResend: "every-turn",
+  },
+  subagents: {
+    identity: "native",
+    parentBinding: "native",
+    blockStart: "native",
+    worktreeIsolation: "undocumented",
+    maxConcurrency: "undocumented",
+    agentPrefix: "workit-",
+  },
+  provenance: { sessionId: "native", agentIdOnTool: "native", postToolObserve: "native" },
+  interaction: { questions: "native", writeBoundary: "partial" },
+  stopControl: "partial",
+  shellAvailable: "native",
+  perEventCost: "low",
+  capabilities: [
+    {
+      name: "known_product_writes",
+      surface: "edit/shell",
+      refs: ["permission.evaluate"],
+      requires: [],
+      assurance: "unavailable",
+      reason:
+        "file writes are host-policy; OpenCode native permissions govern them, workit no longer gates write tools",
+    },
+    {
+      name: "direct_child_workers",
+      surface: "subagent",
+      refs: ["subagent"],
+      requires: ["subagents.parentBinding", "subagents.blockStart"],
+      assurance: "enforced",
+      reason:
+        "nested subagent launches are denied and observed child sessions are parent-bound before they may own a worker",
+    },
+    {
+      name: "fresh-context-review",
+      surface: "subagent",
+      refs: ["subagent"],
+      requires: ["event:subagent.start"],
+      assurance: "agent_guided",
+      reason:
+        "independent review runs as a native child session; evidence evaluation enforces creator and duplicate-reviewer exclusion",
+    },
+  ],
+};

package/src/hooks/hosts/pi.ts

@@ -0,0 +1,78 @@
+// Pi: an in-process extension; its events call core/hooks functions directly.
+import type { HostDescriptor } from "../descriptor";
+
+export const PI_DESCRIPTOR: HostDescriptor = {
+  host: "pi",
+  label: "Pi",
+  verifiedAgainst: "@earendil-works/pi-coding-agent 1.4.0",
+  docs: ["https://github.com/earendil-works/pi-coding-agent"],
+  transport: "in-process-plugin",
+  events: {
+    "session.start": { support: "native", native: "session_start" },
+    "context.turn": { support: "native", native: "before_agent_start" },
+    "shell.pre": { support: "native", native: "tool_call" },
+    "tool.pre": { support: "native", native: "tool_call" },
+    "write.pre": { support: "native", native: "tool_call" },
+    "shell.post": { support: "native", native: "tool_result" },
+    // Workers are supervised stock-Pi processes, not host subagents.
+    "subagent.start": { support: "none", native: null },
+    "subagent.stop": { support: "none", native: null },
+    "prompt.submit": { support: "undocumented", native: null },
+    "compact.pre": { support: "native", native: "session_before_compact" },
+    // agent_end carries the run's messages; pi.sendMessage(…, {triggerTurn})
+    // starts one more turn (pi-coding-agent 1.4.0 types.d.ts). The host has
+    // no loop guard: the extension continues at most once per run.
+    stop: { support: "native", native: "agent_end" },
+  },
+  shellPolicy: { deny: "native", channel: "block", failClosed: false, rewrite: "native" },
+  context: {
+    sessionStart: "native",
+    // before_agent_start runs every turn; its message stays in the session,
+    // so the extension resends the task context only when it changed.
+    perTurn: "native",
+    afterCompact: "native",
+    task: "session-bound",
+    turnResend: "on-change",
+  },
+  subagents: {
+    identity: "none",
+    parentBinding: "none",
+    blockStart: "none",
+    worktreeIsolation: "none",
+    maxConcurrency: "undocumented",
+    agentPrefix: "workit-",
+  },
+  provenance: { sessionId: "native", agentIdOnTool: "none", postToolObserve: "native" },
+  interaction: { questions: "native", writeBoundary: "native" },
+  stopControl: "native",
+  shellAvailable: "native",
+  perEventCost: "low",
+  capabilities: [
+    {
+      name: "product_write_interception",
+      surface: "write/edit tool_call",
+      refs: ["tool_call"],
+      requires: ["interaction.writeBoundary"],
+      assurance: "enforced",
+      reason:
+        "Pi exposes a before-tool boundary for known built-in write tools; it enforces project trust while file targets stay host-policy.",
+    },
+    {
+      name: "arbitrary_shell_write",
+      surface: "bash",
+      refs: ["tool_call"],
+      requires: ["shellAvailable"],
+      assurance: "agent_guided",
+      reason: "Pi extensions do not sandbox arbitrary shell commands.",
+    },
+    {
+      name: "fresh-context-review",
+      surface: "supervised_worker",
+      refs: ["worker"],
+      requires: [],
+      assurance: "agent_guided",
+      reason:
+        "independent review runs as a supervised stock-Pi process; evidence evaluation enforces reviewer exclusivity",
+    },
+  ],
+};