agent-handoff

/agent-handoff - Cross-Host Agent Contact (T-1429 wrapper)

Wraps termlink agent contact so vendored Claude Code agents can hand off context to a peer agent in one command. Replaces the legacy remote push

• inbox.push improv pattern (T-1166 retired).

Invocation: /agent-handoff <target> <task-id> "<message>"

• <target> — the peer agent's display_name, resolvable via local termlink session.discover (e.g., framework-agent, oss-dash).
• <task-id> — the active task this handoff belongs to (e.g., T-1429). Must exist under .tasks/active/. Embedded as a [T-XXX] prefix in the message body so the receiver can route by thread.
• <message> — the handoff summary in plain text. Quote it.

Protocol canon is documented on the topic itself — run termlink channel info agent-chat-arc to see the 5 invariants in-place (T-1430).

Step 1: Verify the task exists

Run:

ls .tasks/active/<task-id>-*.md 2>/dev/null

If no match, stop. Print:

agent-handoff: task <task-id> not found in .tasks/active/.
Create it first: fw work-on "topic" --type build

Exit non-zero. Do NOT post to a non-existent task.

Step 2: Capture self identity (for log visibility)

Run:

termlink whoami --json 2>/dev/null

If single candidate: capture sender_id. If multi-candidate (multiple sessions on this hub): prefer the one whose cwd matches $(pwd). If still ambiguous, fall back to the first candidate and note the ambiguity in the Update entry. If whoami fails: continue with sender_id=unknown — identity binding is enforced server-side once T-1427 ships, not here.

Step 3: Post to the peer

Run:

termlink agent contact "<target>" --message "[<task-id>] <message>" --json

Capture stdout. The actual JSON shape (T-1429 Phase-1, verified live 2026-05-01):

{
  "delivered": { "offset": <integer>, "ts": <ms-since-epoch> }
}

If exit code is non-zero or delivered is missing: stop. Print the verb's stderr and exit non-zero. The verb already prints actionable errors (peer offline, missing identity_fingerprint, etc.) — do not swallow them.