The problem
Agents don't reliably use dispatch_pin. When one spins up a dev server, opens a PR, makes a call on the architecture, or gets blocked on a question, that information often never makes it into a pin, so it doesn't show up in the sidebar where the user can grab it. Meanwhile dispatch_event (the moment-to-moment status) gets reported consistently. We'd like pinning to become just as natural a habit.
One clarification up front so this doesn't get muddled: pins and events aren't the same thing. Events are the running status log, basically "here's what I'm doing right now." Pins are the small handful of durable things a user wants to find or copy later, like a dev URL or a PR link. This issue is only about pins. It is not about logging events through pins.
Why events stick and pins don't
It comes down to how the two tools are described to the agent. dispatch_event is spelled out as mandatory, with specific moments it has to fire, in three separate places, and it even has a safety net. dispatch_pin is described as a nice-to-have everywhere, with nothing behind it.
| Lever |
dispatch_event |
dispatch_pin |
Launch system prompt (apps/server/src/agents/tmux/command-builder.ts, buildLaunchGuidance()) |
Rule 3: "Emit working at turn start... a terminal event before your final response." Tied to specific moments. |
Rule 4: "Pin key info... good things to pin: URLs, ports...". Just a list, no trigger. |
CLAUDE.md / AGENTS.md |
"CRITICAL ... Mandatory", numbered checkpoints, "Hard requirements" |
one short feature description |
| MCP tool description |
"Must be called at the start of each turn... before the final response" (shared/mcp/agent-lifecycle-tools.ts) |
"Good things to pin:", purely advisory (shared/mcp/server.ts) |
| Backstop |
activity monitor auto-corrects status drift (agents/activity-monitor.ts) |
none |
The real reason is simpler than the table makes it look. "Emit working at the start of your turn" works because it's tied to a moment. "Pin anything interesting as you go" doesn't, because the agent has to decide on its own what counts and when, every single turn, and it forgets. Models are good at "when X happens, do Y" and bad at "please remember to do Y."
What would help
I'd approach this in layers, cheapest first.
Layer 1: tie pinning to specific moments. This is the big one, and it's just wording. In buildLaunchGuidance() (Rule 4), the Pins section of CLAUDE.md and AGENTS.md, and the dispatch_pin description, swap the "good things to pin" list for actual triggers:
- started a dev server, pin the URL or port
- opened a PR or created a branch, pin the link or name
- landed on an architecture decision or a key finding, pin it (
string or markdown)
- went into
waiting_user, pin the question you're blocked on
Layer 2: lean on the habit agents already have. They report events reliably, so hang the pin reminders off those same moments. On done, check that the important artifacts (PR, URLs, decisions) are pinned. On waiting_user, pin the question. The event still says what state you're in, and the pin is what makes the artifact stick around. They do different jobs, they don't replace each other.
Layer 3 (optional, only if 1 and 2 aren't enough): a small safety net. The pieces for this already exist. There's the activity monitor (agents/activity-monitor.ts), a lifecycle-hook framework that's built to take more hooks but only wires stop today (agents/lifecycle-hooks.ts), and the mid-session tmux injection already used for persona review round-trips (server/agent-prompts.ts, injectAgentPrompt). The idea would be to notice when an agent hits waiting_user with no question pinned, or finishes with a dev server running but no URL pinned, and drop in a one-line nudge. I'd stay away from timer-based or blanket nudges, and from any hard "you must pin N things" rule, since both just produce junk pins.
My suggestion is to do Layers 1 and 2 first. They're pure wording changes, easy to reverse, and they probably close most of the gap. Only reach for Layer 3 if pinning is still spotty afterward.
Still to decide
- Job agents don't get any pin guidance right now (Rule 4 is skipped for them in
buildLaunchGuidance()). Should they pin too?
- The brain memory tools aren't mentioned anywhere, and their descriptions are purely mechanical (for example
brain_store_object only explains expectedRevision). If we want those used consistently, they'd need the Layer 1 treatment at a minimum.
Filed from a Dispatch agent session. File references are under apps/server/src.
The problem
Agents don't reliably use
dispatch_pin. When one spins up a dev server, opens a PR, makes a call on the architecture, or gets blocked on a question, that information often never makes it into a pin, so it doesn't show up in the sidebar where the user can grab it. Meanwhiledispatch_event(the moment-to-moment status) gets reported consistently. We'd like pinning to become just as natural a habit.One clarification up front so this doesn't get muddled: pins and events aren't the same thing. Events are the running status log, basically "here's what I'm doing right now." Pins are the small handful of durable things a user wants to find or copy later, like a dev URL or a PR link. This issue is only about pins. It is not about logging events through pins.
Why events stick and pins don't
It comes down to how the two tools are described to the agent.
dispatch_eventis spelled out as mandatory, with specific moments it has to fire, in three separate places, and it even has a safety net.dispatch_pinis described as a nice-to-have everywhere, with nothing behind it.dispatch_eventdispatch_pinapps/server/src/agents/tmux/command-builder.ts,buildLaunchGuidance())workingat turn start... a terminal event before your final response." Tied to specific moments.CLAUDE.md/AGENTS.mdshared/mcp/agent-lifecycle-tools.ts)shared/mcp/server.ts)agents/activity-monitor.ts)The real reason is simpler than the table makes it look. "Emit
workingat the start of your turn" works because it's tied to a moment. "Pin anything interesting as you go" doesn't, because the agent has to decide on its own what counts and when, every single turn, and it forgets. Models are good at "when X happens, do Y" and bad at "please remember to do Y."What would help
I'd approach this in layers, cheapest first.
Layer 1: tie pinning to specific moments. This is the big one, and it's just wording. In
buildLaunchGuidance()(Rule 4), the Pins section ofCLAUDE.mdandAGENTS.md, and thedispatch_pindescription, swap the "good things to pin" list for actual triggers:stringormarkdown)waiting_user, pin the question you're blocked onLayer 2: lean on the habit agents already have. They report events reliably, so hang the pin reminders off those same moments. On
done, check that the important artifacts (PR, URLs, decisions) are pinned. Onwaiting_user, pin the question. The event still says what state you're in, and the pin is what makes the artifact stick around. They do different jobs, they don't replace each other.Layer 3 (optional, only if 1 and 2 aren't enough): a small safety net. The pieces for this already exist. There's the activity monitor (
agents/activity-monitor.ts), a lifecycle-hook framework that's built to take more hooks but only wiresstoptoday (agents/lifecycle-hooks.ts), and the mid-session tmux injection already used for persona review round-trips (server/agent-prompts.ts,injectAgentPrompt). The idea would be to notice when an agent hitswaiting_userwith no question pinned, or finishes with a dev server running but no URL pinned, and drop in a one-line nudge. I'd stay away from timer-based or blanket nudges, and from any hard "you must pin N things" rule, since both just produce junk pins.My suggestion is to do Layers 1 and 2 first. They're pure wording changes, easy to reverse, and they probably close most of the gap. Only reach for Layer 3 if pinning is still spotty afterward.
Still to decide
buildLaunchGuidance()). Should they pin too?brain_store_objectonly explainsexpectedRevision). If we want those used consistently, they'd need the Layer 1 treatment at a minimum.Filed from a Dispatch agent session. File references are under
apps/server/src.