Herdr 0.7.5 breaks subagent spawn: agent start --cwd removed

[pael-akkio]

Summary

pi-herdr-subagents fails to spawn subagents on Herdr ≥ 0.7.5 (current Homebrew stable). The extension calls a CLI shape that existed in 0.7.1–0.7.4 but was removed in 0.7.5.

Error when invoking the subagent tool:

Failed to start herdr pane for "<name>": unknown option: --cwd

Herdr itself is fine (HERDR_ENV=1, socket reachable). This is an API mismatch, not a Herdr outage.

Environment

• Herdr: 0.7.5 (Homebrew stable, macOS Apple Silicon)
• pi-herdr-subagents: main @ 2026-07-22 (pre-fix)
• pi: running inside a Herdr pane
• OS: macOS

Steps to reproduce

1. Install Herdr 0.7.5 (brew install herdr or install script on stable channel).
2. Start pi inside a Herdr pane with pi-herdr-subagents enabled.
3. Invoke subagent (e.g. spawn a reviewer agent).
4. Observe spawn failure with unknown option: --cwd.

Expected behavior

Subagent pane opens; wrapper script runs; orchestrator receives lifecycle events.

Actual behavior

Spawn fails immediately. No pane is created.

Root cause

src/herdr/client.ts → agentStart() builds:

herdr agent start <name> --cwd <path> [--tab …] [--split …] [--env …] --no-focus -- bash <wrapper.sh>

Herdr 0.7.5 (release notes) replaced this with a live-agent facade:

herdr agent start <name> --kind <KIND> --pane <PANE_ID> [-- <agent-args>]

Topology (--cwd, --tab, --split, --env) is no longer accepted on agent start. Layout must be created separately via herdr pane split, then an interactive agent kind is started in that pane.

Subagents are not interactive agent kinds — they launch a bash wrapper that exports env and execs pi. So the 0.7.5 agent start --kind path is the wrong primitive anyway.

Proposed fix

Keep the public agentStart() interface; change implementation to:

1. herdr pane split --current --direction right|down --cwd <cwd> [--env K=V] --no-focus
2. Parse result.pane.pane_id from JSON envelope
3. herdr pane run <pane_id> bash <wrapper.sh> …

This matches Herdr's current SKILL.md guidance for non-agent commands and argv launches.

Scope of change

File	Change
src/herdr/client.ts	Rewrite agentStart() (~30 net LOC)
test/herdr-client.test.ts	Expect split + run instead of agent start
README.md, docs	Note 0.7.5 migration; bump minimum Herdr version

No changes needed to index.ts, launch.ts, or the watcher — contract is preserved.

Version compatibility

Herdr	agent start --cwd	Works with current extension?
0.7.1 – 0.7.4	✅	✅
0.7.5+	❌ removed	❌ (without fix)

README currently says herdr ≥ 0.7.1, which implies 0.7.5 works — it doesn't.

Suggested follow-ups

• Merge fix above (happy to open a PR if useful)
• Document that tabId in launch plan is ignored on 0.7.5+ (pane split --current only)
• Consider runtime version check with actionable error if herdr agent start --help lacks --cwd but code path hasn't been updated

Workarounds (until fixed)

1. Downgrade Herdr to 0.7.4 (last release with legacy API)
2. Local patch to client.ts as described above
3. Reinstalling Herdr via install script on stable still yields 0.7.5 — won't help

[regutierrez]

PS: above writeup was made by a clanker, but issue was experienced and validated personally by me. (this is my personal acct. made a mistake opening an issue using my work account. sorry about that 😓)