@brainervirus/workit-core 8.29.0 → 8.29.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.29.0",
+  "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/heavy.ts

@@ -446,8 +446,8 @@ export type HeavyPlan =
   | { kind: "rewrite"; command: string; reason: string }
   /** A chain with heavy parts: run each part alone (`unblock` is the first heavy one). */
   | { kind: "split"; reason: string; unblock: string | null }
-  /** A host rule names it, or wrapping would raise it: it runs as typed. */
-  | { kind: "passthrough"; note: string };
+  /** A host rule names it, or wrapping would raise it: it runs as typed, saying nothing. */
+  | { kind: "passthrough"; note: "" };
 
 export type PlanOptions = HeavyOptions & {
   /** The host's permission rules; null where the host has none to read (Pi). */
@@ -476,7 +476,7 @@ export function heavyPlan(command: string, options: PlanOptions): HeavyPlan {
   if (!lines) return { kind: "none" };
   const heavy = heavyLines(lines, options);
   if (!heavy.length) return { kind: "none" };
-  const simple = simpleCommand(command, dialect);
+  const simple = simpleCommand(command, dialect, 0, true);
   const single = simple && !WORKIT.test(baseName(simple[0])) && heavyLines([simple], options)[0];
   const judged = single
     ? [{ words: lines.flat(), text: command }]
@@ -490,7 +490,7 @@ export function heavyPlan(command: string, options: PlanOptions): HeavyPlan {
       if (!verdict.ok)
         return {
           kind: "passthrough",
-          note: `workit: \`${command.trim()}\` is heavy but runs outside the heavy-check lease because a host permission rule names it (or \`workit\` is allowlisted); the host decides.`,
+          note: "",
         };
     }
   if (single) {
@@ -502,7 +502,7 @@ export function heavyPlan(command: string, options: PlanOptions): HeavyPlan {
   const parts = heavy.map((match) => leaseCommand(match.line));
   return {
     kind: "split",
-    reason: `heavy_command: \`${command.trim()}\` chains heavy work (${heavy.map((match) => match.reason).join("; ")}) with other commands, and a chain cannot run under the machine-wide heavy-check lease. Run each heavy part alone as \`workit check --heavy -- <segment>\` (here: ${parts.map((part) => `\`${part}\``).join("; ")}); run the other parts as their own commands.`,
+    reason: `heavy_command: \`${command.trim()}\` chains heavy work (${heavy.map((match) => match.reason).join("; ")}) with other commands, and a chain cannot run under the machine-wide heavy-check lease. Run the heavy part alone, now: \`${parts[0]}\`; then run the other parts as their own commands${parts.length > 1 ? ", each heavy one the same way" : ""}.`,
     unblock: parts[0] ?? null,
   };
 }

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,39 +81,43 @@ 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.`;
   const readOnly = `Workit observed ${who} as read-only/agent-guided.`;
   if (role !== "judge" || !event.agentId) return readOnly;
   const own = subagentSession(session, event.agentId);
+  const cwd = input.cwd || process.cwd();
+  const judge = event.agentType.endsWith("reviewer") ? "reviewer" : "verifier";
+  const pick = judge === "verifier" ? ", --kind live when you drove the real surface" : "";
+  const branch = judgeBranch(cwd);
+  // Codex runs a subagent's shell with its own CODEX_THREAD_ID: the CLI already
+  // acts as that session, so the line names no --session and no --token (a
+  // token on a command line lands in the rollout, #427) and nothing is issued.
+  if (descriptor.host === "codex_cli" || descriptor.host === "codex_desktop")
+    return `${readOnly} Its shell already acts as its own Workit session, so the ledger tells its verdicts apart from the author's. Record the verdict with exactly this command (pick the result${pick}, name the candidate branch if it differs, say what you ran): \`${verdictCommand({ branch, judge })}\`. Add no session or token option to it, and never set WORKIT_SESSION_ID by hand.`;
   // `ledger verdict` accepts `<lead>:<agent id>` only when this hook issued it,
-  // and only with the token it hands to this subagent alone.
+  // and only with the token it hands to this subagent alone. Claude Code
+  // subagents share the lead's environment, so no per-agent env var or file
+  // can carry it: the token stays on the line (docs/agents/hosts.md, #427).
   // (An isolated judge's text is rebuilt with cwd "": the hook's own cwd then.)
   // Issued once: a replayed SubagentStart for the same id gets no token.
-  const cwd = input.cwd || process.cwd();
   const token = session ? recordIssuedSession(cwd, session, own) : null;
   // Already issued: without its token the id is refused (unbound_session).
   if (session && !token)
     return `${readOnly} ${own} was already issued to an earlier subagent, so no token is handed out again and a verdict under it would be refused (unbound_session). Record no verdict as ${own}: spawn a fresh verifier or reviewer, which gets its own session and token.`;
-  const judge = event.agentType.endsWith("reviewer") ? "reviewer" : "verifier";
-  const line = verdictCommand({ branch: judgeBranch(cwd), judge, session: own, token });
-  const pick = judge === "verifier" ? ", --kind live when you drove the real surface" : "";
+  const line = verdictCommand({ branch, judge, session: own, token });
   return `${readOnly} Its own Workit session is ${own}, so the ledger tells its verdicts apart from the author's. Record the verdict with exactly this command (pick the result${pick}, name the candidate branch if it differs, say what you ran): \`${line}\`.${token ? " The token is this subagent's alone: never write it into a report, a file or a commit. --token needs a workit CLI at least as new as this plugin; if the CLI answers that --token is an unknown option, update the workit CLI (workit upgrade --cli) and record again." : ""}`;
 };
 
@@ -264,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);
@@ -727,15 +729,19 @@ export function workitCheckTail(
     : { argv: tail, cwd };
 }
 
+const OUTPUT_FILTERS = new Set(["tail", "head", "grep"]);
+
 /**
  * The one command `command` runs after its wrappers (env prefixes, `timeout`,
  * `nice`, `flock`, `bash -c '<one command>'`), or null when it is a chain,
- * pipe, redirect, substitution, group or heredoc anywhere.
+ * pipe, redirect, substitution, group or heredoc anywhere (`shaped` allows
+ * redirects and one trailing `| tail|head|grep` filter).
  */
 export function simpleCommand(
   command: string,
   dialect: ShellDialect = "posix",
   depth = 0,
+  shaped = false,
 ): string[] | null {
   let segments: Segment[];
   try {
@@ -743,13 +749,27 @@ export function simpleCommand(
   } catch {
     return null;
   }
-  if (segments.length !== 1) return null;
+  // `shaped`: output shaping around the one command is not a chain: any
+  // redirects, and at most one trailing `| tail|head|grep …` filter.
+  const filter = shaped && segments.length === 2 ? segments[1] : null;
+  if (filter) {
+    if (
+      !segments[0].pipe ||
+      !OUTPUT_FILTERS.has(commandName(filter.words[0])) ||
+      filter.group ||
+      filter.pipe ||
+      filter.unanalyzable ||
+      filter.subs?.length ||
+      filter.stdin?.length
+    )
+      return null;
+  } else if (segments.length !== 1) return null;
   const [segment] = segments;
   if (
     segment.group ||
-    segment.pipe ||
+    (segment.pipe && !filter) ||
     segment.unanalyzable ||
-    segment.redirects.length ||
+    (segment.redirects.length && !shaped) ||
     segment.subs?.length ||
     segment.stdin?.length
   )
@@ -1679,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);
+};

package/src/host-session.ts

@@ -381,6 +381,20 @@ export type SessionClaimRefusal = { error: string; unblock: string };
  * Anything else is a forged id: a verdict recorded under it would make author
  * is not verifier a naming convention.
  */
+const isOwnShellClaim = (real: RealSession, claimed: string): boolean =>
+  (claimed === real.session && !(real.kind === "declared" && claimed.includes(":"))) ||
+  (real.kind === "derived" && claimed.endsWith(`:${real.session}`));
+
+/**
+ * `claimed` is the shell's own derived session (OPENCODE_SESSION_ID,
+ * PI_SESSION_ID, CODEX_THREAD_ID), alone or as `<lead>:<it>`: a `--session`
+ * naming it adds nothing, so the CLI acts as the shell's session instead.
+ */
+export const namesOwnDerivedSession = (env: NodeJS.ProcessEnv, claimed: string): boolean => {
+  const real = realHostSession(env);
+  return real.kind === "derived" && isOwnShellClaim(real, claimed);
+};
+
 export function sessionClaimRefusal(
   env: NodeJS.ProcessEnv,
   claimed: string,
@@ -397,16 +411,17 @@ export function sessionClaimRefusal(
       unblock: `record the verdict from the ${real.host} session's own shell, where ${HOST_SET_VARIABLE[host]} is set`,
     };
   if (real.kind === "none" || !real.session) return null;
-  const ownShell =
-    (claimed === real.session && !(real.kind === "declared" && claimed.includes(":"))) ||
-    (real.kind === "derived" && claimed.endsWith(`:${real.session}`));
-  if (ownShell)
-    return options.flag
-      ? {
-          error: `session_flag: --session ${claimed} names this shell's own ${real.host} session; on a host only an issued subagent id is passed as --session`,
-          unblock: "drop --session: the shell's own session is already the acting one",
-        }
-      : null;
+  const ownShell = isOwnShellClaim(real, claimed);
+  if (ownShell) {
+    // A derived session (the host's own shell variable) cannot be replaced by
+    // a flag, so naming it is a no-op, not an error: a printed line that
+    // carries it still records. Declared sessions keep refusing the flag.
+    if (!options.flag || real.kind === "derived") return null;
+    return {
+      error: `session_flag: --session ${claimed} names this shell's own ${real.host} session; on a host only an issued subagent id is passed as --session`,
+      unblock: "drop --session: the shell's own session is already the acting one",
+    };
+  }
   const issuedClaim = claimed === real.session || claimed.startsWith(`${real.session}:`);
   if (issuedClaim) {
     const binding = issuedBinding(cwd, claimed);