@brainervirus/workit-core 8.1.1 → 8.4.0

package/src/forge/types.ts

@@ -140,6 +140,28 @@ export type MergeResult = {
   mergeSha: string | null;
 };
 
+/** The editable fields of a PR/MR (`workit pr ready|edit`). */
+export type PrMeta = {
+  number: number;
+  url: string;
+  state: PrState;
+  draft: boolean;
+  title: string;
+  base: string;
+  headBranch: string;
+};
+
+/** What `workit pr edit` changes; unset fields are left alone. */
+export type PrEdit = {
+  title?: string;
+  body?: string;
+  base?: string;
+  addLabels: string[];
+  removeLabels: string[];
+  /** Logins; on GitHub `org/team` requests a team. */
+  addReviewers: string[];
+};
+
 /** A repository as the forge sees it: id and the repo it was forked from. */
 export type RepoInfo = { id: number | null; parent: string | null };
 
@@ -163,4 +185,14 @@ export interface Forge {
   merge(n: number, options: { sha: string; method: MergeMethod }): ForgeResult<MergeResult>;
   /** Retarget a PR/MR to another base branch (S12 stacks). */
   updateBase(n: number, base: string): ForgeResult<void>;
+  /** Title, draft flag, base and state of one PR/MR. */
+  prMeta(n: number): ForgeResult<PrMeta>;
+  /** Mark a draft ready (`draft: false`) or convert it back to a draft. */
+  setDraft(n: number, draft: boolean): ForgeResult<void>;
+  editPr(n: number, edit: PrEdit): ForgeResult<void>;
+  /** Reply to a review thread (GitHub review thread id, GitLab discussion id). */
+  replyThread(n: number, thread: string, body: string): ForgeResult<{ url: string | null }>;
+  resolveThread(n: number, thread: string): ForgeResult<void>;
+  /** One review thread of PR `n` read directly: null when it is not on that PR. */
+  threadState(n: number, thread: string): ForgeResult<"open" | "resolved" | null>;
 }

package/src/hooks/handle.ts

@@ -2,6 +2,14 @@
 import { sessionContextText, turnContextText } from "./context";
 import type { HostDescriptor, Support } from "./descriptor";
 import { shellPolicy } from "./policy";
+import {
+  callKey,
+  NEXT_COMMAND,
+  noteRawCommit,
+  rawGitPost,
+  rawGitPre,
+  settlePendingCommit,
+} from "./raw-git";
 import { shellWrites, writeGate } from "./write-gate";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
@@ -74,13 +82,32 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       return text ? { kind: "context", text } : NONE;
     }
     case "shell.pre": {
-      const policy = usable(descriptor.shellPolicy.deny)
-        ? shellPolicy(input.cwd, event.command)
-        : NONE;
-      if (policy.kind !== "none" || !usable(descriptor.events["write.pre"].support)) return policy;
-      const writes = shellWrites(event.command);
-      return writes.writes ? writeGate(input.cwd, writes.targets) : NONE;
+      const canDeny = usable(descriptor.shellPolicy.deny);
+      const policy = canDeny ? shellPolicy(input.cwd, event.command) : NONE;
+      if (policy.kind !== "none") return policy;
+      // Without a post-tool event, the previous raw commit is recorded now.
+      const postTool = usable(descriptor.events["shell.post"].support);
+      if (!postTool) settlePendingCommit(input);
+      const raw = canDeny ? rawGitPre(input, event.command) : NONE;
+      if (raw.kind === "deny") return raw;
+      const writes = usable(descriptor.events["write.pre"].support)
+        ? shellWrites(event.command)
+        : { writes: false, targets: null };
+      const gate = writes.writes ? writeGate(input.cwd, writes.targets) : NONE;
+      if (gate.kind === "deny") return gate;
+      // The command will run: note HEAD so the post-tool hook (or the next
+      // command, without one) can tell whether a raw commit moved it.
+      noteRawCommit(
+        input,
+        event.command,
+        postTool ? callKey(event.toolUseId, event.command) : NEXT_COMMAND,
+      );
+      return raw;
     }
+    case "shell.post":
+      if (usable(descriptor.events["shell.post"].support))
+        rawGitPost(input, event.command, callKey(event.toolUseId, event.command));
+      return NONE;
     case "write.pre":
       return usable(descriptor.events["write.pre"].support)
         ? writeGate(input.cwd, event.paths)
@@ -99,7 +126,6 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     // Host permission policy owns other tools; attestation, prompt and stop
     // control arrive with the CLI-observed evidence model.
     case "tool.pre":
-    case "shell.post":
     case "subagent.stop":
     case "prompt.submit":
     case "stop":

package/src/hooks/hosts/claude-code.ts

@@ -135,6 +135,8 @@ type Parsed = { ok: true; event: HookEvent } | { ok: false; error: string };
 
 /** Claude's shell tools: Bash everywhere, PowerShell on Windows. */
 const SHELL_TOOLS = new Set(["Bash", "PowerShell"]);
+const dialectOf = (value: Record<string, unknown>) =>
+  value.tool_name === "PowerShell" ? ("powershell" as const) : ("posix" as const);
 const toolCommand = (value: Record<string, unknown>): string | null =>
   isRecord(value.tool_input) ? commandText(value.tool_input.command) : null;
 
@@ -163,7 +165,7 @@ const eventOf = (name: ClaudeHookEvent, value: Record<string, unknown>): Parsed
         return { ok: true, event: { kind: "tool.pre", tool: value.tool_name, toolUseId } };
       const command = toolCommand(value);
       return command
-        ? { ok: true, event: { kind: "shell.pre", command, toolUseId } }
+        ? { ok: true, event: { kind: "shell.pre", command, toolUseId, dialect: dialectOf(value) } }
         : { ok: false, error: `tool_input.command is required for ${value.tool_name}` };
     }
     case "PostToolUse": {
@@ -179,6 +181,7 @@ const eventOf = (name: ClaudeHookEvent, value: Record<string, unknown>): Parsed
           stdout: optionalText(response.stdout) ?? "",
           exitCode: typeof response.exit_code === "number" ? response.exit_code : null,
           toolUseId,
+          dialect: dialectOf(value),
         },
       };
     }
@@ -222,7 +225,14 @@ const eventOf = (name: ClaudeHookEvent, value: Record<string, unknown>): Parsed
   }
 };
 
-const CONTEXT_EVENTS = new Set(["SessionStart", "UserPromptSubmit", "SubagentStart"]);
+/** Events whose hookSpecificOutput takes additionalContext (PreToolUse: a raw-git nudge). */
+const CONTEXT_EVENTS = new Set([
+  "SessionStart",
+  "UserPromptSubmit",
+  "SubagentStart",
+  "PreToolUse",
+  "PostToolUse",
+]);
 
 /** Never emits `allow`: that would bypass the user's own permission prompt. */
 const render = (decision: HookDecision, native: string | null) => {

package/src/hooks/hosts/codex.ts

@@ -4,7 +4,12 @@ import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../pro
 import { commandText, existingDirectory, isRecord, nonEmpty, optionalText } from "./fields";
 
 export type CodexHost = "codex_cli" | "codex_desktop";
-export type CodexHookEvent = "SessionStart" | "PreToolUse" | "SubagentStart" | "SubagentStop";
+export type CodexHookEvent =
+  | "SessionStart"
+  | "PreToolUse"
+  | "PostToolUse"
+  | "SubagentStart"
+  | "SubagentStop";
 type SessionSource = "startup" | "resume" | "clear" | "compact";
 
 export type CodexHookInput = {
@@ -21,6 +26,8 @@ export type CodexHookInput = {
   /** The shell command as one string; argv arrays are joined. */
   command?: string;
   tool_use_id?: string;
+  /** PostToolUse: the model-facing tool output. */
+  tool_response?: string;
   agent_id?: string;
   agent_type?: string;
   agent_transcript_path?: string | null;
@@ -53,7 +60,7 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
     // Codex PreToolUse intercepts shell calls, not apply_patch edits: the
     // before-write gate stays advisory rather than half-enforced.
     "write.pre": { support: "undocumented", native: null },
-    "shell.post": undocumented,
+    "shell.post": { support: "native", native: "PostToolUse" },
     "subagent.start": { support: "native", native: "SubagentStart" },
     "subagent.stop": { support: "native", native: "SubagentStop" },
     "prompt.submit": undocumented,
@@ -74,7 +81,7 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
     worktreeIsolation: "undocumented",
     maxConcurrency: "undocumented",
   },
-  provenance: { sessionId: "native", agentIdOnTool: "partial", postToolObserve: "undocumented" },
+  provenance: { sessionId: "native", agentIdOnTool: "partial", postToolObserve: "native" },
   interaction: { questions: "none", writeBoundary: "partial" },
   stopControl: "undocumented",
   shellAvailable: "native",
@@ -146,6 +153,7 @@ export const codexDescriptor = (host: CodexHost): HostDescriptor => ({ ...CODEX_
 const EVENTS: Record<CodexHookEvent, HookEventKind> = {
   SessionStart: "session.start",
   PreToolUse: "shell.pre",
+  PostToolUse: "shell.post",
   SubagentStart: "subagent.start",
   SubagentStop: "subagent.stop",
 };
@@ -166,10 +174,10 @@ export const parseCodexHookInput = (value: unknown): CodexParseResult => {
   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 toolEvent = event === "PreToolUse" || event === "PostToolUse";
+  if (toolEvent && !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)
+  if (toolEvent && 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" };
@@ -188,7 +196,10 @@ export const parseCodexHookInput = (value: unknown): CodexParseResult => {
         : {}),
       ...(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 } : {}),
+      ...(toolEvent ? { tool_input: value.tool_input } : {}),
+      ...(event === "PostToolUse" && typeof value.tool_response === "string"
+        ? { tool_response: value.tool_response }
+        : {}),
       ...(command ? { command } : {}),
       ...(nonEmpty(value.tool_use_id) ? { tool_use_id: value.tool_use_id } : {}),
       ...(nonEmpty(value.agent_id) ? { agent_id: value.agent_id } : {}),
@@ -218,6 +229,20 @@ const protocolEvent = (input: CodexHookInput): HookEvent => {
           }
         : { kind: "tool.pre", tool: input.tool_name!, toolUseId };
     }
+    case "PostToolUse": {
+      const toolUseId = input.tool_use_id ?? null;
+      return isShellTool(input.tool_name)
+        ? {
+            kind: "shell.post",
+            command: input.command ?? "",
+            stdout: input.tool_response ?? "",
+            // Codex reports the model-facing output, not an exit code.
+            exitCode: null,
+            toolUseId,
+          }
+        : // A non-shell tool result carries nothing workit observes.
+          { kind: "tool.pre", tool: input.tool_name!, toolUseId };
+    }
     case "SubagentStart":
       return {
         kind: "subagent.start",
@@ -288,5 +313,5 @@ export const codexAdapter: HostAdapter = {
   },
   render,
   addendum: (input) =>
-    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. A verifier or reviewer records workit ledger verdict under a session the lead assigns (WORKIT_SESSION_ID=<lead>-v<n>), never the author's. Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
+    `<workit-codex-mutations>Codex MCP is read-only: unattested callers cannot mutate. Run workit verbs with the workit CLI on the shell (node_modules/.bin/workit, or npx -y @brainervirus/workit-cli): check, git branch|commit|push, pr, ci, stack, ledger, handoff; task-family mutations take --json${input.session.id ? ` --actor ${input.session.id}` : ""}. workit acts as this thread (CODEX_THREAD_ID${input.session.id ? `=${input.session.id}` : ""}) unless WORKIT_SESSION_ID is set. A verifier or reviewer records workit ledger verdict under a session the lead assigns (WORKIT_HOST=codex_cli WORKIT_SESSION_ID=<lead>-v<n>), never the author's. Merge and release need a workspace grant (workit grant show); a question answer is not host permission.</workit-codex-mutations>`,
 };

package/src/hooks/hosts/cursor.ts

@@ -77,8 +77,10 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
   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",
+  // 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",
@@ -278,6 +280,10 @@ const render = (decision: HookDecision, native: string | null) => {
       json: cursorDeny(decision.reason),
       exitCode: native !== null && BLOCKING.has(native) ? 2 : 0,
     };
+  // beforeShellExecution has no context channel: a raw-git nudge rides on
+  // agent_message next to Cursor's required permission answer.
+  if (decision.kind === "context" && native === "beforeShellExecution")
+    return { json: { permission: "allow", agent_message: decision.text }, exitCode: 0 };
   if (decision.kind === "context")
     return { json: { additional_context: decision.text }, exitCode: 0 };
   if (decision.kind === "notice")
@@ -319,4 +325,10 @@ export const cursorAdapter: HostAdapter = {
     };
   },
   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: prefix workit commands that record authorship with WORKIT_SESSION_ID=${input.session.id} (e.g. \`WORKIT_SESSION_ID=${input.session.id} workit git commit -m …\`). A verifier uses its own id, never this one.</workit-session>`
+      : null,
 };

package/src/hooks/index.ts

@@ -18,6 +18,7 @@ export {
 } from "./context";
 export { shellPolicy } from "./policy";
 export { shellWrites, writeGate } from "./write-gate";
+export { callKey, noteRawCommit, rawGitPost, rawGitPre } from "./raw-git";
 export { isWriteTool, writePaths } from "./hosts/fields";
 export { dispatchHook, failureDecision, handleHook, type HookDeps } from "./handle";
 export { HOOK_ADAPTERS, runHookProcess } from "./run";

package/src/hooks/protocol.ts

@@ -17,7 +17,13 @@ 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 }
+  | {
+      kind: "shell.pre";
+      command: string;
+      toolUseId: string | null;
+      /** The shell that runs `command`; posix when absent. */
+      dialect?: "posix" | "powershell";
+    }
   /** A pre-tool gate for a non-shell tool. Host permission policy owns these. */
   | { kind: "tool.pre"; tool: string; toolUseId: string | null }
   /** A file-writing tool (Edit, Write, apply_patch…): the before-write gate (S17). */
@@ -28,6 +34,7 @@ export type HookEvent =
       stdout: string;
       exitCode: number | null;
       toolUseId: string | null;
+      dialect?: "posix" | "powershell";
     }
   | { kind: "subagent.start"; agentId: string; agentType: string; task: string | null }
   | {