@brainervirus/workit-core 2.1.5 → 2.2.0

package/src/hooks/hosts/codex.ts

@@ -0,0 +1,298 @@
+// Codex CLI and Desktop: command hooks (hooks/hooks.json) mapped onto the protocol.
+import type { HostDescriptor } from "../descriptor";
+import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
+import { commandText, existingDirectory, isRecord, nonEmpty, optionalText } from "./fields";
+
+export type CodexHost = "codex_cli" | "codex_desktop";
+export type CodexHookEvent = "SessionStart" | "PreToolUse" | "SubagentStart" | "SubagentStop";
+type SessionSource = "startup" | "resume" | "clear" | "compact";
+
+export type CodexHookInput = {
+  hook_event_name: CodexHookEvent;
+  session_id: string;
+  cwd: string;
+  model: string | null;
+  permission_mode: string | null;
+  transcript_path: string | null;
+  source?: SessionSource;
+  turn_id?: string;
+  tool_name?: string;
+  tool_input?: unknown;
+  /** The shell command as one string; argv arrays are joined. */
+  command?: string;
+  tool_use_id?: string;
+  agent_id?: string;
+  agent_type?: string;
+  agent_transcript_path?: string | null;
+  last_assistant_message?: string | null;
+  stop_hook_active?: boolean;
+};
+
+export type CodexParseResult = { ok: true; data: CodexHookInput } | { ok: false; error: string };
+
+export function detectCodexSurface(env: NodeJS.ProcessEnv): CodexHost {
+  return env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE === "Codex Desktop" ||
+    Boolean(env.CODEX_ELECTRON_RESOURCES_PATH)
+    ? "codex_desktop"
+    : "codex_cli";
+}
+
+const undocumented = { support: "undocumented", native: null } as const;
+
+export const CODEX_DESCRIPTOR: HostDescriptor = {
+  host: "codex_cli",
+  label: "Codex",
+  verifiedAgainst: "codex-cli 0.153.4; Codex Desktop 26.901.20858",
+  docs: ["https://developers.openai.com/codex/hooks"],
+  transport: "hook-process",
+  events: {
+    "session.start": { support: "native", native: "SessionStart" },
+    "context.turn": undocumented,
+    "shell.pre": { support: "native", native: "PreToolUse" },
+    "tool.pre": { support: "native", native: "PreToolUse" },
+    "shell.post": undocumented,
+    "subagent.start": { support: "native", native: "SubagentStart" },
+    "subagent.stop": { support: "native", native: "SubagentStop" },
+    "prompt.submit": undocumented,
+    "compact.pre": { support: "none", native: null },
+    stop: undocumented,
+  },
+  shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
+  context: {
+    sessionStart: "native",
+    perTurn: "undocumented",
+    afterCompact: "native",
+    task: "single-active",
+  },
+  subagents: {
+    identity: "native",
+    parentBinding: "none",
+    blockStart: "none",
+    worktreeIsolation: "undocumented",
+    maxConcurrency: "undocumented",
+  },
+  provenance: { sessionId: "native", agentIdOnTool: "partial", postToolObserve: "undocumented" },
+  interaction: { questions: "none", writeBoundary: "partial" },
+  stopControl: "undocumented",
+  shellAvailable: "native",
+  perEventCost: "low",
+  capabilities: [
+    {
+      name: "interactive_decision",
+      surface: "Question",
+      refs: ["Question"],
+      requires: [],
+      assurance: "agent_guided",
+      reason: "Codex hooks expose no native arbitrary-question answer receipt",
+    },
+    {
+      name: "known_product_writes",
+      surface: "PreToolUse",
+      refs: ["PreToolUse"],
+      requires: [],
+      assurance: "unavailable",
+      reason: "file writes are host-policy; PreToolUse allows write tools",
+    },
+    {
+      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 subagent; evidence evaluation enforces reviewer exclusivity, and stops remain untrusted",
+      unavailableReason: "Codex subagent lifecycle hooks are unavailable for independent review",
+    },
+    {
+      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: "Codex reports stable child identities, but cannot block creation or bind a writer",
+      unavailableReason: "Codex subagent lifecycle hooks are untrusted or incomplete",
+    },
+    {
+      name: "native_subagent_start",
+      surface: "SubagentStart",
+      refs: ["SubagentStart"],
+      requires: ["event:subagent.start"],
+      observed: ["subagent.start"],
+      assurance: "agent_guided",
+      reason:
+        "SubagentStart supplies identity and bounded read-only guidance; continue:false cannot stop creation",
+      unavailableReason: "SubagentStart hook is untrusted or unavailable",
+    },
+    {
+      name: "arbitrary_shell_write",
+      surface: "unobservable_shell",
+      refs: ["PreToolUse"],
+      requires: [],
+      assurance: "unavailable",
+      reason:
+        "Only covered known tool inputs are interceptable; specialized and write_stdin paths are not complete",
+    },
+    {
+      name: "compact_context",
+      surface: "SessionStart",
+      refs: ["SessionStart"],
+      requires: ["context.afterCompact"],
+      observed: ["session.start"],
+      assurance: "agent_guided",
+      reason: "SessionStart source=compact is the single restore path",
+    },
+  ],
+};
+
+export const codexDescriptor = (host: CodexHost): HostDescriptor => ({ ...CODEX_DESCRIPTOR, host });
+
+const EVENTS: Record<CodexHookEvent, HookEventKind> = {
+  SessionStart: "session.start",
+  PreToolUse: "shell.pre",
+  SubagentStart: "subagent.start",
+  SubagentStop: "subagent.stop",
+};
+const SHELL_TOOLS = new Set(["bash", "unified-exec"]);
+const isShellTool = (name: unknown) => SHELL_TOOLS.has(String(name).toLowerCase());
+const SOURCES = new Set<string>(["startup", "resume", "clear", "compact"]);
+
+/**
+ * Read a Codex payload, checking only what each mapping needs (D17): the
+ * event and cwd always, the shell command for shell tools, the tool name for
+ * PreToolUse, and the agent id for SubagentStart. Every other field is
+ * optional, and unknown keys or values (a new permission mode, say) are
+ * ignored, so a Codex release can never turn branch policy off.
+ */
+export const parseCodexHookInput = (value: unknown): CodexParseResult => {
+  if (!isRecord(value) || !Object.hasOwn(EVENTS, String(value.hook_event_name)))
+    return { ok: false, error: "hook_event_name is required" };
+  const event = value.hook_event_name as CodexHookEvent;
+  const cwd = existingDirectory(value.cwd);
+  if (!cwd) return { ok: false, error: "cwd must be an existing absolute directory" };
+  if (event === "PreToolUse" && !nonEmpty(value.tool_name))
+    return { ok: false, error: "tool_name is required" };
+  const command = isRecord(value.tool_input) ? commandText(value.tool_input.command) : null;
+  if (event === "PreToolUse" && isShellTool(value.tool_name) && !command)
+    return { ok: false, error: "tool_input.command is required for shell tools" };
+  if (event === "SubagentStart" && !nonEmpty(value.agent_id))
+    return { ok: false, error: "agent_id is required" };
+  return {
+    ok: true,
+    data: {
+      hook_event_name: event,
+      session_id: nonEmpty(value.session_id) ? value.session_id : "",
+      model: optionalText(value.model),
+      permission_mode: optionalText(value.permission_mode),
+      transcript_path: optionalText(value.transcript_path),
+      cwd,
+      // An unknown start source restores context but never offers history.
+      ...(event === "SessionStart"
+        ? { source: SOURCES.has(String(value.source)) ? (value.source as SessionSource) : "resume" }
+        : {}),
+      ...(nonEmpty(value.turn_id) ? { turn_id: value.turn_id } : {}),
+      ...(nonEmpty(value.tool_name) ? { tool_name: value.tool_name } : {}),
+      ...(event === "PreToolUse" ? { tool_input: value.tool_input } : {}),
+      ...(command ? { command } : {}),
+      ...(nonEmpty(value.tool_use_id) ? { tool_use_id: value.tool_use_id } : {}),
+      ...(nonEmpty(value.agent_id) ? { agent_id: value.agent_id } : {}),
+      ...(nonEmpty(value.agent_type) ? { agent_type: value.agent_type } : {}),
+      ...(event === "SubagentStop"
+        ? {
+            agent_transcript_path: optionalText(value.agent_transcript_path),
+            last_assistant_message: optionalText(value.last_assistant_message),
+            stop_hook_active: value.stop_hook_active === true,
+          }
+        : {}),
+    },
+  };
+};
+
+const protocolEvent = (input: CodexHookInput): HookEvent => {
+  switch (input.hook_event_name) {
+    case "SessionStart":
+      return { kind: "session.start", source: input.source! };
+    case "PreToolUse": {
+      const toolUseId = input.tool_use_id ?? null;
+      return isShellTool(input.tool_name)
+        ? {
+            kind: "shell.pre",
+            command: input.command ?? "",
+            toolUseId,
+          }
+        : { kind: "tool.pre", tool: input.tool_name!, toolUseId };
+    }
+    case "SubagentStart":
+      return {
+        kind: "subagent.start",
+        agentId: input.agent_id!,
+        agentType: input.agent_type ?? "unknown",
+        task: null,
+      };
+    case "SubagentStop":
+      return {
+        kind: "subagent.stop",
+        agentId: input.agent_id ?? null,
+        agentType: input.agent_type ?? null,
+        lastMessage: input.last_assistant_message ?? null,
+        stopHookActive: input.stop_hook_active ?? false,
+      };
+  }
+};
+
+const output = (event: string, extra: Record<string, unknown> = {}) => ({
+  hookSpecificOutput: { hookEventName: event, ...extra },
+});
+
+const render = (decision: HookDecision, native: string | null) => {
+  if (native === "SubagentStop" || native === null) return { json: {}, exitCode: 0 };
+  if (decision.kind === "deny")
+    return {
+      json: output(native, {
+        permissionDecision: "deny",
+        permissionDecisionReason: decision.reason,
+      }),
+      exitCode: 0,
+    };
+  if (decision.kind === "context")
+    return { json: output(native, { additionalContext: decision.text }), exitCode: 0 };
+  return { json: output(native), exitCode: 0 };
+};
+
+export const codexAdapter: HostAdapter = {
+  descriptor: CODEX_DESCRIPTOR,
+  parse(raw, env) {
+    const host = detectCodexSurface(env);
+    const parsed = parseCodexHookInput(raw);
+    if (!parsed.ok) {
+      const native =
+        isRecord(raw) && Object.hasOwn(EVENTS, String(raw.hook_event_name))
+          ? (raw.hook_event_name as CodexHookEvent)
+          : 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,
+        cwd: input.cwd,
+        session: {
+          id: input.session_id,
+          agentId: input.agent_id ?? null,
+          agentType: input.agent_type ?? null,
+          parentId: null,
+        },
+        permissionMode: input.permission_mode,
+        transcriptPath: input.transcript_path,
+        event: protocolEvent(input),
+      },
+    };
+  },
+  render,
+  // Without a session id there is no actor to bind a writer to.
+  addendum: (input) =>
+    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run the workit CLI for task mutations: node_modules/.bin/workit <family> <action> --json --confirm${input.session.id ? `; bind the writer to this session with node_modules/.bin/workit writer acquire --task <id> --revision <rev> --actor ${input.session.id} --confirm` : ""}. Binding decisions and external actions need a human.</workit-codex-mutations>`,
+};

package/src/hooks/hosts/cursor.ts

@@ -0,0 +1,321 @@
+// Cursor: command hooks (hooks/hooks-cursor.json) mapped onto the protocol.
+import path from "node:path";
+import type { HostDescriptor } from "../descriptor";
+import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
+import { existingDirectory, isRecord, nonEmpty } from "./fields";
+
+export type CursorHookEvent =
+  | "sessionStart"
+  | "preToolUse"
+  | "beforeShellExecution"
+  | "subagentStart"
+  | "subagentStop"
+  | "preCompact";
+
+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";
+};
+
+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" },
+    "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: undocumented,
+  },
+  shellPolicy: { deny: "native", channel: "exit2+json", failClosed: true },
+  context: {
+    sessionStart: "native",
+    perTurn: "none",
+    afterCompact: "partial",
+    task: "single-active",
+  },
+  subagents: {
+    identity: "native",
+    parentBinding: "native",
+    blockStart: "native",
+    worktreeIsolation: "undocumented",
+    maxConcurrency: "undocumented",
+  },
+  provenance: {
+    sessionId: "native",
+    agentIdOnTool: "undocumented",
+    postToolObserve: "undocumented",
+  },
+  interaction: { questions: "none", writeBoundary: "partial" },
+  stopControl: "undocumented",
+  shellAvailable: "native",
+  // Every hook spawns `npx -y --prefer-online …@latest`: a registry round-trip per event.
+  perEventCost: "npx-network",
+  capabilities: [
+    {
+      name: "interactive_decision",
+      surface: "AskQuestion",
+      refs: ["AskQuestion"],
+      requires: [],
+      assurance: "agent_guided",
+      reason: "Cursor does not expose AskQuestion answers to Workit hooks or MCP",
+    },
+    {
+      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",
+};
+
+/** 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 } : {}),
+    },
+  };
+};
+
+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 { 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" };
+  }
+};
+
+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 === "context")
+    return { json: { additional_context: decision.text }, exitCode: 0 };
+  if (decision.kind === "notice")
+    return { json: { user_message: decision.userMessage }, exitCode: 0 };
+  return {
+    json: native !== null && BLOCKING.has(native) ? { permission: "allow" } : {},
+    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,
+};

package/src/hooks/hosts/fields.ts

@@ -0,0 +1,55 @@
+// 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;
+};