opencode-herdr-orchestration 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,284 @@
+# opencode-herdr-orchestration
+
+Capability-separated OpenCode agents for planning, implementation, independent review, and delivery through Herdr.
+
+This package registers the agents, provides complete structured worker-response retrieval, injects session-specific orchestration mode into shell environments, and ships a reproducible Git `pre-push` policy for new and existing repositories.
+
+Requires Node.js 22.22.2 or newer when running the package CLI or tests.
+
+## Architecture
+
+```text
+shepherd-plan
+└── sheep-plan
+
+shepherd-build
+├── sheep-plan
+├── sheep-build
+├── shearer-review-low
+└── shearer-review-medium
+```
+
+| Agent | Direct mutation | Delegation | Git authority | Model |
+| --- | --- | --- | --- | --- |
+| `shepherd-plan` | Markdown planning artifacts | `sheep-plan` only | Markdown commits; current non-protected branch push | Active strong model |
+| `shepherd-build` | Markdown handoffs/review notes | All four leaf roles | Integration, push, PR, merge, delivery | Active strong model |
+| `sheep-plan` | None | None | Read-only inspection | `litellm/glm-5.3-flash` |
+| `sheep-build` | Assigned implementation | None | Local task commit only | `litellm/glm-5.3-flash` |
+| `shearer-review-low` | None | None | Read-only inspection | GPT-5.6 Terra, low |
+| `shearer-review-medium` | None | None | Read-only inspection | GPT-5.6 Terra, medium |
+
+The build shepherd chooses low review for localized mechanical changes with strong deterministic coverage. It chooses medium review for security, architecture, migrations, public APIs, deployment, concurrency, cross-component work, weak coverage, or material uncertainty.
+
+## Install the plugin
+
+During local development, reference the source directly in the global OpenCode configuration:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    "file:///C:/Dev/opencode-herdr-orchestration/src/index.js"
+  ]
+}
+```
+
+After publishing, use the package name instead:
+
+```jsonc
+{
+  "plugin": ["opencode-herdr-orchestration"]
+}
+```
+
+Plugin tuple options can override model defaults:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-herdr-orchestration",
+      {
+        "workerModel": "litellm/glm-5.3-flash",
+        "reviewerModel": "litellm-responses/gpt-5.6-terra"
+      }
+    ]
+  ]
+}
+```
+
+Local agent definitions with the same names are merged over plugin defaults. This permits deliberate user customization without losing unspecified plugin permissions or prompts.
+
+During migration, existing files such as `~/.config/opencode/agents/shepherd-build.md` continue to override the plugin prompt. Keep them while existing sessions depend on them. After those sessions end and the plugin has been validated, archive or remove the duplicate standalone definitions so the package becomes the single source of truth. Do not remove files merely to activate the plugin in already-running OpenCode processes; configuration is loaded at process startup.
+
+OpenCode loads plugins and agent definitions at startup. Restart OpenCode when intentionally enabling or updating the plugin. The installer never stops or restarts an OpenCode process.
+
+## Install the Git policy
+
+Run once after installing the npm package:
+
+```bash
+npx opencode-herdr-orchestration install-hooks
+```
+
+Or run directly from this checkout:
+
+```powershell
+node C:\Dev\opencode-herdr-orchestration\bin\orchestration.js install-hooks
+```
+
+The command copies the hook to a stable user location and configures:
+
+```text
+~/.config/opencode-herdr-orchestration/hooks
+```
+
+as global `core.hooksPath`. Every new clone, initialized repository, and linked worktree then receives the same policy automatically.
+
+The installer refuses to replace an existing global `core.hooksPath`. Review and compose existing hooks first; `--force` is available only for an intentional replacement.
+
+Inspect or remove the setting from an installed package:
+
+```bash
+npx opencode-herdr-orchestration status
+npx opencode-herdr-orchestration uninstall-hooks
+```
+
+From this checkout:
+
+```powershell
+node .\bin\orchestration.js status
+node .\bin\orchestration.js uninstall-hooks
+```
+
+Add repository-specific protected branches:
+
+```bash
+git config --add orchestration.protectedBranch production
+git config --add orchestration.protectedBranch release
+```
+
+`main` and `master` are always protected in planning mode.
+
+## Push policy
+
+The plugin tracks the selected agent per OpenCode session and injects `SHEPHERD_MODE` into that session's shell environment.
+
+| Mode | Hook behavior |
+| --- | --- |
+| `plan` | Allows only the attached current branch to the same non-protected remote branch |
+| `build` | Does not add planning restrictions; shepherd-build owns delivery |
+| `sheep-plan` | Denies every push |
+| `sheep-build` | Denies every push |
+| `review` | Denies every push |
+| Missing/unknown | Does not interfere with normal human Git use |
+
+The hook rejects detached-HEAD planning pushes, protected branches, ref renames, unrelated refs, and deletions.
+
+### Security boundary
+
+The hook and OpenCode Bash matchers are defense in depth, not a security sandbox. A process with arbitrary local command execution may be able to alter environment variables, Git configuration, hooks, or invoke remote protocols outside ordinary `git push`. Keep server-side protected branches and repository permissions as the authoritative control. A future integration can strengthen mode provenance with signed, session-scoped policy data, but cannot replace remote authorization.
+
+## Planning handoff
+
+Final plans include:
+
+```text
+Plan-ID: <topic>-<YYYYMMDD>-<sequence>
+Base-Commit: <full commit hash>
+Status: PROPOSED
+```
+
+Switching the session to `shepherd-build` approves that plan. Build startup reports the plan ID, approved base, and current HEAD, then inspects divergence before delegation.
+
+Implementation contracts include the objective, ownership and forbidden paths, dependencies, acceptance criteria, verification, escalation conditions, and required deliverables. `sheep-build` hands a verified local commit upward. `shepherd-build` runs deterministic checks before requesting semantic review.
+
+Reviewer verdicts are:
+
+- `PASS`: integrate after shepherd checks.
+- `REWORK`: return actionable findings to the responsible sheep and review the correction.
+- `ESCALATE`: research, re-plan, or request user judgment.
+
+Two failed semantic review cycles escalate instead of looping indefinitely.
+
+## Worker interruption
+
+Herdr currently exposes `send-keys`, not a narrower agent interrupt command. Shepherds retain it to send Ctrl+C only after confirming that a worker is genuinely stuck. Prompts prohibit using worker terminals to type implementation commands or bypass shepherd permissions.
+
+This restriction is not hard-enforced by Herdr. A native `herdr agent interrupt <target>` command would close that capability gap.
+
+## Worker response retrieval
+
+The `herdr_agent_response` OpenCode tool retrieves completed responses from Herdr-managed OpenCode workers without reading terminal scrollback or creating response files.
+
+Initial call:
+
+```json
+{
+  "target": "frontend_worker",
+  "maxBytes": 8192
+}
+```
+
+Continuation call:
+
+```json
+{
+  "cursor": "<opaque-signed-cursor>",
+  "maxBytes": 8192
+}
+```
+
+Successful page:
+
+```json
+{
+  "ok": true,
+  "target": "frontend_worker",
+  "sessionID": "ses_...",
+  "messageID": "msg_...",
+  "role": "sheep-build",
+  "finish": "stop",
+  "offset": 0,
+  "nextOffset": 8192,
+  "totalBytes": 24500,
+  "complete": false,
+  "cursor": "<opaque-signed-cursor>",
+  "text": "..."
+}
+```
+
+Shepherds must continue until `complete` is true before acting on the response. Pages use UTF-8 byte offsets and never split a multibyte character.
+
+The tool:
+
+- resolves Herdr's tracked OpenCode session ID;
+- runs `opencode export <sessionID>` with an argv API rather than shell interpolation;
+- selects the latest completed final assistant message after the latest user prompt;
+- excludes intermediate tool-call steps, errors, ignored text, reasoning, and terminal rendering;
+- pins continuation reads to the original session, message, response digest, and offset;
+- HMAC-signs opaque cursors with a random per-plugin-process secret;
+- paginates on UTF-8-safe boundaries with a bounded tool-output budget;
+- supports concurrent shepherds without response files or shared mutable retrieval state;
+- allows only `shepherd-plan` and `shepherd-build`, with a second authorization check inside the tool;
+- accepts only settled Herdr targets with a trusted `herdr:opencode` session mapping and an approved leaf role.
+
+The export backend is intentional. Herdr starts each worker as a separate OpenCode process, so the shepherd plugin's SDK client may be tied to a different OpenCode server. `opencode export` reads the shared OpenCode session store across those process boundaries.
+
+Normal lifecycle failures return structured errors such as:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "AGENT_NOT_SETTLED",
+    "message": "Herdr agent frontend_worker is working; wait for idle or done.",
+    "retryable": true
+  }
+}
+```
+
+Cursor continuations do not query Herdr again, so a worker may begin another turn or leave the live agent list after the initial page. The response remains pinned as long as the OpenCode session and message still exist and are unchanged. Cursors expire after six hours by default and do not survive a restart of the shepherd's OpenCode plugin process.
+
+The previous file helper may remain for already-running OpenCode sessions. Once those processes end and this plugin is active, it is no longer needed by new sessions.
+
+## Development
+
+```bash
+npm run check
+npm test
+```
+
+Tests cover topology, model variants, permissions, override merging, session mode isolation, response selection, signed cursors, UTF-8 pagination, concurrent response reads, tool authorization, and Git hook behavior on protected, worker, review, build, and planning pushes.
+
+## Releases
+
+CI runs syntax checks, tests, and an npm package dry run on every branch push and pull request.
+
+Releases are triggered only by tags shaped like `vMAJOR.MINOR.PATCH`. The release workflow verifies that the strict semantic version in the tag exactly matches `package.json`, reruns all checks, publishes the public npm package with provenance, and creates a GitHub release with generated notes.
+
+The release job uses the protected GitHub environment named `npm`. Configure the repository Actions secret once before the first release:
+
+```bash
+gh secret set NPM_TOKEN --repo CodingJinxx/opencode-herdr-orchestration
+```
+
+Use an npm automation or granular access token authorized to publish `opencode-herdr-orchestration`. Then release by updating `package.json` and `package-lock.json`, committing, and pushing the matching tag:
+
+```bash
+npm version patch
+git push origin master --follow-tags
+```
+
+The workflow intentionally fails before publishing when the tag and package version differ. It does not publish prerelease tags such as `v1.0.0-beta.1`.
+
+For stronger release control, configure required reviewers on the `npm` environment and require the CI check on the protected default branch. The release is retry-safe: if npm already contains the same version from the same commit, it skips republishing and resumes GitHub release creation; a version published from another commit fails closed.
+
+## Known limitations
+
+- OpenCode command patterns cannot prove semantic Git intent; the hook adds checks but server-side protection is still required.
+- `herdr agent send-keys` is broader than interrupt-only authority.
+- Global `core.hooksPath` is singular. Existing hook frameworks must be composed rather than overwritten.
+- PR commands are narrowly available to `shepherd-build`, but work only in GitHub repositories with an authenticated `gh` installation.
+- Agent registration and environment hooks take effect only in newly started OpenCode processes.
+- Worker session exports are capped at 64 MiB by default to bound host memory use. The response tool returns `SESSION_EXPORT_TOO_LARGE` rather than loading a larger session.

package/bin/orchestration.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { chmodSync, copyFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const hooksPath = join(homedir(), ".config", "opencode-herdr-orchestration", "hooks");
+const sourceHook = join(packageRoot, "hooks", "pre-push");
+const installedHook = join(hooksPath, "pre-push");
+const [command, ...flags] = process.argv.slice(2);
+
+function git(args, options = {}) {
+  return execFileSync("git", args, { encoding: "utf8", windowsHide: true, ...options }).trim();
+}
+
+function currentHooksPath() {
+  try {
+    return git(["config", "--global", "--get", "core.hooksPath"]);
+  } catch {
+    return "";
+  }
+}
+
+function install() {
+  const existing = currentHooksPath();
+  const force = flags.includes("--force");
+  if (existing && existing !== hooksPath && !force) {
+    throw new Error(`Global core.hooksPath is already ${existing}. Re-run with --force only after reviewing that hook setup.`);
+  }
+  mkdirSync(hooksPath, { recursive: true });
+  copyFileSync(sourceHook, installedHook);
+  try { chmodSync(installedHook, 0o755); } catch {}
+  git(["config", "--global", "core.hooksPath", hooksPath]);
+  process.stdout.write(`Installed pre-push hook and set global core.hooksPath=${hooksPath}\n`);
+}
+
+function uninstall() {
+  if (currentHooksPath() === hooksPath) {
+    git(["config", "--global", "--unset", "core.hooksPath"]);
+    rmSync(hooksPath, { recursive: true, force: true });
+    process.stdout.write("Removed the orchestration global core.hooksPath setting and installed hook.\n");
+  } else {
+    process.stdout.write("Global core.hooksPath does not point at this package; nothing changed.\n");
+  }
+}
+
+function status() {
+  process.stdout.write(`${JSON.stringify({
+    configuredHooksPath: currentHooksPath() || null,
+    expectedHooksPath: hooksPath,
+    hookInstalled: existsSync(installedHook),
+    active: currentHooksPath() === hooksPath && existsSync(installedHook),
+  }, null, 2)}\n`);
+}
+
+try {
+  if (command === "install-hooks") install();
+  else if (command === "uninstall-hooks") uninstall();
+  else if (command === "status") status();
+  else {
+    process.stderr.write("Usage: opencode-herdr-orchestration <install-hooks [--force]|uninstall-hooks|status>\n");
+    process.exitCode = 2;
+  }
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/hooks/pre-push

@@ -0,0 +1,62 @@
+#!/bin/sh
+
+set -eu
+
+mode=${SHEPHERD_MODE:-none}
+case "$mode" in
+  sheep-build|sheep-plan|review)
+    echo "opencode-herdr-orchestration: $mode may not push; remote Git belongs to shepherd-build." >&2
+    exit 1
+    ;;
+  plan)
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+current_branch=$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+if [ -z "$current_branch" ]; then
+  echo "opencode-herdr-orchestration: shepherd-plan may not push from detached HEAD." >&2
+  exit 1
+fi
+
+is_protected() {
+  candidate=$1
+  case "$candidate" in
+    main|master) return 0 ;;
+  esac
+
+  git config --get-all orchestration.protectedBranch 2>/dev/null |
+    grep -F -x -- "$candidate" >/dev/null 2>&1
+}
+
+if is_protected "$current_branch"; then
+  echo "opencode-herdr-orchestration: shepherd-plan may not push protected branch $current_branch." >&2
+  exit 1
+fi
+
+zero=0000000000000000000000000000000000000000
+while read -r local_ref local_sha remote_ref remote_sha; do
+  [ -n "${local_ref:-}" ] || continue
+
+  if [ "$local_sha" = "$zero" ]; then
+    echo "opencode-herdr-orchestration: shepherd-plan may not delete remote refs." >&2
+    exit 1
+  fi
+
+  expected_local="refs/heads/$current_branch"
+  expected_remote="refs/heads/$current_branch"
+  if [ "$local_ref" != "$expected_local" ] || [ "$remote_ref" != "$expected_remote" ]; then
+    echo "opencode-herdr-orchestration: shepherd-plan may push only $expected_local to the same remote branch." >&2
+    exit 1
+  fi
+
+  remote_branch=${remote_ref#refs/heads/}
+  if is_protected "$remote_branch"; then
+    echo "opencode-herdr-orchestration: shepherd-plan may not update protected branch $remote_branch." >&2
+    exit 1
+  fi
+done
+
+exit 0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opencode-herdr-orchestration",
+  "version": "0.1.0",
+  "description": "Capability-separated Herdr orchestration agents for OpenCode",
+  "author": "CodingJinxx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodingJinxx/opencode-herdr-orchestration.git"
+  },
+  "homepage": "https://github.com/CodingJinxx/opencode-herdr-orchestration#readme",
+  "bugs": {
+    "url": "https://github.com/CodingJinxx/opencode-herdr-orchestration/issues"
+  },
+  "type": "module",
+  "exports": "./src/index.js",
+  "bin": {
+    "opencode-herdr-orchestration": "bin/orchestration.js"
+  },
+  "files": [
+    "bin",
+    "hooks",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js && node --check src/agents.js && node --check src/prompts.js && node --check src/response.js && node --check bin/orchestration.js"
+  },
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.3.0 <2"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.3.14"
+  },
+  "keywords": [
+    "opencode",
+    "herdr",
+    "orchestration",
+    "agents"
+  ],
+  "license": "MIT"
+}

package/src/agents.js

@@ -0,0 +1,258 @@
+import {
+  SHEEP_BUILD_PROMPT,
+  SHEEP_PLAN_PROMPT,
+  SHEPHERD_BUILD_PROMPT,
+  SHEPHERD_PLAN_PROMPT,
+  SHEARER_REVIEW_PROMPT,
+} from "./prompts.js";
+
+const separatorDenials = {
+  "*;*": "deny",
+  "*&&*": "deny",
+  "*||*": "deny",
+  "*|*": "deny",
+  "*>*": "deny",
+  "*<*": "deny",
+};
+
+const safeGitInspection = {
+  "git status": "allow",
+  "git status --short": "allow",
+  "git status --porcelain": "allow",
+  "git diff": "allow",
+  "git diff --cached": "allow",
+  "git diff --stat": "allow",
+  "git diff --cached --stat": "allow",
+  "git log": "allow",
+  "git log --oneline": "allow",
+  "git log --oneline -10": "allow",
+  "git show": "allow",
+  "git branch --show-current": "allow",
+  "git branch --list": "allow",
+  "git rev-parse HEAD": "allow",
+  "git rev-parse --show-toplevel": "allow",
+  "git rev-parse --abbrev-ref HEAD": "allow",
+  "git merge-base HEAD main": "allow",
+  "git merge-base HEAD master": "allow",
+  "git ls-files": "allow",
+};
+
+const herdrInspection = {
+  "Get-Item Env:HERDR_ENV": "allow",
+  "herdr --help": "allow",
+  "herdr agent": "allow",
+  "herdr agent list*": "allow",
+  "herdr agent prompt*": "allow",
+  "herdr agent wait*": "allow",
+  "herdr agent get*": "allow",
+  "herdr agent read*": "allow",
+  "herdr agent send-keys*": "allow",
+  "herdr pane current*": "allow",
+  "herdr pane list*": "allow",
+  "herdr pane layout*": "allow",
+  "herdr pane split*": "allow",
+  "herdr pane read*": "allow",
+};
+
+const markdownOnly = {
+  "*": "deny",
+  "*.md": "allow",
+  "**/*.md": "allow",
+};
+
+function mergeRecord(base, override) {
+  if (!base || typeof base !== "object" || Array.isArray(base)) return override ?? base;
+  if (!override || typeof override !== "object" || Array.isArray(override)) return override ?? base;
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    merged[key] = mergeRecord(base[key], value);
+  }
+  return merged;
+}
+
+export function mergeAgent(defaults, override) {
+  return mergeRecord(defaults, override);
+}
+
+export function createAgents(options = {}) {
+  const workerModel = options.workerModel ?? "litellm/glm-5.3-flash";
+  const reviewerModel = options.reviewerModel ?? "litellm-responses/gpt-5.6-terra";
+
+  return {
+    "shepherd-plan": {
+      mode: "primary",
+      description: "Researches and presents implementation-ready plans through sheep-plan workers without implementing them.",
+      prompt: SHEPHERD_PLAN_PROMPT,
+      permission: {
+        grep: "allow",
+        todowrite: "allow",
+        edit: markdownOnly,
+        apply_patch: markdownOnly,
+        herdr_agent_response: "allow",
+        bash: {
+          "*": "deny",
+          ...herdrInspection,
+          "herdr agent start * --kind opencode --pane * -- --agent sheep-plan": "allow",
+          "git status*": "allow",
+          "git diff*": "allow",
+          "git log*": "allow",
+          "git show*": "allow",
+          "git branch*": "allow",
+          "git rev-parse*": "allow",
+          "git merge-base*": "allow",
+          "git worktree*": "allow",
+          "git add *.md": "allow",
+          "git add **/*.md": "allow",
+          "git commit*": "allow",
+          "git push origin HEAD": "allow",
+          "git push -u origin HEAD": "allow",
+          "git push --set-upstream origin HEAD": "allow",
+          "git commit --no-verify*": "deny",
+          "git commit * --no-verify*": "deny",
+          "git push *main*": "deny",
+          "git push *master*": "deny",
+          "git push *:*": "deny",
+          "git push *--no-verify*": "deny",
+          "git push *--force*": "deny",
+          "git push *-f*": "deny",
+          "git push *--delete*": "deny",
+          "git branch -D*": "deny",
+          "git branch -d*": "deny",
+          "git worktree remove * --force*": "deny",
+          ...separatorDenials,
+        },
+        task: "deny",
+      },
+    },
+
+    "shepherd-build": {
+      mode: "primary",
+      description: "Executes approved plans through planning, implementation, and independent review workers.",
+      prompt: SHEPHERD_BUILD_PROMPT,
+      permission: {
+        grep: "allow",
+        edit: markdownOnly,
+        apply_patch: markdownOnly,
+        herdr_agent_response: "allow",
+        "ia-forge_deployment_status": "allow",
+        "ia-forge_file_logs": "allow",
+        "ia-forge_run_preset": "allow",
+        "ia-forge_service_control": "allow",
+        "ia-forge_service_logs": "allow",
+        bash: {
+          "*": "deny",
+          ...herdrInspection,
+          "herdr agent start * --kind opencode --pane * -- --agent sheep-plan": "allow",
+          "herdr agent start * --kind opencode --pane * -- --agent sheep-build": "allow",
+          "herdr agent start * --kind opencode --pane * -- --agent shearer-review-low": "allow",
+          "herdr agent start * --kind opencode --pane * -- --agent shearer-review-medium": "allow",
+          "git status*": "allow",
+          "git diff*": "allow",
+          "git log*": "allow",
+          "git show*": "allow",
+          "git branch*": "allow",
+          "git rev-parse*": "allow",
+          "git merge-base*": "allow",
+          "git worktree*": "allow",
+          "git add *.md": "allow",
+          "git add **/*.md": "allow",
+          "git commit*": "allow",
+          "git push*": "allow",
+          "git merge*": "allow",
+          "git fetch*": "allow",
+          "git pull --ff-only*": "allow",
+          "git push --force*": "deny",
+          "git push * --force*": "deny",
+          "git push -f*": "deny",
+          "git push * -f*": "deny",
+          "git push *--delete*": "deny",
+          "git push *--no-verify*": "deny",
+          "git commit *--no-verify*": "deny",
+          "git merge *--no-verify*": "deny",
+          "git branch -D*": "deny",
+          "git branch -d*": "deny",
+          "git worktree remove * --force*": "deny",
+          "gh pr create*": "allow",
+          "gh pr view*": "allow",
+          "gh pr checks*": "allow",
+          ...separatorDenials,
+        },
+        task: "deny",
+      },
+    },
+
+    "sheep-plan": {
+      mode: "primary",
+      model: workerModel,
+      description: "Performs read-only repository research for a shepherd.",
+      prompt: SHEEP_PLAN_PROMPT,
+      permission: {
+        read: "allow",
+        glob: "allow",
+        grep: "allow",
+        list: "allow",
+        todowrite: "allow",
+        edit: "deny",
+        apply_patch: "deny",
+        herdr_agent_response: "deny",
+        bash: { "*": "deny", ...safeGitInspection, ...separatorDenials },
+        task: "deny",
+      },
+    },
+
+    "sheep-build": {
+      mode: "primary",
+      model: workerModel,
+      description: "Implements a bounded task, verifies it, and hands a local commit to shepherd-build.",
+      prompt: SHEEP_BUILD_PROMPT,
+      permission: {
+        grep: "allow",
+        herdr_agent_response: "deny",
+        bash: {
+          "*": "allow",
+          "git push*": "deny",
+          "git merge*": "deny",
+          "git pull*": "deny",
+          "git branch -D*": "deny",
+          "git branch -d*": "deny",
+          "git rebase*": "deny",
+          "git reset*": "deny",
+          "git commit *--no-verify*": "deny",
+          "git commit --no-verify*": "deny",
+          "git *;*": "deny",
+          "git *&&*": "deny",
+          "git *||*": "deny",
+          "git *|*": "deny",
+          "git *>*": "deny",
+          "git *<*": "deny",
+        },
+        task: "deny",
+      },
+    },
+
+    "shearer-review-low": reviewerAgent(reviewerModel, "low"),
+    "shearer-review-medium": reviewerAgent(reviewerModel, "medium"),
+  };
+}
+
+function reviewerAgent(model, variant) {
+  return {
+    mode: "primary",
+    model,
+    variant,
+    description: `Independently reviews an implementation with GPT-5.6 Terra ${variant} reasoning.`,
+    prompt: SHEARER_REVIEW_PROMPT,
+    permission: {
+      read: "allow",
+      glob: "allow",
+      grep: "allow",
+      list: "allow",
+      edit: "deny",
+      apply_patch: "deny",
+      todowrite: "deny",
+      herdr_agent_response: "deny",
+      bash: { "*": "deny", ...safeGitInspection, ...separatorDenials },
+      task: "deny",
+    },
+  };
+}

package/src/index.js

@@ -0,0 +1,46 @@
+import { createAgents, mergeAgent } from "./agents.js";
+import { createResponseTool } from "./response.js";
+
+const SESSION_MODES = new Map();
+
+function modeForAgent(agent) {
+  if (agent === "shepherd-plan") return "plan";
+  if (agent === "shepherd-build") return "build";
+  if (agent === "shearer-review-low" || agent === "shearer-review-medium") return "review";
+  if (agent === "sheep-plan") return "sheep-plan";
+  if (agent === "sheep-build") return "sheep-build";
+  return "none";
+}
+
+export const HerdrOrchestrationPlugin = async (_input, options = {}) => ({
+  tool: {
+    herdr_agent_response: createResponseTool(options.response),
+  },
+  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 "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 { createAgents, modeForAgent };

package/src/prompts.js

@@ -0,0 +1,98 @@
+export const SHEPHERD_PLAN_PROMPT = String.raw`
+You are shepherd-plan, a planning orchestrator. Research the user's goal through repository evidence and sheep-plan workers, then present an implementation-ready plan. Planning may mutate planning infrastructure and Markdown planning artifacts, but never product implementation.
+
+Before using Herdr, verify HERDR_ENV=1. If absent, explain that orchestration requires a Herdr-managed pane and stop. Inspect repository instructions, status, branches, worktrees, HEAD, and relevant history. Preserve unrelated changes. Use todos for substantial planning.
+
+You may write only Markdown plans, research notes, task briefs, and handoffs. You may commit intended Markdown artifacts and push only the current attached non-protected branch using an approved HEAD push command. Immediately before pushing, inspect the current branch and stop on main, master, detached HEAD, or any repository-defined protected branch. Never merge, deploy, implement, or spawn an implementation-capable agent.
+
+Spawn only sheep-plan, using exactly:
+
+herdr agent start <name> --kind opencode --pane <pane-id> -- --agent sheep-plan
+
+Never pass another agent, model, --auto, or extra OpenCode argument. Use send-keys only to interrupt a genuinely stuck worker with Ctrl+C after inspection. Never type commands, answer arbitrary prompts, or use a worker terminal as a capability bypass.
+
+After a worker settles, use herdr_agent_response as the authoritative result channel. Call it first with the worker name, then call it with each returned cursor until complete is true. Do not summarize, decide, or act on the worker result until every page has been read in order. Use herdr agent read only for live status, blocked dialogs, and stuck-worker diagnosis; terminal snapshots are never the completed worker response. If retrieval says the worker is not settled, wait and retry. If an interrupted worker has no completed response, inspect its actual partial state and redesign the task.
+
+Assume workers may fail on very large one-shot writes. Identify large-file work and plan generators or coherent bounded stages with valid checkpoints. If a worker later fails on a large write, the shepherd owns recovery: inspect partial state, preserve valid work, and redesign the task rather than repeating the same oversized prompt.
+
+Every final plan must begin with:
+
+Plan-ID: <short-project-topic>-<YYYYMMDD>-<sequence>
+Base-Commit: <full commit hash>
+Status: PROPOSED
+
+Include scope, ordered tasks, likely files and symbols, dependencies, delegation boundaries, acceptance criteria, verification, integration order, risks, and unresolved decisions. Present the plan and stop. Switching to shepherd-build is approval; planning completion alone is not.
+`.trim();
+
+export const SHEPHERD_BUILD_PROMPT = String.raw`
+You are shepherd-build, a delivery orchestrator. Selecting this agent after shepherd-plan approves the latest presented plan. You coordinate; every non-Markdown implementation change must come from a sheep-build commit. You may directly write only Markdown task briefs, handoffs, and review notes.
+
+Before using Herdr, verify HERDR_ENV=1. Inspect repository instructions, status, branches, worktrees, current HEAD, and history. Preserve unrelated changes and never force-push, bypass hooks, or rewrite history.
+
+At startup identify and report:
+
+Executing Plan-ID: <id>
+Approved Base-Commit: <hash>
+Current HEAD: <hash>
+
+Inspect divergence from the approved base. Continue through mechanical drift, reporting deviations. Re-plan or escalate when changes invalidate approved architecture, scope, or assumptions. For direct requests without a plan, establish an equivalent bounded execution contract before implementation.
+
+Delegate using structured contracts containing, where relevant: task_id, plan_id, base_commit, objective, owned_paths, forbidden_paths, dependencies, acceptance_criteria, verification, escalate_if, and deliver. Resolve global ambiguity before delegating. Workers must escalate rather than guess when evidence contradicts the task, scope expands, public APIs or migrations change unexpectedly, a product or architecture decision is required, permissions block work, or repeated attempts fail.
+
+Spawn only these configured workers with no extra OpenCode arguments:
+
+herdr agent start <name> --kind opencode --pane <pane-id> -- --agent sheep-plan
+herdr agent start <name> --kind opencode --pane <pane-id> -- --agent sheep-build
+herdr agent start <name> --kind opencode --pane <pane-id> -- --agent shearer-review-low
+herdr agent start <name> --kind opencode --pane <pane-id> -- --agent shearer-review-medium
+
+Use sheep-plan for research and sheep-build for implementation. Choose Terra low review for localized, mechanical changes with strong deterministic coverage. Choose Terra medium for security, architecture, migrations, public APIs, deployment, concurrency, cross-component work, weak coverage, or material uncertainty.
+
+Use send-keys only to interrupt a genuinely stuck worker with Ctrl+C after inspection. Never type implementation commands, answer arbitrary prompts, or use a worker terminal as a capability bypass. After interruption, inspect any completed response and actual diff, preserve valid partial work, and issue a bounded recovery task.
+
+After any worker or shearer settles, use herdr_agent_response as the authoritative result channel. Call it first with the agent name, then call it with each returned cursor until complete is true. Do not summarize, review, integrate, or act on the result until every page has been read in order. Use herdr agent read only for live status, blocked dialogs, and stuck-worker diagnosis; terminal snapshots are never a completed response. If retrieval says the agent is not settled, wait and retry. If an interrupted worker has no completed response, inspect its actual partial state and redesign the task.
+
+Assume workers may fail on very large one-shot writes. Prefer repository-native generators or coherent bounded stages with valid checkpoints. If a write fails, inspect partial state and redesign the prompt; never discard correct work, reduce required functionality, or repeat the same oversized prompt blindly.
+
+Require sheep-build to return a local commit, files changed, checks and results, assumptions, risks, and blockers. Sheep never pushes, merges, opens PRs, or delivers. Run or delegate deterministic repository-native checks before semantic review. Give the shearer fresh bounded context: user goal, approved plan, task contract, base and implementation commits, diff, and verification results, not the worker conversation.
+
+Review verdicts are PASS, REWORK, or ESCALATE. PASS permits integration after your own checks. REWORK returns concrete findings to the responsible sheep-build and requires review of the correction. ESCALATE returns to you for research, re-planning, or user judgment. After two failed semantic review cycles for the same task, escalate rather than loop indefinitely.
+
+Integrate only reviewed committed work. Perform repository-level verification after integration. Own push, PR, merge, and deployment according to repository instructions and user scope. Use gh only for GitHub repositories and only when PR delivery is requested. Finish with plan ID, assignments, commits, checks, review verdicts, integration and delivery result, deviations, and unresolved risks.
+
+When ia-forge tools are available, use them as the source of truth for managed deployments and services. After pushing an infrastructure change, poll deployment status until the attempt finishes; success requires a successful attempt at the pushed commit. On failure inspect deployment service logs, delegate the correction to sheep-build, and repeat verification and review before another delivery attempt.
+`.trim();
+
+export const SHEEP_PLAN_PROMPT = String.raw`
+You are sheep-plan, a read-only research worker. Investigate the bounded question from shepherd-plan or shepherd-build using repository instructions, source, tests, configuration, documentation, and allowed Git inspection.
+
+Use todos when research has multiple steps. Do not edit, commit, change branches or worktrees, push, merge, install dependencies, run mutating commands, or spawn agents. Trace behavior across relevant boundaries and cite files and symbols. Stop rather than guess when evidence is unavailable or a product or architecture decision is required.
+
+Return implementation-ready findings: current behavior, recommended approach, alternatives and tradeoffs, dependencies, edge cases, risks, likely files and symbols, acceptance criteria, verification commands, uncertainties, and blockers. Do not implement.
+`.trim();
+
+export const SHEEP_BUILD_PROMPT = String.raw`
+You are sheep-build, an implementation leaf. Execute only the bounded task contract from shepherd-build. Inspect repository instructions and existing code first, preserve unrelated work, and make the smallest complete change within owned scope.
+
+You may implement, run repository-native checks, inspect your diff, and create a local task commit. You must not spawn agents, push, pull, merge, rebase, reset history, delete branches, open PRs, deploy, bypass hooks, or perform remote Git operations.
+
+Large files may exceed one-shot tool limits. Prefer repository-native generators or coherent bounded edits that preserve valid checkpoints. If a write fails, inspect actual partial state and continue safely in smaller sections. If the intended result cannot be completed reliably, stop and report the precise failure and partial state rather than omitting content.
+
+Escalate instead of guessing when evidence contradicts the assignment, ownership must expand, a public API or migration changes unexpectedly, a product or architecture decision is needed, permissions block required work, or repeated attempts fail.
+
+Complete relevant checks, inspect the final diff, and commit all intended changes. Report: task ID, plan ID, commit hash, files changed, verification commands and results, assumptions, remaining risks, and blockers. The shepherd owns everything after the local commit.
+`.trim();
+
+export const SHEARER_REVIEW_PROMPT = String.raw`
+You are shearer-review, an independent read-only semantic reviewer. Judge the implementation from repository evidence, the approved plan, task contract, base revision, implementation commit, diff, and verification results. Do not rely on the implementation worker's reasoning and never repair your own findings.
+
+You must not edit, implement, commit, change branches or worktrees, merge, push, spawn agents, or run mutating commands. Deterministic tooling should decide formatting, lint, types, tests, builds, generated consistency, and secret scanning. Focus on semantic correctness: task and plan compliance, functional behavior, edge cases, regressions, scope violations, unnecessary complexity, meaningful tests, security and safety, and unresolved risk.
+
+Return exactly one high-level verdict:
+
+PASS - The task and plan are satisfied with adequate verification and no material unresolved issue.
+REWORK - Concrete defects are fixable within the approved task. Give ordered, actionable findings with file and symbol references, expected behavior, and verification.
+ESCALATE - The plan is invalid, requirements conflict, product or architecture judgment is needed, or scope materially expanded. State the decision required and supporting evidence.
+
+Keep summaries secondary to findings. Never implement fixes.
+`.trim();

package/src/response.js

@@ -0,0 +1,390 @@
+import { execFile } from "node:child_process";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+
+import { tool } from "@opencode-ai/plugin";
+
+const execFileAsync = promisify(execFile);
+const ALLOWED_CALLERS = new Set(["shepherd-plan", "shepherd-build"]);
+const ALLOWED_TARGET_ROLES = new Set([
+  "sheep-plan",
+  "sheep-build",
+  "shearer-review-low",
+  "shearer-review-medium",
+]);
+const SETTLED_STATES = new Set(["idle", "done"]);
+const DEFAULT_PAGE_BYTES = 8192;
+const MIN_PAGE_BYTES = 1024;
+const MAX_PAGE_BYTES = 16384;
+const MAX_TOOL_OUTPUT_BYTES = 32768;
+const DEFAULT_CURSOR_TTL_MS = 6 * 60 * 60 * 1000;
+const DEFAULT_MAX_EXPORT_BYTES = 64 * 1024 * 1024;
+const MAX_HERDR_OUTPUT_BYTES = 1024 * 1024;
+
+function error(code, message, retryable = false) {
+  return { ok: false, error: { code, message, retryable } };
+}
+
+function processErrorDetail(cause) {
+  const value = String(cause?.stderr ?? cause?.message ?? cause).replace(/\s+/g, " ").trim();
+  return value.length > 1000 ? `${value.slice(0, 1000)}...` : value;
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("base64url");
+}
+
+function encodeCursor(payload, secret) {
+  const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+  const signature = createHmac("sha256", secret).update(encoded).digest("base64url");
+  return `${encoded}.${signature}`;
+}
+
+function decodeCursor(cursor, secret, now) {
+  if (typeof cursor !== "string" || cursor.length > 4096) {
+    return error("INVALID_CURSOR", "The response cursor is malformed.");
+  }
+  const [encoded, signature, extra] = cursor.split(".");
+  if (!encoded || !signature || extra) {
+    return error("INVALID_CURSOR", "The response cursor is malformed.");
+  }
+  const expected = createHmac("sha256", secret).update(encoded).digest();
+  let supplied;
+  try {
+    supplied = Buffer.from(signature, "base64url");
+  } catch {
+    return error("INVALID_CURSOR", "The response cursor signature is malformed.");
+  }
+  if (supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) {
+    return error("INVALID_CURSOR", "The response cursor signature is invalid.");
+  }
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+  } catch {
+    return error("INVALID_CURSOR", "The response cursor payload is invalid.");
+  }
+  if (
+    payload?.v !== 1 ||
+    typeof payload.target !== "string" ||
+    typeof payload.sessionID !== "string" ||
+    typeof payload.messageID !== "string" ||
+    typeof payload.role !== "string" ||
+    typeof payload.digest !== "string" ||
+    !Number.isSafeInteger(payload.offset) ||
+    payload.offset < 0 ||
+    !Number.isSafeInteger(payload.expiresAt)
+  ) {
+    return error("INVALID_CURSOR", "The response cursor payload is incomplete.");
+  }
+  if (now() > payload.expiresAt) {
+    return error("EXPIRED_CURSOR", "The response cursor has expired. Start retrieval again.");
+  }
+  return { ok: true, payload };
+}
+
+function parseJsonOutput(output, label) {
+  const start = output.indexOf("{");
+  if (start === -1) throw new Error(`${label} returned no JSON object.`);
+  return JSON.parse(output.slice(start));
+}
+
+async function defaultRun(command, args, signal, maxBuffer) {
+  const { stdout } = await execFileAsync(command, args, {
+    encoding: "utf8",
+    maxBuffer,
+    windowsHide: true,
+    signal,
+  });
+  return stdout;
+}
+
+function completedText(message) {
+  return message?.parts
+    ?.filter(
+      (part) =>
+        part?.type === "text" &&
+        typeof part.text === "string" &&
+        !part.ignored,
+    )
+    .map((part) => part.text)
+    .join("\n\n");
+}
+
+export function selectLatestCompletedResponse(exported) {
+  const messages = Array.isArray(exported?.messages) ? exported.messages : [];
+  let latestUser;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.info?.role === "user") {
+      latestUser = messages[index];
+      break;
+    }
+  }
+  if (!latestUser) return error("NO_COMPLETED_RESPONSE", "The worker session has no user prompt.", true);
+
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    const info = message?.info;
+    const text = completedText(message);
+    if (
+      info?.role === "assistant" &&
+      info.parentID === latestUser.info.id &&
+      info.time?.completed &&
+      !info.error &&
+      info.finish !== "tool-calls" &&
+      text
+    ) {
+      return {
+        ok: true,
+        response: {
+          sessionID: info.sessionID,
+          messageID: info.id,
+          role: info.agent ?? info.mode,
+          finish: info.finish ?? "unknown",
+          text,
+        },
+      };
+    }
+  }
+  return error(
+    "NO_COMPLETED_RESPONSE",
+    "The latest worker turn has no completed final text response. Wait for the worker and retry.",
+    true,
+  );
+}
+
+export function findPinnedResponse(exported, messageID) {
+  const message = exported?.messages?.find((candidate) => candidate?.info?.id === messageID);
+  const info = message?.info;
+  const text = completedText(message);
+  if (
+    info?.role !== "assistant" ||
+    !info.time?.completed ||
+    info.error ||
+    info.finish === "tool-calls" ||
+    !text
+  ) {
+    return error("MESSAGE_CHANGED", "The pinned worker response is no longer available in completed form.");
+  }
+  return {
+    ok: true,
+    response: {
+      sessionID: info.sessionID,
+      messageID: info.id,
+      role: info.agent ?? info.mode,
+      finish: info.finish ?? "unknown",
+      text,
+    },
+  };
+}
+
+function normalizePageBytes(value) {
+  if (value === undefined) return { ok: true, value: DEFAULT_PAGE_BYTES };
+  if (!Number.isSafeInteger(value) || value < MIN_PAGE_BYTES || value > MAX_PAGE_BYTES) {
+    return error(
+      "INVALID_REQUEST",
+      `maxBytes must be an integer from ${MIN_PAGE_BYTES} through ${MAX_PAGE_BYTES}.`,
+    );
+  }
+  return { ok: true, value };
+}
+
+function utf8PageEnd(buffer, offset, requestedBytes) {
+  let end = Math.min(buffer.length, offset + requestedBytes);
+  while (end > offset && end < buffer.length && (buffer[end] & 0xc0) === 0x80) end -= 1;
+  return end;
+}
+
+function makePage({ response, target, offset, requestedBytes, secret, expiresAt }) {
+  const bytes = Buffer.from(response.text, "utf8");
+  if (offset > bytes.length) return error("INVALID_CURSOR", "The response cursor offset exceeds the message length.");
+  const digest = sha256(bytes);
+  let pageBytes = requestedBytes;
+
+  while (pageBytes >= MIN_PAGE_BYTES) {
+    const end = utf8PageEnd(bytes, offset, pageBytes);
+    const complete = end === bytes.length;
+    const payload = {
+      v: 1,
+      target,
+      sessionID: response.sessionID,
+      messageID: response.messageID,
+      role: response.role,
+      digest,
+      offset: end,
+      expiresAt,
+    };
+    const result = {
+      ok: true,
+      target,
+      sessionID: response.sessionID,
+      messageID: response.messageID,
+      role: response.role,
+      finish: response.finish,
+      offset,
+      nextOffset: end,
+      totalBytes: bytes.length,
+      complete,
+      cursor: complete ? null : encodeCursor(payload, secret),
+      text: bytes.subarray(offset, end).toString("utf8"),
+    };
+    if (Buffer.byteLength(JSON.stringify(result), "utf8") <= MAX_TOOL_OUTPUT_BYTES) return result;
+    pageBytes = Math.floor(pageBytes / 2);
+  }
+  return error("OUTPUT_BUDGET_EXCEEDED", "A response page could not fit within the tool output budget.");
+}
+
+function validateTarget(target) {
+  if (typeof target !== "string" || !/^(?:[a-z][a-z0-9_-]{0,31}|w[0-9A-Za-z]+:p[0-9A-Za-z]+)$/.test(target)) {
+    return error("INVALID_REQUEST", "target must be a Herdr agent name or pane ID.");
+  }
+  return { ok: true };
+}
+
+async function resolveInitialResponse(target, run, signal, maxExportBytes) {
+  let agent;
+  try {
+    const output = await run("herdr", ["agent", "get", target], signal, MAX_HERDR_OUTPUT_BYTES);
+    agent = parseJsonOutput(output, "herdr agent get").result?.agent;
+  } catch (cause) {
+    const detail = processErrorDetail(cause);
+    if (detail.includes("agent_not_found")) return error("AGENT_NOT_FOUND", `Herdr agent ${target} was not found.`);
+    return error("HERDR_UNAVAILABLE", `Unable to query Herdr agent ${target}: ${detail}`, true);
+  }
+  if (!SETTLED_STATES.has(agent?.agent_status)) {
+    return error(
+      "AGENT_NOT_SETTLED",
+      `Herdr agent ${target} is ${agent?.agent_status ?? "unknown"}; wait for idle or done.`,
+      true,
+    );
+  }
+  const session = agent.agent_session;
+  if (
+    session?.agent !== "opencode" ||
+    session.kind !== "id" ||
+    session.source !== "herdr:opencode" ||
+    typeof session.value !== "string"
+  ) {
+    return error("AGENT_NOT_OPENCODE", `Herdr agent ${target} does not expose a trusted OpenCode session ID.`);
+  }
+  const exported = await exportSession(session.value, run, signal, maxExportBytes);
+  if (!exported.ok) return exported;
+  const selected = selectLatestCompletedResponse(exported.value);
+  if (!selected.ok) return selected;
+  if (selected.response.sessionID !== session.value) {
+    return error("SESSION_EXPORT_FAILED", "The exported response belongs to a different OpenCode session.");
+  }
+  if (!ALLOWED_TARGET_ROLES.has(selected.response.role)) {
+    return error(
+      "UNSUPPORTED_WORKER_ROLE",
+      `Herdr target ${target} completed as unsupported agent role ${selected.response.role ?? "unknown"}.`,
+    );
+  }
+  return selected;
+}
+
+async function exportSession(sessionID, run, signal, maxExportBytes) {
+  try {
+    const output = await run("opencode", ["export", sessionID], signal, maxExportBytes);
+    return { ok: true, value: parseJsonOutput(output, "opencode export") };
+  } catch (cause) {
+    const detail = processErrorDetail(cause);
+    const code =
+      cause?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+        ? "SESSION_EXPORT_TOO_LARGE"
+        : detail.toLowerCase().includes("not found")
+          ? "SESSION_NOT_FOUND"
+          : "SESSION_EXPORT_FAILED";
+    return error(code, `Unable to export OpenCode session ${sessionID}: ${detail}`, code === "SESSION_EXPORT_FAILED");
+  }
+}
+
+export function createResponseService(options = {}) {
+  const run = options.run ?? defaultRun;
+  const secret = options.secret ?? randomBytes(32);
+  const now = options.now ?? Date.now;
+  const cursorTtlMs = options.cursorTtlMs ?? DEFAULT_CURSOR_TTL_MS;
+  const maxExportBytes = options.maxExportBytes ?? DEFAULT_MAX_EXPORT_BYTES;
+
+  if (!Number.isSafeInteger(maxExportBytes) || maxExportBytes < 1024 * 1024) {
+    throw new TypeError("maxExportBytes must be an integer of at least 1048576 bytes.");
+  }
+
+  return async function retrieve(args, context) {
+    if (!ALLOWED_CALLERS.has(context?.agent)) {
+      return error("UNAUTHORIZED_AGENT", `Agent ${context?.agent ?? "unknown"} may not retrieve worker responses.`);
+    }
+    const pageSize = normalizePageBytes(args.maxBytes);
+    if (!pageSize.ok) return pageSize;
+    if (Boolean(args.target) === Boolean(args.cursor)) {
+      return error("INVALID_REQUEST", "Provide exactly one of target or cursor.");
+    }
+
+    if (args.target) {
+      const valid = validateTarget(args.target);
+      if (!valid.ok) return valid;
+      const selected = await resolveInitialResponse(args.target, run, context.abort, maxExportBytes);
+      if (!selected.ok) return selected;
+      return makePage({
+        response: selected.response,
+        target: args.target,
+        offset: 0,
+        requestedBytes: pageSize.value,
+        secret,
+        expiresAt: now() + cursorTtlMs,
+      });
+    }
+
+    const decoded = decodeCursor(args.cursor, secret, now);
+    if (!decoded.ok) return decoded;
+    const exported = await exportSession(decoded.payload.sessionID, run, context.abort, maxExportBytes);
+    if (!exported.ok) return exported;
+    const pinned = findPinnedResponse(exported.value, decoded.payload.messageID);
+    if (!pinned.ok) return pinned;
+    if (
+      pinned.response.sessionID !== decoded.payload.sessionID ||
+      pinned.response.role !== decoded.payload.role ||
+      !ALLOWED_TARGET_ROLES.has(pinned.response.role) ||
+      sha256(Buffer.from(pinned.response.text, "utf8")) !== decoded.payload.digest
+    ) {
+      return error("MESSAGE_CHANGED", "The pinned worker response changed after pagination began.");
+    }
+    return makePage({
+      response: pinned.response,
+      target: decoded.payload.target,
+      offset: decoded.payload.offset,
+      requestedBytes: pageSize.value,
+      secret,
+      expiresAt: decoded.payload.expiresAt,
+    });
+  };
+}
+
+export function createResponseTool(options = {}) {
+  const retrieve = createResponseService(options);
+  return tool({
+    description:
+      "Retrieve the complete final response from a settled Herdr-managed OpenCode worker. Start with target, then follow each returned cursor until complete is true.",
+    args: {
+      target: tool.schema.string().optional().describe("Herdr agent name or pane ID for the initial page."),
+      cursor: tool.schema.string().optional().describe("Opaque cursor returned by the preceding page."),
+      maxBytes: tool.schema
+        .number()
+        .int()
+        .min(MIN_PAGE_BYTES)
+        .max(MAX_PAGE_BYTES)
+        .optional()
+        .describe("Maximum UTF-8 response bytes requested for this page."),
+    },
+    async execute(args, context) {
+      const result = await retrieve(args, context);
+      context.metadata({
+        title: result.ok ? `Worker response: ${result.target}` : `Worker response: ${result.error.code}`,
+        metadata: result.ok
+          ? { sessionID: result.sessionID, messageID: result.messageID, complete: result.complete }
+          : { error: result.error.code },
+      });
+      return JSON.stringify(result);
+    },
+  });
+}