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.

[kangal-bot]

hi @gxbsst, thanks for opening this.

this issue does not appear to use the full bug report template. herdr issues are only for reproducible bugs and maintainer-created or maintainer-converted work items.

bug reports must include the reproducible-bug confirmation, current behavior, expected behavior, reproduction, impact, and environment fields with herdr version, update channel, operating system, and terminal.

feature requests, ideas, questions, contribution proposals, and direction checks belong in discussions:
https://github.com/herdrdev/herdr/discussions

please read the contributing guidelines before opening issues or prs:
https://github.com/herdrdev/herdr/blob/master/CONTRIBUTING.md

closing this so the issue tracker stays limited to actionable bug reports.