herdr-link 0.4.0 → 0.5.0

package/src/herdr.ts

@@ -1,7 +1,7 @@
 import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
-import { resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import {
   AGENT_ERROR_DETAILS,
   buildEnvelope,
@@ -108,7 +108,13 @@ interface ValidatedStartVariant {
   args: string[];
 }
 
+/** Placing a configured Agent: a fresh tab, or co-located with a live anchor Agent. */
+type ValidatedPlacement =
+  | { mode: "new_tab"; label?: string }
+  | { mode: "with" };
+
 interface ConfiguredStartAgent {
+  placement: ValidatedPlacement;
   strategy?: "round-robin";
   variants: ValidatedStartVariant[];
 }
@@ -116,7 +122,7 @@ interface ConfiguredStartAgent {
 const startCursors = new Map<string, number>();
 const startLocks = new Map<string, Promise<void>>();
 const START_CONFIG_PATH_PARTS = [".agents", "agent_config.json"] as const;
-const START_INPUT_KEYS = new Set(["name", "pane", "config_agent", "kind", "args"]);
+const START_INPUT_KEYS = new Set(["name", "with", "cwd", "config_agent", "kind", "args"]);
 
 /** @internal Test seam only: clears process-local configured-start state. */
 export function resetStartStateForTests(): void {
@@ -140,8 +146,8 @@ function startConfigError(
 }
 
 function validateStartInput(input: unknown):
-  | { mode: "configured"; name: string; pane: string; configAgent: string }
-  | { mode: "explicit"; name: string; pane: string; variant: ValidatedStartVariant } {
+  | { mode: "configured"; name: string; configAgent: string; withName?: string; cwd?: string }
+  | { mode: "explicit"; name: string; variant: ValidatedStartVariant; withName?: string; cwd?: string } {
   const value = asRecord(input);
   if (!value) throw startInputError("start input must be an object");
   for (const key of Object.keys(value)) {
@@ -150,11 +156,25 @@ function validateStartInput(input: unknown):
 
   const name = value.name;
   if (typeof name !== "string" || !isValidAgentName(name)) {
-    throw startInputError("\"name\" must be a valid Herdr Agent Name");
+    throw startInputError('"name" must be a valid Herdr Agent Name');
   }
-  const pane = value.pane;
-  if (typeof pane !== "string" || pane.trim() === "") {
-    throw startInputError("\"pane\" must be a non-empty pane id");
+
+  let withName: string | undefined;
+  if (hasOwn(value, "with")) {
+    const withValue = value.with;
+    if (typeof withValue !== "string" || !isValidAgentName(withValue)) {
+      throw startInputError('"with" must be a valid Herdr Agent Name');
+    }
+    withName = withValue;
+  }
+
+  let cwd: string | undefined;
+  if (hasOwn(value, "cwd")) {
+    const cwdValue = value.cwd;
+    if (typeof cwdValue !== "string" || cwdValue.trim() === "") {
+      throw startInputError('"cwd" must be a non-empty string');
+    }
+    cwd = cwdValue;
   }
 
   const hasConfigAgent = hasOwn(value, "config_agent");
@@ -166,9 +186,9 @@ function validateStartInput(input: unknown):
   if (hasConfigAgent) {
     const configAgent = value.config_agent;
     if (typeof configAgent !== "string" || configAgent.trim() === "") {
-      throw startInputError("\"config_agent\" must be a non-empty string");
+      throw startInputError('"config_agent" must be a non-empty string');
     }
-    return { mode: "configured", name, pane, configAgent };
+    return { mode: "configured", name, configAgent, ...(withName !== undefined ? { withName } : {}), ...(cwd !== undefined ? { cwd } : {}) };
   }
 
   if (!hasKind || !hasArgs) {
@@ -176,13 +196,17 @@ function validateStartInput(input: unknown):
   }
   const kind = value.kind;
   if (typeof kind !== "string" || kind.trim() === "") {
-    throw startInputError("\"kind\" must be a non-empty string");
+    throw startInputError('"kind" must be a non-empty string');
   }
   const args = value.args;
   if (!Array.isArray(args) || !args.every((arg) => typeof arg === "string")) {
-    throw startInputError("\"args\" must be an array of strings");
+    throw startInputError('"args" must be an array of strings');
+  }
+  // Explicit `with` (same-tab placement) never takes a launch `cwd`.
+  if (withName !== undefined && cwd !== undefined) {
+    throw startInputError('"cwd" cannot be combined with "with"');
   }
-  return { mode: "explicit", name, pane, variant: { kind, args: [...args] } };
+  return { mode: "explicit", name, variant: { kind, args: [...args] }, ...(withName !== undefined ? { withName } : {}), ...(cwd !== undefined ? { cwd } : {}) };
 }
 
 function assertAllowedKeys(value: Record<string, unknown>, allowed: readonly string[], label: string): void {
@@ -195,8 +219,7 @@ function assertAllowedKeys(value: Record<string, unknown>, allowed: readonly str
 function validateConfiguredDocument(document: unknown): Map<string, ConfiguredStartAgent> {
   const root = asRecord(document);
   if (!root) throw startConfigError("START_CONFIG_INVALID", "configuration root must be an object");
-  assertAllowedKeys(root, ["version", "agents"], "configuration root");
-  if (root.version !== 1) throw startConfigError("START_CONFIG_INVALID", "configuration version must be 1");
+  assertAllowedKeys(root, ["agents"], "configuration root");
 
   const agents = asRecord(root.agents);
   if (!agents) throw startConfigError("START_CONFIG_INVALID", "agents must be an object");
@@ -208,7 +231,11 @@ function validateConfiguredDocument(document: unknown): Map<string, ConfiguredSt
     }
     const entry = asRecord(rawEntry);
     if (!entry) throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent} must be an object`);
-    assertAllowedKeys(entry, ["strategy", "variants"], `agents.${configAgent}`);
+    assertAllowedKeys(entry, ["placement", "strategy", "variants"], `agents.${configAgent}`);
+    if (!hasOwn(entry, "placement")) {
+      throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.placement is required`);
+    }
+    const placement = validatePlacement(entry.placement, configAgent);
 
     const rawVariants = entry.variants;
     if (!Array.isArray(rawVariants) || rawVariants.length === 0) {
@@ -238,6 +265,7 @@ function validateConfiguredDocument(document: unknown): Map<string, ConfiguredSt
     });
 
     result.set(configAgent, {
+      placement,
       ...(hasStrategy ? { strategy: "round-robin" as const } : {}),
       variants,
     });
@@ -245,6 +273,30 @@ function validateConfiguredDocument(document: unknown): Map<string, ConfiguredSt
   return result;
 }
 
+/** Strict placement validation: `new_tab` with optional presentation-only label, or `with` without a label. */
+function validatePlacement(rawPlacement: unknown, configAgent: string): ValidatedPlacement {
+  const placement = asRecord(rawPlacement);
+  if (!placement) {
+    throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.placement must be an object`);
+  }
+  if (placement.mode === "new_tab") {
+    assertAllowedKeys(placement, ["mode", "label"], `agents.${configAgent}.placement`);
+    let label: string | undefined;
+    if (hasOwn(placement, "label")) {
+      if (typeof placement.label !== "string" || placement.label.trim() === "") {
+        throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.placement.label must be a non-empty string`);
+      }
+      label = placement.label;
+    }
+    return { mode: "new_tab", ...(label !== undefined ? { label } : {}) };
+  }
+  if (placement.mode === "with") {
+    assertAllowedKeys(placement, ["mode"], `agents.${configAgent}.placement`);
+    return { mode: "with" };
+  }
+  throw startConfigError("START_CONFIG_INVALID", `agents.${configAgent}.placement.mode is unsupported`);
+}
+
 async function loadConfiguredStartAgents(configPath: string): Promise<Map<string, ConfiguredStartAgent>> {
   let text: string;
   try {
@@ -295,22 +347,185 @@ async function runStart(name: string, pane: string, variant: ValidatedStartVaria
 }
 
 export interface StartAgentOptions {
-  /** Runtime context directory used to locate the optional project config. */
-  cwd?: string;
+  /**
+   * Adapter context directory: locates `.agents/agent_config.json`, is the
+   * default launch cwd for a new tab, and is the resolution base for a
+   * relative model `cwd`. Never used as the launch cwd of a `with` placement.
+   */
+  contextDirectory?: string;
+}
+
+type ResolvedPlacement =
+  | { kind: "new-tab"; label?: string }
+  | { kind: "with"; withName: string };
+
+type PlacementAllocation = {
+  paneId: string;
+  rollback(): Promise<void>;
+};
+
+function startFailure(detail: string): HerdrLinkError {
+  return new HerdrLinkError("START_FAILED", detail);
+}
+
+/**
+ * Resolves the effective placement for a validated start. Configured mode
+ * derives it from the declared placement; explicit mode derives it from the
+ * presence of `with` (present → same-tab, absent → new-tab).
+ */
+function resolvePlacement(
+  validated: ReturnType<typeof validateStartInput>,
+  configPlacement: ValidatedPlacement | undefined,
+): ResolvedPlacement {
+  if (validated.mode === "configured") {
+    if (configPlacement?.mode === "new_tab") {
+      if (validated.withName !== undefined) {
+        throw startInputError('"with" is not allowed for a new_tab configured placement');
+      }
+      return { kind: "new-tab", label: configPlacement.label };
+    }
+    // configured `with`:
+    if (validated.withName === undefined) {
+      throw startInputError('configured "with" placement requires "with"');
+    }
+    if (validated.cwd !== undefined) {
+      throw startInputError('"cwd" is not allowed for a "with" placement');
+    }
+    return { kind: "with", withName: validated.withName };
+  }
+  return validated.withName !== undefined
+    ? { kind: "with", withName: validated.withName }
+    : { kind: "new-tab" };
+}
+
+/**
+ * New-tab launch cwd: `input.cwd` resolved against the context directory
+ * when relative, used as-is when absolute; otherwise the context directory
+ * itself. NEVER affects where `.agents/agent_config.json` is looked up.
+ */
+function resolveLaunchCwd(contextDirectory: string, inputCwd: string | undefined): string {
+  if (inputCwd === undefined) return contextDirectory;
+  return isAbsolute(inputCwd) ? inputCwd : resolve(contextDirectory, inputCwd);
+}
+
+/** Best-effort tab close; rollback failures never replace the primary error. */
+async function bestEffortCloseTab(tabId: string): Promise<void> {
+  try {
+    await runFor(["tab", "close", tabId], "START_FAILED");
+  } catch {
+    // Preserve the primary start failure classification.
+  }
+}
+
+/** Best-effort pane close; rollback failures never replace the primary error. */
+async function bestEffortClosePane(paneId: string): Promise<void> {
+  try {
+    await runFor(["pane", "close", paneId], "START_FAILED");
+  } catch {
+    // Preserve the primary start failure classification.
+  }
+}
+
+
+/**
+ * New-tab allocation: create a focus-free tab, then resolve its exactly-one
+ * root pane through a fresh `pane list` filtered by the created tab id.
+ * Raw topology ids stay inside this function and the returned allocation.
+ */
+async function allocateNewTab(
+  contextDirectory: string,
+  inputCwd: string | undefined,
+  label: string | undefined,
+): Promise<PlacementAllocation> {
+  const self = await getSelfContext();
+  const launchCwd = resolveLaunchCwd(contextDirectory, inputCwd);
+  const created = await runFor(
+    [
+      "tab", "create",
+      "--workspace", self.workspace_id,
+      "--cwd", launchCwd,
+      ...(label !== undefined ? ["--label", label] : []),
+      "--no-focus",
+    ],
+    "START_FAILED",
+  );
+  const createdTabId = parseTabCreateResult(created);
+  if (createdTabId === undefined) throw startFailure("created tab reported no tab id");
+  try {
+    const panes = await runFor(["pane", "list", "--workspace", self.workspace_id], "START_FAILED");
+    const rootPanes = filterPanesByTab(panes, createdTabId);
+    if (rootPanes.length !== 1 || rootPanes[0] === undefined) {
+      throw startFailure("created tab must contain exactly one root pane");
+    }
+    return {
+      paneId: rootPanes[0],
+      rollback: () => bestEffortCloseTab(createdTabId),
+    };
+  } catch (error) {
+    // The tab was allocated but not yet exposed: close the exact created tab.
+    await bestEffortCloseTab(createdTabId);
+    throw error;
+  }
+}
+
+/**
+ * `with` allocation: resolve the live anchor, enforce same-workspace, read
+ * the anchor pane's cwd, and split that pane so the new Agent inherits the
+ * anchor's live cwd. Raw pane ids stay inside this function.
+ */
+async function allocateWith(withName: string): Promise<PlacementAllocation> {
+  const self = await getSelfContext();
+  const anchor = await getAgentContext(withName);
+  assertSameWorkspace(self, anchor);
+  const anchorPane = await getPaneCwd(anchor.pane_id);
+  if (anchorPane.workspace_id === "" || anchorPane.workspace_id !== self.workspace_id) {
+    throw new HerdrLinkError("PEER_NOT_FOUND", AGENT_ERROR_DETAILS.PEER_NOT_FOUND);
+  }
+  if (anchorPane.cwd === undefined || anchorPane.cwd === "") {
+    throw startFailure(`anchor pane ${anchor.pane_id} has no cwd; cannot inherit worktree binding`);
+  }
+  const split = await runFor(
+    [
+      "pane", "split", anchor.pane_id,
+      "--direction", "right",
+      "--cwd", anchorPane.cwd,
+      "--no-focus",
+    ],
+    "START_FAILED",
+  );
+  const newPaneId = parsePaneSplitResult(split);
+  if (newPaneId === undefined) throw startFailure("pane split returned no created pane id");
+  return {
+    paneId: newPaneId,
+    rollback: () => bestEffortClosePane(newPaneId),
+  };
 }
 
-/** Starts an Agent from a complete configured entry or a complete explicit launch specification. */
+/** Starts an Agent with Link-managed placement: allocation, mech start, failed-start rollback. */
 export async function startAgent(input: StartAgentInput, options: StartAgentOptions = {}): Promise<StartAgentReceipt> {
   assertHerdrEnvironment();
   const validated = validateStartInput(input);
+  const contextDirectory =
+    typeof options.contextDirectory === "string" && options.contextDirectory.trim() !== ""
+      ? options.contextDirectory
+      : process.cwd();
 
   if (validated.mode === "explicit") {
-    await runStart(validated.name, validated.pane, validated.variant);
+    const placement = resolvePlacement(validated, undefined);
+    const allocation =
+      placement.kind === "new-tab"
+        ? await allocateNewTab(contextDirectory, validated.cwd, placement.label)
+        : await allocateWith(placement.withName);
+    try {
+      await runStart(validated.name, allocation.paneId, validated.variant);
+    } catch (error) {
+      await allocation.rollback().catch(() => {});
+      throw error;
+    }
     return { status: "started", agent: validated.name, kind: validated.variant.kind };
   }
 
-  const projectRoot = typeof options.cwd === "string" && options.cwd.trim() !== "" ? options.cwd : process.cwd();
-  const configPath = resolve(projectRoot, ...START_CONFIG_PATH_PARTS);
+  const configPath = resolve(contextDirectory, ...START_CONFIG_PATH_PARTS);
   const cursorKey = `${configPath}\u0000${validated.configAgent}`;
   return withStartCursorLock(cursorKey, async () => {
     const configuredAgents = await loadConfiguredStartAgents(configPath);
@@ -319,14 +534,24 @@ export async function startAgent(input: StartAgentInput, options: StartAgentOpti
       throw startConfigError("START_AGENT_NOT_FOUND", `configured Agent "${validated.configAgent}" was not found`);
     }
 
+    const placement = resolvePlacement(validated, configured.placement);
     const current = startCursors.get(cursorKey) ?? 0;
     const variantIndex = current % configured.variants.length;
     const variant = configured.variants[variantIndex]!;
-    await runStart(validated.name, validated.pane, variant);
-    if (configured.variants.length > 1) {
-      startCursors.set(cursorKey, (variantIndex + 1) % configured.variants.length);
+    const allocation =
+      placement.kind === "new-tab"
+        ? await allocateNewTab(contextDirectory, validated.cwd, placement.label)
+        : await allocateWith(placement.withName);
+    try {
+      await runStart(validated.name, allocation.paneId, variant);
+      if (configured.variants.length > 1) {
+        startCursors.set(cursorKey, (variantIndex + 1) % configured.variants.length);
+      }
+      return { status: "started", agent: validated.name, kind: variant.kind };
+    } catch (error) {
+      await allocation.rollback().catch(() => {});
+      throw error;
     }
-    return { status: "started", agent: validated.name, kind: variant.kind };
   });
 }
 
@@ -410,7 +635,75 @@ function agentList(value: unknown): unknown[] {
 }
 
 /* ------------------------------------------------------------------ *
- * Live record readers (blueprint v2)
+ * Topology parsing helpers (pure, unit-testable)
+ *
+ * Hersdr topology responses are parsed here, never guessed inline in the
+ * allocation flow. Shapes follow the measured Herdr CLI responses:
+ * - tab create -> { result: { tab: { tab_id }, root_pane: { ... } } }
+ * - pane list  -> { result: { panes: [{ tab_id, pane_id, ... }] } }
+ * - pane get   -> { result: { pane: { workspace_id, cwd, ... } } }
+ * - pane split -> { result: { pane: { pane_id, ... } } }
+ * ------------------------------------------------------------------ */
+
+interface PaneInfoRecord {
+  workspace_id?: string;
+  cwd?: string;
+  tab_id?: string;
+}
+
+/** Parses the created tab id from `tab create` output; undefined when absent. */
+function parseTabCreateResult(value: unknown): string | undefined {
+  const root = asRecord(value);
+  const result = asRecord(root?.result);
+  const tab = asRecord(result?.tab) ?? asRecord(root?.tab) ?? asRecord(result);
+  return nonEmptyString(tab?.tab_id);
+}
+
+/** Returns pane ids of the created tab from a fresh `pane list` response. */
+function filterPanesByTab(value: unknown, tabId: string): string[] {
+  const root = asRecord(value);
+  const result = asRecord(root?.result);
+  const rawPanes = result?.panes;
+  if (!Array.isArray(rawPanes)) return [];
+  const paneIds: string[] = [];
+  for (const raw of rawPanes) {
+    const pane = asRecord(raw);
+    if (pane && pane.tab_id === tabId) {
+      const paneId = nonEmptyString(pane.pane_id);
+      if (paneId !== undefined) paneIds.push(paneId);
+    }
+  }
+  return paneIds;
+}
+
+/** Parses a pane record from `pane get` output. */
+function parsePaneInfoResult(value: unknown): PaneInfoRecord {
+  const root = asRecord(value);
+  const result = asRecord(root?.result);
+  const pane = asRecord(result?.pane) ?? asRecord(root);
+  return {
+    workspace_id: nonEmptyString(pane?.workspace_id),
+    cwd: nonEmptyString(pane?.cwd),
+    tab_id: nonEmptyString(pane?.tab_id),
+  };
+}
+
+/** Fresh `pane get` for an anchor pane: authoritative cwd/workspace facts. */
+async function getPaneCwd(paneId: string): Promise<PaneInfoRecord> {
+  const response = await runFor(["pane", "get", paneId], "START_FAILED");
+  return parsePaneInfoResult(response);
+}
+
+/** Parses the created sibling pane id from `pane split` output; undefined when absent. */
+function parsePaneSplitResult(value: unknown): string | undefined {
+  const root = asRecord(value);
+  const result = asRecord(root?.result);
+  const pane = asRecord(result?.pane) ?? asRecord(result);
+  return nonEmptyString(pane?.pane_id);
+}
+
+/* ------------------------------------------------------------------ *
+ * Live record readers
  *
  * Every communication call resolves fresh records from Herdr. Ambient
  * environment values such as HERDR_WORKSPACE_ID are never consulted:

package/src/mcp.ts

@@ -7,7 +7,7 @@
  * Tool execution reuses the herdr.ts control layer. Tool gating and error semantics follow
  * PROTOCOL.md §7; tool-name presentation follows PROTOCOL.md §4.6.
  *
- * Lazy presentation (blueprint v2): the tool surface is session-local and
+ * Lazy presentation: the tool surface is session-local and
  * dormant until activated. Outside Herdr, `tools/list` is empty. Inside
  * Herdr, a dormant session lists only the Tier 0 `herdr_link` gateway;
  * calling the gateway with `{}` activates THIS server session (per stdio
@@ -39,7 +39,7 @@ import {
 
 export const MCP_SERVER_NAME = "herdr-link";
 /** Keep in sync with package.json "version" (serverInfo is informational). */
-export const MCP_SERVER_VERSION = "0.2.1";
+export const MCP_SERVER_VERSION = "0.5.0";
 /** Fallback protocol version advertised when the client sends none. */
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
 
@@ -79,24 +79,23 @@ type CanonicalToolName = (typeof HERDR_LINK_TOOLS)[number];
 const NORMAL_MESSAGING_RULE = "Use Herdr Link, not raw Herdr CLI, pane ids, or terminal input, for normal inter-agent messaging.";
 const TOOL_DESCRIPTIONS: Record<CanonicalToolName, string> = {
   [TOOL_START]: `${START_TOOL_DESCRIPTION} ${NORMAL_MESSAGING_RULE}`,
-  [TOOL_PEERS]: `Discover live named peers in the same Herdr workspace; each state is advisory and Agent Names are the only addresses. ${NORMAL_MESSAGING_RULE}`,
-  [TOOL_SEND]:
-    `Send a herdr-link/1 message to a live named peer in your own workspace; status "sent" means Herdr accepted delivery. ${NORMAL_MESSAGING_RULE}`,
-  [TOOL_CLOSE]:
-    `Close the pane currently hosting a named same-workspace agent. If you need to send a final message before closing, complete the send first and call close in a later tool step. ${NORMAL_MESSAGING_RULE}`,
+  [TOOL_PEERS]: `List live same-workspace agent names. ${NORMAL_MESSAGING_RULE}`,
+  [TOOL_SEND]: `Send a Link message; "sent" is delivery only. ${NORMAL_MESSAGING_RULE}`,
+  [TOOL_CLOSE]: `Close a named agent's pane. If a final message is needed, send first and close in a later tool step. ${NORMAL_MESSAGING_RULE}`,
 };
 
 const TOOL_INPUT_SCHEMAS: Record<CanonicalToolName, Record<string, unknown>> = {
   [TOOL_START]: {
     type: "object",
     properties: {
-      name: { type: "string", description: "New Herdr Agent Name" },
-      pane: { type: "string", description: "Existing pane id" },
-      config_agent: { type: "string", description: "Configured Agent key; do not combine with kind or args" },
-      kind: { type: "string", description: "Herdr Agent kind for explicit start" },
-      args: { type: "array", items: { type: "string" }, description: "Complete Herdr Agent arguments for explicit start" },
+      name: { type: "string", description: "New agent name." },
+      with: { type: "string", description: "Co-locate with this agent." },
+      cwd: { type: "string", description: "New-tab working directory." },
+      config_agent: { type: "string", description: "Config key." },
+      kind: { type: "string", description: "Agent kind." },
+      args: { type: "array", items: { type: "string" }, description: "Agent arguments." },
     },
-    required: ["name", "pane"],
+    required: ["name"],
     oneOf: [
       { required: ["config_agent"], not: { anyOf: [{ required: ["kind"] }, { required: ["args"] }] } },
       { required: ["kind", "args"], not: { required: ["config_agent"] } },
@@ -129,7 +128,7 @@ const FALLBACK_ERROR_CODE: Record<CanonicalToolName, LinkErrorCode> = {
 };
 
 /**
- * Tier 0 gateway tool (blueprint v2): the single always-present registration
+ * Tier 0 gateway tool: the single always-present registration
  * surface while dormant, and the explicit action-dispatch fallback for hosts
  * that do not react to `notifications/tools/list_changed`.
  */
@@ -274,7 +273,7 @@ export function createRequestHandler(
   const runStart = deps.startAgent ?? startAgent;
   const notify = deps.notify ?? stdoutNotificationSink;
 
-  /** Session-local lazy activation (blueprint v2). True ⇒ Tier 1 tools are listed. */
+  /** Session-local lazy activation. True ⇒ Tier 1 tools are listed. */
   let activated = false;
 
   /**
@@ -443,7 +442,7 @@ export function createRequestHandler(
       case "ping":
         return respond(id, {});
       case "tools/list": {
-        // Zero side-effect gate (ADR-013) + lazy presentation (blueprint v2):
+        // Zero side-effect gate (ADR-013) + lazy presentation:
         // outside Herdr nothing; dormant only the Tier 0 gateway; active the
         // gateway plus the canonical Tier 1 tools.
         if (!environmentOk()) return respond(id, { tools: [] });
@@ -526,7 +525,7 @@ function contractWithAppendix(appendix: string): string {
  * Contract text for prefix-style MCP hosts (e.g. Codex): tools are exposed as
  * independent `mcp__<namespace>__<canonical>` functions. `namespace` is the
  * host tool namespace and must be explicit. Presentation is lazy: only the
- * gateway is listed until the model activates it (blueprint v2).
+ * gateway is listed until the model activates it.
  */
 export function buildMcpPrefixedCommunicationContract(namespace: string): string {
   const [peers, send, close] = HERDR_LINK_COMMUNICATION_TOOLS.map((name) =>
@@ -551,7 +550,7 @@ export function buildMcpPrefixedCommunicationContract(namespace: string): string
  * Contract text for wrapper-style MCP hosts (e.g. AGY's call_mcp_tool): the
  * model invokes one native wrapper carrying ServerName/ToolName/Arguments
  * instead of per-tool functions (PROTOCOL.md §4.6 wrapper form). Both values
- * must be explicit. Presentation is lazy (blueprint v2): activate the gateway
+ * must be explicit. Presentation is lazy: activate the gateway
  * first, then address the canonical tools through the same wrapper.
  */
 export function buildMcpWrapperCommunicationContract(

package/src/opencode.ts

@@ -1,5 +1,5 @@
 /**
- * Herdr Link OpenCode Runtime adapter v2 — single-gateway presentation.
+ * Herdr Link OpenCode Runtime adapter — single-gateway presentation.
  *
  * The model-facing surface is exactly one tiny `herdr_link` dispatcher tool,
  * in both dormant and active states. Calling it with no arguments (`{}`)
@@ -95,7 +95,7 @@ export const herdrLinkPlugin: Plugin = async () => {
         description:
           "Herdr Link cross-agent control gateway (herdr-link/1). Activate only when the user explicitly asks to use Herdr or when handling an inbound Herdr Link message. " +
           'Call once with no arguments {} to activate Herdr Link for this session; the response lists capabilities. ' +
-            'Then pass action "start" with name + pane and either config_agent or complete kind + args, action "peers" to list live same-workspace agents, action "send" with to + message to deliver an inter-agent message or ordinary reply, or action "close" with agent to close a named agent\'s pane — ' +
+            'Then pass action "start" with name and either config_agent or complete kind + args (with to co-locate with a live agent, cwd for a new-tab working directory), action "peers" to list live same-workspace agents, action "send" with to + message to deliver an inter-agent message or ordinary reply, or action "close" with agent to close a named agent\'s pane — ' +
             'start modes are mutually exclusive and close is only after any final send has returned status "sent", in a later tool step.',
         args: {
           action: tool.schema
@@ -120,10 +120,14 @@ export const herdrLinkPlugin: Plugin = async () => {
             .string()
             .optional()
             .describe('New Agent Name; required for action "start".'),
-          pane: tool.schema
+          with: tool.schema
             .string()
             .optional()
-            .describe('Existing pane id; required for action "start".'),
+            .describe('Live Agent Name to co-locate with for action "start"; do not combine with cwd.'),
+          cwd: tool.schema
+            .string()
+            .optional()
+            .describe('New-tab working directory for action "start".'),
           config_agent: tool.schema
             .string()
             .optional()
@@ -149,7 +153,7 @@ export const herdrLinkPlugin: Plugin = async () => {
           if (args.action === "start") {
             const startInput = Object.fromEntries(Object.entries(args).filter(([key]) => key !== "action"));
             try {
-              return jsonResult(await startAgent(startInput as unknown as StartAgentInput, { cwd: context.directory }));
+              return jsonResult(await startAgent(startInput as unknown as StartAgentInput, { contextDirectory: context.directory }));
             } catch (error) {
               failWith(error, "START_FAILED");
             }