@brainervirus/workit-core 8.27.0 → 8.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.27.0",
+  "version": "8.28.1",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/branch.ts

@@ -318,6 +318,16 @@ export const validateCommitMessagePolicy = (
   };
 };
 
+/**
+ * A TypeError or ReferenceError while resolving a policy is a bug in this
+ * runtime (or a host too old for it), not a config problem the user can
+ * repair: it propagates so the hook's failure decision applies instead of a
+ * misleading "repair or select a valid workspace policy".
+ */
+const rethrowRuntimeBug = (error: unknown): void => {
+  if (error instanceof TypeError || error instanceof ReferenceError) throw error;
+};
+
 export const validateBranchNameFor = (
   workspaceRoot: string,
   name: string,
@@ -326,6 +336,7 @@ export const validateBranchNameFor = (
     const resolved = branchPolicySnapshotFor(workspaceRoot);
     return validateBranchNamePolicy(name, resolved.namePolicy, resolved.source);
   } catch (error) {
+    rethrowRuntimeBug(error);
     const correction = "repair or select a valid workspace policy before creating a branch";
     return {
       ok: false,
@@ -347,6 +358,7 @@ export const validateCommitMessageFor = (
     const resolved = commitPolicySnapshotFor(workspaceRoot);
     return validateCommitMessagePolicy(message, resolved.policy, resolved.source);
   } catch (error) {
+    rethrowRuntimeBug(error);
     const correction = "repair or select a valid workspace policy before committing";
     return {
       ok: false,

package/src/core/operation-input.ts

@@ -184,9 +184,11 @@ export function flatOperationJsonSchema(
   // Reads advertise only what reads take: no revisions, and task reads only their filters.
   const readField = (name: string) =>
     name === "taskId" || (family === "task" ? READ_TASK_FIELDS.has(name) : family === "policy");
+  // Only advertise what some listed action takes (derived from the contract).
+  const taken = (name: string) =>
+    family === "policy" || actions.some((action) => actionKeys(family, action)?.accepted.has(name));
   for (const [name, field] of Object.entries({ ...COMMON, ...spec.fields }))
-    if (options.readOnly ? readField(name) : !(family === "state" && name === "expectedRevision"))
-      properties[name] = property(field);
+    if (options.readOnly ? readField(name) : taken(name)) properties[name] = property(field);
   return {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     type: "object",
@@ -482,6 +484,129 @@ export function normalizeOperationInput(
   return request;
 }
 
+// ---------------------------------------------------------------------------
+// per-action keys, derived from the contract
+
+type ZodLike = {
+  _zod: { def: { type: string; shape?: Record<string, ZodLike>; innerType?: ZodLike } };
+};
+const defOf = (node: ZodLike) => node._zod.def;
+const unwrap = (node: ZodLike): ZodLike => {
+  let inner = node;
+  while (["optional", "nullable"].includes(defOf(inner).type) && defOf(inner).innerType)
+    inner = defOf(inner).innerType!;
+  return inner;
+};
+/** Contract keys the flat form renames. */
+const FLAT_NAME: Record<string, string> = {
+  authorityRefs: "refs",
+  contentRefs: "refs",
+  statedChoice: "choice",
+  reviewContext: "reviewSession",
+};
+const NOT_FLAT = new Set(["schemaVersion", "action", "workspaceId"]);
+
+export type ActionKeys = { accepted: Set<string>; required: string[] };
+
+/**
+ * What one action of a family takes, read from the advertised contract:
+ * every top-level key, the keys of its nested objects (flat form, renamed per
+ * FLAT_NAME), and the required scalars. Lists, scopes and nullables are
+ * defaulted by normalization, so they are accepted but never required.
+ */
+export function actionKeys(family: OperationFamily, action: string): ActionKeys | null {
+  const options = (advertisedOperationSchemas[family] as unknown as { options: ZodLike[] }).options;
+  const option = options.find((item) => {
+    const literal = defOf(item).shape?.action as unknown as { _zod: { def: { values: string[] } } };
+    return literal._zod.def.values.includes(action);
+  });
+  if (!option) return null;
+  const out: ActionKeys = { accepted: new Set(), required: [] };
+  const walk = (shape: Record<string, ZodLike>, nested: boolean): void => {
+    for (const [key, node] of Object.entries(shape)) {
+      if (NOT_FLAT.has(key) || (nested && key === "taskId")) continue;
+      const inner = unwrap(node);
+      const type = defOf(inner).type;
+      const needed = !["optional", "nullable"].includes(defOf(node).type);
+      if (key === "scope")
+        for (const name of ["scope", "paths", "exclusions"]) out.accepted.add(name);
+      else if (type === "object" && key !== "bundle" && !(key in FLAT_NAME)) {
+        out.accepted.add(key);
+        walk(defOf(inner).shape!, true);
+      } else {
+        const name = FLAT_NAME[key] ?? key;
+        out.accepted.add(name);
+        if (needed && type !== "array" && type !== "record" && !out.required.includes(name))
+          out.required.push(name);
+      }
+    }
+  };
+  walk(defOf(option).shape!, false);
+  return out;
+}
+
+/** A minimal valid flat payload for one action: required scalars with placeholders. */
+export function exampleOperation(family: OperationFamily, action: string): Record<string, unknown> {
+  const keys = actionKeys(family, action);
+  const example: Record<string, unknown> = { action };
+  for (const name of keys?.required ?? [])
+    example[name] = FLAT[family].fields[name]?.enum?.[0] ?? `<${name}>`;
+  if (family === "policy" && !keys?.required.length && action !== "explain")
+    example.riskTier = "normal";
+  return example;
+}
+
+const oneOf = (values: readonly string[]): string => values.join(" | ");
+
+/** Every invalid_input the hosts return: the exact fix for this family and action. */
+function invalidOperation(
+  family: OperationFamily,
+  input: unknown,
+  error: ZodErrorLike,
+): Result<never> {
+  const request = isObject(input) ? input : {};
+  const action = typeof request.action === "string" ? request.action : "";
+  const actions = OPERATION_ACTIONS[family];
+  if (!actions.includes(action))
+    return failure("invalid_input", `${family}: action must be one of ${oneOf(actions)}`, {
+      fields: [{ path: "action", reason: `got ${JSON.stringify(request.action ?? null)}` }],
+    });
+  const own = actionKeys(family, action)!;
+  const fields: { path: string; reason: string }[] = [];
+  const sentence: string[] = [];
+  for (const issue of error.issues) {
+    if (issue.code === "unrecognized_keys") {
+      for (const key of issue.keys) {
+        const home = actions.find(
+          (other) => other !== action && actionKeys(family, other)!.accepted.has(key),
+        );
+        const reason = home
+          ? `${key} belongs to action: ${home}`
+          : `${key} is not a field of ${family} ${action}; it takes ${[...own.accepted].join(", ")}`;
+        fields.push({ path: key, reason });
+        sentence.push(reason);
+      }
+      continue;
+    }
+    const last = String(issue.path.at(-1) ?? "");
+    const name = Object.entries(FLAT_NAME).find(([contract]) => contract === last)?.[1] ?? last;
+    const missing = issue.code === "invalid_type" && /received undefined/.test(issue.message);
+    // A nested container (binding, intent, ...) is absent because its flat fields are.
+    const absent = own.required.filter((key) => !(key in request));
+    const needs = missing && issue.path.length === 1 && absent.length ? absent.join(", ") : name;
+    const reason = missing ? `${family} ${action} requires ${needs}` : `${name}: ${issue.message}`;
+    fields.push({ path: issue.path.join("."), reason });
+    sentence.push(reason);
+  }
+  const example = JSON.stringify(exampleOperation(family, action));
+  return failure("invalid_input", `${[...new Set(sentence)].join("; ")}. Example: ${example}`, {
+    fields,
+  });
+}
+type ZodErrorLike = {
+  issues: { code: string; keys: string[]; path: PropertyKey[]; message: string }[];
+};
+
 /**
  * Host-side validation before the engine runs: normalize, then parse against
  * the advertised contract (taskId optional: the engine resolves the branch's
@@ -497,10 +622,5 @@ export function parseAdvertisedOperation(
     return failure("unsupported_version", "unsupported schema version", { operation: family });
   const parsed = advertisedOperationSchemas[family].safeParse(request);
   if (parsed.success) return success(null, null, request);
-  return failure("invalid_input", "operation input is invalid", {
-    fields: parsed.error.issues.map((issue) => ({
-      path: issue.code === "unrecognized_keys" ? issue.keys.join(".") : issue.path.join("."),
-      reason: issue.message,
-    })),
-  });
+  return invalidOperation(family, request, parsed.error as unknown as ZodErrorLike);
 }

package/src/core/role-models.ts

@@ -207,3 +207,30 @@ export const roleModelIssues = (cwd: string, dir?: string): string[] => {
   }
   return issues;
 };
+
+/**
+ * The role a Claude Code subagent type runs as: the Workit agents by their
+ * namespaced name, the built-in `Explore`. Plan, general-purpose and every
+ * other type map to none (their model is not Workit's to choose). An
+ * implementer spawn names its brief tier on a `TIER: <tier>` line in its
+ * prompt; without one it is `standard`.
+ */
+export const roleForAgentType = (agentType: unknown, prompt?: unknown): RoleSelector | null => {
+  switch (agentType) {
+    case "workit:implementer": {
+      const tier =
+        typeof prompt === "string"
+          ? /^[ \t]*TIER:[ \t]*(mundane|standard|hard)\b/im.exec(prompt)?.[1]
+          : undefined;
+      return { role: "implementer", tier: (tier?.toLowerCase() as ModelTier) ?? "standard" };
+    }
+    case "workit:verifier":
+      return { role: "verifier" };
+    case "workit:reviewer":
+      return { role: "reviewer" };
+    case "Explore":
+      return { role: "explore" };
+    default:
+      return null;
+  }
+};

package/src/hooks/agent-model.ts

@@ -0,0 +1,40 @@
+// Role models on a Claude Code subagent spawn (#420): a spawn that names no
+// `model` gets its role's model (and effort) from the role config, through
+// PreToolUse `updatedInput` on the Agent tool. An explicit `model` always
+// wins and a spawn is never denied over its model: a type with no role, or a
+// role with nothing usable configured, runs as the caller wrote it.
+import { resolveRoleModel, roleForAgentType } from "../core/role-models";
+import type { HookDecision } from "./protocol";
+
+/** The Agent tool's `model` and `effort` enums (claude 2.1.309); anything else fails its schema. */
+const MODELS = new Set(["sonnet", "opus", "haiku", "fable"]);
+const EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+
+const given = (value: unknown): boolean => typeof value === "string" && value.trim() !== "";
+
+export const agentModelDecision = (
+  cwd: string,
+  tool: Record<string, unknown>,
+  env: NodeJS.ProcessEnv = process.env,
+): HookDecision => {
+  // The host fixes the model itself: nothing to fill, and `model` is not in its schema.
+  if (given(tool.model) || env.CLAUDE_CODE_SUBAGENT_MODEL_FORCE) return { kind: "none" };
+  const selector = roleForAgentType(tool.subagent_type, tool.prompt);
+  if (!selector) return { kind: "none" };
+  const resolved = resolveRoleModel(cwd, selector, "claude_code");
+  if (!resolved) return { kind: "none" };
+  const model = resolved.model.toLowerCase();
+  const effort = resolved.effort?.toLowerCase() ?? null;
+  const input: Record<string, unknown> = { ...tool };
+  if (MODELS.has(model)) input.model = model;
+  if (effort && EFFORTS.has(effort) && !given(tool.effort)) input.effort = effort;
+  if (input.model === undefined && input.effort === tool.effort) return { kind: "none" };
+  const label = selector.tier ? `${selector.role} ${selector.tier}` : selector.role;
+  return {
+    kind: "update-input",
+    input,
+    text: `Workit set ${String(input.model ?? "no model")}${
+      input.effort !== tool.effort ? ` (effort ${String(input.effort)})` : ""
+    } on this ${String(tool.subagent_type)} spawn: role ${label}, ${resolved.source}. Name a model to choose another.`,
+  };
+};

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 { judgeBranch, recordIssuedSession, verdictCommand } from "../host-session";
+import { agentModelDecision } from "./agent-model";
 import { cwdRewrite, verbFirst } from "./cwd-normalize";
 import { workitBypassFlag } from "./delivery-verbs";
 import { heavyDenial, heavyGate, rewriteNote, splitDenial } from "./heavy-gate";
@@ -159,7 +160,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     return decision;
   const delta = standingDelta(input);
   if (!delta) return decision;
-  return decision.kind === "rewrite"
+  return decision.kind === "rewrite" || decision.kind === "update-input"
     ? { ...decision, text: [decision.text, delta].filter(Boolean).join("\n") }
     : withContextLine(decision, delta);
 }
@@ -307,6 +308,8 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
     case "tool.pre":
       // Host permission policy owns other tools; a skill load is recorded.
       if (event.skill) recordSkillLoad(input, event.skill, "tool");
+      if (event.agentInput && input.host === "claude_code")
+        return agentModelDecision(input.cwd, event.agentInput);
       return NONE;
     case "stop":
       return usable(descriptor.events.stop.support) ? stopDecision(input, descriptor) : NONE;

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

@@ -186,6 +186,17 @@ const eventOf = (name: ClaudeHookEvent, value: Record<string, unknown>): Parsed
             skill: isRecord(value.tool_input) ? optionalText(value.tool_input.skill) : null,
           },
         };
+      // `Task` is the Agent tool's legacy name.
+      if (value.tool_name === "Agent" || value.tool_name === "Task")
+        return {
+          ok: true,
+          event: {
+            kind: "tool.pre",
+            tool: value.tool_name,
+            toolUseId,
+            ...(isRecord(value.tool_input) ? { agentInput: value.tool_input } : {}),
+          },
+        };
       if (!SHELL_TOOLS.has(value.tool_name))
         return { ok: true, event: { kind: "tool.pre", tool: value.tool_name, toolUseId } };
       const command = toolCommand(value);
@@ -276,7 +287,11 @@ const CONTEXT_EVENTS = new Set([
  * yielded as the input to run).
  */
 const render = (decision: HookDecision, native: string | null) => {
-  if (decision.kind === "rewrite" && native === "PreToolUse" && decision.input)
+  if (
+    (decision.kind === "rewrite" || decision.kind === "update-input") &&
+    native === "PreToolUse" &&
+    decision.input
+  )
     return {
       json: {
         hookSpecificOutput: {

package/src/hooks/protocol.ts

@@ -37,6 +37,8 @@ export type HookEvent =
       toolUseId: string | null;
       /** The skill a skill-loading tool loads (Claude Code's Skill tool). */
       skill?: string | null;
+      /** A subagent spawn's whole tool input (Claude Code's Agent tool), where a default is filled in. */
+      agentInput?: Record<string, unknown>;
     }
   /** A file-writing tool (Edit, Write, apply_patch…): the before-write gate (S17). */
   | {
@@ -105,6 +107,12 @@ export type HookDecision =
    * host takes the whole input back; `text` is model-visible context.
    */
   | { kind: "rewrite"; command: string; input: Record<string, unknown> | null; text: string | null }
+  /**
+   * tool.pre: run the tool with `input` (the host's whole tool input, with
+   * defaults filled in) instead; `text` is model-visible context. Never a
+   * permission decision.
+   */
+  | { kind: "update-input"; input: Record<string, unknown>; text: string | null }
   /** Stop/SubagentStop: keep working. */
   | { kind: "continue"; reason: string }
   | { kind: "notice"; userMessage: string };