Open a forked agent session in its own tab (and background sessions bind the wrong pane)

[daniele-casciani]

What I'd like

Claude Code's /fork copies the conversation into a new background session, and the original keeps running in the current pane. The copy then exists only in claude agents. To work with both, I open a tab by hand and run claude attach <id>.

I'd like Herdr to do that for me. When an agent in a pane forks, open the copy in a new tab of the same workspace, next to the source tab, with the agent's attach command.

What works today, as a user hook

A Claude Code SessionStart hook with matcher fork does most of it:

#!/bin/bash
# SessionStart (source=fork): open the fork in a new Herdr tab.
input=$(cat)
sid=$(jq -r '.session_id // empty' <<<"$input")
cwd=$(jq -r '.cwd // empty' <<<"$input")
[ "$(jq -r '.source' <<<"$input")" = fork ] && [ -n "$sid" ] || exit 0
[ -S "${HERDR_SOCKET_PATH:-$HOME/.config/herdr/herdr.sock}" ] || exit 0

args=(tab create --cwd "$cwd" --label "$(basename "$cwd") ⑂" --no-focus)
[ -n "$HERDR_WORKSPACE_ID" ] && args+=(--workspace "$HERDR_WORKSPACE_ID")
pane=$(herdr "${args[@]}" | jq -r '.result.root_pane.pane_id // empty')
[ -n "$pane" ] && herdr pane run "$pane" "sleep 3; claude attach ${sid:0:8}"

Tested on Herdr 0.9.5 with Claude Code /fork. The hook fires with source=fork, the tab opens, and the copy is attached.

Where the hook falls short

• Timing. The fork registers as a background agent a moment after SessionStart. sleep 3 is a guess.
• Placement. The hook does not know the source tab, so the new tab goes at the end of the workspace.
• Agent coverage. It is Claude-only. Herdr already builds resume commands per agent (agent_resume.rs), so it could do this for any agent that forks.

Background sessions bind the wrong pane (related to #5557)

Edit: I first wrote this section from the code alone. I then tested it: the problem exists today, and it affects every background session, not only forks. Below is the tested version.

#5557 asks to add fork to the herdr:claude arm of session_report_allows_session_replacement (src/terminal/state.rs). For --fork-session in the same pane, that is right. Background sessions are a different case: their reports go to a pane they do not run in, and today they already get through.

How the report reaches a pane:

1. Claude Code runs background sessions in its daemon's claude bg-pty-host processes. On my machine every one of them carries the same HERDR_ENV=1 and HERDR_PANE_ID, which looks like the pane the daemon first started in. Foreground sessions carry their own pane, as expected.
2. The Claude hook script (assets/claude/herdr-agent-state.sh) reports to HERDR_PANE_ID. handle_pane_report_agent_session (src/app/api/panes.rs) resolves the pane from that value alone and does not check that the reporter is the pane's process.

What I tested (Herdr 0.9.5, Claude integration v11 installed for the test):

• Before the test, the daemon pane (call it P) had no Claude session id.
• After /fork, P was bound to herdr:claude with the fork's session id.
• The tab where the fork actually runs (opened by my hook with claude attach) had agent_session: null.
• A few minutes later, P was bound to a third id: another background session, the one I had forked from originally. It had sent its own report while the integration was installed.
• Nothing appeared in herdr-server.log. pane.report_agent_session is a routine method, logged only when it fails, so these reports succeeded. Because of that, I could not see which source the second report used.

So P is bound to whichever background session reported last. None of them runs in P.

Why the gate did not stop the first report: the replacement gate acts only when the pane already holds a different herdr:claude id, and P held none. The second replacement got through the gate too, so its source must have been one the gate allows (clear, resume or compact). With fork added, as #5557 proposes, every background fork would replace the id as well.

A possible guard: accept a report only when the reporter's process descends from the pane's process. Or give background sessions no pane binding at all.

Questions

1. Is "agent forked into the background" the right event for opening a tab, or would a generic "agent spawned a background session" fit better?
2. Should the new tab sit next to the source tab and stay unfocused by default?
3. For Claude SessionStart fork reports are rejected: agent.list keeps a stale session id forever #5557 and this case: is a process-ancestry check the right way to tell "agent in this pane" from "background session that inherited the pane's environment"?