@brainervirus/workit-core 8.29.1 → 8.29.2

package/package.json

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

package/src/core/methods.ts

@@ -102,13 +102,13 @@ Autonomy contract:
   or an unresolved blocker; report open gaps and uncertain workers.
 - No endpoint named: stop at a local commit on a policy-compliant branch and
   state the next command. If the request implies delivery (fix, implement,
-  ship), go to the effective endpoint in \`workit grant show\`: \`pr\` opens
-  the PR; \`green\` babysits it without asking (workit-ship) to merge-ready,
-  never merging; \`merged\` also lands it with \`workit pr merge\`.
-  Merge and release need a workspace grant only the user raises from their
-  own terminal (a blocked verb names how); never edit workspaces.json or route
-  around grant_required. Release: \`workit release start <v>\`, commits,
-  \`finish\`; \`publish\` if asked.
+  ship), go to the effective endpoint in \`workit grant show\`: \`pr\` stops
+  at the PR even with merge granted; \`green\` babysits it (workit-ship) to
+  merge-ready, never merging; \`merged\` lands it with \`workit pr merge\`.
+  Only the user raises a grant or the endpoint, in a terminal outside the agent
+  host (\`workit grant set <ws> defaultEndpoint=merged\`); never edit
+  workspaces.json or route around grant_required. Release: \`workit release
+  start <v>\`, commits, \`finish\`; \`publish\` if asked.
 - Ask only for a product or preference choice, or for authority you lack, with
   your recommended answer. Facts are yours: read, run or prototype.
 - Label claims measured (run and seen this session), inferred, or guess.
@@ -122,9 +122,8 @@ Autonomy contract:
   is not evidence of a requested remote push. Before reporting delivery,
   reconcile every requested item and observe it (\`workit verify-delivery\`).
 
-CLI first: if a step has one right answer, use the \`workit\` verb instead of
-hand-running git, gh or glab (\`workit git|pr|ci|check|help\`;
-else \`npx -y @brainervirus/workit-cli\`).
+Read-only git and gh run raw; mutations go through workit verbs
+(\`workit git|pr|ci|check|help\`; else \`npx -y @brainervirus/workit-cli\`).
 Other checkout: \`workit <verb> --cwd <dir> …\` (verb first: host rules match it); one workit
 verb per shell call, never \`cd <dir> && workit\`. zsh-safe: no \`echo =====\`
 (\`printf '%s\\n' ---\`), quote globs and URLs, no variable named \`status\` or \`path\`.

package/src/hooks/context.ts

@@ -3,6 +3,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { allowedKinds, branchPolicySnapshotFor } from "../core/branch";
 import { invariantBootstrap } from "../core/methods";
 import { resolveStore } from "../store/paths";
 import { canonicalJson } from "../core/task-contract";
@@ -298,6 +299,40 @@ export const sessionContextText = (
 };
 
 /** Per-turn task context only (no bootstrap or offer), or null when none applies. */
+/** The checkout holding `cwd` and its branch, read from the git dir (no spawn). */
+const checkoutAt = (cwd: string): { root: string; branch: string | null } | null => {
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    const dotGit = path.join(dir, ".git");
+    if (fs.existsSync(dotGit)) {
+      const admin = fs.statSync(dotGit).isFile()
+        ? path.resolve(
+            dir,
+            /^gitdir:\s*(.+)$/mu.exec(fs.readFileSync(dotGit, "utf8"))?.[1]?.trim() ?? "",
+          )
+        : dotGit;
+      const head = fs.readFileSync(path.join(admin, "HEAD"), "utf8").trim();
+      return { root: dir, branch: /^ref: refs\/heads\/(.+)$/u.exec(head)?.[1] ?? null };
+    }
+    if (path.dirname(dir) === dir) return null;
+  }
+};
+
+/** One short line: where the agent is and which branch kinds it may create (#431). */
+export const whereLine = (cwd: string): string | null => {
+  try {
+    const checkout = checkoutAt(cwd);
+    if (!checkout) return null;
+    const allowed = branchPolicySnapshotFor(cwd).namePolicy.allowed;
+    const kinds = allowed.some((pattern) => pattern.source === "^.*$")
+      ? "any"
+      : allowedKinds(allowed).join(", ") || "see `workit help git`";
+    const place = checkout.root === path.resolve(cwd) ? "" : ` in ${checkout.root}`;
+    return `cwd ${cwd}${place} on ${checkout.branch ?? "detached HEAD"}; branch kinds: ${kinds}`;
+  } catch {
+    return null;
+  }
+};
+
 export const turnContextText = (input: HookInput, descriptor: HostDescriptor): string | null => {
   try {
     const text = sessionCompactContext(
@@ -307,7 +342,9 @@ export const turnContextText = (input: HookInput, descriptor: HostDescriptor): s
       descriptor.context.task,
     );
     if (text === MIGRATION_PENDING_NOTE) return text;
-    return text ? `<workit-task-context>${text}</workit-task-context>` : null;
+    return text
+      ? `<workit-task-context>${[whereLine(input.cwd), text].filter(Boolean).join("\n")}</workit-task-context>`
+      : null;
   } catch {
     return null;
   }

package/src/hooks/handle.ts

@@ -34,7 +34,8 @@ import { trackJudge } from "./session-marker";
 import { stopDecision } from "./stop";
 import { liveOwner } from "../core/live-session";
 import { liveTargets, shellGate, writeGate } from "./write-gate";
-import { confineImplementer, confineImplementerShell, hostIsolated } from "./worktree-confine";
+import { confineImplementer, confineImplementerShell } from "./worktree-confine";
+import { agentSteering, workitRole } from "./steering";
 import type { HookDecision, HookEventKind, HookInput, HostAdapter, RenderedHook } from "./protocol";
 
 export type HookDeps = { descriptor: HostDescriptor; addendum: string | null };
@@ -48,29 +49,6 @@ const resendsOnChange = (descriptor: HostDescriptor): boolean =>
 /** Sessions already offered unfinished tasks in this process. */
 const offered = new Set<string>();
 
-const ROLES: Readonly<Record<string, "implementer" | "judge">> = {
-  implementer: "implementer",
-  verifier: "judge",
-  reviewer: "judge",
-};
-
-/**
- * The Workit agent role an agent type names, spelled the host's way
- * (`descriptor.subagents.agentPrefix`): Claude Code namespaces plugin agents
- * (`workit:implementer`, so a bare `workit-implementer` is someone else's);
- * other hosts name custom agents freely (`workit-implementer`). The
- * implementer is the one subagent that writes; verifier and reviewer are
- * read-only judges that record verdicts as their own session.
- */
-const workitRole = (
-  descriptor: HostDescriptor,
-  agentType: string,
-): "implementer" | "judge" | null => {
-  const prefix = descriptor.subagents.agentPrefix;
-  const name = agentType.startsWith(prefix) ? agentType.slice(prefix.length) : "";
-  return Object.hasOwn(ROLES, name) ? ROLES[name] : null;
-};
-
 /** A tool call made by a Workit implementer subagent (the host names its agent type). */
 const implementerAgent = (input: HookInput, descriptor: HostDescriptor): boolean =>
   Boolean(input.session.agentId) &&
@@ -85,9 +63,6 @@ const subagentSession = (session: string | null, agentId: string): string =>
     .replace(/[^A-Za-z0-9_.:@/+-]/g, "-")
     .slice(0, 128);
 
-/** A Claude Code worktree path: `<repo>/.claude/worktrees/<name>`. */
-const CLAUDE_WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]/;
-
 /**
  * Claude Code's worktree isolation refuses any command that wraps git
  * (`workit git …` included) and cannot be turned off, so an isolated agent
@@ -106,21 +81,17 @@ const subagentStartText = (
   event: Extract<HookInput["event"], { kind: "subagent.start" }>,
 ): string => {
   const session = input.session.id ?? null;
-  const role = workitRole(descriptor, event.agentType);
+  const { role, isolated, git } = agentSteering(descriptor, input.cwd, {
+    type: event.agentType,
+    id: event.agentId,
+  });
   const who = `${descriptor.label} subagent ${event.agentId} (${event.agentType})`;
-  // An implementer is host-isolated only when the host put it in its own
-  // worktree (`.claude/worktrees/agent-<id>`); by default the lead makes one.
-  const isolated =
-    descriptor.subagents.worktreeIsolation === "native" &&
-    (role === "implementer"
-      ? hostIsolated(input.cwd, event.agentId)
-      : CLAUDE_WORKTREE.test(input.cwd));
   const guide = role === "implementer" ? branchGuidance(input.cwd) : null;
-  if (role === "implementer" && isolated)
+  if (git === "plain")
     return `Workit observed ${who} working in its own git worktree: it may edit and commit there, within its brief's scope. ${isolatedGit(input.cwd)} Plain git is expected here, and the branch name is still policy-checked: a raw \`git switch -c\`, \`git checkout -b\`, \`git branch\` or \`git worktree add -b\` onto a protected or non-compliant name is denied, so use a policy-compliant branch.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
   if (isolated)
     return `${isolatedGit(input.cwd)}\n${subagentStartText({ ...input, cwd: "" }, descriptor, event)}`;
-  if (role === "implementer")
+  if (git === "workit")
     // No host isolation: the lead makes the worktree, Workit's hooks confine
     // the implementer to it (worktree-confine.ts), and workit git works there.
     return `Workit observed ${who} as an implementer: it edits and commits only in its own git worktree, the one its brief names (the lead makes it with \`workit fanout worktree create <slice>\` before spawning), never in the lead's checkout, within its brief's scope. Workit binds it to the first Workit worktree it changes: from then on an edit or a mutating git command outside that worktree is denied, and before then so is one outside every Workit worktree. Run Workit against the worktree one verb per call, never \`cd … &&\` chains or \`$VAR\` paths: \`workit git --cwd <worktree> commit -m "<message>" -- <paths>\`, \`workit check --cwd <worktree> <name>\` (verb first, so host allow rules match). The worktree is on the brief's branch once the lead made it; otherwise switch with \`workit git --cwd <worktree> branch <branch> --base <base>\` (or \`--kind <kind> --slug <slug>\`, which picks the base); branch policy hooks still deny protected or non-compliant branches, raw git included.${guide ? ` ${guide}` : " (e.g. feature/<slug>)"} Never record a verdict on your own work. Never push, open a PR, or merge unless the brief asks for it.`;
@@ -272,8 +243,14 @@ function decide(input: HookInput, deps: HookDeps): HookDecision {
       // 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 rewritten(null);
+      // Only an agent no start text told how to run git is nudged (#428).
+      const { nudges } = agentSteering(descriptor, input.cwd, {
+        type: input.session.agentType,
+        id: input.session.agentId,
+      });
+      const nudge = canDeny ? rawGitPre(input, event.command, { nudge: nudges }) : NONE;
       const nudged = withContextLine(
-        withContextLine(canDeny ? rawGitPre(input, event.command) : NONE, aside),
+        withContextLine(nudge, aside),
         shipNudge(input, event.command),
       );
       // A deny always wins over the cwd rewrite.

package/src/hooks/raw-git.ts

@@ -6,8 +6,10 @@
 //     remote onto a protected branch or the default target, naming the
 //     workit command;
 //   - lets routine raw commands run (`git commit`, a feature-branch push,
-//     `gh pr create|view|checks`, `glab mr create|view`) with a short nudge,
-//     once per kind per session, and none on a command that runs workit.
+//     `gh pr create`, `glab mr create`) with a short nudge, once per kind per
+//     session, only for an agent no start text told how to run git
+//     (steering.ts), and none on a command that runs workit. Read-only
+//     commands (`gh pr view|checks`, `git status`) get none.
 // A raw `git commit` is recorded as the session's `commit.recorded` row so
 // the author's own verdict never reads as independent. The pre-tool hook
 // notes HEAD before the command (a marker in the commit's own repository);
@@ -1697,8 +1699,8 @@ const nudgeFor = (action: RawAction, host: HookInput["host"], session: string):
         : `workit: prefer ${quote("workit git push")}: it refuses protected branches and verifies the remote tip.`;
     case "pr-create":
       return `workit: prefer ${quote("workit pr create --fill")} (or --title/--body): it records the PR the merge gate checks.`;
+    // Read-only: raw is fine (the contract says so once).
     case "pr-read":
-      return `workit: ${quote("workit pr status")} shows the PR, its checks and the verdict state; ${quote("workit ci wait")} waits for checks.`;
     case "merge":
       return null;
   }

package/src/hooks/steering.ts

@@ -0,0 +1,61 @@
+// What Workit tells an agent about git, by role: one source for the
+// SubagentStart text (handle.ts) and the raw-git nudge set (raw-git.ts), so
+// the two cannot disagree (#428).
+import type { HostDescriptor } from "./descriptor";
+import { hostIsolated } from "./worktree-confine";
+
+export type WorkitRole = "implementer" | "judge";
+
+const ROLES: Readonly<Record<string, WorkitRole>> = {
+  implementer: "implementer",
+  verifier: "judge",
+  reviewer: "judge",
+};
+
+/**
+ * The Workit agent role an agent type names, spelled the host's way
+ * (`descriptor.subagents.agentPrefix`): Claude Code namespaces plugin agents
+ * (`workit:implementer`, so a bare `workit-implementer` is someone else's);
+ * other hosts name custom agents freely (`workit-implementer`).
+ */
+export const workitRole = (descriptor: HostDescriptor, agentType: string): WorkitRole | null => {
+  const prefix = descriptor.subagents.agentPrefix;
+  const name = agentType.startsWith(prefix) ? agentType.slice(prefix.length) : "";
+  return Object.hasOwn(ROLES, name) ? ROLES[name] : null;
+};
+
+/** A Claude Code worktree path: `<repo>/.claude/worktrees/<name>`. */
+const CLAUDE_WORKTREE = /[\\/]\.claude[\\/]worktrees[\\/]/;
+
+export type RoleSteering = {
+  role: WorkitRole | null;
+  /** The host put the agent in its own worktree. */
+  isolated: boolean;
+  /** How the start text tells it to run git: `plain` (host isolation refuses a wrapper), `workit`, or not at all. */
+  git: "plain" | "workit" | null;
+  /** Raw commit/push/PR-create nudges: only for an agent no start text told how to run git. */
+  nudges: boolean;
+};
+
+export const roleSteering = (role: WorkitRole | null, isolated: boolean): RoleSteering => ({
+  role,
+  isolated,
+  git: role === "implementer" ? (isolated ? "plain" : "workit") : null,
+  // An implementer has its git line already; a judge does not commit.
+  nudges: role === null,
+});
+
+/** The steering for one agent, as the host names it (no agent type: the lead). */
+export const agentSteering = (
+  descriptor: HostDescriptor,
+  cwd: string,
+  agent: { type: string | null; id: string | null },
+): RoleSteering => {
+  const role = agent.type ? workitRole(descriptor, agent.type) : null;
+  // An implementer is host-isolated only when the host put it in its own
+  // worktree (`.claude/worktrees/agent-<id>`); by default the lead makes one.
+  const isolated =
+    descriptor.subagents.worktreeIsolation === "native" &&
+    (role === "implementer" ? hostIsolated(cwd, agent.id) : CLAUDE_WORKTREE.test(cwd));
+  return roleSteering(role, isolated);
+};