Proposal: herdr tool run — labeled, reusable tool panes with structured results

[gxbsst]

Proposal: herdr tool run — labeled, reusable tool panes with structured results

Motivation

Agents (Codex, Claude Code, and any skill-driven harness) frequently need to run
long-running commands — tests, builds, servers, database queries — without
blocking their own reasoning pane or stealing the user's focus. Herdr already
provides every primitive needed (pane split, pane run, pane wait-output,
pane read), but each harness re-implements "create-or-reuse a labeled pane,
run a command, detect completion, read a result" on top of them. Herdr Kit's
ToolPaneService is one such re-implementation; a first-class Herdr surface
would give every agent the same contract without depending on a plugin.

Proposed CLI

herdr tool run <label> [--direction right|down] [--focus] [--timeout-ms N]
                     [--new] [--json] -- <command...>

Behavior:

• Labeled pane: find a pane labeled Tool · <label> in the caller's
  workspace, or create one by splitting from the caller pane (right by default,
  down for stacking) with --no-focus.
• Atomic run: execute the command with pane run, appending a completion
  marker that carries the exit code:
  command; printf '\n__HERDR_TOOL_DONE_<ns>__:%s\n' "$?".
• Completion: pane wait-output --match <marker>; on timeout return
  timed_out: true and keep the pane for inspection.
• Result: read the tail and return JSON:
  {label, pane_id, reused, exit_code, timed_out, output_tail}.
• Reuse: same label reuses the pane by default; --new forces a fresh pane.
• Focus: never steal focus unless the caller passes --focus.
• Scope: only creates panes — no workspaces, tabs, worktrees, or cwd
  changes beyond the caller's context.

Design notes

• Marker-based exit detection keeps the contract shell-agnostic and works with
  any foreground process; it does not require an integration or agent state.
• Reuse is exact-label within the caller's workspace; stale panes fall back to
  creating a new one.
• The pane stays open after completion so output can be inspected; agents
  decide when to close or reuse it.
• Composes the existing primitives (split/run/wait-output/read) rather than
  adding a new execution model.

Acceptance criteria

• herdr tool run tests -- pytest -q returns JSON with pane_id and
  exit_code; a pane labeled Tool · tests exists in the caller's workspace.
• Running the same label again reuses the pane (reused: true).
• A command that exceeds --timeout-ms returns timed_out: true with
  exit_code: null and keeps the pane.
• Without --focus, user focus is unchanged.
• No workspace/tab/worktree is created.

Relationship to the agent skill

The official skills/herdr/SKILL.md currently teaches the four-step primitive
sequence. herdr tool run collapses it into one command, making the skill
shorter and behavior consistent across Codex, Claude Code, and custom harnesses.