@brainervirus/workit-core 6.0.1 → 7.1.0

package/src/core/vcs-config.ts

@@ -1,14 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { configDir, PRESETS } from "./config";
-import { resolveRuntimeWorkspaceVcs } from "./workspaces";
-import { resolveBranchPolicyFor } from "./branch";
+import { configDir, vcsConfigPath } from "./config";
+import { resolveRuntimeWorkspaceVcs, workspaceDefaultTarget } from "./workspaces";
+import { resolveTrackFor, type RuntimeReleaseTrack, type TrackResolution } from "./release-tracks";
 // VCS resolution and CLI-backed identity/style reads.
 
-export const vcsConfigPath = (): string =>
-  process.env.WORKFLOW_VCS_CONFIG ?? path.join(configDir(), "vcs.json");
-
 const workspacesPath = (): string => path.join(configDir(), "workspaces.json");
 
 const vcsCwd = (cwd?: string): string =>
@@ -146,8 +143,45 @@ export const readVcsConfig = (): VcsConfigResult => {
   return { status: "malformed", path: file, config: {}, error: `${file} is not a JSON object` };
 };
 
+/** The release track a vcsConfig call resolved (null: the workspace has no tracks). */
+export type ResolvedReleaseTrack = {
+  name: string | null;
+  source: string;
+  detail: string;
+  warnings: string[];
+  track: RuntimeReleaseTrack | null;
+  /** Every configured track, for displays and the branch policy. */
+  tracks: RuntimeReleaseTrack[];
+  /** The line is undetermined (or WORKFLOW_RELEASE_TRACK is wrong): mutating verbs refuse. */
+  blocking: string | null;
+};
+
+export type VcsConfigOptions = {
+  /** An explicit release track (`--track`); WORKFLOW_RELEASE_TRACK is read below it. */
+  track?: string | null;
+  /** Resolve the track for this branch instead of the checked-out one. */
+  branch?: string | null;
+};
+
+const trackSummary = (resolution: TrackResolution): ResolvedReleaseTrack | null =>
+  resolution.status === "resolved"
+    ? {
+        name: resolution.track?.name ?? null,
+        source: resolution.source,
+        detail: resolution.detail,
+        warnings: resolution.warnings,
+        track: resolution.track,
+        tracks: resolution.tracks,
+        blocking: resolution.blocking,
+      }
+    : null;
+
 /** Port of scripts/vcs/config.sh — mode: load | summary | resolve. */
-export function vcsConfig(mode: "load" | "summary" | "resolve", cwd?: string): Record<string, any> {
+export function vcsConfig(
+  mode: "load" | "summary" | "resolve",
+  cwd?: string,
+  options: VcsConfigOptions = {},
+): Record<string, any> {
   const ws = resolveRuntimeWorkspaceVcs(vcsCwd(cwd));
   const wsVcs = (ws?.vcs ?? {}) as Record<string, any>;
   const wsYt = (ws?.youtrack ?? {}) as Record<string, any>;
@@ -183,14 +217,9 @@ export function vcsConfig(mode: "load" | "summary" | "resolve", cwd?: string): R
   // main). Explicit workspace vcs.defaultTargetBranch stays authoritative; a
   // workspace without a branchPolicy still falls back to the global vcs.json
   // default, and unmatched repos keep it too.
-  const wp = (ws?.branchPolicy ?? {}) as Record<string, any>;
-  const hasWorkspacePolicy = typeof wp.preset === "string" && Object.hasOwn(PRESETS, wp.preset);
-  const policyDefault = resolveBranchPolicyFor(root).defaultTargetBranch;
-  const defaultTarget = String(
-    wsVcs.defaultTargetBranch ??
-      (hasWorkspacePolicy ? policyDefault : (cfg.defaultTargetBranch ?? policyDefault)) ??
-      "develop",
-  );
+  // CA-05/CA-02 (workspaces.ts workspaceDefaultTarget): shared with doctor
+  // and grant show so their display never disagrees with the commands.
+  const workspaceDefault = workspaceDefaultTarget(root, cfg.defaultTargetBranch);
   const linkIssues = typeof wsYt.link_issues === "boolean" ? wsYt.link_issues : null;
   const youtrackBaseUrl = typeof wsYt.baseUrl === "string" ? wsYt.baseUrl : null;
   // github issues path only when BOTH providers are github (mirrors WorkspaceConfig.issues).
@@ -210,11 +239,30 @@ export function vcsConfig(mode: "load" | "summary" | "resolve", cwd?: string): R
     // instead of silently resolving defaults; a missing file is still a
     // legitimate unconfigured state that falls back to defaults.
     if (cfgStatus === "malformed") return { ok: false, error: cfgError, configPath: cfgPath };
+    // Release tracks (core/release-tracks.ts): the one place a branch's line is
+    // decided, in resolve mode only (load serves identity, push and tracker
+    // paths that never need it). With tracks, the PR target and the base for
+    // new branches come from the resolved track; without, the workspace
+    // default stays as is.
+    const trackResolution = resolveTrackFor(root, {
+      track: options.track,
+      ...(options.branch !== undefined ? { branch: options.branch } : {}),
+      defaultBranch: workspaceDefault,
+    });
+    if (trackResolution.status === "invalid")
+      return { ok: false, error: trackResolution.error, configPath: workspacesPath() };
+    const releaseTrack = trackSummary(trackResolution);
+    const defaultTarget = releaseTrack?.track?.pullRequestTarget ?? workspaceDefault;
+    const baseBranch = releaseTrack?.track?.baseBranch ?? defaultTarget;
     return {
       ok: true,
       workspace_name: ws?.name ?? null,
       provider,
       defaultTargetBranch: defaultTarget,
+      /** The target before release tracks (vcs.defaultTargetBranch or the policy default). */
+      workspaceDefaultTargetBranch: workspaceDefault,
+      baseBranch,
+      releaseTrack,
       link_issues: linkIssues,
       youtrack_base_url: youtrackBaseUrl,
       issues_provider: issuesProvider,
@@ -241,7 +289,8 @@ export function vcsConfig(mode: "load" | "summary" | "resolve", cwd?: string): R
     ok: true,
     configPath: path.resolve(cfgPath),
     provider,
-    defaultTargetBranch: defaultTarget,
+    // Load mode does not resolve release tracks: the workspace default.
+    defaultTargetBranch: workspaceDefault,
     pr: cfg.pr ?? {},
     workspace_name: ws?.name ?? null,
     link_issues: linkIssues,

package/src/core/workspaces.ts

@@ -7,6 +7,7 @@ import {
   PRESETS,
   configDir,
   isConfigObject,
+  readConfig,
   resolveBranchPolicy as resolveConfiguredBranchPolicy,
   resolveCommitPolicy as resolveConfiguredCommitPolicy,
   type BranchPreset,
@@ -68,31 +69,43 @@ const versionSourceSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("git-tag") }).strict(),
   z.object({ kind: z.literal("manual") }).strict(),
 ]);
+// Only the production and integration branches are required: runtime
+// (core/release-tracks.ts) defaults the rest. Unknown keys pass through (D17:
+// a newer Workit's field must not invalidate the file for an older one); a
+// track lists the ones an older reader must not ignore in `critical`.
 const releaseTrackSchema = z
   .object({
-    strategy: branchPreset,
+    strategy: branchPreset.optional(),
     productionBranch: nonBlank,
     integrationBranch: nonBlank,
-    naming: z.object({ feature: nonBlank, release: nonBlank, hotfix: nonBlank }).strict(),
-    baseBranch: nonBlank,
-    mergeBackBranches: z.array(nonBlank),
-    pullRequestTarget: nonBlank,
-    tagNamespace: z.string(),
-    versionSource: versionSourceSchema,
-    requiredChecks: z.array(nonBlank),
+    naming: z
+      .object({
+        feature: nonBlank.optional(),
+        release: nonBlank.optional(),
+        hotfix: nonBlank.optional(),
+      })
+      .passthrough()
+      .optional(),
+    baseBranch: nonBlank.optional(),
+    mergeBackBranches: z.array(nonBlank).optional(),
+    pullRequestTarget: nonBlank.optional(),
+    tagNamespace: z.string().optional(),
+    versionSource: versionSourceSchema.optional(),
+    requiredChecks: z.array(nonBlank).optional(),
+    critical: z.array(nonBlank).optional(),
   })
-  .strict()
+  .passthrough()
   .superRefine((track, context) => {
     for (const [field, values] of [
-      ["mergeBackBranches", track.mergeBackBranches],
-      ["requiredChecks", track.requiredChecks],
+      ["mergeBackBranches", track.mergeBackBranches ?? []],
+      ["requiredChecks", track.requiredChecks ?? []],
     ] as const) {
       if (new Set(values).size !== values.length) {
         context.addIssue({ code: "custom", path: [field], message: "entries must be unique" });
       }
     }
     if (
-      track.versionSource.kind === "package-json" &&
+      track.versionSource?.kind === "package-json" &&
       (path.posix.isAbsolute(track.versionSource.path.replaceAll("\\", "/")) ||
         /^[A-Za-z]:\//u.test(track.versionSource.path.replaceAll("\\", "/")) ||
         track.versionSource.path.replaceAll("\\", "/").split("/").includes(".."))
@@ -121,6 +134,8 @@ const workspaceConfigSchema = z
     autoApprove: z.union([z.boolean(), z.array(nonBlank)]).optional(),
     /** Where an unnamed request stops (skills read it); same rules as grants. */
     defaultEndpoint: z.enum(["commit", "pr"]).optional(),
+    /** How a normal-risk behavior change is verified (S17); same rules as grants. */
+    verification: z.enum(["self", "independent"]).optional(),
     /** Autonomy grants (D15): only ever set here, by the user. */
     autonomy: z
       .object(
@@ -555,10 +570,10 @@ const runtimeWorkspaceIndexSchema = z
   })
   .passthrough();
 
-const resolveRuntimeWorkspaceCandidate = (
+/** The workspaces.json entry matching cwd, checked only for name/glob (D17). */
+const matchRuntimeWorkspace = (
   cwd: string,
-  kind: RuntimeWorkspacePolicy,
-): RuntimeWorkspaceCandidate | null => {
+): { file: string; selected: Record<string, unknown> & { name: string } } | null => {
   const file = path.join(configDir(), "workspaces.json");
   let raw: string;
   try {
@@ -599,7 +614,30 @@ const resolveRuntimeWorkspaceCandidate = (
   });
   const workspaceName = process.env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined;
   const selected = selectWorkspaceMatch(matches, cwd, workspaceName);
-  if (!selected) return null;
+  return selected ? { file, selected } : null;
+};
+
+/**
+ * The raw `releaseTracks` of the workspace matching cwd, unvalidated: the
+ * runtime reads them leniently (core/release-tracks.ts) so one malformed track
+ * is reported instead of disabling every command.
+ */
+export const resolveRuntimeReleaseTracks = (
+  cwd: string,
+): { workspace: string; releaseTracks: unknown } | null => {
+  const matched = matchRuntimeWorkspace(cwd);
+  return matched
+    ? { workspace: matched.selected.name, releaseTracks: matched.selected.releaseTracks }
+    : null;
+};
+
+const resolveRuntimeWorkspaceCandidate = (
+  cwd: string,
+  kind: RuntimeWorkspacePolicy,
+): RuntimeWorkspaceCandidate | null => {
+  const matched = matchRuntimeWorkspace(cwd);
+  if (!matched) return null;
+  const { file, selected } = matched;
   const policy = runtimeWorkspacePolicySchema(kind).safeParse(selected);
   if (!policy.success) {
     const detail = policy.error.issues
@@ -728,3 +766,31 @@ export const selectReleaseTrack = (
   }
   return { status: "selected", name: requestedTrack, track: tracks[requestedTrack] };
 };
+
+/**
+ * The workspace default target before release tracks: the one computation
+ * vcsConfig, `workit doctor` and `workit grant show` share (CA-05/CA-02).
+ * Explicit workspace vcs.defaultTargetBranch wins; a workspace with its own
+ * branchPolicy uses its preset's default (gitflow -> develop, github-flow ->
+ * main, trunk-based -> master); otherwise the global vcs.json
+ * `defaultTargetBranch` (`globalDefault`), else the effective preset's.
+ */
+export function workspaceDefaultTarget(cwd: string, globalDefault: unknown): string {
+  const ws = resolveRuntimeWorkspaceVcs(cwd);
+  const wp = (ws?.branchPolicy ?? {}) as Record<string, unknown>;
+  const hasWorkspacePolicy = typeof wp.preset === "string" && Object.hasOwn(PRESETS, wp.preset);
+  const selected = resolveRuntimeWorkspacePolicy(
+    cwd,
+    "branch",
+    process.env.WORKFLOW_PROFILE?.trim() || undefined,
+  );
+  const policyDefault = resolveConfiguredBranchPolicy(
+    readConfig(),
+    selected.policy ? { branchPolicy: selected.policy as WorkspaceBranchPolicy } : null,
+  ).defaultTargetBranch;
+  return String(
+    (ws?.vcs as { defaultTargetBranch?: unknown } | undefined)?.defaultTargetBranch ??
+      (hasWorkspacePolicy ? policyDefault : (globalDefault ?? policyDefault)) ??
+      "develop",
+  );
+}

package/src/core.ts

@@ -8,11 +8,6 @@ export {
   OPERATION_FAMILIES,
   operationSchemas,
   advertisedOperationSchemas,
-  operationJsonSchema,
-  boundedOperationJsonSchema,
-  OPERATION_SCHEMA_DEPTH,
-  OPERATION_SCHEMA_MAX_DEPTH,
-  canonicalFieldsDescription,
   parseOperation,
   success,
   failure,
@@ -25,6 +20,13 @@ export {
   requirementId,
   rewriteRecordRefs,
 } from "./core/task-contract";
+export {
+  flatOperationJsonSchema,
+  normalizeOperationInput,
+  operationDescription,
+  operationJsonSchema,
+  parseAdvertisedOperation,
+} from "./core/operation-input";
 export type {
   OperationFamily,
   OperationRequest,
@@ -32,7 +34,7 @@ export type {
   Caller,
   Scope,
   Ref,
-  Assessment,
+  Judgment,
   Dimension,
   Requirement,
   Constraint,

package/src/forge/pr-ops.ts

@@ -18,6 +18,7 @@
 import { requireGrant, type AutonomySource } from "../autonomy";
 import { isProtectedTarget } from "../core/branch";
 import { vcsConfig } from "../core/vcs-config";
+import { workspaceReleaseTracks } from "../core/release-tracks";
 import { deleteRemoteBranch } from "../git/ops";
 import { spawnSync } from "node:child_process";
 import { currentBranch, fetchRefs, GIT_TIMEOUTS, remoteRefTip, resolveRef } from "../git/rev";
@@ -260,6 +261,33 @@ export type MergeOutcome = {
   grant: { source: AutonomySource };
   deletedBranch: boolean | { error: string };
   recorded: { id: string } | { error: string };
+  /**
+   * Release tracks: when the PR landed on a track's production branch, the
+   * branches it must flow back into (mergeBackBranches); empty otherwise.
+   * Workit reports them; it does not open the merge-back PRs itself.
+   */
+  mergeBack: string[];
+  mergeBackTrack: string | null;
+};
+
+/**
+ * The merge-back a merge into `base` owes: the track whose production branch
+ * `base` is, by ownership alone (no --track, no WORKFLOW_RELEASE_TRACK, no
+ * history). Best effort: a config problem never stops the pr.merged record.
+ */
+const mergeBackFor = (cwd: string, base: string): { track: string | null; branches: string[] } => {
+  try {
+    const owners = workspaceReleaseTracks(cwd).tracks.filter(
+      (track) => track.productionBranch === base,
+    );
+    if (owners.length !== 1) return { track: null, branches: [] };
+    return {
+      track: owners[0].name,
+      branches: owners[0].mergeBackBranches.filter((branch) => branch !== base),
+    };
+  } catch {
+    return { track: null, branches: [] };
+  }
 };
 
 /** Why `pr merge` refused, for the envelope `data` (agents branch on `reason`). */
@@ -431,6 +459,7 @@ export async function mergePullRequest(
     deletedBranch =
       deleted.ok || (gone && gone.ok && gone.sha === null) ? true : { error: deleted.error };
   }
+  const mergeBack = mergeBackFor(cwd, doc.base);
   const row = appendObserved(cwd, {
     type: "pr.merged",
     actor: input.actor,
@@ -457,6 +486,8 @@ export async function mergePullRequest(
       grant: { source: grant.source },
       deletedBranch,
       recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
+      mergeBack: mergeBack.branches,
+      mergeBackTrack: mergeBack.track,
     },
   };
 }

package/src/git/ops.ts

@@ -27,7 +27,8 @@ import {
 } from "../core/branch";
 import { detectCommitFlavor, matchCommitFlavor } from "../core/commit-flavors";
 import { pushTargetIsStable } from "../core/pr-create";
-import { vcsConfig } from "../core/vcs-config";
+import { recordBranchBase, trackBranchName } from "../core/release-tracks";
+import { vcsConfig, type ResolvedReleaseTrack } from "../core/vcs-config";
 import { redactText } from "../forge/redact";
 import { failure, success, type ForgeResult } from "../forge/types";
 import { appendObserved, readLedger, type LedgerActor } from "../ledger";
@@ -119,15 +120,51 @@ export type BranchOutcome = {
   carried: boolean;
   /** Fallbacks taken (fetch failed, base used from the local copy). */
   notes: string[];
+  /** The release track the base and name came from; null without tracks. */
+  releaseTrack: ResolvedReleaseTrack | null;
 };
 
-export function gitBranch(
-  cwd: string,
-  input: { name: string; base?: string | null; carry?: boolean },
-): ForgeResult<BranchOutcome> {
-  const name = input.name.trim();
+export type BranchInput = {
+  /** An explicit branch name; else `kind` + `slug` through the track's naming. */
+  name?: string;
+  kind?: "feature" | "bugfix" | "hotfix";
+  slug?: string;
+  base?: string | null;
+  carry?: boolean;
+  /** An explicit release track (`--track`). */
+  track?: string | null;
+};
+
+export function gitBranch(cwd: string, input: BranchInput): ForgeResult<BranchOutcome> {
   if (!headSha(cwd) && currentBranch(cwd) === null)
     return failure("invalid_input", "not inside a git repository with a commit");
+  // One resolution: the default target, the base for new branches and the
+  // release track (core/release-tracks.ts) all come from vcsConfig. With
+  // --base the track is the base's line (it decides the --kind naming);
+  // otherwise the checkout's.
+  const explicitBase = input.base?.trim() || null;
+  const resolved = vcsConfig("resolve", cwd, {
+    track: input.track ?? null,
+    ...(explicitBase ? { branch: explicitBase } : {}),
+  });
+  const releaseTrack: ResolvedReleaseTrack | null =
+    resolved.ok === false ? null : (resolved.releaseTrack ?? null);
+  // An undetermined line blocks whenever the track would decide something:
+  // the base (no --base) or the --kind/--slug name.
+  if (releaseTrack?.blocking && (!explicitBase || input.name === undefined))
+    return failure(
+      "blocked",
+      String(releaseTrack.blocking),
+      "workit git branch … --track <name>  # or --base <branch>",
+    );
+  const name = (
+    input.name ??
+    (input.kind && input.slug
+      ? (trackBranchName(releaseTrack?.track ?? null, input.kind, input.slug) ??
+        `${input.kind}/${input.slug}`)
+      : "")
+  ).trim();
+  if (!name) return failure("invalid_input", "missing branch name");
   if (!validRefName(cwd, name))
     return failure("invalid_input", `invalid branch name ${JSON.stringify(name)}`);
   const policy = validateBranchNameFor(cwd, name);
@@ -135,28 +172,36 @@ export function gitBranch(
   if (resolveRef(cwd, `refs/heads/${name}`))
     return failure("failed", `branch_exists: ${name} already exists`, `git switch ${name}`);
 
-  let base = input.base?.trim() || null;
+  let base = explicitBase;
   let defaultTarget: string | null = null;
-  const resolved = vcsConfig("resolve", cwd);
-  if (resolved.ok === false && !base)
+  let defaultBase: string | null = null;
+  // An explicit --track that does not resolve is never ignored, even with --base.
+  if (resolved.ok === false && (!base || input.track))
     return failure(
       "blocked",
       String(resolved.error),
       "fix ~/.config/workit/vcs.json or pass --base <branch>",
     );
-  if (resolved.ok !== false) defaultTarget = String(resolved.defaultTargetBranch ?? "") || null;
-  base ??= defaultTarget;
+  if (resolved.ok !== false) {
+    defaultTarget = String(resolved.defaultTargetBranch ?? "") || null;
+    defaultBase = String(resolved.baseBranch ?? "") || defaultTarget;
+  }
+  base ??= defaultBase;
   if (!base)
     return failure("invalid_input", "no default target branch is configured; pass --base <branch>");
   if (base.startsWith("-")) return failure("invalid_input", "--base must not start with -");
 
-  const notes: string[] = [];
+  const notes: string[] = [...(releaseTrack?.warnings ?? [])];
   const remotes = remoteNames(cwd);
   const remote = remotes.includes("origin") ? "origin" : pushRemoteName(cwd);
   const localTip = resolveRef(cwd, `refs/heads/${base}`);
   // A local, unprotected branch that is not the default target is a stack
   // parent: its local tip is the truth (it may not be pushed yet).
-  const stackParent = localTip !== null && base !== defaultTarget && !isProtectedTarget(cwd, base);
+  const stackParent =
+    localTip !== null &&
+    base !== defaultTarget &&
+    base !== defaultBase &&
+    !isProtectedTarget(cwd, base);
   let baseRef: string | null = null;
   if (stackParent) baseRef = `refs/heads/${base}`;
   else if (remote && validRefName(cwd, base)) {
@@ -194,6 +239,8 @@ export function gitBranch(
   const previous = currentBranch(cwd);
   const switched = git(cwd, ["switch", "--no-track", "-c", name, baseSha]);
   if (!switched.ok) return failure("failed", `git switch -c ${name} failed: ${gitError(switched)}`);
+  // The cheapest track signal later (release-tracks.ts): where this branch began.
+  recordBranchBase(cwd, name, base);
   return success({
     branch: name,
     previous,
@@ -202,6 +249,7 @@ export function gitBranch(
     baseSha,
     carried: dirt !== "clean",
     notes,
+    releaseTrack,
   });
 }
 

package/src/hooks/handle.ts

@@ -2,6 +2,7 @@
 import { sessionContextText, turnContextText } from "./context";
 import type { HostDescriptor, Support } from "./descriptor";
 import { shellPolicy } from "./policy";
+import { shellWrites, writeGate } from "./write-gate";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
 export type HookDeps = { descriptor: HostDescriptor; addendum: string | null };
@@ -58,9 +59,13 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       const key = input.session.id ? `${input.host}\0${input.session.id}` : null;
       const offer = event.source === "startup" && (key === null || !offered.has(key));
       if (offer && key !== null) offered.add(key);
+      const advisory = usable(descriptor.events["write.pre"].support)
+        ? null
+        : `Workit cannot gate file writes on ${descriptor.label} (no pre-write hook): before-write requirements (an open product choice, a missing plan) are advisory here, so settle them before editing.`;
+      const addendum = [deps.addendum, advisory].filter(Boolean).join("\n") || null;
       return {
         kind: "context",
-        text: sessionContextText(input, descriptor, { offer, addendum: deps.addendum }),
+        text: sessionContextText(input, descriptor, { offer, addendum }),
       };
     }
     case "context.turn": {
@@ -68,8 +73,18 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
       const text = turnContextText(input, descriptor);
       return text ? { kind: "context", text } : NONE;
     }
-    case "shell.pre":
-      return usable(descriptor.shellPolicy.deny) ? shellPolicy(input.cwd, event.command) : 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;
+    }
+    case "write.pre":
+      return usable(descriptor.events["write.pre"].support)
+        ? writeGate(input.cwd, event.paths)
+        : NONE;
     case "subagent.start":
       return {
         kind: "context",
@@ -102,7 +117,7 @@ export const failureDecision = (
   event: HookEventKind | null,
   error: string,
 ): HookDecision => {
-  if (event === "shell.pre" || event === "tool.pre")
+  if (event === "shell.pre" || event === "tool.pre" || event === "write.pre")
     return descriptor.shellPolicy.failClosed
       ? { kind: "deny", reason: error, unblock: null }
       : NONE;

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

@@ -8,7 +8,15 @@ import type {
   HostAdapter,
   SessionSource,
 } from "../protocol";
-import { commandText, existingDirectory, isRecord, nonEmpty, optionalText } from "./fields";
+import {
+  commandText,
+  existingDirectory,
+  isRecord,
+  isWriteTool,
+  nonEmpty,
+  optionalText,
+  writePaths,
+} from "./fields";
 
 type ClaudeHookEvent =
   | "SessionStart"
@@ -31,6 +39,7 @@ export const CLAUDE_CODE_DESCRIPTOR: HostDescriptor = {
     "context.turn": { support: "native", native: "UserPromptSubmit" },
     "shell.pre": { support: "native", native: "PreToolUse" },
     "tool.pre": { support: "native", native: "PreToolUse" },
+    "write.pre": { support: "native", native: "PreToolUse" },
     "shell.post": { support: "native", native: "PostToolUse" },
     // SubagentStart output is additionalContext only: it cannot block or bind.
     "subagent.start": { support: "native", native: "SubagentStart" },
@@ -140,6 +149,16 @@ const eventOf = (name: ClaudeHookEvent, value: Record<string, unknown>): Parsed
       return { ok: true, event: { kind: "context.turn" } };
     case "PreToolUse": {
       if (!nonEmpty(value.tool_name)) return { ok: false, error: "tool_name is required" };
+      if (isWriteTool(value.tool_name))
+        return {
+          ok: true,
+          event: {
+            kind: "write.pre",
+            tool: value.tool_name,
+            paths: writePaths(value.tool_input),
+            toolUseId,
+          },
+        };
       if (!SHELL_TOOLS.has(value.tool_name))
         return { ok: true, event: { kind: "tool.pre", tool: value.tool_name, toolUseId } };
       const command = toolCommand(value);

package/src/hooks/hosts/codex.ts

@@ -50,6 +50,9 @@ export const CODEX_DESCRIPTOR: HostDescriptor = {
     "context.turn": undocumented,
     "shell.pre": { support: "native", native: "PreToolUse" },
     "tool.pre": { support: "native", native: "PreToolUse" },
+    // 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,
     "subagent.start": { support: "native", native: "SubagentStart" },
     "subagent.stop": { support: "native", native: "SubagentStop" },

package/src/hooks/hosts/cursor.ts

@@ -2,7 +2,7 @@
 import path from "node:path";
 import type { HostDescriptor } from "../descriptor";
 import type { HookDecision, HookEvent, HookEventKind, HostAdapter } from "../protocol";
-import { existingDirectory, isRecord, nonEmpty } from "./fields";
+import { existingDirectory, isRecord, isWriteTool, nonEmpty, writePaths } from "./fields";
 
 export type CursorHookEvent =
   | "sessionStart"
@@ -44,6 +44,8 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     "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.
@@ -212,7 +214,14 @@ const protocolEvent = (input: CursorHookInput): HookEvent => {
       // 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 };
+      return isWriteTool(input.tool_name)
+        ? {
+            kind: "write.pre",
+            tool: input.tool_name ?? "",
+            paths: writePaths(input.tool_input),
+            toolUseId: null,
+          }
+        : { kind: "tool.pre", tool: input.tool_name ?? "", toolUseId: null };
     case "subagentStart":
       return {
         kind: "subagent.start",