Starting a session from a Help Desk ticket
Two ways a Help Desk ticket becomes a Claude Code session: you start one from the open ticket, and a newly arrived ticket starts an investigation by itself. Neither one writes to the ticket or reaches the customer, unless you choose One agent per ticket, where a ticket's own agent may answer on that ticket.
What it is
A support ticket is read and answered by a person, and some tickets describe a real defect — something you want an agent on, in the repo, with a worktree and the app's own rules. Retyping a customer's report into a blank session is the slow, lossy way to do that. These are the two doors that skip the retyping.
- The one you press. Start session is an item in the open ticket's More options (⋯) menu, in its header.
- The one that starts itself. A ticket that newly arrives in the waiting queue gets ONE investigation of its own.
They share one prompt builder and one dialog, so a session started by either door opens on the same picture of the ticket.
Where to find it
- In the developer console — the full-screen Help Desk console draws the control in its top strip, on the row with the ticket's identity and Mark resolved.
- In the small widget and on a phone — the same control sits in the ticket's Back row, so it is reachable without expanding to full screen.
- The automatic half has no surface. It starts on arrival, puts a normal session on your board, and appears under Fix sessions with the other intake work. It is switched in Settings → Features as
helpdeskTicketInvestigationEnabled, and it ships on.
Choosing who handles new tickets
One switch, Who handles new tickets in Bug Intake → Intake settings (setting helpdeskTicketRouting), decides what happens when a ticket arrives. It is read fresh for every ticket, so a change applies to the next one with no restart, and an agent can flip it for you over the command line.
- Help Desk crew (the default) — the investigation joins the Help Desk crew, and its overseer runs it. This is how it always worked. A ticket agent joining the crew does not use up one of the crew lead's places, in this mode or in the mission group below: the desk already limits how many tickets can start in a day, so counting them against a lead's limit counted the same tickets twice and parked ready tickets as waiting for a seat.
- One agent per ticket — one independent session per ticket, with no crew push. Its intake source can still place it in the Help Desk crew (an in-app report always does), and that never closes its reply road. Its finished turn comes to your inbox, and it may answer the customer itself on its own ticket only (below).
- A person — no agent starts. The ticket waits in the Help Desk console with its incoming alert for someone to pick it up, and no crew is pinged.
Beside it, Where ticket agents run (helpdeskTicketAgentLocation) is Cloud first (a cloud machine when one is free, otherwise this computer) or This computer, and Investigation engine picks the AI. Agent replies wait for my approval (requireApprovalForCliHelpdeskReply) decides whether a ticket agent's reply waits for your one click or goes straight to the customer — and that switch is the only thing that decides it: a ticket's own agent answering on its own ticket is not held back by the rule that makes an agent reading outside content wait for your card, and it never lands in your inbox.
The switch covers tickets in the Help Desk inbox. Emailed bug reports, GitHub issues and your own in-app reports keep their crew for now.
A ticket agent can join a mission group
An agent can report into one of your missions instead of your inbox. Set helpdeskTicketGroupId to the id of a live group (the Missions screen shows it) and every new ticket agent is attached to that group's leader before its first turn: its finished turn and any question it asks reach the overseer, it opens with the group's name and where it stands, and it is told not to archive itself. The group is looked up fresh for every ticket, so replacing the overseer needs no change here.
Leave it empty (the default) and ticket agents behave exactly as before. This applies to One agent per ticket; a ticket handled by a crew joins that crew and is never put in a mission group. An id that names no live group, or a group that has ended, still starts the ticket as usual and says why in the log.
A ticket agent does not use up one of that group's places. Every lead has a limit on how many sessions report directly to it (five unless you raise it), and ticket agents are not counted against it: the desk already limits how many can start in a day, and each one has its own claim on its ticket, so counting them again would count the same tickets twice. That keeps the overseer's places free for the helpers it starts itself, and it means a busy day of tickets never pushes a ticket out of the group. Everything else you or the overseer starts still counts.
How a ticket's own agent answers the customer
In One agent per ticket mode the agent is told the one road it may use: POST /helpdesk/tickets/<ticket id>/agent-reply with its own session token and a { "text": "…" } body. The app checks the caller is the session the ticket was started for and that routing is still One agent per ticket; anything else is refused. Being in a crew does not close the road — an in-app report's agent is in the Help Desk crew by default, and the card it owns is what decides. Only text goes out, through the same checks as a console reply (no folder paths, no dates, no status-only notes). In every other mode a ticket agent cannot reach the customer at all, and the no-contact lock does not depend on a Help Desk crew existing.
A cloud-placed agent can use this road once the app has been rebuilt after the change; until then its reply is refused and its finished turn still reaches you.
The first reply comes first
In One agent per ticket mode the agent is told to send one short acknowledgement to the reporter before it reads any code — two or three sentences saying the report has landed and is being looked into, with no date or deadline in it. That is the one exception to the desk rule that an agent sends only one reply per real update, and it is not sent at all when the ticket is about money, account access, privacy, a security report or an upset customer: those still go to a person.
Every ticket gets that receipt, whatever kind it is: a bug report, a feature request, a question or feedback. The receipt is not the answer — a feature request still waits for your go-ahead before any work starts — it only tells the reporter their report arrived.
If a ticket is close to its reply promise and the reporter has still heard nothing, the desk pings the ticket's own agent once, about fifteen minutes before the promise lapses, with a reminder and the exact command that answers the ticket. A ping is never repeated for the same reporter message, it is skipped when the agent has already answered or the desk has already sent its own receipt, and if it cannot be delivered it is retried on the next sweep rather than counted as sent. The desk now reads the conversation itself before pinging: if the reporter already has a reply from us, it records that as the acknowledgement instead of sending a ping that would claim otherwise.
The customer handbook
Every ticket agent starts with the same written guide to working a ticket and talking to customers — see helpdesk-customer-handbook.md.
How it behaves
You press Start session
- The shared start-session dialog opens with a Message box for your own instruction and, folded under details, the ticket's subject, who opened it, how it arrived, and the conversation so far, oldest first. You can edit the details before you start.
- The session's first message is your instruction, then an About this item note the app adds (the ticket's id and the commands for reading and working with it), then the ticket text. See Starting a session from an item.
- A long ticket is capped and says so — you get the newest messages and an
(earlier messages omitted)marker, never a wall of text and never an empty prompt. - Confirming starts a real Claude Code session and does nothing else to the customer: no reply, no note, no notice. The control is inert until you confirm. It DOES record the session on the ticket, so you can get back to it.
- The way back is on the ticket. Once a ticket has a session working it — the one you started, or the one the app started by itself — the ticket's More options menu offers Open session, which jumps straight to it. The Help Desk board shows the same link, because both read the same card.
A ticket arrives by itself
- The investigation reads the ticket and reports what it found and what it recommends. For a feature request, a question or feedback it then waits for you; for a bug report it carries the fix through the dev pipeline, which stops at its plan gate where your own rules decide. That is its brief, the same one the email-ticket lane's investigations get.
- One per ticket, ever. The claim is written before the session is created, so a redelivery, a restart replaying the queue, or a follow-up on the same ticket can never buy a second one.
- A daily ceiling bounds how many start (fifty a day), and each skip is named in the log — the ceiling, an already-claimed ticket, no claimable card, or no target project.
- A ticket over the ceiling is QUEUED, never forgotten. It is parked on its own ticket card, so closing and reopening Omniscio does not lose it; the app picks the OLDEST queued ticket and starts it when the day's allowance frees, one at a time, about every poll tick. It is visible either way:
npm run helpdesk:queuelists it as its investigation is queued and starts by itself, and the limit itself never moves. A ticket you answer or resolve before its turn simply leaves the queue — it is never investigated behind your back. - A ticket whose automatic investigation could not start says so. It keeps its place through a brief fault — the safety screen being unreachable, or a spawn that throws — for a bounded run of five consecutive attempts, and only then leaves the queue; a ticket the screen actually JUDGED (it flagged the report, or the report was too long or had a file it could not read) leaves at once. A ticket that leaves appears on
npm run helpdesk:queuemarked its automatic investigation could not start, so it needs a hand start, so a real failure never sits in front of the ones behind it and one brief fault never fails every waiting reporter. The same is true of a ticket that has just ARRIVED and whose investigation could not start: it is parked on its ticket card on the spot, so the retry above and the waiting card below both reach it, instead of the arrival being the one path where a brief fault was final. A ticket this computer could not even find a project or a session slot for is parked the same way while the automatic investigation is switched on. A parked card leaves that list as soon as its own ticket has been handled — the desk answered it (an answered stamp, or a reply a person sent), or an open crew task owns it — because a hand start is no longer what the reporter is waiting on. The card is never rewritten, so a ticket that is not actually answered (an automatic receipt does not count) stays listed, and one whose only claim on it is an open crew task comes back the moment that task closes; an answered stamp and a sent reply are permanent, so an answered ticket stays off this list even if it reopens. - A ticket whose session was deleted before its launch says so, in its own words. If the session row the launch was about to use is gone by the time it reads the row back, the card is parked under its own reason and never retried — a retry would buy a fresh session, and a fresh machine, for a session the operator had already removed. It appears on
npm run helpdesk:queuemarked its session was deleted before its investigation could start, so it needs a hand start, so the cause is readable instead of hiding behind the shared could-not-start phrase. - A ticket whose investigation could not start is not lost. The claim is handed back when the start fails, and a start that was interrupted is released the next time the app starts, so the ticket stays startable.
- One switch turns it off without touching the button you press by hand.
Inside the session
A session started from a ticket does not look like an ordinary session. Its icon in the title row is a headset, coloured by how the session is doing. Right under the title it has a Help Desk row, the same height as the title row and the crew row, and it is the same on a phone:
- Left — the Agent | Ticket switch. Agent shows the agent's conversation; Ticket swaps the panel to the customer's conversation, read-only. On a phone the two buttons show icons only. Your message box to the agent stays where it is.
- Middle — who sent it. The customer's name, in full. The ticket's subject is the session title, and its status lives in the Help Desk console.
- Right — the actions. While the Ticket view is open, a Reply in Help Desk button sits here: replies are written in the console, with its drafts and checks. The three-dot menu's Open in Help Desk opens that same ticket in the console, and Copy ticket ID copies its id.
Who sent each reply
Every agent sends its replies through your computer, so the cloud labels them all with your account. The Ticket view and the console's conversation look each reply up in this computer's own record of what it sent, and label it:
- Agent · <session name> with a robot picture — an agent session sent it. Click the name to open that session. If the session record has been cleaned up, it reads plain Agent.
- Automatic reply — the desk sent it by itself: the receipt, a deadline notice, an autopilot note, or the note that a ticket was closed or reopened.
- You — you typed it in the console.
A reply this computer has no record of — sent from another computer, or older than 90 days — looks the same as before. The console's Sent replies list carries the same labels. A new block of messages, with its own name and time, starts whenever the sender changes or more than 5 minutes pass, so a reply hours later always shows when it was sent.
Looking at the ticket from a session never tells the customer you have seen it. The row refreshes when you come back to the session and when the customer writes again.
Only someone who can open the Help Desk console sees the subject, the customer and the messages. Anyone else sees no Help Desk row at all; the headset icon still marks the session. If the ticket cannot be read — offline, or the ticket is gone — the row says Ticket details unavailable and still offers Open in Help Desk. There is no keyboard shortcut for the Agent | Ticket switch; it sits on the row, and Ctrl+Shift+H opens Help Desk.
What neither door does
- It never writes a reply, a draft, a private note, or a status change to the ticket.
- It never notifies, messages or answers the customer. An investigation's findings go to you; nothing reaches the person who wrote in. The one exception is a ticket's own agent in One agent per ticket mode, through its own reply road (above).
- The control is never drawn on the customer's side of a conversation — it is gated on the console's own open-ticket state.
The investigation that starts itself is held to that twice
A brief is not a lock, and one investigation emailed a customer from a personal address. So the automatic door is now fenced in two places:
- Its prompt says so, in as many words. The investigation is told never to contact the reporter,
with the app's own send road named — no
/agent/email/send, no ticket reply, no mail of any kind — and told where its findings go instead. - The app refuses it anyway. While a ticket session is one that the app started for a Help Desk source, the two roads that put words in front of a customer — a hand-written email and the console's ticket reply — turn it away. The prompt is the half that holds before the attempt; this is the half that holds when the prompt is ignored.
It is not a dead end. The member the session reports to — its foreman, or the crew's lead — can admit it in one call, and the admittance takes effect on the very next send rather than at a restart. Anyone else is refused.
Two limits are worth knowing, because they are real rather than theoretical. The caller identifies
itself by a header that is a trace hint rather than a proof, so this stops the accident it was built
for rather than a determined forger. And sending mail straight from your own Gmail through the
gog command never touches this app's server at all, so no gate here can see it — on that road the
prompt rule is the only cover, which is exactly why it is there.
The session belongs to the crew that owns the ticket
An investigation started by the app belongs to the Help Desk crew, so its finished turn reaches
its crew rather than landing in your inbox as an open question. It is enrolled at birth, badged
Intake, and it reports to that crew's foreman — the one carrying the fewest reports among those
with room, falling back to the crew's lead. That matters: the lead sits at its four-report limit
almost always, and before this rule the fifth investigation of the day was turned away at enrolment
and started outside its crew, where the only place its turn could go was your Needs-You.
When the whole crew is full, the investigation does not start at all. There is no seat for it, so
starting one anyway would leave a session belonging to nobody — and that session's only destination
is your inbox. Instead the ticket waits: it stays on Get Help as an open ticket, it appears on
npm run helpdesk:queue marked its crew has no free seat for the investigation yet, and the crew's
own board gets one line saying so. The app re-checks on every poll, so the investigation starts by
itself the moment a seat frees — and a seat frees when a finished report is archived. Nothing is
dropped, and nothing lands on you.
Three lanes are not yet covered by that rule. A Sentry report, a GitHub issue, an in-app report,
and an emailed [BUG:] report still start their session even when the crew is full, and such a
session can still end up outside its crew. They are left as they are on purpose: their pipelines
cannot come back for a report they refused — an emailed one says so itself, "an email pipeline cannot
hold a message for later" — so refusing there would LOSE the report rather than defer it, which is
worse than the leak. Only the ticket lane, which retries, is protected today.
Related
The wider Help Desk story — the queue, its status tabs, drafts and routing rules — is on Get Help (Helpdesk) part 2. How a ticket arrives by email in the first place is on Help Desk email tickets, and the console the Start session control is drawn on is on Help Desk.
Last verified 2026-11-19