chant workspace agent

Synopsis

chant workspace agent [<name>] [--json]

Description

An agent session is declared in the declaration’s agents list and bound to one member or several (#2548, #2524 D20, ws-101). chant workspace agent <name> prints what the session reloads from.

Part	What it holds
agent	The session, the members it is bound to and the principals it lists. members lists each in the order the declaration names them; member is the first, for readers written before a session could name several
scope	The members whose files the session writes. Each declared record kind in its reach, the workspace’s own and then each member’s, is listed with the verbs (new, amend, review, close) the session may write the kind with. protected lists the paths writeScope.agent.protected keeps it from writing, each { path, except } (#3146)
spec	The spec block chant workspace records --current --json prints: the current records of the kinds with spec: true, each with the files it pins
reload	The two reads that rebuild the session’s context

An agent that resumes runs this and reads nothing else. It needs no memory of an earlier run and no state outside the checkout.

The session and its scope come from the declaration at base (origin/HEAD, main or master). The record writes and check --changes read them there too. Without a declaration at base, the working tree’s declaration is used. workspace.scopeFrom says which one was read. The spec is read in the working tree, since that is what the agent works on. Without a name, the command prints the session CHANT_AGENT names.

Whatever runs the agent sets CHANT_AGENT=<name> in its environment. It finds the names bound to a member in that member’s agents in chant workspace ls --json, read from the same declaration (#3615). The record writes and the MCP record tools then refuse a write outside the session’s scope. A commit the agent makes carries a Chant-Agent: <name> trailer, so check --changes judges it as the session.

$ chant workspace agent app
agent     app, bound to member app (app), scope read from base
records   decision (decisions/decision.kind.mjs): new, review
records   work (work/work.kind.mjs): new, amend, review
spec      3 current records of 1 spec kinds
          decision/ref-001 decided decisions/ref-001-how-the-app-is-deployed.md
          ...
reload    chant workspace agent app --json; chant workspace records --current --json

Options

Option	Effect
--json	Print the read contract document, which follows https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json

chant serve mcp serves the same document as the workspace-agent tool.

Exit codes

Code	Meaning
0	The session was printed
1	No name was given and CHANT_AGENT is unset. Or the declaration can’t be read, with its reason code, or it declares no such session (agent-unknown)