@brainervirus/workit-core 2.1.5 → 2.2.0

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-ai/plugin 1.18.30",
+  docs: ["https://opencode.ai/docs/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")' },
+    "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")' },
+    stop: { support: "partial", native: "session.idle" },
+  },
+  shellPolicy: { deny: "native", channel: "effect", failClosed: false },
+  context: {
+    sessionStart: "none",
+    perTurn: "native",
+    afterCompact: "native",
+    task: "session-bound",
+  },
+  subagents: {
+    identity: "native",
+    parentBinding: "native",
+    blockStart: "native",
+    worktreeIsolation: "undocumented",
+    maxConcurrency: "undocumented",
+  },
+  provenance: { sessionId: "native", agentIdOnTool: "native", postToolObserve: "native" },
+  interaction: { questions: "native", writeBoundary: "partial" },
+  stopControl: "partial",
+  shellAvailable: "native",
+  perEventCost: "low",
+  capabilities: [
+    {
+      name: "interactive_decision",
+      surface: "question",
+      refs: ["question"],
+      requires: ["interaction.questions"],
+      assurance: "enforced",
+      reason: "native question answers are observed by tool.execute.after and consumed once",
+    },
+    {
+      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,80 @@
+// 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 0.85.1",
+  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" },
+    "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" },
+    stop: { support: "none", native: null },
+  },
+  shellPolicy: { deny: "native", channel: "block", failClosed: false },
+  context: {
+    sessionStart: "native",
+    perTurn: "native",
+    afterCompact: "native",
+    task: "session-bound",
+  },
+  subagents: {
+    identity: "none",
+    parentBinding: "none",
+    blockStart: "none",
+    worktreeIsolation: "none",
+    maxConcurrency: "undocumented",
+  },
+  provenance: { sessionId: "native", agentIdOnTool: "none", postToolObserve: "native" },
+  interaction: { questions: "native", writeBoundary: "native" },
+  stopControl: "none",
+  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: "interactive_decision",
+      surface: "ui.confirm",
+      refs: ["ui.confirm"],
+      requires: ["interaction.questions"],
+      observed: ["ui"],
+      assurance: "enforced",
+      reason: "Pi supplies a native confirmation receipt when dialog UI is available.",
+      unavailableReason: "Pi is running without dialog UI, so required decisions need user input.",
+    },
+    {
+      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",
+    },
+  ],
+};

package/src/hooks/index.ts

@@ -0,0 +1,43 @@
+// Shared host-hook protocol. Hook bundles import this, not the core barrel.
+export * from "./protocol";
+export {
+  capabilitiesFor,
+  support,
+  type Axis,
+  type CapabilityRule,
+  type HostDescriptor,
+  type Support,
+} from "./descriptor";
+export {
+  currentTaskEntry,
+  sessionCompactContext,
+  sessionContextText,
+  turnContextText,
+  unfinishedTaskOffer,
+  type SessionHandle,
+} from "./context";
+export { shellPolicy } from "./policy";
+export { dispatchHook, failureDecision, handleHook, type HookDeps } from "./handle";
+export { HOOK_ADAPTERS, runHookProcess } from "./run";
+export { CLAUDE_CODE_DESCRIPTOR, claudeCodeAdapter } from "./hosts/claude-code";
+export {
+  CODEX_DESCRIPTOR,
+  codexAdapter,
+  codexDescriptor,
+  detectCodexSurface,
+  parseCodexHookInput,
+  type CodexHookEvent,
+  type CodexHookInput,
+  type CodexHost,
+} from "./hosts/codex";
+export {
+  CURSOR_DESCRIPTOR,
+  cursorAdapter,
+  cursorDeny,
+  cursorWorkspaceRoot,
+  parseCursorHookInput,
+  type CursorHookEvent,
+  type CursorHookInput,
+} from "./hosts/cursor";
+export { OPENCODE_DESCRIPTOR } from "./hosts/opencode";
+export { PI_DESCRIPTOR } from "./hosts/pi";

package/src/hooks/policy.ts

@@ -0,0 +1,14 @@
+import { shellBranchPolicyViolation } from "../core/route-intent";
+import type { HookDecision } from "./protocol";
+
+/**
+ * Branch policy for one shell command: only direct literal branch creation
+ * onto a noncompliant name is denied. Every other command keeps the host's own
+ * permission decision. The reason carries the policy's correction.
+ */
+export const shellPolicy = (cwd: string, command: string): HookDecision => {
+  const policy = shellBranchPolicyViolation(cwd, command);
+  return policy && !policy.ok
+    ? { kind: "deny", reason: `branch_policy_denied: ${policy.error}`, unblock: null }
+    : { kind: "none" };
+};

package/src/hooks/protocol.ts

@@ -0,0 +1,89 @@
+// The shared host-hook protocol: every host adapter parses its native payload
+// into a HookInput and renders a HookDecision back. Types only, no I/O.
+import type { HostDescriptor } from "./descriptor";
+
+export type HostId = "claude_code" | "opencode" | "codex_cli" | "codex_desktop" | "cursor" | "pi";
+
+export type Session = {
+  id: string;
+  agentId: string | null;
+  agentType: string | null;
+  parentId: string | null;
+};
+
+export type SessionSource = "startup" | "resume" | "clear" | "compact" | "fork";
+
+export type HookEvent =
+  | { kind: "session.start"; source: SessionSource }
+  /** Per-turn injection (OpenCode session context, Pi before_agent_start, Claude UserPromptSubmit). */
+  | { kind: "context.turn" }
+  | { kind: "shell.pre"; command: string; toolUseId: string | null }
+  /** A pre-tool gate for a non-shell tool. Host permission policy owns these. */
+  | { kind: "tool.pre"; tool: string; toolUseId: string | null }
+  | {
+      kind: "shell.post";
+      command: string;
+      stdout: string;
+      exitCode: number | null;
+      toolUseId: string | null;
+    }
+  | { kind: "subagent.start"; agentId: string; agentType: string; task: string | null }
+  | {
+      kind: "subagent.stop";
+      agentId: string | null;
+      agentType: string | null;
+      lastMessage: string | null;
+      stopHookActive: boolean;
+    }
+  | { kind: "prompt.submit"; prompt: string; source: string | null }
+  | { kind: "compact.pre"; trigger: "manual" | "auto" }
+  | { kind: "stop"; lastMessage: string | null; stopHookActive: boolean };
+
+export type HookEventKind = HookEvent["kind"];
+
+export const HOOK_EVENT_KINDS = [
+  "session.start",
+  "context.turn",
+  "shell.pre",
+  "tool.pre",
+  "shell.post",
+  "subagent.start",
+  "subagent.stop",
+  "prompt.submit",
+  "compact.pre",
+  "stop",
+] as const satisfies readonly HookEventKind[];
+
+export type HookInput = {
+  host: HostId;
+  cwd: string;
+  session: Session;
+  permissionMode: string | null;
+  transcriptPath: string | null;
+  event: HookEvent;
+};
+
+export type HookDecision =
+  | { kind: "none" }
+  /** Model-visible additional context. */
+  | { kind: "context"; text: string }
+  /** The reason text always carries its own correction (principle 3). */
+  | { kind: "deny"; reason: string; unblock: string | null }
+  /** Stop/SubagentStop: keep working. */
+  | { kind: "continue"; reason: string }
+  | { kind: "notice"; userMessage: string };
+
+/** A hook-process parse: the native event name is kept for rendering. */
+export type ParsedHook =
+  | { ok: true; input: HookInput; native: string }
+  | { ok: false; error: string; native: string | null; event: HookEventKind | null };
+
+export type RenderedHook = { json: Record<string, unknown>; exitCode: number };
+
+export type HostAdapter = {
+  descriptor: HostDescriptor;
+  parse(raw: unknown, env: NodeJS.ProcessEnv): ParsedHook;
+  render(decision: HookDecision, native: string | null): RenderedHook;
+  /** Host-specific lines appended inside the session-start contract. */
+  addendum?(input: HookInput): string | null;
+};

package/src/hooks/run.ts

@@ -0,0 +1,52 @@
+// Hook-process entry: stdin JSON → parse → handle → render → stdout.
+import { dispatchHook } from "./handle";
+import { claudeCodeAdapter } from "./hosts/claude-code";
+import { codexAdapter } from "./hosts/codex";
+import { cursorAdapter } from "./hosts/cursor";
+import type { HostAdapter, HostId } from "./protocol";
+
+type ProcessHost = Exclude<HostId, "opencode" | "pi">;
+
+export const HOOK_ADAPTERS: Record<ProcessHost, HostAdapter> = {
+  claude_code: claudeCodeAdapter,
+  codex_cli: codexAdapter,
+  codex_desktop: codexAdapter,
+  cursor: cursorAdapter,
+};
+
+type Sink = { write(chunk: string): unknown };
+
+/** Runs one hook invocation and returns the process exit code. A broken
+ * payload never throws: the host's fail policy decides what is written. */
+export async function runHookProcess(
+  host: ProcessHost | HostAdapter,
+  stdin: AsyncIterable<unknown> | Iterable<unknown>,
+  stdout: Sink,
+  stderr: Sink = process.stderr,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<number> {
+  const adapter = typeof host === "string" ? HOOK_ADAPTERS[host] : host;
+  let text = "";
+  for await (const chunk of stdin) text += String(chunk);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text || "{}");
+  } catch {
+    raw = undefined;
+  }
+  const result = dispatchHook(adapter, raw, env);
+  if (raw === undefined || result.error)
+    stderr.write(
+      `[workit] hook input rejected: ${raw === undefined ? "invalid JSON hook input" : result.error}\n`,
+    );
+  stdout.write(`${JSON.stringify(result.json)}\n`);
+  return result.exitCode;
+}
+
+if (import.meta.main) {
+  const host = process.argv[2] as ProcessHost;
+  if (!Object.hasOwn(HOOK_ADAPTERS, host)) {
+    process.stderr.write(`usage: run.ts <${Object.keys(HOOK_ADAPTERS).join("|")}>\n`);
+    process.exitCode = 64;
+  } else process.exitCode = await runHookProcess(host, process.stdin, process.stdout);
+}