Agent Runs from Claude Code: Workflow Runs, Facts and Usage

The agent_runs toolset on the systemprompt MCP server gives developers and project managers the run lifecycle from inside Claude Code: start a workflow run, follow the headless agent steps it queues, read their event streams and recorded facts, cancel them, answer the decisions the workflow is waiting on, and read usage for themselves or one of their projects. It is one of the toolsets the single systemprompt server (port 5010) hosts, beside core's issue and document tools and the admin toolsets. The workflow engine itself is described in Workflow Orchestration; these tools are the developer-facing way in.

Who reaches it

Entitlement is declared in services/access-control/rules.yaml like every other entity. The agent_farm_runs skill inside the astound-commons plugin is closed by default and allowed to the developer, project_manager, admin, platform_admin and super_admin roles. The mcp_server/systemprompt entity is open to every signed-in role; who may list and call the run tools is declared on the agent_runs toolset in services/mcp/systemprompt.yaml (the developer, project_manager, knowledge_worker, admin, platform_admin and super_admin roles) and enforced per tool by core's MCP host. These tools are not the admin plane: project_manager is named because every run tool scopes itself.

That declaration only decides who sees the tools. Inside them, every run tool applies one rule:

• a person reaches a run they launched, or that ran as them, including a step that ran as a workflow's service account on a run they started;
• a person reaches every run of a project they belong to;
• an administrator reaches every run.

Anything else is refused with a Forbidden: error that names the run. The scope word is the same on every listing tool: mine, project, or all, and all is refused without an administrator role.

Tools

Tool	Read-only	What it does
run_start	no	Start a workflow definition's manual trigger as yourself; returns the workflow run id at once
run_status	yes	One agent run's lifecycle state, timings, tokens, cost, error class
run_events	yes	A page of the run's event stream, by seq
run_cancel	no	Cancel the workflow run a step belongs to, then the step
run_list	yes	Runs the caller may see, newest first, with recorded facts; workflow_run and definition narrow it
run_facts	yes	Everything recorded about one run, plus the workflow run's decisions, effects and history
run_stats	yes	Rollups over 24h, 7d or 30d, by status, error class and origin kind
workflow_inbox	yes	The open decisions addressed to a role you hold
workflow_decide	no	Answer one: approve, request_changes, reject or cancel
analytics_costs	yes	Spend over a window for the caller or a project
analytics_requests	yes	Gateway requests, failures, denials, latency, by model
analytics_skills	yes	Skill adoption and the conversations it reached
analytics_tools	yes	MCP tool executions by server and tool
catalog_list	yes	What the caller's access grants

Every input is flat: strings and numbers with defaults, so a client never has to guess a flag. Nothing here is model-judged: run_facts reports what the tables recorded and nothing else.

A run from start to facts

run_start       {"origin": "workflow", "definition": "core-dev", "context_json": "{\"issue\":\"systempromptio/systemprompt-astound-prod#42\"}"}
run_list        {"scope": "mine", "workflow_run": "<origin_run_id>"}
run_status      {"run_id": "<id>"}          until terminal
run_events      {"run_id": "<id>", "after_seq": 0}
run_facts       {"run_id": "<id>"}
workflow_inbox  {}
workflow_decide {"decision_id": "<id>", "outcome": "approve"}

run_start goes through the workflow engine's own trigger service, so the definition's trigger roles, required context keys, variant and project rules are resolved exactly as the console's Start button resolves them. The engine then queues the run's agent steps; the tool never waits for them.

run_facts is the record the tables hold: outcome, tokens, reported and metered cost, tool use counts by name, hook and governance decisions, structured output and whether it matched the schema the request asked for, and the workspace diff summary. A step's project and launcher come from its workflow run (workflow_runs.project_id and initiated_by), which is how a step that ran as a service account still belongs to the person who started the workflow.

Connecting from Claude Code

MCP servers are reached through the gateway, never on their own port: the server URL is https://<your instance>/api/v1/mcp/systemprompt/mcp. A personal access token (PAT) is not accepted there directly; exchange it for a short-lived gateway token first (core's PAT exchange endpoint) and present that as the bearer:

curl -s -X POST https://<your instance>/v1/auth/bridge/pat \
     -H "Authorization: Bearer <pat>" -H "Content-Type: application/json" -d '{}'
claude mcp add --transport http systemprompt https://<your instance>/api/v1/mcp/systemprompt/mcp \
     --header "Authorization: Bearer <gateway token>"

A call made straight to the server's port fails with Invalid request context headers by design.

Operating it

The tools are the agent_runs toolset of the systemprompt MCP server (extensions/mcp/systemprompt/src/agent_runs/), declared in services/mcp/systemprompt.yaml. The server is the systemprompt binary started under the name systemprompt-mcp-agent, not a binary of its own. The crate is compiled with the workflows feature on, which links the workflows crate. Access audit rows land in user_activity like every other server's; tool usage lands in the same ledger the admin console reads.