The Agent Integration Layer, September 2026
What pi, Herdr and iTerm2 each decided to wrap
Table of Contents
- 1. The snapshot
- 2. Three products, three different things wrapped
- 3. The hook surface is the integration point
- 4. Per-agent messaging
- 5. Session status, and what each consumer wants from it
- 6. OpenTelemetry, and what belongs elsewhere
- 7. What none of them persists
- 8. Addendum, 2026-10-02: Pi 1.0
- 9. Related
1. The snapshot
| Component | Version | Read on |
|---|---|---|
| pi | 0.87.1 | 2026-09-26 |
| Herdr | 0.9.1 | 2026-09-26 |
| iTerm2 | 3.7.2 | 2026-09-26 |
| Claude Code | 2.1.283 | 2026-09-26 |
2. Three products, three different things wrapped
Each wraps a different layer, and only one of them wraps an agent.
2.1. pi wraps providers
Third-party sources (pi coding-agent reviews and cheatsheets indexed October 2026) corroborate the built-in tool set as read/bash/edit/write/grep/find/ls, with powershell as the Windows substitute for bash -- consistent with this note's eight-item --help dump. pi.dev's own marketing page confirms it is a self-described "agent harness" and names "15+ providers, hundreds of models" as its multi-provider pitch, supporting the "pi wraps providers" framing, though the specific "roughly forty API-key environment variables" and "three regional token plans for Xiaomi MiMo" figures were read directly off the local --help output on this machine and were not independently re-run here.
pi is an agent, not a wrapper around one — it holds the model, the tools, the system prompt and the session. It is a peer of Claude Code. What it abstracts is the provider: its help lists roughly forty API-key environment variables, from Anthropic and OpenAI through to three separate regional token plans for Xiaomi MiMo.
Its built-in tool set:
read bash powershell edit write grep find ls
Files on disk and the stdout of one command. No debugger, no REPL, no persistent instrument, in a release shipped in September 2026.
2.2. Herdr wraps agents
The quoted tagline "terminal workspace manager for AI coding agents" matches Herdr's GitHub repository description verbatim (checked via web search of third-party guides quoting the same README text), and workspace/tab/pane/agent hierarchy plus "herdr worktree create" and a CLI+socket API are independently corroborated across multiple October-2026 third-party write-ups. Herdr's own marketing homepage, fetched directly on 2026-10-08, now reads "the agent runtime" / "the runtime coding agents run on" and surfaces different example subcommands (server, client, update, machine add) -- a live-site drift since this note's 2026-09-26 observation, not a correction of it; the exact =herdr agent=/=herdr pane=/=herdr workspace= subcommand names were not independently re-run against the CLI's own --help here.
Herdr describes itself as a "terminal workspace manager for AI coding
agents". Panes, tabs, git worktrees, named persistent sessions, saved SSH
machines, and a socket API with herdr agent, herdr pane, herdr worktree
and herdr workspace subcommands. It is a peer of tmux that knows what an
agent is. This is the only one of the three that is a wrapper in the ordinary
sense.
It also ships herdr --skill, which prints an agent skill file describing how
to drive it — the workspace manager supplying its own operating instructions
to whatever agent is running inside it.
2.3. iTerm2 instruments the agent
Direct fetch of the primary source, =iterm2.com/claude-code-integration.html=, on 2026-10-08 confirms every specific claim: session state reported into iTerm2's Session Status tool as working/waiting/idle, a Claude Code Workgroup of three linked sessions (Chat, Diff, Code Review), the mechanism as hooks written into =~/.claude/settings.json= plus iTerm2's Python API, and a near-exact match for the quoted installer behavior -- the page states Claude Code "occasionally rewrites =~/.claude/settings.json= and can drop the cc-status hook," and iTerm2 "notices the next time Claude runs and offers to reinstall the hook."
The iTerm2 Claude Code integration runs the other direction: the terminal emulator reaches into the agent. It reports each session's state (working, waiting, idle) into iTerm2's Session Status tool, and installs a Workgroup of three linked sessions — chat, a working-tree diff, and a code review pane.
The mechanism is hooks written into ~/.claude/settings.json, plus iTerm2's
Python API.
3. The hook surface is the integration point
Checked the 30-name list against Claude Code's current (2026-10-08) official hooks reference (code.claude.com/docs/en/hooks), which now documents 33 distinct hook events -- the same 30 named here plus DirectoryAdded, PreModelSwitch, and PostModelSwitch. Those three are absent from this note's list, consistent with them having been added to the hook surface after 2026-09-26 rather than the note's count being wrong at the time; this corroborates the note's own framing of itself as a dated snapshot rather than a stable count.
Claude Code 2.1.283 exposes thirty hook events:
ConfigChange CwdChanged Elicitation ElicitationResult FileChanged InstructionsLoaded MessageDisplay Notification PermissionDenied PermissionRequest PostCompact PostToolBatch PostToolUse PostToolUseFailure PreCompact PreToolUse SessionEnd SessionStart Setup Stop StopFailure SubagentStart SubagentStop TaskCompleted TaskCreated TeammateIdle UserPromptExpansion UserPromptSubmit WorktreeCreate WorktreeRemove
On this machine three independent systems are subscribed to that surface, and they overlap:
| Event | Consumers |
|---|---|
| PostToolUse | crowsnest, aq, iTerm2 |
| PreToolUse | crowsnest, iTerm2 |
| Notification | crowsnest, iTerm2 |
| PermissionRequest | crowsnest, iTerm2 |
| SessionStart/End | crowsnest, iTerm2 |
| Stop | crowsnest, iTerm2 |
| the other 23 | crowsnest |
Three consumers, one config file, no coordination between them. The vendor documentation acknowledges the consequence: iTerm2's installer "detects when Claude rewrites settings and breaks the hook, offering automatic reinstallation". That is a repair loop for a contended resource, shipped as a feature, which is the honest response to a config file with no ownership model. Nothing arbitrates between the three; they coexist because appending happens to work.
4. Per-agent messaging
Shared REPL as Gossip Protocol covers the transport question. What is running
here now is aq, an "ambient agent queue (gossip layer for multi-agent
development)":
| Verb | Meaning |
|---|---|
announce / whisper |
broadcast presence, TTL 300s / 60s |
check |
check for conflicts with active broadcasts |
status |
list active broadcasts |
listen |
subscribe to transports, materialize incoming |
validate |
invariant checks, advisory, never blocks |
The design choice is in the last row and in the TTLs. It is gossip, not locks — two agents editing the same file is a thing you find out about, not a thing you are prevented from doing. That is the right trade for a fleet where the cost of a false block exceeds the cost of a rare collision, and the wrong one where it does not. The TTL is the whole safety argument: a claim that outlives the work it describes is worse than no claim.
It hangs off PostToolUse with an Edit|Write matcher, which means the
announcement is made after the edit lands. The protocol tells you a collision
happened; it cannot tell you one is about to.
5. Session status, and what each consumer wants from it
The three consumers read the same events for different purposes:
- iTerm2 wants a state machine with three values — working, waiting, idle — rendered in a status bar. Latency is what it needs; history is irrelevant to it.
- aq wants the file path being touched and a claim string. It needs identity, not timing.
- crowsnest wants a trace.
The crowsnest hook is the one that extracts the most from the same payload. Its own comment records the method:
Models the hook control flow FROM THE PAYLOAD (not docs). Claude Code gives a real call graph: session_id ⊃ turn_id ⊃ tool_use_id (Pre/Post share it) + duration_ms (real tool time).
That is a span tree recovered from a hook stream — session contains turn
contains tool call, with PreToolUse and PostToolUse sharing a
tool_use_id so a call's start and end can be joined, and a real
duration_ms rather than an inferred one. It maps onto a sighting with
service as a per-session trace lane, run as the correlation group, and
after as the causal link.
The first is that the hook surface was
evidently not designed as a tracing API, and turned out to be one — the
tool_use_id shared across Pre and Post is what makes the join possible, and
that is a correlation identifier whether or not it was meant as one. The
second is the parenthetical: from the payload, not docs. The schema was
derived by observing traffic rather than by reading a specification, which is
the only method that survives a vendor changing the payload without changing
the documentation.
6. OpenTelemetry, and what belongs elsewhere
The trace shape above is OTel-shaped without being OTel: spans, a parent relation, durations, a correlation group. Converting it is a mapping exercise, not a redesign, and the collector is already running — nexus exposes OTLP on 4317 (gRPC) and 4318 (HTTP).
Agent Telemetry Systems covers token spend, model routing and cost, and that is a different question from this one. This note is about plumbing — what emits, what subscribes, what correlates — and the telemetry note is about economics — what the traffic costs and how to route it more cheaply. They share a transport and almost nothing else. Folding them together would make both worse, because the plumbing question is answered by reading a payload and the economics question is answered by reading an invoice.
7. What none of them persists
| Product | Persists | Does not persist |
|---|---|---|
| pi | the transcript — sessions, forks, resume, export | the program under test |
| Herdr | the terminal — panes, tabs, worktrees, SSH | the program under test |
| iTerm2 | the view — status, diff, review pane | the program under test |
pi is strikingly stateful about conversation: --continue, --resume,
--session, --session-id, --fork, --session-dir, --export to HTML. So
persistence did arrive. It arrived for what the agent said, for the terminal
it said it in, and for the human's view of both — and not for the running
system the agent is reasoning about. Three 2026 products, three different
answers to "what should survive between turns", and not one of them keeps a
debugger attached or a REPL warm.
The integration layer is being built quickly and in the open; the question worth re-asking in a quarter is whether anything in it has started persisting the program rather than the conversation about it.
8. Addendum, 2026-10-02: Pi 1.0
The snapshot above stands as written, for 0.87.1. Six days later Earendil
shipped Pi 1.0 (announced 2026-10-01). This box was updated from 0.87.1 to
1.0.0 with pi update --self on 2026-10-02.
What the announcement lists as added:
- Codemode: native support for MCP, and for non-LLM models (it names Jev and image models)
- Extension support for virtual models
- Deferred tool loading
- Cache warming for Anthropic models
- Mid-conversation system messages
- A new TUI theme, and full-screen mode by default
Alongside it, an experimental package, Pi Durable, described as "a new substrate for building long-running agentic applications". Both are MIT licensed; code is at earendil-works/pi.
What can be confirmed from the 1.0.0 binary's own help on this machine:
- A new
pi mcpsubcommand:add,remove,list,login,logout. It reads~/.pi/agent/mcp.jsonand, in trusted projects,.pi/mcp.json. --tui-mode, withfullscreenas the stated default.- The built-in tool list is unchanged: the same eight names as in the snapshot
(
read,bash,powershell,edit,write,grep,find,ls). What 1.0 adds arrives through MCP and extensions, not as new built-ins.
"pi wraps providers" now undersells it: with MCP in the agent, pi wraps tool servers as well. The closing question, whether anything in this layer has started persisting the program rather than the conversation about it, now has a named candidate in Pi Durable. That is the announcement's claim; it has not been tried here.
Not checked: codemode in use, deferred tool loading, cache warming, virtual models, and anything about Pi Durable. The comparison rows for Herdr and iTerm2 above were not re-read.
9. Related
- CLI Coding Agents: 2026 Q2 Comparison — compares the agents themselves; this note covers the layer that grew around them two quarters later.
- Terminal AI Agents: The 2025 Landscape — the prior year's field.
- Shared REPL as Gossip Protocol — inter-agent transport, of which
aqis one implementation. - Agent Telemetry Systems — the cost side, deliberately separate.
- Claude Code Workshop (2026 Q2) — the hook surface as it stood earlier in the year.