opencode-herdr-orchestration 0.3.0 → 0.3.1

package/README.md

@@ -595,11 +595,11 @@ This restriction is not hard-enforced by Herdr. Matchers are string globs and ca
 
 ## Developer steering
 
-Developer steering is a trusted-Developer queue scoped per Plan ID target under `<git-common-dir>/flocky/steering/<planId>/`. There is exactly one submission tool, `herdr_steering_submit`, registered through the existing plugin mechanism. The submission allowlist holds only the explicit non-flock `developer` context; `shepherd`, `shepherd-governor`, `sheepdog`, `grazer`, `sheep`, `shearer-low`, `shearer-medium`, `unknown`, `ambiguous`, `none`, and unset contexts are denied fail-closed with no filesystem write. Developer is never inferred from session mode, directory, environment text, or prompt content. Static per-agent permissions deny the tool for all seven orchestration roles as defense in depth; the runtime `context.agent` check stays authoritative over static overrides.
+Developer steering is a trusted-Developer queue scoped per Plan ID target under `<git-common-dir>/flocky/steering/<planId>/`. There is exactly one submission tool, `herdr_steering_submit`, plus one native `/steer` command hook as a second enforcement point with parity: both share the single `STEERING_TOOL_ACCESS` allowlist and both write directly through the existing state service with identical validation plus journaling and no parallel store. The submission allowlist holds only the explicit non-flock `developer` context; `shepherd`, `shepherd-governor`, `sheepdog`, `grazer`, `sheep`, `shearer-low`, `shearer-medium`, `unknown`, `ambiguous`, `none`, and unset contexts are denied fail-closed with no filesystem write. Developer is never inferred from session mode, directory, environment text, or prompt content. Static per-agent permissions deny the tool for all seven orchestration roles as defense in depth; the runtime `context.agent` check plus the `/steer` SDK session-agent check stays authoritative over static overrides.
 
 ### Steering UX through the existing integration
 
-There is no `herdr steer` command and no package CLI steering command. The Developer submits only through the `herdr_steering_submit` plugin tool in a Developer context:
+There is no `herdr steer` command and no package CLI steering command; the native `/steer` opencode command is installer-owned (`command.steer` with agent pin `developer`, `$ARGUMENTS` template, and description) and intercepted by `command.execute.before`, which writes directly via the existing state service then throws to abort before any model turn with confirmation carrying the steering id plus resolved target and a minimal text-parts fallback. The Developer submits either through `/steer` or through the `herdr_steering_submit` plugin tool in a Developer context:
 
 ```json
 {
@@ -627,7 +627,7 @@ The recorded `developer` submitter is integration-asserted by the OpenCode plugi
 }
 ```
 
-Any session that can present as `developer` — including a custom-configured `developer` agent — can submit. Flock roles cannot present as Developer: `developer` is not a registered orchestration agent, no spawn matrix entry creates it, static per-agent permissions deny `herdr_steering_submit` for all seven orchestration roles, and the runtime allowlist holds only `developer`. The runtime check stays authoritative over static overrides: even a local config that flips a flock role to `allow` still fails with `UNAUTHORIZED_AGENT` and writes nothing. Developer is mapped to an explicit non-flock `SHEPHERD_MODE` value `developer`, distinct from `shepherd`, `governor`, `sheepdog`, `grazer`, `sheep`, `shearer`, and `none`. Keep remote authorization and human review as the authoritative controls for anything consequential. There is no `herdr steer` command and no package CLI steering command; `bin/orchestration.js` and `package.json` expose only `opencode-herdr-orchestration` with `install`, `update`, `configure-agents`, `status`, `uninstall`, `install-hooks`, and `uninstall-hooks`.
+Any session that can present as `developer` — including the registered `developer` profile — can submit. Flock roles cannot present as Developer: the `developer` profile holds only `herdr_steering_submit` with no spawn rights and no spawn matrix entry creates or targets it, static per-agent permissions deny `herdr_steering_submit` for all seven orchestration roles, and the runtime allowlist holds only `developer`. The runtime check plus the `/steer` SDK session-agent resolution stays authoritative over static overrides: even a local config that flips a flock role to `allow` still fails with `UNAUTHORIZED_AGENT` and writes nothing, and an unresolvable session agent fails closed with no write. Developer is mapped to an explicit non-flock `SHEPHERD_MODE` value `developer`, distinct from `shepherd`, `governor`, `sheepdog`, `grazer`, `sheep`, `shearer`, and `none`. Keep remote authorization and human review as the authoritative controls for anything consequential. There is still no `herdr steer` command and no package CLI steering command; `bin/orchestration.js` and `package.json` expose only `opencode-herdr-orchestration` with `install`, `update`, `configure-agents`, `status`, `uninstall`, `install-hooks`, and `uninstall-hooks`, while the installer owns `command.steer` in the OpenCode config. `/steer` arguments are `<content>` or `<planId> :: <content>`; omit `planId` only for a single active target.
 
 ## Shepherd ownership and lifecycle synchronization
 
@@ -715,7 +715,7 @@ Live-verified on `herdr 0.8.2` plus `opencode 1.18.29` plus package `0.2.1` with
 
 **Cause:** On Windows PowerShell `opencode` may resolve to the direct exe (`node_modules/opencode-ai/bin/opencode.exe`) or to a shim (`opencode.cmd`, `opencode.ps1`, `opencode.exe` in the npm prefix) depending on `PATH` order. `PATH` here means the session `PATH` inspected read-only with `$env:PATH`. File-version text is not authoritative next to CLI `opencode --version` output `1.18.29`. Herdr panes inherit the Herdr server environment, not the current session `PATH`. A global `opencode upgrade` recreates the npm shims, so a previously durable order can flap back to shim-first with a bumped `opencode --version` versus `npm view opencode-ai version`.
 
-**Check:** Inspect the resolver without changing it. `(Get-Command opencode).Source` shows the winning launcher. `(Get-Command opencode -All).Source` lists every candidate in order and reveals a reappearing shim after a global update. `(Get-Command herdr).Source` plus `(Get-Command herdr -All).Source` confirms Herdr resolves to a single `bin` exe with no shim confusion. Compare `opencode --version` against the full-path exe and shim forms; healthy hosts report the same `1.18.29` from each, while a bumped `opencode --version` against `npm view opencode-ai version` signals a recent global update. Confirm the process-spawn path with `Start-Process` using `-FilePath` from the resolved launcher plus `-ArgumentList --version -NoNewWindow -Wait`; live the extensionless shim fails with `%1 is not a valid Win32 application` while the direct exe reports `1.18.29`. Inspect order read-only with `$env:PATH`. Confirm the server split with `herdr status` showing `status: running` for `server` separate from client. This package never overwrites the global environment. Config resolution only reads the environment in `src/installer.js:40` (`configDirectory`) and validation runs isolated with `OPENCODE_DISABLE_PROJECT_CONFIG` in `src/installer.js:529` (`validateOpenCode`), with status reporting in `src/installer.js:552` (`status`). Autoupdate context is `npm view opencode-herdr-orchestration version` reporting `0.2.1` matching `node bin/orchestration.js status` plus `herdr channel show` reporting `stable` plus `herdr update --help` describing the handoff option plus `opencode upgrade --help` listing upgrade targets and methods.
+**Check:** Inspect the resolver without changing it. `(Get-Command opencode).Source` shows the winning launcher. `(Get-Command opencode -All).Source` lists every candidate in order and reveals a reappearing shim after a global update. `(Get-Command herdr).Source` plus `(Get-Command herdr -All).Source` confirms Herdr resolves to a single `bin` exe with no shim confusion. Compare `opencode --version` against the full-path exe and shim forms; healthy hosts report the same `1.18.29` from each, while a bumped `opencode --version` against `npm view opencode-ai version` signals a recent global update. Confirm the process-spawn path with `Start-Process` using `-FilePath` from the resolved launcher plus `-ArgumentList --version -NoNewWindow -Wait`; live the extensionless shim fails with `%1 is not a valid Win32 application` while the direct exe reports `1.18.29`. Inspect order read-only with `$env:PATH`. Confirm the server split with `herdr status` showing `status: running` for `server` separate from client. This package never overwrites the global environment. Config resolution only reads the environment in `src/installer.js:48` (`configDirectory`) and validation runs isolated with `OPENCODE_DISABLE_PROJECT_CONFIG` in `src/installer.js:594` (`validateOpenCode`), with status reporting in `src/installer.js:617` (`status`). Autoupdate context is `npm view opencode-herdr-orchestration version` reporting `0.2.1` matching `node bin/orchestration.js status` plus `herdr channel show` reporting `stable` plus `herdr update --help` describing the handoff option plus `opencode upgrade --help` listing upgrade targets and methods.
 
 **Fix:** For current-session relief use the winning full exe path directly. For a durable fix apply a persistent user-chosen `PATH` reorder that places the direct exe directory before the npm shim directory, then restart Herdr plus the terminal plus OpenCode intentionally when ready, then follow [Upgrade](#upgrade) for the package update path. Session-local changes alone never fix Herdr spawns because panes inherit the server environment. This package never reorders global state automatically and never sets global environment values automatically; the persistent reorder is an operator-chosen Windows user environment change, not a package write.
 

package/bin/orchestration.js

@@ -22,6 +22,7 @@ import {
   validateOpenCode,
   writeAgentFilesManifest,
   writePluginConfig,
+  writeSteerCommand,
 } from "../src/installer.js";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -127,12 +128,14 @@ async function installOrUpdate(useLatest) {
     restoreBackup(result.file, result.backup, result.existed);
     throw new Error(`OpenCode validation failed; restored the previous config. ${error.message}`);
   }
+  const steerResult = writeSteerCommand(configDir, false);
   const reconciliation = reconcileAgentFiles(configDir, { remove: false });
   writeAgentFilesManifest(configDir, reconciliation.manifestEntries, version);
   if (flags.includes("--with-hooks")) installHooks();
   process.stdout.write(`Configured ${PACKAGE_NAME}@${version} in ${result.file}\n`);
   reportReconciliation(reconciliation);
   if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
+  if (steerResult.backup && steerResult.backup !== result.backup) process.stdout.write(`Backup: ${steerResult.backup}\n`);
   for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
   process.stdout.write("Restart OpenCode intentionally to load the new configuration.\n");
 }
@@ -157,6 +160,7 @@ async function configureAgents() {
 
 function uninstallOrchestration() {
   const configDir = configDirectory();
+  const steerResult = writeSteerCommand(configDir, true);
   const result = writePluginConfig(configDir, true);
   const packageBackups = uninstallPackage(configDir);
   const reconciliation = reconcileAgentFiles(configDir, { remove: true });
@@ -167,7 +171,8 @@ function uninstallOrchestration() {
     process.stdout.write(`Removed package-owned agent file: ${relPath}\n`);
   }
   reportReconciliation(reconciliation);
-  if (result.backup) process.stdout.write(`Backup: ${result.backup}\n`);
+  if (steerResult.backup) process.stdout.write(`Backup: ${steerResult.backup}\n`);
+  if (result.backup && result.backup !== steerResult.backup) process.stdout.write(`Backup: ${result.backup}\n`);
   for (const backup of packageBackups) process.stdout.write(`Backup: ${backup}\n`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-herdr-orchestration",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Capability-separated Herdr orchestration agents for OpenCode",
   "author": "CodingJinxx",
   "repository": {
@@ -28,7 +28,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "check": "node --check src/plugin.js && node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check src/state.js && node --check src/diagnostics.js && node --check bin/orchestration.js"
+    "check": "node --check src/plugin.js && node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check src/state.js && node --check src/diagnostics.js && node --check src/steer.js && node --check src/installer.js && node --check bin/orchestration.js"
   },
   "engines": {
     "node": ">=20"

package/src/agents.js

@@ -105,11 +105,15 @@ function stateToolPermissions(allowedTools) {
 // Developer steering submission (M2, Option A, trusted Developer only).
 // The explicit non-flock `developer` context is the sole submitter; all
 // seven orchestration roles are denied as defense in depth. The runtime
-// context-agent check in src/index.js stays authoritative over these static
-// entries: even a user override flipping one to "allow" must not bypass the
-// allowlist. No flock role may present as Developer: developer is not a
-// registered orchestration agent and no spawn matrix entry creates it.
+// context-agent check in src/index.js plus the /steer hook in src/steer.js
+// stays authoritative over these static entries: even a user override
+// flipping one to "allow" must not bypass the allowlist. No flock role may
+// present as Developer: the developer profile below holds only the submit
+// tool and no spawn matrix entry creates or targets it.
 export const DEVELOPER_AGENT = "developer";
+export const DEVELOPER_PROMPT = String.raw`
+You are developer, the trusted steering submitter. Submit bounded steering via /steer as <content> or <planId> :: <content>; omit planId only when exactly one active steering target exists. You hold only herdr_steering_submit; you never implement flock work, never spawn workers, and never read raw steering.
+`.trim();
 export const ORCHESTRATION_ROLES = Object.freeze([
   "shepherd",
   "shepherd-governor",
@@ -629,6 +633,23 @@ export function createAgents(options = {}) {
 
     "shearer-low": reviewerAgent(reviewerModel, "low"),
     "shearer-medium": reviewerAgent(reviewerModel, "medium"),
+
+    developer: {
+      mode: "primary",
+      description: "Trusted Developer steering submitter; submits bounded steering via /steer; never implements flock work.",
+      prompt: DEVELOPER_PROMPT,
+      permission: {
+        ...stateToolPermissions([]),
+        ...steeringToolPermissions([STEERING_TOOLS.submit]),
+        ...rawSteeringToolPermissions([]),
+        ...ownershipToolPermissions([]),
+        herdr_agent_response: "deny",
+        task: "deny",
+        edit: "deny",
+        apply_patch: "deny",
+        bash: { "*": "deny", ...separatorDenials },
+      },
+    },
   };
 }
 

package/src/index.js

@@ -16,6 +16,7 @@ import {
 } from "./agents.js";
 import { createResponseTool } from "./response.js";
 import { createStateService } from "./state.js";
+import { createSteerCommandHook } from "./steer.js";
 
 const SESSION_MODES = new Map();
 
@@ -344,39 +345,56 @@ export function createOwnershipTools(stateOptions = {}) {
   return tools;
 }
 
-export const HerdrOrchestrationPlugin = async (_input, options = {}) => ({
-  tool: {
-    herdr_agent_response: createResponseTool(options.response),
-    ...createStateTools(options.state),
-    ...createSteeringTools(options.state),
-    ...createRawSteeringTools(options.state),
-    ...createOwnershipTools(options.state),
-  },
-  config(config) {
-    config.agent ??= {};
-    const agents = createAgents(options);
-    for (const [name, defaults] of Object.entries(agents)) {
-      config.agent[name] = mergeAgent(defaults, config.agent[name]);
-    }
-  },
+export const HerdrOrchestrationPlugin = async (pluginInput = {}, options = {}) => {
+  const stateOptions = { ...(options.state ?? {}) };
+  if (stateOptions.cwd === undefined) {
+    const fallback = pluginInput?.directory ?? pluginInput?.worktree;
+    if (typeof fallback === "string" && fallback.length > 0) stateOptions.cwd = fallback;
+  }
+  const resolveAgent = options.steerResolveAgent ?? options.steer?.resolveAgent;
+  const steerBefore = createSteerCommandHook({
+    client: pluginInput?.client,
+    stateOptions,
+    ...(resolveAgent ? { resolveAgent } : {}),
+  });
+  return {
+    tool: {
+      herdr_agent_response: createResponseTool(options.response),
+      ...createStateTools(options.state),
+      ...createSteeringTools(options.state),
+      ...createRawSteeringTools(options.state),
+      ...createOwnershipTools(options.state),
+    },
+    config(config) {
+      config.agent ??= {};
+      const agents = createAgents(options);
+      for (const [name, defaults] of Object.entries(agents)) {
+        config.agent[name] = mergeAgent(defaults, config.agent[name]);
+      }
+    },
 
-  async "chat.message"(input) {
-    if (input.sessionID) SESSION_MODES.set(input.sessionID, modeForAgent(input.agent));
-  },
+    async "command.execute.before"(input, output) {
+      return steerBefore(input, output);
+    },
 
-  async "shell.env"(input, output) {
-    output.env.SHEPHERD_MODE = input.sessionID
-      ? (SESSION_MODES.get(input.sessionID) ?? "none")
-      : "none";
-  },
+    async "chat.message"(input) {
+      if (input.sessionID) SESSION_MODES.set(input.sessionID, modeForAgent(input.agent));
+    },
 
-  async event({ event }) {
-    if (event?.type === "session.deleted") {
-      const sessionID = event.properties?.info?.id ?? event.properties?.sessionID;
-      if (sessionID) SESSION_MODES.delete(sessionID);
-    }
-  },
-});
+    async "shell.env"(input, output) {
+      output.env.SHEPHERD_MODE = input.sessionID
+        ? (SESSION_MODES.get(input.sessionID) ?? "none")
+        : "none";
+    },
+
+    async event({ event }) {
+      if (event?.type === "session.deleted") {
+        const sessionID = event.properties?.info?.id ?? event.properties?.sessionID;
+        if (sessionID) SESSION_MODES.delete(sessionID);
+      }
+    },
+  };
+};
 
 export default HerdrOrchestrationPlugin;
 export {

package/src/installer.js

@@ -5,6 +5,13 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import spawn from "cross-spawn";
 import { applyEdits, modify, parse, printParseErrorCode } from "jsonc-parser";
+import {
+  STEER_COMMAND_AGENT as STEER_AGENT,
+  STEER_COMMAND_DESCRIPTION as STEER_DESCRIPTION,
+  STEER_COMMAND_NAME as STEER_NAME,
+  STEER_COMMAND_TEMPLATE as STEER_TEMPLATE,
+  steerCommandEntry as steerEntry,
+} from "./steer.js";
 
 export const PACKAGE_NAME = "opencode-herdr-orchestration";
 const NPM_COMMAND = "npm";
@@ -17,6 +24,7 @@ export const AGENT_NAMES = [
   "sheep",
   "shearer-low",
   "shearer-medium",
+  "developer",
 ];
 
 // Agents register dynamically through the plugin, so the package owns no agent
@@ -391,6 +399,64 @@ export function writePluginConfig(configDir, remove = false, models) {
   return { file, backup, changed: true, existed };
 }
 
+// Native /steer command owned by the installer. Single source for the shape
+// lives in src/steer.js; these helpers persist it with the same JSONC
+// preserve-comments plus backup discipline as the plugin config. The entry
+// pins agent developer, carries an $ARGUMENTS template, and describes the
+// Developer-only direct-write hook.
+export {
+  STEER_COMMAND_AGENT,
+  STEER_COMMAND_DESCRIPTION,
+  STEER_COMMAND_NAME,
+  STEER_COMMAND_TEMPLATE,
+  steerCommandEntry,
+} from "./steer.js";
+
+export function updateCommandConfig(text, commandName, entry, remove = false) {
+  const errors = [];
+  const parsed = parse(text || "{}", errors, { allowTrailingComma: true, disallowComments: false });
+  if (errors.length) {
+    const first = errors[0];
+    throw new Error(`Invalid OpenCode JSONC at offset ${first.offset}: ${printParseErrorCode(first.error)}.`);
+  }
+  if (typeof commandName !== "string" || commandName.length === 0) {
+    throw new Error("Command name must be a non-empty string.");
+  }
+  const source = text || "{}";
+  if (remove && parsed?.command?.[commandName] === undefined) return source;
+  const formattingOptions = { insertSpaces: true, tabSize: 2, eol: source.includes("\r\n") ? "\r\n" : "\n" };
+  const value = remove ? undefined : entry;
+  return applyEdits(source, modify(source, ["command", commandName], value, { formattingOptions }));
+}
+
+export function updateSteerCommand(text, entry = steerEntry(), remove = false) {
+  return updateCommandConfig(text, STEER_NAME, entry, remove);
+}
+
+export function isSteerCommandConfigured(text) {
+  const config = parse(text || "{}", [], { allowTrailingComma: true, disallowComments: false });
+  const entry = config?.command?.[STEER_NAME];
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  return (
+    entry.agent === STEER_AGENT &&
+    typeof entry.template === "string" &&
+    entry.template.includes("$ARGUMENTS") &&
+    entry.description === STEER_DESCRIPTION
+  );
+}
+
+export function writeSteerCommand(configDir, remove = false) {
+  mkdirSync(configDir, { recursive: true });
+  const file = findConfigFile(configDir);
+  const existed = existsSync(file);
+  const previous = existed ? readFileSync(file, "utf8") : '{\n  "$schema": "https://opencode.ai/config.json"\n}\n';
+  const next = updateSteerCommand(previous, steerEntry(), remove);
+  if (next === previous) return { file, backup: null, changed: false, existed };
+  const backup = backupFile(file);
+  writeFileSync(file, next, "utf8");
+  return { file, backup, changed: true, existed };
+}
+
 export function restoreBackup(file, backup, existed = true) {
   if (backup && existsSync(backup)) copyFileSync(backup, file);
   else if (!existed) rmSync(file, { force: true });
@@ -552,9 +618,16 @@ export function validateOpenCode(configDir) {
 export function status(configDir, packageRoot) {
   const file = findConfigFile(configDir);
   let configured = false;
+  let steerCommandConfigured = false;
   if (existsSync(file)) {
-    const config = parse(readFileSync(file, "utf8"), [], { allowTrailingComma: true, disallowComments: false });
+    const text = readFileSync(file, "utf8");
+    const config = parse(text, [], { allowTrailingComma: true, disallowComments: false });
     configured = Array.isArray(config?.plugin) && config.plugin.some(isOrchestrationPlugin);
+    try {
+      steerCommandConfigured = isSteerCommandConfigured(text);
+    } catch {
+      steerCommandConfigured = false;
+    }
   }
   const installed = installedVersion(configDir);
   let detectedAgents = [];
@@ -586,6 +659,7 @@ export function status(configDir, packageRoot) {
     updateAvailable: Boolean(installed && latest && installed !== latest),
     configFile: file,
     pluginConfigured: configured,
+    steerCommandConfigured,
     detectedAgents,
     agentsReady: detectedAgents.length === AGENT_NAMES.length,
     obsoleteAgentFiles,

package/src/steer.js

@@ -0,0 +1,124 @@
+import { DEVELOPER_AGENT, STEERING_TOOL_ACCESS, STEERING_TOOLS } from "./agents.js";
+import { createStateService } from "./state.js";
+
+// Native /steer command owned by the installer. The hook in this module is
+// the sole writer: it calls the existing state service directly so validation
+// plus journaling stay identical to the submit tool with no parallel store.
+export const STEER_COMMAND_NAME = "steer";
+export const STEER_COMMAND_AGENT = DEVELOPER_AGENT;
+export const STEER_COMMAND_DESCRIPTION =
+  "Submit bounded Developer steering for one Plan ID target (Developer only; flock roles denied).";
+export const STEER_COMMAND_TEMPLATE =
+  "Submit Developer steering with arguments: $ARGUMENTS\n\nFormat $ARGUMENTS as `<content>` or `<planId> :: <content>`; omit planId only when exactly one active steering target exists.";
+
+export function steerCommandEntry() {
+  return {
+    template: STEER_COMMAND_TEMPLATE,
+    description: STEER_COMMAND_DESCRIPTION,
+    agent: STEER_COMMAND_AGENT,
+  };
+}
+
+// Parse /steer arguments into the exact { content plus optional planId }
+// shape the state service validates. `::` separates an explicit planId
+// candidate from content when the left side is a single token (no whitespace);
+// the candidate is passed through so the state service reports
+// INVALID_PLAN_ID identically to the submit tool. A left side with whitespace
+// is prose, so the whole string stays content and `::` inside sentences never
+// misroutes.
+export function parseSteerArguments(rawArguments) {
+  const raw = typeof rawArguments === "string" ? rawArguments : "";
+  const separator = raw.indexOf("::");
+  if (separator !== -1) {
+    const left = raw.slice(0, separator).trim();
+    const right = raw.slice(separator + 2).trim();
+    if (left.length > 0 && !/\s/.test(left)) {
+      return { planId: left, content: right };
+    }
+  }
+  return { content: raw.trim() };
+}
+
+// Single shared allowlist with the submit tool: only the explicit developer
+// context passes. All seven orchestration roles plus unknown plus none plus
+// unset fail closed.
+export function isSteerAllowedAgent(agent) {
+  return STEERING_TOOL_ACCESS.get(STEERING_TOOLS.submit)?.has(agent) === true;
+}
+
+// Resolve the session agent via the SDK client, fail closed to undefined on
+// any unresolvable shape. Prefers session messages (UserMessage.agent) then
+// falls back to session get; any throw or missing agent is unresolvable.
+export async function resolveSessionAgentViaClient(client, sessionID) {
+  if (!client || typeof sessionID !== "string" || sessionID.length === 0) return undefined;
+  try {
+    const session = client?.session;
+    if (!session) return undefined;
+    if (typeof session.messages === "function") {
+      const result = await session.messages({ path: { id: sessionID } });
+      const data = result?.data ?? result;
+      if (Array.isArray(data)) {
+        for (let index = data.length - 1; index >= 0; index -= 1) {
+          const agent = data[index]?.info?.agent;
+          if (typeof agent === "string" && agent.length > 0) return agent;
+        }
+      }
+    }
+    if (typeof session.get === "function") {
+      const result = await session.get({ path: { id: sessionID } });
+      const data = result?.data ?? result;
+      const agent = data?.agent ?? data?.info?.agent;
+      if (typeof agent === "string" && agent.length > 0) return agent;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function pushPart(output, text) {
+  const part = { type: "text", text };
+  if (output && Array.isArray(output.parts)) {
+    output.parts.push(part);
+    return;
+  }
+  if (output && output.parts === undefined) {
+    output.parts = [part];
+  }
+}
+
+// command.execute.before intercept for /steer. Performs the write directly
+// through the existing state service, enforces the shared Developer-only
+// allowlist, then throws to abort before any model turn. The throw carries
+// the confirmation (steering id plus resolved target); output.parts carries
+// the same text as a minimal fallback if error styling is unacceptable.
+export function createSteerCommandHook({ client, stateOptions = {}, resolveAgent } = {}) {
+  const resolve = resolveAgent ?? ((sessionID) => resolveSessionAgentViaClient(client, sessionID));
+  return async function steerCommandBefore(input, output) {
+    if (!input || input.command !== STEER_COMMAND_NAME) return;
+    let agent;
+    try {
+      agent = await resolve(input.sessionID);
+    } catch {
+      agent = undefined;
+    }
+    if (typeof agent !== "string" || !isSteerAllowedAgent(agent)) {
+      const denial = `Steering denied: agent ${JSON.stringify(agent ?? "unknown")} may not use /${STEER_COMMAND_NAME}. Developer context only.`;
+      pushPart(output, denial);
+      throw new Error(denial);
+    }
+    const parsed = parseSteerArguments(input.arguments);
+    const state = createStateService(stateOptions);
+    const payload =
+      parsed.planId === undefined ? { content: parsed.content } : { planId: parsed.planId, content: parsed.content };
+    const result = await state.submitSteering(payload);
+    if (!result.ok) {
+      const failure = `Steering failed [${result.error.code}]: ${result.error.message}`;
+      pushPart(output, failure);
+      throw new Error(failure);
+    }
+    const confirmation = `Steering recorded: ${result.entry.id} for target ${result.entry.planId}#${result.entry.sequence}`;
+    pushPart(output, confirmation);
+    throw new Error(confirmation);
+  };
+}