@brainervirus/workit-core 8.15.1 → 8.17.0

package/src/core/resources.ts

@@ -20,6 +20,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { tailLines, type CheckRun } from "../checks";
+import { stateDir } from "./heavy";
+
+export { stateDir };
+export {
+  probeScope,
+  scopePrefix,
+  scopeSupport,
+  type ScopeProbe,
+  type ScopeSupport,
+} from "./heavy-scope";
 
 /** Named checks that take the lease when nothing is configured. */
 export const DEFAULT_HEAVY_CHECKS = ["test", "build", "typecheck"];
@@ -183,17 +193,6 @@ export function resolveResourceSettings(
 // ---------------------------------------------------------------------------
 // the machine lease
 
-/** Workit's state dir for `env` (the logger's resolution, over an explicit env). */
-export function stateDir(env: NodeJS.ProcessEnv, platform: NodeJS.Platform = process.platform) {
-  if (env.WORKFLOW_TOOLKIT_STATE) return env.WORKFLOW_TOOLKIT_STATE;
-  if (env.XDG_STATE_HOME) return path.join(env.XDG_STATE_HOME, "workit");
-  const home = env.HOME || os.homedir();
-  if (platform === "darwin") return path.join(home, "Library", "Application Support", "workit");
-  if (platform === "win32")
-    return path.join(env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "workit");
-  return path.join(home, ".local", "state", "workit");
-}
-
 export const leaseDir = (env: NodeJS.ProcessEnv): string => path.join(stateDir(env), "leases");
 
 export type LeaseRecord = {
@@ -588,71 +587,6 @@ export function describeHolder(holder: LeaseHolder, now = Date.now()): string {
   return `${holder.check}, pid ${holder.pid}${holder.session ? `, session ${holder.session}` : ""}, ${age}, ${holder.cwd}`;
 }
 
-// ---------------------------------------------------------------------------
-// the systemd user scope
-
-export type ScopeSupport = { ok: true } | { ok: false; reason: string };
-
-const onPath = (command: string, env: NodeJS.ProcessEnv): boolean =>
-  (env.PATH ?? "")
-    .split(path.delimiter)
-    .filter(Boolean)
-    .some((dir) => {
-      try {
-        fs.accessSync(path.join(dir, command), fs.constants.X_OK);
-        return true;
-      } catch {
-        return false;
-      }
-    });
-
-/**
- * Can heavy checks run in their own `systemd-run --user --scope`? Needs Linux,
- * `systemd-run` on PATH, a running user manager, and the memory and cpu
- * controllers delegated to it (cgroup v2).
- */
-export function scopeSupport(
-  env: NodeJS.ProcessEnv,
-  platform: NodeJS.Platform = process.platform,
-  read: (file: string) => string | null = readText,
-): ScopeSupport {
-  if (platform !== "linux") return { ok: false, reason: `no systemd scopes on ${platform}` };
-  if (!onPath("systemd-run", env)) return { ok: false, reason: "systemd-run is not on PATH" };
-  const uid = process.getuid?.() ?? 0;
-  const runtime = env.XDG_RUNTIME_DIR || `/run/user/${uid}`;
-  if (!fs.existsSync(path.join(runtime, "systemd", "private")))
-    return { ok: false, reason: "no user systemd manager is running" };
-  const controllers = read(
-    `/sys/fs/cgroup/user.slice/user-${uid}.slice/user@${uid}.service/cgroup.controllers`,
-  );
-  if (controllers === null)
-    return { ok: false, reason: "cgroup v2 is not mounted for the user manager" };
-  const missing = ["memory", "cpu"].filter((name) => !controllers.split(/\s+/u).includes(name));
-  if (missing.length)
-    return { ok: false, reason: `the user manager is not delegated ${missing.join(" and ")}` };
-  return { ok: true };
-}
-
-/** The `systemd-run` prefix that runs a command in its own limited scope. */
-export function scopePrefix(
-  unit: string,
-  settings: Pick<ResourceSettings, "memoryMax" | "cpuQuota">,
-) {
-  return [
-    "systemd-run",
-    "--user",
-    "--scope",
-    "--quiet",
-    "--collect",
-    `--unit=${unit}`,
-    "-p",
-    `MemoryMax=${settings.memoryMax}`,
-    "-p",
-    `CPUQuota=${settings.cpuQuota}`,
-    "--",
-  ];
-}
-
 /** systemd-run's own failure before it ran the command (bus, unit, property). */
 const SCOPE_START_FAILURE =
   /^Failed to (?:connect to bus|create bus connection|start transient scope unit|parse \S+?=)/u;
@@ -745,3 +679,25 @@ export function firstNotice(
   }
   return true;
 }
+
+export type SlotState = {
+  slot: number;
+  /** The lease in this slot, or null when it is free. */
+  holder: LeaseHolder | null;
+  /** Why the lease in it no longer holds (the next acquirer reclaims it). */
+  stale: string | null;
+};
+
+/** What each of `slots` lease slots holds right now. Read-only: nothing is reclaimed. */
+export function leaseSlots(dir: string, slots: number, probe: LeaseProbe = {}): SlotState[] {
+  const states: SlotState[] = [];
+  for (let slot = 0; slot < slots; slot += 1) {
+    const lease = parseLease(readText(path.join(dir, `slot-${slot}.json`)));
+    states.push({
+      slot,
+      holder: lease ? holderOf(lease) : null,
+      stale: lease ? staleReason(lease, probe) : null,
+    });
+  }
+  return states;
+}

package/src/core/task-contract.ts

@@ -823,6 +823,27 @@ export const taskSummarySchema = z
   })
   .strict();
 export type TaskSummary = z.infer<typeof taskSummarySchema>;
+/** Bounded `inspect` projection (`view: "summary"`): under 4 KB however long the task history is. */
+export type TaskBrief = {
+  id: string;
+  revision: string;
+  workspaceRevision: string;
+  updatedAt: string;
+  objective: string;
+  status: TaskSummary["status"];
+  closure: { outcome: Closure["outcome"]; at: string; summary: string } | null;
+  progress: {
+    summary: string;
+    nextAction: string | null;
+    blockers: { reason: string; dependentAction: string }[];
+  };
+  requirements: {
+    total: number;
+    unmet: number;
+    open: { dimension: Dimension; before: string; status: RequirementEvaluation["status"] }[];
+  };
+  truncated: boolean;
+};
 export const taskListItemSchema = taskSummarySchema
   .omit({ policy: true, requirements: true })
   .extend({ source: provenanceSchema.pick({ host: true, kind: true }) })

package/src/core/task-engine.ts

@@ -35,6 +35,7 @@ import {
   type Result,
   type Scope,
   type TaskRecord,
+  type TaskBrief,
   type TaskListItem,
   type TaskSummary,
   type TaskView,
@@ -81,6 +82,7 @@ import {
   type NativeWorkerVerifier,
 } from "./workers";
 import {
+  boundTaskSummary,
   captureCandidate,
   checkPin,
   signalFreshness,
@@ -115,6 +117,8 @@ export type OperationContext = {
   now: Utc | (() => Utc);
   nativeWorker?: NativeWorkerVerifier;
   workerId?: string | null;
+  /** A child session with no worker record: it may only read the bounded task summary. */
+  readOnlyChild?: boolean;
 };
 
 export type ObserveCheckRequest = {
@@ -872,19 +876,27 @@ export class WorkitCore {
     return failure("invalid_input", "unknown state action");
   }
 
-  task(request: unknown): Result<TaskSummary | TaskListItem[] | TaskView> {
+  task(request: unknown): Result<TaskSummary | TaskBrief | TaskListItem[] | TaskView> {
     const resolved = this.implicitTask("task", request);
     if (!resolved.ok) return resolved;
     const value = resolved.data;
     return this.retryOmittedRevisions(value, () => this.taskOnce(value));
   }
 
-  private taskOnce(request: unknown): Result<TaskSummary | TaskListItem[] | TaskView> {
+  private taskOnce(request: unknown): Result<TaskSummary | TaskBrief | TaskListItem[] | TaskView> {
     const root = this.contextRootError();
     if (!root.ok) return root;
     const parsed = parseOperation("task", request);
     if (!parsed.ok) return parsed;
     const input = parsed.data;
+    if (this.context.readOnlyChild) {
+      if (input.action !== "inspect")
+        return failure("permission_denied", "child sessions can only inspect the task summary");
+      const task = this.store.readTask(input.taskId);
+      if (!task.ok) return task;
+      const summary = this.summary(task.data);
+      return summary.ok ? { ...summary, data: boundTaskSummary(summary.data) } : summary;
+    }
     if ((this.context.workerId ?? null) !== null) {
       if (input.action !== "inspect" && input.action !== "list")
         return failure("permission_denied", "helpers cannot control task lifecycle or scope");

package/src/core/task-evaluation.ts

@@ -18,6 +18,8 @@ import {
   type EvidenceEvaluation,
   type Outcome,
   type Requirement,
+  type TaskBrief,
+  type TaskSummary,
   type Result,
   type Scope,
   type TaskRecord,
@@ -1074,3 +1076,72 @@ export function evaluateClosure(
     requirementIds: evaluations.map((item) => item.requirementId),
   });
 }
+
+export const TASK_BRIEF_MAX_BYTES = 4096;
+const BRIEF_TEXT = 250;
+const BRIEF_BLOCKERS = 3;
+const BRIEF_OPEN = 8;
+
+/** Cut `value` until its JSON-escaped form fits `BRIEF_TEXT` bytes. */
+const clip = (value: string): string => {
+  const fits = (text: string) => Buffer.byteLength(JSON.stringify(text)) <= BRIEF_TEXT;
+  if (fits(value)) return value;
+  let length = Math.min(value.length, BRIEF_TEXT);
+  while (length > 0 && !fits(`${value.slice(0, length)}…`)) length -= 1;
+  return `${value.slice(0, length)}…`;
+};
+
+/**
+ * Bound a task summary for `inspect --view summary`: text is clipped, lists
+ * capped and the policy reduced to the requirements still owed, so the JSON
+ * stays under {@link TASK_BRIEF_MAX_BYTES} however long the task history is.
+ */
+export function boundTaskSummary(summary: TaskSummary): TaskBrief {
+  const rules = new Map((summary.policy?.requirements ?? []).map((item) => [item.id, item]));
+  const unmet = summary.requirements.filter(
+    (item) => item.status === "unsatisfied" || item.status === "unavailable",
+  );
+  const { progress, closure } = summary;
+  const next = progress.nextAction;
+  const open = unmet.slice(0, BRIEF_OPEN).map((item) => ({
+    dimension: rules.get(item.requirementId)?.dimension ?? "verification",
+    before: rules.get(item.requirementId)?.before ?? "close",
+    status: item.status,
+  }));
+  const brief: TaskBrief = {
+    id: summary.id,
+    revision: summary.revision,
+    workspaceRevision: summary.workspaceRevision,
+    updatedAt: summary.updatedAt,
+    objective: clip(summary.objective),
+    status: summary.status,
+    closure: closure && {
+      outcome: closure.outcome,
+      at: closure.at,
+      summary: clip(closure.summary),
+    },
+    progress: {
+      summary: clip(progress.summary),
+      nextAction: next && clip(next),
+      blockers: progress.blockers.slice(0, BRIEF_BLOCKERS).map((item) => ({
+        reason: clip(item.reason),
+        dependentAction: clip(item.dependentAction),
+      })),
+    },
+    requirements: { total: summary.requirements.length, unmet: unmet.length, open },
+    truncated: false,
+  };
+  brief.truncated =
+    JSON.stringify(brief).includes("…") ||
+    progress.blockers.length > BRIEF_BLOCKERS ||
+    unmet.length > BRIEF_OPEN;
+  return brief;
+}
+
+/** For a child or unattested caller: `task inspect` with the summary view returns the brief. */
+export function briefInspectResult(request: unknown, result: Result<unknown>): Result<unknown> {
+  const { action, view } = (request ?? {}) as { action?: unknown; view?: unknown };
+  return result.ok && action === "inspect" && (view ?? "summary") === "summary"
+    ? { ...result, data: boundTaskSummary(result.data as TaskSummary) }
+    : result;
+}

package/src/core/workspaces.ts

@@ -143,6 +143,13 @@ const workspaceConfigSchema = z
     defaultEndpoint: z.unknown().optional(),
     /** How a normal-risk behavior change is verified (S17); same rules as grants. */
     verification: z.enum(["self", "independent"]).optional(),
+    /**
+     * Who does the work (skills and `fanout plan` read it): `inline-first`
+     * (default) keeps the lead working itself and refuses a slice without a
+     * reason to delegate; `lead-orchestrates` allows slices without one.
+     * Read leniently (workspaceDelegation): an unknown value reads as unset.
+     */
+    delegation: z.unknown().optional(),
     /**
      * Whether commits get the `Workit-Session:` trailer (default true). With
      * `false`, `workit git commit` and the session hook write none and
@@ -766,6 +773,21 @@ export const workspaceLiveSessionGuard = (cwd: string, dir?: string): boolean =>
   inheritedSetting(cwd, dir, (entry) => typeof entry.liveSessionGuard === "boolean")?.source
     ?.liveSessionGuard !== false;
 
+export const DELEGATION_MODES = ["inline-first", "lead-orchestrates"] as const;
+export type DelegationMode = (typeof DELEGATION_MODES)[number];
+
+const isDelegation = (value: unknown): value is DelegationMode =>
+  (DELEGATION_MODES as readonly unknown[]).includes(value);
+
+/**
+ * The workspace's `delegation` mode, default `inline-first`; inherited like
+ * `trailers`. A value this version does not know reads as unset.
+ */
+export const workspaceDelegation = (cwd: string, dir?: string): DelegationMode => {
+  const source = inheritedSetting(cwd, dir, (entry) => isDelegation(entry.delegation))?.source;
+  return isDelegation(source?.delegation) ? source.delegation : "inline-first";
+};
+
 const hostFamily = (host: string): string => host.replace(/_(?:cli|desktop)$/u, "");
 
 const TIER_KEYS = new Set(["mundane", "standard", "hard"]);

package/src/fanout-brief.ts

@@ -112,6 +112,7 @@ const rules = (
       ? '  3. Commit with plain `git commit -m <msg> --trailer "Workit-Session: <the WORKIT_SESSION_ID in your env>" --trailer "<your host attribution trailer>" -- <paths in SCOPE>`; push only if this brief says so.'
       : "  3. Commit with `workit git commit -m <msg> -- <paths in SCOPE>`; push only if this brief says so.",
     "  4. Never record a verdict on your own work.",
+    "  5. Run tests, lint, typecheck and builds only through `workit check` (a named check, or `workit check --heavy -- <cmd>`): one machine-wide lease queues every agent, so never a hand-made flock; `workit lock status` shows who holds it.",
   ];
 };
 
@@ -210,6 +211,7 @@ export function renderBrief(
     "ACCEPTANCE:",
     ...slice.acceptance.map((line) => `  - ${line}`),
     `VERIFY: ${slice.verify.join("; ")}`,
+    ...(slice.reason ? [`REASON: ${slice.reason}`] : []),
     `TIER: ${slice.tier}`,
     ...(model
       ? [`  model: ${model.model}  (fanout.tierModels in workspace ${model.workspace})`]

package/src/fanout.ts

@@ -20,7 +20,7 @@
 //
 // Each slice's `hash` covers what it is (goal, acceptance, verify, forbidden,
 // scope, owns, branch, base, dependencies), not how it is briefed (tier,
-// timebox, context, issues) or where its worktree goes. A re-plan that changes a
+// reason, timebox, context, issues) or where its worktree goes. A re-plan that changes a
 // slice starts a new run for that slice alone: its `hashSince` moves to now,
 // and only ledger rows recorded under its hash (worktree rows carry
 // `sliceHash`) or since then link a gone branch's merged PR to it or count as
@@ -45,6 +45,7 @@ import {
   storeRoot,
   type LedgerActor,
 } from "./ledger";
+import { workspaceDelegation, type DelegationMode } from "./core/workspaces";
 import { stackFileName } from "./stack";
 
 export const FANOUT_VERSION = 1;
@@ -58,6 +59,8 @@ export type Slice = {
   base: string;
   worktree: string;
   tier: Tier;
+  /** Why this work is delegated; required under `delegation: inline-first`. */
+  reason: Reason | null;
   dependsOn: string[];
   /** The file-scope manifest: globs (`*`, `**`, `?`, `{a,b}`) relative to the repo root. */
   scope: string[];
@@ -77,6 +80,10 @@ export type Slice = {
   hashSince: string;
 };
 
+/** Why a slice is delegated at all (the brief's REASON line). */
+export const REASONS = ["explore", "parallel", "backstop", "high-risk-verify"] as const;
+export type Reason = (typeof REASONS)[number];
+
 export const FAN_IN_MODES = ["prs", "integration"] as const;
 export type FanInMode = (typeof FAN_IN_MODES)[number];
 
@@ -321,6 +328,8 @@ export type PlanDefaults = {
   root: string;
   /** Where default worktrees go: `<repo>-wt/` next to the main checkout. */
   worktreeRoot: string;
+  /** Under inline-first (the default when absent), a slice needs a reason. */
+  delegation?: DelegationMode;
 };
 
 type Parsed = { ok: true; plan: FanoutFile } | { ok: false; problems: string[] };
@@ -405,6 +414,15 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
     const tier = item.tier;
     if (typeof tier !== "string" || !(TIERS as readonly string[]).includes(tier))
       problems.push(`${where}: tier must be one of ${TIERS.join(", ")}`);
+    const rawReason = typeof item.reason === "string" ? item.reason.trim() : item.reason;
+    let reason: Reason | null = null;
+    if (rawReason === undefined || rawReason === null || rawReason === "") {
+      if ((defaults.delegation ?? "inline-first") === "inline-first")
+        problems.push(
+          `${where}: reason is empty; delegation is inline-first, so name why this is delegated: ${REASONS.join(", ")} (or set delegation to lead-orchestrates in the workspace)`,
+        );
+    } else if ((REASONS as readonly unknown[]).includes(rawReason)) reason = rawReason as Reason;
+    else problems.push(`${where}: reason must be one of ${REASONS.join(", ")}`);
     const dependsOn = textList(item.dependsOn ?? []);
     if (dependsOn === null) problems.push(`${where}: dependsOn must be a list of slice ids`);
     const issues = textList(item.issue ?? []);
@@ -420,6 +438,7 @@ export function parsePlan(raw: unknown, defaults: PlanDefaults, name?: string |
         optional("worktree") ?? path.join(defaults.worktreeRoot, id),
       ),
       tier: tier as Tier,
+      reason,
       dependsOn: [...new Set(dependsOn ?? [])],
       scope,
       owns,
@@ -782,7 +801,7 @@ export const planLeads = (
 
 /**
  * sha256 (16 hex) of the slice's definition. Brief-only fields (tier,
- * timebox, context, issues) and the worktree path are left out, so fixing a typo in
+ * reason, timebox, context, issues) and the worktree path are left out, so fixing a typo in
  * them never re-dispatches landed work.
  */
 export function sliceHash(slice: Slice): string {
@@ -791,6 +810,7 @@ export function sliceHash(slice: Slice): string {
     hash: _hash,
     hashSince: _since,
     tier: _tier,
+    reason: _reason,
     timebox: _timebox,
     context: _context,
     issues: _issues,
@@ -839,6 +859,9 @@ function parseStored(raw: unknown): FanoutFile | null {
       base: text(item.base) || raw.trunk,
       worktree: text(item.worktree),
       tier: (TIERS as readonly unknown[]).includes(item.tier) ? (item.tier as Tier) : "standard",
+      reason: (REASONS as readonly unknown[]).includes(item.reason)
+        ? (item.reason as Reason)
+        : null,
       dependsOn: list(item.dependsOn),
       scope: globs(item.scope),
       owns: globs(item.owns),
@@ -1043,6 +1066,7 @@ export function planFanout(
       trunk: input.trunk ?? defaultTrunk(cwd),
       root: mainCheckout(cwd),
       worktreeRoot: worktreeRoot(cwd),
+      delegation: workspaceDelegation(cwd),
     },
     input.name,
   );

package/src/hooks/descriptor.ts

@@ -19,6 +19,8 @@ export type HostDescriptor = {
     channel: "permissionDecision" | "exit2+json" | "effect" | "block" | null;
     /** A parse or handler failure on a pre-tool gate denies instead of passing. */
     failClosed: boolean;
+    /** The pre-shell hook can replace the command before it runs (the heavy-command lease). */
+    rewrite: Support;
   };
   context: {
     sessionStart: Support;

package/src/hooks/handle.ts

@@ -9,6 +9,7 @@ import type { HostDescriptor, Support } from "./descriptor";
 import { branchGuidance } from "../core/branch";
 import { workspaceTrailers } from "../core/workspaces";
 import { recordIssuedSession } from "../host-session";
+import { heavyDenial, heavyGate, rewriteNote, splitDenial } from "./heavy-gate";
 import { shellPolicy } from "./policy";
 import {
   callKey,
@@ -162,6 +163,19 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         ? shellGate(input.cwd, event.command, liveOwner(input, descriptor.transport), event.dialect)
         : NONE;
       if (gate.kind === "deny") return gate;
+      // A heavy command runs under the machine lease: rewritten where the
+      // host can replace the command, else denied with the exact rewrite.
+      // Every gate above passed on the original command (ruling mvid5onk).
+      const plan = heavyGate(input.cwd, event.command, {
+        host: input.host,
+        dialect: event.dialect,
+        permissionMode: input.permissionMode,
+      });
+      if (plan.kind === "split" && canDeny) return splitDenial(plan);
+      const rewrites = usable(descriptor.shellPolicy.rewrite);
+      if (plan.kind === "rewrite" && !rewrites && canDeny) return heavyDenial(event.command, plan);
+      const lease = plan.kind === "rewrite" && rewrites ? plan : null;
+      const aside = plan.kind === "passthrough" ? plan.note : null;
       // 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(
@@ -169,13 +183,28 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
         event.command,
         postTool ? callKey(event.toolUseId, event.command) : NEXT_COMMAND,
       );
+      const rewritten = (text: string | null): HookDecision =>
+        lease
+          ? {
+              kind: "rewrite",
+              command: lease.command,
+              input: event.toolInput ? { ...event.toolInput, command: lease.command } : null,
+              text,
+            }
+          : NONE;
       // An in-process plugin shows nudges on the tool result (shellNudge):
       // spending the once-per-session nudge here would lose it.
-      if (descriptor.transport !== "hook-process") return NONE;
-      return withContextLine(
-        canDeny ? rawGitPre(input, event.command) : NONE,
+      if (descriptor.transport !== "hook-process") return rewritten(null);
+      const nudged = withContextLine(
+        withContextLine(canDeny ? rawGitPre(input, event.command) : NONE, aside),
         shipNudge(input, event.command),
       );
+      if (!lease) return nudged;
+      return rewritten(
+        [rewriteNote(lease), nudged.kind === "context" ? nudged.text : null]
+          .filter(Boolean)
+          .join("\n"),
+      );
     }
     case "shell.post":
       if (usable(descriptor.events["shell.post"].support))

package/src/hooks/heavy-gate.ts

@@ -0,0 +1,91 @@
+// The heavy-command gate (issue #325, ruling mvid5onk): after every Workit
+// gate passed on the original command, a raw heavy command (tests, builds,
+// lint, typecheck, installs; core/heavy.ts) runs under the machine-wide
+// heavy-check lease:
+//   - one simple heavy command: rewritten to `workit check --heavy -- <cmd>`
+//     where the host can replace it (Claude Code, OpenCode, Pi), else denied
+//     with that exact command (Codex, Cursor);
+//   - a chain with heavy parts: denied, naming each part's lease command
+//     (never `bash -c`);
+//   - a command a host permission rule names, or one whose wrapper only an
+//     allow for `workit` would let through: left alone, with a note.
+import {
+  claudeRules,
+  codexRules,
+  cursorRules,
+  opencodeRules,
+  type RuleRead,
+} from "../core/heavy-rules";
+import { heavyPlan, workitOnPath, type HeavyPlan } from "../core/heavy";
+import { maybeHeavy } from "../core/heavy-words";
+import type { HookDecision, HostId } from "./protocol";
+import type { ShellDialect } from "./shell-words";
+
+/** The host's readable permission rules (null where it keeps none the hook could read). */
+const rulesFor = (host: HostId, cwd: string, env: NodeJS.ProcessEnv): RuleRead | null => {
+  switch (host) {
+    case "claude_code":
+      return claudeRules(cwd, env);
+    case "opencode":
+      return opencodeRules(cwd, env);
+    case "codex_cli":
+    case "codex_desktop":
+      return codexRules(cwd, env);
+    case "cursor":
+      return cursorRules(cwd, env);
+    case "pi":
+      return null;
+  }
+};
+
+export type GateOptions = {
+  host: HostId;
+  dialect?: ShellDialect;
+  /** Claude `permission_mode`: bypassPermissions skips the allowlist check. */
+  permissionMode?: string | null;
+  env?: NodeJS.ProcessEnv;
+};
+
+/**
+ * The gate's plan for `command`, run after the Workit gates allowed it.
+ * Nothing when no `workit` is on PATH (the wrapper could not run) or the
+ * host sets WORKIT_HEAVY_GATE=0. Never throws.
+ */
+export function heavyGate(cwd: string, command: string, options: GateOptions): HeavyPlan {
+  const env = options.env ?? process.env;
+  try {
+    // The launchers' cheap word check first: most commands stop here.
+    if (env.WORKIT_HEAVY_GATE === "0" || !maybeHeavy(command, cwd, env) || !workitOnPath(env))
+      return { kind: "none" };
+    return heavyPlan(command, {
+      cwd,
+      env,
+      dialect: options.dialect ?? "posix",
+      rules: rulesFor(options.host, cwd, env),
+      bypass: options.permissionMode === "bypassPermissions",
+    });
+  } catch {
+    return { kind: "none" };
+  }
+}
+
+/** The model-visible line after a rewrite. */
+export const rewriteNote = (plan: Extract<HeavyPlan, { kind: "rewrite" }>): string =>
+  `workit: this heavy command (${plan.reason}) runs under the machine-wide heavy-check lease as \`${plan.command}\`: it waits while another heavy check holds the lease (\`workit lock status\` shows who). Run heavy commands that way yourself; \`workit help lock\` explains the lease.`;
+
+/** The deny on hosts that cannot rewrite: the exact command to run instead. */
+export const heavyDenial = (
+  original: string,
+  plan: Extract<HeavyPlan, { kind: "rewrite" }>,
+): HookDecision => ({
+  kind: "deny",
+  reason: `heavy_command: \`${original.trim()}\` is heavy (${plan.reason}) and must run under the machine-wide heavy-check lease, so parallel agents cannot exhaust this machine's memory and CPU. Run exactly: ${plan.command}`,
+  unblock: plan.command,
+});
+
+/** The deny for a chain with heavy parts. */
+export const splitDenial = (plan: Extract<HeavyPlan, { kind: "split" }>): HookDecision => ({
+  kind: "deny",
+  reason: plan.reason,
+  unblock: plan.unblock,
+});

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

@@ -54,7 +54,12 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     // `stop_hook_active` and `last_assistant_message` (claude 2.1.295).
     stop: { support: "native", native: "Stop" },
   },
-  shellPolicy: { deny: "native", channel: "permissionDecision", failClosed: false },
+  shellPolicy: {
+    deny: "native",
+    channel: "permissionDecision",
+    failClosed: false,
+    rewrite: "native",
+  },
   context: {
     sessionStart: "native",
     perTurn: "native",
@@ -185,7 +190,16 @@ 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, dialect: dialectOf(value) } }
+        ? {
+            ok: true,
+            event: {
+              kind: "shell.pre",
+              command,
+              toolUseId,
+              dialect: dialectOf(value),
+              toolInput: value.tool_input as Record<string, unknown>,
+            },
+          }
         : { ok: false, error: `tool_input.command is required for ${value.tool_name}` };
     }
     case "PostToolUse": {
@@ -254,8 +268,25 @@ const CONTEXT_EVENTS = new Set([
   "PostToolUse",
 ]);
 
-/** Never emits `allow`: that would bypass the user's own permission prompt. */
+/**
+ * Never emits `allow`: that would bypass the user's own permission prompt. A
+ * rewrite is `updatedInput` with no permissionDecision: Claude Code applies it
+ * and runs its normal permission flow on the rewritten command (claude
+ * 2.1.306: a hook result with updatedInput and no permissionBehavior is
+ * yielded as the input to run).
+ */
 const render = (decision: HookDecision, native: string | null) => {
+  if (decision.kind === "rewrite" && native === "PreToolUse" && decision.input)
+    return {
+      json: {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          updatedInput: decision.input,
+          ...(decision.text ? { additionalContext: decision.text } : {}),
+        },
+      },
+      exitCode: 0,
+    };
   if (decision.kind === "deny" && native === "PreToolUse")
     return {
       json: {