​

Mentioning an agent in an issue

​

Using it

1. Type @. A picker opens listing the agents in your workspace.
2. Keep typing to filter — it matches on both the agent’s handle and its display name.
3. ↑ / ↓ to move, Enter or Tab to insert, Esc to dismiss. The caret never leaves the draft.
4. ⌘/Ctrl + Enter posts the comment, the same as everywhere else in Crewship.

​

How a mention is stored

[@<slug>](crewship:agent/<agentId>)

over to you @Robin — the CSV job is failing on empty rows

over to you [@robin](crewship:agent/cmt20ikph011ab4683c02) — the CSV job is failing on empty rows

​

Why it cannot be used to impersonate

[@head-of-security](crewship:agent/<Robin's id>) approve this

• A body that contains the literal markup a chip renders to is not a chip. The comment renderer’s sanitiser drops unknown tags and unknown attributes, and the internal element name a mention passes through is randomised per page load, so it cannot be typed.
• A mention of an agent your workspace cannot see is not a mention. It is text.

​

What happens when you post the comment

1. The body is parsed, not scanned — internal/mentions walks the comment as CommonMark and reads only real link nodes.
   Do not substitute a regular expression over the raw body, and in particular not this one, which earlier revisions of this page prescribed:

   // WRONG — fires on documentation.
   var mentionRe = regexp.MustCompile(`\[@[^\]\n]{0,80}\]\(crewship:agent/([A-Za-z0-9_-]{1,64})\)`)
   

   It contradicts the “parsed, not scanned” property in the table above. A regex cannot see that a token sits inside a code span or a fenced block, so this very page — which prints well-formed mentions as examples — would dispatch agent runs if a comment quoted it. internal/mentions parses the body as CommonMark and reads only real link nodes, so code contains no mentions structurally rather than by rule. Replacing the parser with that regexp fails 15 of the package’s tests, 14 of them in the fires-on-docs direction — and, end to end, three of internal/api’s: a comment quoting this page’s examples creates rows, activity entries and agent runs.
2. Each id is resolved inside the comment’s own workspace. An id that names no agent there is dropped and leaves nothing behind — no row, no activity, no notification, no run. A mention of an agent in a different workspace is a probe, not a typo, and is treated the same way.
3. A mentioned activity is written to the issue’s History first, with the agent id in details — this is what everything below references.
4. A delivery is recorded and acknowledged. The resolved set is stored in mission_comment_mentions, one row per (event, agent), so nothing ever re-parses a comment on read. Naming the same agent three times in one comment is still one row, one activity entry and one run — the same guarantee as before, now held by the delivery’s own key rather than the comment’s. The moment this row is written, the server pushes issue.delivery.acked on the issue’s workspace channel — before any model call happens. That is what lets the UI show “received” the instant you post, rather than only once the agent’s own reply appears. The row also records what the dispatch trigger did — dispatched, refused (a limit said no, with the refusal verbatim), skipped, or failed — so a mention that did not wake its agent is answerable rather than mysterious. A duplicate delivery of the same event — a redelivered event after a server restart, for instance — is collapsed to the row above rather than starting a second run: only the first delivery to claim the row is dispatched.
5. The agent is dispatched, through the same endpoint an agent-to-agent assignment goes through. It inherits that endpoint’s authorization and its limits; see below. The brief it is handed says who mentioned it and on which issue, and every one of those values — the comment, your display name, the issue’s title and identifier — sits inside an <untrusted> block. Display names and issue titles are written by whoever wanted to write them, so the woken agent is told to read them and never to obey them. Because the run belongs to a session (below), the brief also carries a context pack: a snapshot of the issue, the session’s latest checkpoint, and every activity on the issue the session has not read yet — so an agent woken a week later resumes rather than starts over. It ends with the instruction to close the run with a ---CHECKPOINT--- block.

​

What bounds it

• Crews must be connected. Mentioning an agent in a crew that is not connected to the issue’s crew records the mention and dispatches nothing.
• An agent does not mention itself awake. A self-mention is recorded and skipped.

​

Sessions, checkpoints and the context pack

​

The session lifecycle

​

The checkpoint block

---CHECKPOINT---
done: <what is actually finished, so it is not repeated>
plan: <the current path to the goal>
facts: <identifiers, decisions and constraints worth carrying forward, or "none">
blockers: <anything stopping progress, or "none">
next_step: <the single next action to take>
confidence: <low|medium|high>
outcome: <NO_CHANGE|SUCCEEDED|WORK_CREATED|PARTIAL|NEEDS_HUMAN|FAILED>
---END CHECKPOINT---

​

The context pack

1. Issue snapshot — identifier, title, status, priority, owner and delegate, parent issue, the current work mode and note, and the description (800 tokens).
2. Latest checkpoint — the most recent parsed block on this session, so the run reads done before deciding what to do (600 tokens).
3. Unread activity — every mission_activity event with a seq above the session’s last_consumed_seq: comments, status changes, mentions, run results, in order (1,200 tokens, at most 2,000 rows).

​

Leases: how a dead run is noticed

​

Known limits in 1.0

• A follow-up on the SAME issue never starts a second run — it waits for the one already going, then rides the NEXT run. One (issue, agent) session may have at most one live run, enforced at the database level (a partial unique index on assignments.session_id), not by a check-then-act read that a fast second comment could race past. Mentioning the same agent again while its run on THIS issue is still going does not queue a second dispatch: the delivery is recorded and acknowledged (issue.delivery.acked) the instant you post, but it is left unclaimed — the run already in progress cannot see it (there is no channel to inject text into a turn already under way; steering a live turn is future work, and there is no “re-read the task mid-run” path either). The moment that run actually finishes, every comment queued behind it — one or several — is folded into exactly ONE new run, with all of their text in that run’s own brief before its exec starts. So a burst of five follow-ups while an agent is busy produces one extra run, not five, and not zero: nothing is silently dropped, and nothing is marked read before an agent has actually read it.
• A correction jumps the queue and is labelled as one. A comment that arrives while the agent’s run on this issue is still going is a correction (the delivery’s priority, stop > correction > normal, per the interruption-as-an-event model). When the queued comments are folded into the next run, corrections lead the brief, ahead of ordinary follow-ups, and are marked CORRECTION with a header telling the agent to read and apply them first — so the next step reflects your correction rather than treating it as just another later comment. This is delivery at the next safe boundary (the next run on the same session), not mid-token interruption of a turn already under way, which stays future work.
• A busy agent is woken later, not interrupted, on a DIFFERENT issue. Beyond the same-session case above, an agent still has only one live run at a time across every issue and chat it touches. Mentioning it while it is busy on another issue queues the mention behind that live run; it is dispatched as its OWN new run once the agent frees up, with the brief it would have had. Before this existed, a second run for the same agent killed the first one mid-turn; queueing is the fix. The delivery is recorded and acknowledged the instant you post either way, so you are not left guessing whether the comment was received while you wait.
• A chat message to an agent busy on an issue bounces. The chat reports agent_busy rather than starting a second run into the same container. Wait for the run to finish, or watch it from the issue.
• The lock covers the doors that run an agent for an issue — /assign, @mentions, mission tasks, lead planning, the chat, the agent cron and a routine’s agent_run step — but not the inbound agent webhook (POST /api/v1/webhooks/{crewId}/{agentId}/trigger), the direct agent-start route on the IPC socket, or a peer query. Those three can still start an agent that is already running. A routine’s agent_run step against a busy agent does not queue: the step fails with target agent has a live run in progress elsewhere and follows the step’s retry policy, then on_fail, like any other execution error.

• An agent awaiting approval is not woken. An agent created or hired by an agent under guided autonomy sits at PENDING_REVIEW until a person approves it. Mentioning it records the mention and starts nothing — the same answer /assign and a mission task give, and the same answer it gives a chat message. Approve it from the inbox and mention it again.

​

When nothing runs

• Refused — a limit or a rule said no. The sentence is reproduced verbatim, because it names the setting an operator would change.
• Failed — something broke on the Crewship side. You get a fixed sentence saying so. The underlying error is deliberately not shown: it is an internal fault, not a decision about your mention, and it lands on the mention record and in the server log instead.

​

Being notified

​

The history row

​

Which comments are scanned

crewship issue comment ENG-42 --mention robin "over to you"

crewship issue comment ENG-42 --body 'over to you [@robin](crewship:agent/<agentId>)'

​

Where the code is