Task Graph and Projects Activity view
The Task Graph shows what each coding agent is doing, as a tree of tasks and steps per session. Open Task Graph from the console menu. Projects, Sessions and Mosaic rows also show each session's latest step and checklist progress. TUI, web and desktop use the same screens.
Control Room sessions (Control Room chats and their operator and task-pool
executions) are not part of the Task Graph. GET /v1/agent-tasks leaves them
out, so the Task Graph screen, Projects Activity tiles, session step rows, the
not reporting marker, unknown-step statistics and peer
get_project_task_graph results never show them. Their stored reports are
kept, and their MCP results and runtime guide carry no reporting guidance.
Where the data comes from
Two sources feed one session-scoped tree:
- Agent-reported tasks. Agents call the session MCP tool
report_agent_task(andlist_agent_tasksto recover task IDs). Every task has a UUID, an optional parent task fixed at creation, a step type, a status, optional progress (percent, orcompleted/total) and a reporter identity ({role:"main"}or{role:"subagent", id, name, type}). Creating a task needs only atitle, but agents should setstepTypefrom the closed list: devctl never infers it from the title, so an omitted step type is shown asunknownlabeled with the title's first words, and the one-sentencesummaryis optional. A short, redacted multi-linedetailcan carry the plan, findings or the reason a task is blocked. While a session's name is automatic and the agent has not calledset_session_title, the title of the main agent's latest open top-level task also becomes the session title (Session names). - Native steps from Claude Code hooks. The session's own lifecycle hook
records tool steps automatically. Shell commands are classified inside the
container: quotes, comments and heredoc bodies are respected, wrappers
(
sh -c,bash -lc,env,timeout,nohup,rtk/rtk proxy,npx,pnpm exec,uv run,docker exec,kubectl exec,ssh host 'β¦') are unwrapped, and the most specific command of a chain or pipeline wins. Only the category and a short label such aspnpm test,docker logsorssh psqlleave the container β never hosts, container names, SQL, URLs or arguments. Any other program is arunstep labeled with its executable. TodoWrite and Task checklists become per-agent checklist snapshots. - Subagents. A subagent row is titled with the Task/Agent call's
descriptionand badged with its type. Concurrent calls are matched to their SubagentStart by type, a start seen before its call is described when the call arrives, and the call's PostToolUse result (which names the subagent'sagentId) corrects any guess. The subagent's first sentence-like closing line (from SubagentStoplast_assistant_messageor the call's result), sanitized and capped at 160 characters, is shown under it as its outcome.
Each report_agent_task and list_agent_tasks result carries
nativeStepCapture and guidance. Sessions whose hooks reported events are
told to declare one top-level task per user request before their first tool
call (hooks see tool calls, never what the work is) and otherwise report only
phases, waits, blockers and completion;
sessions without native capture (agent CLIs without devctl hooks, or a session
whose hook never reported) are told to report every meaningful step when it
starts and ends. A declared task that repeats a hook step of the same agent
(same title within five minutes) replaces it, and a hook step that repeats
the agent's open declared task joins it, so a step appears once. The Task
Graph marks sessions without native capture as MCP reports only and lists
a running session that is not known to be idle and has reported nothing for
ten minutes as not reporting (an open native step, such as a long test
run, does not count as silence).
Step types and their one-line definitions (the same text is in the
report_agent_task stepType schema and the runtime guide):
| Type | Emoji | ASCII | Meaning |
|---|---|---|---|
plan |
π | pl |
decide the approach, break work into steps, update a checklist |
research |
π | rs |
read code, docs, logs or the web to understand something |
edit |
π | ed |
change source, config or content files |
install |
π₯ | in |
add, update or remove dependencies or tools |
build |
π§± | bd |
compile, bundle or build images |
run |
π | rn |
run a program or script that is not a test, build or lint |
test |
π§ͺ | ts |
run or write tests |
lint |
π§Ή | ln |
run linters, formatters or type checks |
debug |
π | dg |
reproduce and diagnose a failure |
review |
π | rv |
review code, a diff or a pull request |
git |
πΏ | gt |
commit, branch, merge, rebase or push |
deploy |
π | dp |
release, publish or deploy |
docs |
π | dc |
write or update documentation |
coordinate |
π€ | co |
delegate to or message subagents and other sessions |
wait_input |
π | wi |
wait for the user's answer or approval |
wait_external |
β³ | we |
wait for CI, a service, a timer or another process |
cleanup |
π§½ | cl |
remove temporary files, processes or resources |
configure |
π§ | cf |
change settings, permissions, network or environment configuration |
request |
π | rq |
ask the operator or Control Room for access, resources or approval |
other |
π¦ | ot |
a declared value devctl does not know |
unknown |
β | ?? |
no type declared; shown with its label |
Generic reads and runs refined by their shell label use π nw (network),
πΎ db (database) and π³ ct (containers). The table and its lookups are
stepCategoryEmoji, stepCategoryAscii, stepCategoryIcon(task),
stepCategoryGlyph(id) and stepGroupIcon(kind) in
apps/tui/src/step-category-icons.ts; every emoji has default emoji
presentation, no VS16 or ZWJ, and is exactly two columns wide.
A step's type comes only from the agent's declaration or from the structured identity of a native tool call, never from text:
- A declared value outside the list (a newer or older client, a typo) is not
rejected: it is stored as
otherwith the declared value as its label.nullis treated as omitted. Clients parse a stored type they do not know asother, and a hook step type the controller does not know falls back to the tool's own mapping. - devctl's own MCP tools are typed from devctl's tool catalogs: read tools are
research, mutating toolsconfigure,request_permissionand the typed request toolsrequest, their status toolsresearch.control_requestruns an arbitrary discovered operation: the hook types it from the operation's structured HTTP method (GET /v1/β¦isresearch, any other methodconfigure); a call recorded without it staysunknown(mcp:devctl). - Codex built-in tools are typed by their exact names (
collaboration.*coordinate,web.runresearch,clock.sleepwaits,get_goalplan). - A third-party MCP tool is typed by the verb in its own name, with words
separated by
_or-(github__get_issue,notion-fetch,notion-update-page). - Native checklist items (TodoWrite, Task,
update_plan) carry no type field, and a third-party MCP tool without a recognized verb has no structured type: these stayunknown, labeled by their source (for examplemcp:notion). - Steps an earlier hook or Core stored as
unknownalthough their tool is known (Codex tools reported without their namespace dot, hyphenated MCP verbs) are typed again once at Core startup (agent-task-reports:step-types:1inintegration_state, at most 5000 rows), from the stored tool, else the tool name devctl used as the label, else an MCP tool rebuilt from devctl's own fixed title whennativeToolTitlegives that exact title back.
An unknown step carries a free-text label; the Task Graph screen shows
statistics of these labels (and of other values) so missing types can be
identified. The console leaves out labels that are a known tool's own name
(rows an earlier hook stored as unknown, such as clocksleep), typed with the
same tool mapping. Labels that name only an MCP server (mcp:notion recorded
without its tool, mcp:devctl for a control_request recorded without its
operation) carry no tool identity and stay unknown.
The session plan
A session reports its plan as one tree with devctl update_session_plan;
every call replaces the tree. goal (title and an optional note) says why the
work exists and leads the session's header; it may carry spend and eta
of its own. Money or quota is the spend of the node it belongs to (the goal
or the item that spends it), never a node of its own. items are what the agent does
for it, each with a state (running, queued, done, blocked,
waiting-for-user, proposed), optional progress ({done, total}), eta,
spend and note, and children for its steps: at most four levels
including the goal and 60 nodes. A short key keeps an item's identity when
its title changes; without it the title path is the identity.
Core stores the tree as real tasks of the session (source mcp, nativeRef
plan:goal and plan:<path>, the goal as the root and items by
parentTaskId), in fields every console reads: running β running, queued β
pending, done β completed, blocked β blocked, waiting-for-user β
waiting with step type wait_input, proposed β pending with step type
request; progress β progress.completed/total, note β summary, eta and
spend β detail. One transaction upserts the reported nodes, removes the
ones no longer reported and keeps a node's updatedAt when it did not change
(so a stale item can be told from a current one). Each replacement is a
revision; the last ten trees are kept in integration_state
(agent-plan:<session>). New siblings list in reported order. The plan is
the session's tree, never a turn's sentence.
The story view shows the goal as the session's headline with its spend, then
the work's own state and what it needs from the user, then the agent's input
state (Re-check published rules Β· $46 of $200 Β· β³ work runs in the background Β· β 1 item needs you Β· ? waiting for your input): the prompt wait
is the agent's, not the work's. Under it the tree: state
glyph (β³ running, β· queued, β done, β blocked, ? waiting for you,
β proposed), title, progress, ETA/spend and note; a done branch folds its
steps (Enter opens it). The turns move behind one βΈ N turns of history
row. Without a reported plan the story is unchanged, with a dim no plan reported hint.
The reminder. The managed guide asks agents to keep the plan current. The
lifecycle hook (Claude Code and Codex run the same script) also asks once: at
the main agent's Stop after a turn that did work (at least three shell calls,
or an edit, or a subagent) without an update_session_plan call, it answers
the Stop with {decision: "block", reason} naming the tool. It never asks
when the provider marks the Stop as a continuation (stop_hook_active), a
second time in the same turn (recorded in devctl-plan-reminder.json before
it asks), for devctrl's delivered notices or the provider's background-task
notifications, for a turn that used a Control Room tool, or where the launch
left devctl-plan-reminder.off (evidence-only sessions and sessions without
devctl MCP). A blocked Stop is not recorded as the turn's end. Running
sessions get it with the next in-place hook upgrade.
The story view
The Task Graph opens on the story of each session, so the operator can tell what is happening without asking. One row per conversation turn, newest first, under a Now line:
βΆ Now: working on βfind the approval numberβ since 23:05 Β· running: node find-approval.mjs Β· 6m Β· latest answer: βWaiting for approval 42 to finish.β
βΈ β Rebuilt the market report; 15 rows still need manual review. Β· 21:00 Β· 30m
π¬ Implement market analytics
edited report.ts Β· 1 commit Β· 2 errors Β· 4 commands Β· 6 steps (Enter)
βΈ π devctrl: access update Γ7 Β· 21:56β21:59
- Now says the current state from structured data: waiting for an
approval (the session's activity tags), waiting for a subagent that is still
at work while the main agent waits (
waiting for subagent βFix the storey parserβ: Wait for the measurement Β· last update 14:55), waiting for your input, working on the current request since its start, or idle since the last turn ended; then the running step (its description or command, and for how long; a wait step readswaiting on: β¦) and the latest answer. The current request is the newest user turn, never a notice or a background update. - Under Now, for the operator's own sessions:
- the agent's latest answer to a user's message, in full: the console
reads the session's native conversation history through the read-only
session output route (
GET /v1/sessions/:id/output?mode=conversation, the newest 12 messages) and takes the last assistant message after the newest user message that is the user's own (devctrl's delivery envelopes and the provider's<task-notification>are recognized by their fixed formats). It is laid out as Markdown (terminal controls dropped, no HTML), eight lines folded and up to sixty when its row is opened with Enter, and read again when the session's newest turn changes and at most every 30 seconds. Graph-only shares never read it. Without readable history the Now line keeps the stored first sentences (latest answer: β¦). Opening an older turn with Enter shows that turn's own full answer too when the same page reaches back to it (matched by the user message's time). - its background work as the provider's collector reports it in the
session state: background shells and monitors by their agent-written
description, active subagents, and since when the oldest one runs
(
β background: 1 background shell Β· since 13:50 (6h32m) Β· monitor b1 Β· measurement shard progress); never commands. - its plan as it declared it: open top-level
report_agent_tasktasks first, then those finished within the last day, with their state (β° plan: β Re-check published rules Β· β Fix the storey parser). Native checklists (TodoWrite, Codexupdate_plan) are shown above the story when the agent keeps one.
- the agent's latest answer to a user's message, in full: the console
reads the session's native conversation history through the read-only
session output route (
- A turn row carries one sentence, taken in this order: the agent's own
declared
report_agent_taskcreated and last updated within the turn (its summary, else its title: devctl keeps no history of a task's text, so a task updated in a later turn speaks for that turn), else the first sentences of the agent's final answer for the turn (the provider's Stop hooklast_assistant_message, from Claude Code and Codex; terminal text is never parsed), else a declared task the turn only updated, unless an earlier turn of the session already shows its text (a long-lived status task keeps the summary it got turns ago, so it never outranks a newer turn's own answer), else a Decisions model sentence (below; one that only quotes the user's message is ignored), else, for a turn without steps, an answer an older hook stored as its lead-in only, followed byβ¦, else the digest sentence: what the turn's structured digest says, such asRan 7 commands, edited report.ts, requested 2 approvals(No answer recordedfor a finished turn without an answer or steps,No recorded stepsfor one still open). The row's mark is the turn's outcome:βfor failing tests or builds or a failed turn (its sentence then starts withturn failed); failed tool calls the agent went on from stay in the digest (4 errors) under aβ. A stored answer cut that ends on a list's first marker right after a lead-in (Next, in order: 1.) ends at the lead-in withβ¦instead. - The session headline. A session titled by the agent's declared title or
its launch description that is more than six hours older than its newest
request leads with that request's own sentence; the old title follows,
labelled with its age (
declared task ββ¦β Β· updated 3d ago,session description ββ¦β Β· 2d old). A name the operator gave is never replaced. The digest sentence is rendered by the console in the viewer's language from the digest parts (agentTurnDigestSentencein contracts, thetaskGraph.story*andtaskGraph.digest*catalog rows); the API returns it in English with sourcedigest. The user's message is never the turn's sentence. Under the row: the user's message and the digest of what the turn's steps did (edited file names, tests and builds with their result, commits, pushes, approvals requested, errors and commands) and the turn's start and duration. Enter opens the turn and lists its steps;xshows every step of the session. - The recorded answer is the first sentences of the answer's first prose
paragraph. When that paragraph is only a lead-in (it ends with a colon, or is
shorter than 24 characters, like a title), the hook takes the paragraph after
it as well, so
By the latest confirmed status:is followed by the status. An answer stored by an earlier hook that is only such a lead-in is not used as the sentence; the turn falls through to the next source (and is shown withβ¦only when nothing else describes the turn). - devctrl's own notices (access updates, granted approvals, task
outcomes, CI updates, file syncs) are typed into the session by devctrl's
delivery, so they used to look like user turns. The hook recognizes
devctrl's fixed envelope (
devctl: session notice <id>.and its siblings) withparseNativeNoticeEnvelopefrom contracts (embedded into the hook next to the shell classifier; the same function serves Core and the console) and Core treats the turn as a notice only when the id matches a delivery record of the same session: the notice outbox record (and the subsystem that queued it: an effective-access receipt, CI tracking, an operator outcome) or the session's own approval. A notice a human sent through the notice API, or an id without a record, stays a user turn. Notices render asπ devctrl: <type>; back-to-back notices of one type and outcome fold into one row with their count and time span (CI failed Γ8 Β· 21:56β21:59), and the agent's newest answer to them follows on aβline. Notices of different types or outcomes never fold together, so a granted approval or a failed task stays visible. An operator-task notice names the task's kind and its typed failure code from the approval record (task failed Β· repair Β· delivery-uncertain); Core stores that detail as the notice row's narrative (sourcedigest), so the notice fields older consoles parse stay unchanged. Enter opens the folded notices' steps. - Background-task updates. Claude Code types its own
<task-notification>into the session when a background subagent or command reports. Such a turn is not the user's and never gets aπ¬line. A quiet one (no edits, commits, pushes, tests, builds, errors or approvals, no subagent started, at most two steps) renders asβ³ background task update, and back-to-back quiet ones about the same subagent fold (Γ9 Β· subagent βzone readerβ Β· 13:53β14:55) with the newest answer under them. The hook records the notification's own<task-id>and<status>tags (never its summary or output path), so an update names the subagent with that id, and updates of different background tasks never fold together. For rows recorded before, only a subagent whose node ended at the notification is named; one merely at work at the time is not, since another subagent or a background command may have sent it. An update after which the agent did real work keeps its own row,β³ after background task Β· <sentence>, with its digest. - Subagents. A subagent's steps belong to the turn that started it (its
node's start), not to whichever turn was current when they ran, and that
turn shows one line per subagent: its current step and state while it works
(
β³ subagent βFix the storey parserβ: Wait for the measurement Β· waiting since 14:55 Β· 98 steps), else when it finished. The name is the parent's Agent/Task description; the line ends with what its steps did, like a turn's digest. A subagent counts as at work while its newest step is open and changed within two hours of the session's newest change. - Durations. A turn the agent's Stop ended lasts until the Stop; a turn without a Stop record (older hooks) lasts until the main agent's last step in it, not until the next message; with neither, it shows no duration.
- Stored envelope turns. A turn whose hook did not report the envelope (a
session started with an older hook, or a row recorded before Core verified
envelopes) still carries the envelope in its stored prompt, with the id
replaced by
[redacted]by the hook's sanitizer, which only a devctrl delivery produces. Core recognizes such a prompt when it records the turn and in a one-time startup pass over existing rows (keyedagent-task-reports:notice-backfill:1inintegration_state, bounded to 2000 rows): a session notice is matched to the delivery record of the same session queued before the turn and confirmed within a few minutes of it, and typed from that record as above; the other envelopes are typed by their kind. devctrl's effective-access and operator-outcome notices are queued without an automation marker, so their records say originhuman; the subsystem's own record (the effective-access receipt, the approval's requester notice) still makes them devctrl's. The subsystem also writes a fixed prefix right after the envelope (devctrl effective access revision β¦,devctrl CI update for your push of β¦,devctrl operator outcome β¦;nativeNoticeSubjectin contracts): when the stored prompt has one, only that subsystem's records match it, and without a matching record the prefix alone types the notice (Core and the console alike). A second one-time pass (agent-task-reports:notice-backfill:2) types again the rows an earlier Core matched while it skipped those records (an access update shown as a CI notice queued two minutes later). A row Core could not match is still shown as a notice of its subject or its envelope's kind (π devctrl: access update, elseπ devctrl: notice, folded with its neighbours) by the console, which fills the notice in from the stored prompt (storedTurnNotice); an envelope whose id is still visible was typed or sent by a human and stays the user's turn.
Free text of the story (the user's message, the answer, the turn's sentence and command summaries) is returned only to viewers with terminal access to the session, like prompts. Task Graph-only shares, public links and external MCP clients see the same rows with the digest, notices, exit codes and durations, but without any of that text.
The Decisions sentence is the last resort for a finished turn with neither a declaration nor an answer (an interrupted turn, or a provider version without the Stop field). The Decisions API answers choice questions only, so Core offers the owner's configured Decisions model a few candidate sentences built from the turn's structured facts (its digest and the user's message) and stores the one the model picks on the turn. Nothing is classified by text. It runs only for finished turns of the last 24 hours, at most 12 calls per ten minutes and one per session every two minutes, each turn at most once; the owner's Decisions budget is checked and reserved like any other Decisions request, and nothing is asked while the Decisions route is not configured or not published to the owner. A turn is finished when the agent's Stop ended it, when the next turn of the session started, or when the session's structured lifecycle has been idle since the turn started (the provider hook's waiting-for-input state, or an exited or failed process) for two minutes: most sessions started with an older hook record no Stop, and the newest turn of a session has no next turn, so without the idle rule a session's last turn was never asked about. devctrl's own envelope turns are never asked about. A turn without any source shows its digest sentence.
Commands in the step view
A run step says what it did: the agent's own description of the call (Claude
Code's Bash description, Codex's justification), else a short command
summary from the hook's structured argv: program, subcommand or script and a
few arguments (node build-report.mjs, pnpm test api, git push origin main), with paths reduced to file names, URLs to their host, quoted text and
long values to β¦ and secret-looking values or the values of secret-named
options redacted, at most 80 characters. Its outcome follows: β or β exit N when the provider reported an exit code in the PostToolUse response, and
the call's duration. Consecutive identical calls fold as ΓN only when their
command summaries are identical, never because they ran the same program.
Codex apply_patch steps name the files from the patch's own headers.
Step descriptions
Native steps are titled with the text the agent already writes: the Bash and
Task description, the checklist item's activeForm, the search query, the
fetched host, or a verb plus the file's basename for file tools. The step type
and shell label become a badge. Text is sanitized in the hook before it is
written: URLs keep only the host, paths only the basename, secret-looking
values are redacted and each text is capped at 100 characters. Raw commands,
environment values and transcripts are never recorded; the bounded command
summary of a shell step (above) is shown only to viewers with terminal access.
Each step starts with an emoji for its step type (two columns wide, for
example π research, π§ͺ test, π edit). Consecutive steps of the same agent
with the same step type and label fold into one group row, such as
βΈ β π [research: grep] Γ2 Β· completed Β· 16:34β16:33 Β· 17s: its count, the
newest and oldest start times, the summed duration and its status (a failed
or blocked step wins, otherwise the newest step's status). Groups use only
the structured step type and label, never the titles. A single step stays
ungrouped. β opens a group and β folds it again.
Signal and noise
The graph leads with what the agent is doing, not with its mechanics. All of this uses structured step fields only (source, step type, classifier label, tool name, poll mark, status and times), never titles or other free text:
- Declared tasks (
report_agent_task) come first at the top level, before the session's native activity, even when they are older. - Routine steps are hidden: finished zero-second runs, the lifecycle's own
"waiting for input" marker (no tool behind it) and calls to devctl's own
wait and long-poll tools. Core marks those calls with
poll: truefrom devctl's tool catalog (wait_for_user,wait_until,wait_for_rate_limit_reset,wait_for_webhook,wait_for_service,wait_for_messages). An open wait is never hidden: it is the current state. - Repeating idle cycles of one agent fold into one row, for example
βΈ β³ idle β polled 14 times Β· 12:50β16:12 Β· 3h22m. A cycle ends with a wait and holds only waits, looks, trivial runs and turn rows; two or more consecutive cycles with the same set of step types and labels form a loop. An edit, test, build, commit, deploy, subagent or failed step breaks it. β opens the loop and lists every member. - A session that declared no tasks gets a summary row from its native steps: edits, test runs (and failures), builds, commits, pushes and commands.
- The session header is short: title, one state (what needs the operator,
else
idle since 12:50 Β· 14 polls, else working), the declared or derived task and the pull request. Every counter moves to theDid:line under it: agent CLI, declared tasks (done and open) or recorded steps, edits, test runs, builds, commits, pushes, commands, main/subagent split, work kind, markers, other tags and how many routine steps are hidden. Mosaic tiles show the same idle line. - devctl's own bookkeeping calls are routine and hidden the same way:
report_session_handoff,report_agent_task,list_agent_tasksandset_session_title, matched by the step's tool name (mcp__devctl__<tool>) against devctl's catalog. They also do not break an idle loop. A failed call stays visible. - A real handoff gets one row of its own:
βͺ handoff: <next step>. Core records it whenreport_session_handoffcarriesreason: "user_exit"(the user asked to end or hand off the session) or a quota handover captures itsquotaCheckpoint. Routine task-disposition checkpoints for automatic compaction get no row. - Runs of devctl's own session helpers (
devctl-mcp-call.mjs, the managed MCP companion, anddevctl-policy-read.mjs, by the hook classifier's label) are devctl's policy and guidance plumbing: routine and hidden, like the wait tools. - Provider-internal helper agents are not subagents. Claude Code fires SubagentStart/SubagentStop for side agents (for example prompt suggestions after a turn) without an agent type, a Task/Agent call or tool steps; their closing text reads like a user prompt. Core no longer records them or their text, removes rows earlier builds stored, and the graph gives them no lane.
x (Russian layout: Ρ) shows every step: routine steps (including devctl
bookkeeping calls) and idle loops are listed as recorded.
Each new turn of the main agent adds a π¬ input turn row at the top of the
steps it caused. It comes from the hook's UserPromptSubmit (Claude Code and
Codex both fire it) and, when a hook missed the turn, from a structured
turn-started observation; one turn within 15 seconds is one row. The hook
keeps only the prompt's first non-empty line, sanitized like other step text
(URLs keep the host, paths the basename, secret-looking values are redacted)
and cut to 200 characters; terminal text is never parsed. That line is shown as
π¬ <prompt> only to viewers with terminal access to the session: its owner and
users the terminal is shared with. Task Graph-only shares, public links and
external MCP clients get the row without the text, as π¬ input turn. The row
shows "agent working" until the agent's next step and ends the wait before it
at the moment the input arrived. Turns whose prompt repeats (a scheduled
wake-up) can still fold into an idle loop; a new message breaks the loop.
Steps are grouped under the checklist item that was running. Finished items
and subagents fold into a summary of what was done below them: counts by kind
of work, most frequent first (for example reads Γ10, tests Γ5, git Γ3, database Γ2), and the latest two step descriptions. Generic reads and runs
are refined by their shell label into network, database and container work.
Timings and details
Every row shows its local start time and a duration that keeps counting while the step runs. The details view adds a timeline of recent steps and the agent's checklist.
Project tree and activity markers
The Task Graph is one pane: a single tree with the Projects tree's levels β
project group (shown in capitals), repository, container (β³ main), session
and, in the by-agent view (g), each session's agent lanes β with the
session's tasks below. Within a session or lane the newest work is on top at
every level, and the cursor starts on the newest task.
Navigation is the Projects tree's: Up/Down move among rows of the selected
level only (across parents), Right opens a folded node and moves to its first
child, and Left moves to the parent and folds it. Enter on a group,
repository, container, session or lane scopes the view to it; a breadcrumb
line (Showing: Shop βΊ Api βΊ main βΊ alpha) names the scope and the levels
above it, which are left out of the tree. Esc climbs one level, c shows every session again, and / searches
group, repository and session names and task titles in the scope (Up/Down step
through matches, Enter keeps the match, Esc closes the search). The
Conversations and Reviews sections appear for a session or agent in scope.
The tree uses the Projects tree order and lists the sessions the graph lists.
Every node carries activity markers from a closed set. Core derives them from
structured state only β never from agent-written text β per session, then
merges them (deduplicated, most severe first) into the repository and group.
GET /v1/agent-tasks returns them additively as sessions[].tags,
sessions[].groupId and the groups[] / projects[] scope lists. Ids are
stable and are the keys for web icons:
| Id | Glyph | Source |
|---|---|---|
failed |
β | Session status or provider-hook lifecycle failed |
needs-approval |
β | Lifecycle waiting_approval, or an unexpired pending MCP approval of the session |
waiting-input |
? | Running session with lifecycle waiting_input |
blocked |
β | An open reported task with status blocked |
quota |
β³ | Quota recovery whose reset is still ahead, or model-capacity retry scheduled/running |
conflict |
β | Repository only: Exchange conflict set not yet dismissed at its current count |
not-reporting |
β¦ | The existing not reporting rule |
review |
β | Work status marked as requiring review |
frozen |
β | Session freeze in progress, frozen or thawing |
outdated-cli |
β | Running session launched with a CLI older than the latest managed release |
working |
β | Running session with lifecycle working or a running reported task |
New ids may be added; existing ids are never renamed or reused.
A turn row counts as a running task only until it ends: the agent's Stop
completes it. Before, a turn stayed running until the main agent's next step,
and a turn shorter than the Host's lifecycle sampling (a background-task
notification answered in seconds) never got one, so a session waiting for
input kept working and its project and group rows a spinner. Rows an
earlier Core left running after their Stop are completed once at startup
(agent-task-reports:ended-turns:1). A shell step also ends at its
PostToolUse (it used to record only the exit code), and the Stop ends the
main agent's other open steps of that turn; steps an earlier Core left open
after their turn's Stop are completed once at startup
(agent-task-reports:ended-turn-steps:1). The implicit Session activity root,
which stays running for the session's life, never counts as a running task
(the Projects summaries already left it out; the Task Graph counted it while
it was among the listed rows, so a young session always looked busy).
Work kinds and work markers
Each session row also says what the session is working on and what it has
done, like a task list: its declared work kind before the name, then work
markers, the pull request number and how long ago it last reported
(β¦ alpha ββ ββ£ #3981 18m). The graph's session header spells them out with
the task title. GET /v1/agent-tasks returns them additively as
sessions[].work (kind, title, pullRequest, markers[] with id,
source and at, updatedAt). Nothing is inferred from agent-written text:
- Declared by the agent through
report_agent_task:workKindon a top-level task,milestonewhen the task finishes one of the events below, andpullRequest(a number). The kind shown is the one of the open top-level task that declared it, otherwise the latest declaration. These are unverified agent claims, like every report. - Observed by Core from the workspace's captured git status:
uncommitted,unpushed, andpushed/committedfor a commit authored after the session started. When a git status is captured it replaces the agent's owncommitted/pushedclaims.
Of tests-*, build-*, ci-* and committed / pushed, only the latest
marker of each pair is current. At most 12 markers are returned, newest first.
| Work kind | Glyph |
|---|---|
feature |
β¦ |
bugfix |
β |
refactor |
β» |
tests |
β |
docs |
ΒΆ |
review |
β |
release |
β |
investigate |
β |
plan |
β° |
ops |
β |
| Marker | Glyph | Source |
|---|---|---|
tests-passed |
β | agent |
tests-failed |
β | agent |
build-passed |
β£ | agent |
build-failed |
β’ | agent |
committed |
β | git, or agent without a git status |
pushed |
β‘ | git, or agent without a git status |
pr-opened |
β | agent |
ci-passed |
β | agent |
ci-failed |
β | agent |
deployed |
β | agent |
uncommitted |
Β± | git |
unpushed |
β£ | git |
Ids are stable icon keys; new ids may be added, existing ids are never
renamed. Core has no pull request or CI provider integration yet, so
pr-opened, ci-* and the pull request number come only from agent reports.
Projects Activity view
Activity is a third Projects layout next to the list and the mosaic. Select it from the Projects view tabs or save it as the Projects layout preference. It uses the same tile grid, session set, groups and navigation as Mosaic, but each tile shows the session's current work, checklist progress and the latest rows of its work tree instead of its terminal. The graph is polled only while the view is visible, and terminal previews are not fetched for Activity tiles.
Projects Task Graph view
Task Graph is a Projects layout next to the tree, the session mosaic, Activity and Project Agents. It uses the mosaic's tabs, groups, hidden sessions and order; each tile shows one session's compact graph:
- the header
project group Β· repository Β· session Β· agent Β· statewith the shared animated session status icon; - highlighted pending MCP approvals and unanswered questions to the session;
- done, running and blocked counts and the activity markers;
- the agent lanes (
Mβ 4/7 1β 1/2: code, status, done of total) when the session has subagents; - the current task, then the newest tasks with their animated status glyphs and step emoji.
Arrows move between tiles as in the mosaic. Enter opens the full Task Graph
scoped to that session with all of its keys (g, m, v, /, the
breadcrumb); Esc at that scope returns to the mosaic on the same tile. The
browser shows an Open task graph button on each tile. The choice of view
is saved with the other Projects layouts.
Tiles poll GET /v1/agent-tasks/summaries every five seconds for the
sessions of the current tab only, and only while the tiles are visible. The
summaries are bounded (at most 12 recent tasks and 8 lanes per session, 200
sessions); counting happens in Core's database, and no session's full graph
is fetched for a tile. An entered tile reads the full graph like the Task
Graph screen.
API and authority
| Method | Route | Purpose |
|---|---|---|
| GET | /v1/agent-tasks |
The signed-in user's task graph across owned sessions |
| GET | /v1/agent-tasks/summaries |
Bounded per-session summaries for Projects Task Graph tiles |
| GET | /v1/agent-tasks/unknown-steps |
Statistics of unknown step labels |
| PUT | /v1/agents/:id/sessions/:sessionId/task-graph |
Native hook snapshots forwarded by the session's own Host agent |
/v1/agent-tasks accepts optional sessionId, projectId and limit
filters and returns only sessions owned by the caller; its sessions carry
workspaceId and workspaceName for the container level.
/v1/agent-tasks/summaries accepts sessionIds (comma-separated, at most
200) and recent (1β12, default 6) and also covers only owned sessions. External OAuth clients
can read the same data for granted Projects through get_task_graph with the
tasks:read scope; see External MCP clients.
Reports are unverified progress claims. They grant nothing, do not verify
results, do not change session state and do not replace
report_session_handoff. Each session is limited to 500 tasks and a depth of 16. Concurrent hooks journal their events atomically, so parallel tool calls
do not overwrite each other's steps.
Hook upgrades for running sessions
The hook script is read by the agent CLI on every event, so an updated hook applies to running sessions without a restart:
- Container sessions: the Host agent rewrites the session's
devctl-lifecycle-hook.json its next heartbeat after the Host agent is upgraded, for running and starting sessions whose hook already carries the managed prompt marker. - Native host sessions: the hook is upgraded in place when the next session notice or file-sync notification is delivered through the current host runner.
The set of hook events the CLI calls is fixed when the session starts. The events the task graph needs (PreToolUse, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop) have been registered since the Task Graph was introduced, so older running sessions gain the new classification, subagent matching and outcomes after the upgrade. Steps recorded before the upgrade keep their old titles and categories.
Conversations between sessions
GET /v1/agent-tasks also returns conversations (newest first, at most 200,
with conversationsTruncated) for the listed sessions. Each event comes from a
structured record only:
| Kind | Source | Status |
|---|---|---|
message, question, answer |
Project messages sent by or delivered to a listed session | delivered, read, expired, rejected; a question is pending until an answer replies to it, then answered |
delegation |
delegate_task records owned by the user |
running, completed, failed |
handoff |
report_session_handoff reports |
completed |
| any of the above | requests held by the peer-payload check | held |
Bodies are never returned. The only text is the subject, or the first line of the body, redacted and cut to 120 characters; held requests carry no text at all. A sender on a paired Core is shown by its handle and Core id only, and an unlisted recipient by its existing message handle.
In Task Graph each session ends with a "Conversations" section showing its
newest eight events: β sent, β received, then the kind (β message, ?
question, β© answer, β’ delegation, β handoff), the other side, the subject
and the status; a handoff recorded twice with the same subject, sides and
status is listed once. Waiting questions and held requests are highlighted. A task
that links a message thread shows β βsent βreceived ?waiting βanswered for
that thread. Selecting a conversation with another listed session and pressing
Enter scopes the graph to that session. m hides or shows conversations; the
choice is remembered with the other view preferences.
Cross-session links
A task can declare up to eight links with report_agent_task links, IDs only:
a Project message thread ({kind:"thread", threadId}), a Project board item
({kind:"board_item", itemId}) or a peer task
({kind:"assigned_from"|"blocks"|"blocked_by"|"related", sessionId, taskId}).
Passing links replaces the task's links; null clears them. The screen marks a
linked task with β N, and its details list each link with the peer session's
name and, when the peer task is visible, its title. Links are agent claims; they
grant nothing.
Agent sessions read their peers' graphs with get_project_task_graph
(read-only summaries without details; see
session messaging).
Limitations
- Native step capture is implemented for Claude Code hooks. Codex plans and subagents are not captured in the released version.
- No reminder notice is sent to a session that is not reporting; the operator sees the marker in the Task Graph.
- SubagentStart carries no tool-use identifier. Until a foreground subagent's call returns, two concurrent subagents of the same type may show each other's descriptions; the result corrects them.
- Cursor Agent, Grok Build and OpenCode have no devctrl MCP injection, so they do not report tasks.
- Agent-reported text is only as accurate as the agent's own descriptions.
- Turn rows need observation collection for the session; without it a turn is visible only through the steps it causes. A turn row does not say who sent the input (the operator, a scheduled prompt or a devctl notice).
- The Host forwards lifecycle samples before the hook's step snapshot. Core places a late step by its own time, so it no longer closes a newer wait, but the graph can lag the session by one Host polling interval.