@markjaquith/agency 2.68.0 → 2.69.0

package/README.md

@@ -11,7 +11,7 @@ read or write.
 - Git
 - [Jujutsu](https://jj-vcs.github.io/jj/) is preferred when available
 - [GitHub CLI](https://cli.github.com/) for `agency pr`
-- OpenCode, Claude Code, or a configured runner for `agency work`
+- OpenCode, Claude Code, or a configured agent for `agency work`
 
 ## Installation
 
@@ -113,7 +113,7 @@ read-only Agency commands, and use explicit Agency CLI permissions to create or
 update planning structure. Its normal research tools and the complete Agency CLI
 remain available; managed Agency instructions and reported authority govern each
 operation.
-When the subagent launches work in another agent, it verifies that the runner
+When the subagent launches work in another agent, it verifies that the agent
 started and returns without waiting for the task to finish.
 The TUI-only `/agency-debug` command reports TUI companion initialization and
 whether the server plugin registered writable-checkout skills. It uses a native
@@ -360,23 +360,36 @@ retries checkout creation and the hook rather than reusing an uninitialized
 checkout. Hook commands should be idempotent so a retry is safe after any
 external effects the failed invocation may have completed.
 
-### Agent Runners
+### Agents
 
-OpenCode (`opencode2` and `opencode`) and Claude Code are built-in runner presets.
-Without an explicit runner, Agency uses the first available executable in this
-order: `opencode2`, `opencode`, then `claude`. Select a preset or configured
-runner with `agency work --runner <name>`. A launch is fresh unless
-`AGENCY_SESSION_ID` is already set; resumed launches use the runner's
+OpenCode (`opencode2` and `opencode`), Pi, and Claude Code are built-in agent presets.
+Without an explicit agent, Agency uses the first available executable in this
+order: `opencode2`, `opencode`, `pi`, then `claude`. Select a preset or configured
+agent with `agency work --agent <name>`. To select a built-in agent globally,
+set `agent` in `$XDG_CONFIG_HOME/agency/agency.json` (or
+`~/.config/agency/agency.json`):
+
+```json
+{
+	"agent": "pi"
+}
+```
+
+The selection precedence is `--agent` (including the legacy `--opencode` and
+`--claude` aliases), then `AGENCY_AGENT`, then `agent`, then automatic
+detection. Supported global values are `opencode2`, `opencode`, `pi`, and
+`claude`; an unavailable configured agent fails rather than falling back. A launch
+is fresh unless `AGENCY_SESSION_ID` is already set; resumed launches use the agent's
 `resumeCommand` when configured. The built-in presets use `--continue` only for
-resumed launches. By default Agency opens the runner without a prompt. `--auto`
+resumed launches. By default Agency opens the agent without a prompt. `--auto`
 uses its autonomous command and sends the generated task, phase, or epic prompt.
 
-Custom runners are direct argv commands, never shell snippets:
+Custom agents are direct argv commands, never shell snippets:
 
 ```json
 {
 	"version": 2,
-	"runners": {
+	"agents": {
 		"custom": {
 			"command": ["my-agent"],
 			"autoCommand": ["my-agent", "--prompt", "{prompt}"],
@@ -393,19 +406,19 @@ Available placeholders are `{prompt}`, `{workbase}`, `{target}`, `{task}`,
 placeholders are empty when they do not apply. `{prompt}` is empty unless
 `--auto` is set. If `resumeCommand` is omitted, the fresh command is also used
 for resumed sessions. If `autoResumeCommand` is omitted, `autoCommand` is used;
-configured runners without `autoCommand` reject `--auto`.
+configured agents without `autoCommand` reject `--auto`.
 
-Every runner receives the same `AGENCY_RUNNER`, `AGENCY_CLAIMANT`,
+Every agent receives the same `AGENCY_AGENT`, `AGENCY_CLAIMANT`,
 `AGENCY_SESSION_ID`, `AGENCY_CLAIM_REVISION`, `AGENCY_WORKBASE`, `AGENCY_TARGET`,
 `AGENCY_TASK_ID`, `AGENCY_PHASE_ID`, and `AGENCY_PROMPT` environment. Configured
 environment is added without overriding these normalized values.
-Execution-unit runners also receive `AGENCY_WRITABLE_CHECKOUT` with the
+Execution-unit agents also receive `AGENCY_WRITABLE_CHECKOUT` with the
 authoritative writable checkout path.
 `AGENCY_CLAIM_REVISION` is empty for local `agency work` launches.
 `AGENCY_PROMPT` is empty unless `--auto` is set.
 Autonomous prompts begin `Agency worker launch target: <target>.`, carrying the
 same canonical target as `AGENCY_TARGET`. This is the process-local fallback for
-runner clients that attach to a long-lived process and lose launch environment
+agent clients that attach to a long-lived process and lose launch environment
 variables. A worker must verify either signal against `agency context . --json`
 before acting; a matching worker performs the task directly and must not invoke
 `agency work` for the same target. Managed guidance also fails safe for older
@@ -416,7 +429,7 @@ to the receiving OpenCode session, injects an explicit active-worker system
 instruction, and restores Agency identity for that session's shell environment.
 This session bridge is necessary because an OpenCode client can attach to a
 long-lived server process that did not inherit the client's launch environment.
-The `opencode2` and `opencode` runners remain rooted in their task or epic
+The `opencode2` and `opencode` agents remain rooted in their task or epic
 working directory so the workbase `AGENTS.md` and managed OpenCode config are
 discovered normally.
 Agency's managed OpenCode plugin grants the active workbase external-directory
@@ -430,7 +443,7 @@ checkout through `agency context`. A multi-phase
 task root has no single checkout, so launch from its phase directory when using
 plain OpenCode or Pi. Other checkout-local configuration is not composed.
 `--print-command` prints the exact cwd and argv plus non-secret environment keys
-without launching the runner.
+without launching the agent.
 
 ### Custom Chooser Command
 
@@ -791,7 +804,7 @@ agency task new [id] [--work [--auto]]
 ```
 
 `--work` starts work on the newly created entity. Add `--auto` to pass the
-generated context prompt to the selected runner. These launch options are also
+generated context prompt to the selected agent. These launch options are also
 available on `epic new` and `phase new`; they cannot be combined with `--json`.
 
 Create a single-phase task:
@@ -991,7 +1004,7 @@ outcome.
 
 `delegated` remains readable for existing workbases but cannot be newly assigned.
 Delegation is now explicit: the claimant identifies the orchestrator and the
-runner identifies the assigned agent.
+agent identifies the assigned agent.
 
 Human list output is a compact table with lifecycle, readiness, parent,
 repository, branch, recorded PR, and worktree state where applicable. List and
@@ -1007,7 +1020,7 @@ Claim mutations require the SHA-256 revision exposed by `agency context` or
 document lock and atomically replaces the execution document.
 
 ```text
-agency claim <task-id> [phase-id] --claimant <id> --runner <id>
+agency claim <task-id> [phase-id] --claimant <id> --agent <id>
   --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]
 agency release <task-id> [phase-id] --session-id <id>
   --revision <sha256> [--json]
@@ -1027,8 +1040,8 @@ rather than overwriting it. Expired claims may be replaced with a
 revision-guarded claim.
 
 `agency work` does not claim execution units. It refuses active explicit claims,
-marks open execution work `working`, and launches the runner. External
-orchestrators use `agency claim`, launch and monitor their runner separately, and
+marks open execution work `working`, and launches the agent. External
+orchestrators use `agency claim`, launch and monitor their agent separately, and
 later call `agency release` or `agency finish`.
 
 ### Archive
@@ -1071,7 +1084,7 @@ until restored.
 ### Work, Publication, and Pull Requests
 
 ```text
-agency work [<directory> | --epic <epic-id>] [--runner <name>] [--auto] [--print-command]
+agency work [<directory> | --epic <epic-id>] [--agent <name>] [--auto] [--print-command]
 agency work prepare [target] [--evidence <json-or-path>] [--dry-run] [--json]
 agency worktree <list|inspect|prepare|remove|rebuild|repair>
 agency push [--json]
@@ -1084,7 +1097,7 @@ configured external chooser. Pass a directory, including `.` for the current
 directory, to infer its epic, task, or phase. Outside a workbase, Agency first
 presents the registered workbases, then the selected workbase's hierarchy.
 
-Agency automatically uses the first available runner in this order: `opencode2`,
+Agency automatically uses the first available agent in this order: `opencode2`,
 `opencode`, then `claude`. `--opencode` and `--claude` remain aliases for
 requiring their corresponding built-in presets. Launches are interactive and
 promptless by default; use `--auto` to send Agency's generated context prompt.

package/cli-main.ts

@@ -206,7 +206,7 @@ const commands: Record<string, Command> = {
 					taskId: args[0],
 					phaseId: args[1],
 					claimant: options.claimant,
-					runner: options.runner,
+					agent: options.agent,
 					sessionId: options["session-id"],
 					revision: options.revision,
 					expiresAt: options["expires-at"],
@@ -584,7 +584,7 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					opencode: options.opencode,
 					claude: options.claude,
-					runner: options.runner,
+					agent: options.agent,
 					auto: options.auto,
 					printCommand: options["print-command"],
 					force: options.force,

package/fixtures/protocol/orchestration-recipes.json

@@ -28,7 +28,7 @@
     "ui",
     "--claimant",
     "orchestrator-1",
-    "--runner",
+    "--agent",
     "opencode",
     "--session-id",
     "session-123",
@@ -47,7 +47,7 @@
     "--json"
   ],
   ["work", "prepare", "--task", "checkout", "--phase", "ui", "--json"],
-  ["work", "tasks/checkout/phases/ui", "--runner", "opencode"],
+  ["work", "tasks/checkout/phases/ui", "--agent", "opencode"],
   ["sync", "--dry-run", "--json"],
   ["sync", "--json"],
   ["pr", "create", "checkout", "ui", "--json"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.68.0",
+  "version": "2.69.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/schemas/agency-graph-v1.schema.json

@@ -539,7 +539,7 @@
       "additionalProperties": false,
       "required": [
         "claimant",
-        "runner",
+        "agent",
         "sessionId",
         "startedAt",
         "targetRevision",
@@ -547,7 +547,7 @@
       ],
       "properties": {
         "claimant": { "type": "string", "minLength": 1 },
-        "runner": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string", "minLength": 1 },
         "sessionId": { "type": "string", "minLength": 1 },
         "startedAt": { "type": "string", "format": "date-time" },
         "targetRevision": { "type": "string", "pattern": "^[a-f0-9]{64}$" },

package/src/cli-parser.test.ts

@@ -343,7 +343,7 @@ describe("strict CLI parsing", () => {
 					"three",
 					"--claimant",
 					"a",
-					"--runner",
+					"--agent",
 					"r",
 					"--session-id",
 					"s",
@@ -499,7 +499,7 @@ describe("strict CLI parsing", () => {
 				"phase",
 				"--claimant",
 				"orchestrator",
-				"--runner",
+				"--agent",
 				"agent",
 				"--session-id",
 				"job-1",
@@ -699,12 +699,12 @@ describe("strict CLI parsing", () => {
 		expectUsageError(["push", "example"], "agency push")
 	})
 
-	test("accepts runner selection and command inspection for work", () => {
+	test("accepts agent selection and command inspection for work", () => {
 		expect(
 			parseCli([
 				"work",
 				"example",
-				"--runner",
+				"--agent",
 				"custom",
 				"--auto",
 				"--print-command",
@@ -712,10 +712,10 @@ describe("strict CLI parsing", () => {
 		).toMatchObject({
 			commandName: "work",
 			args: ["example"],
-			values: { runner: "custom", auto: true, "print-command": true },
+			values: { agent: "custom", auto: true, "print-command": true },
 		})
 		expect(() =>
-			parseCli(["work", "example", "--runner", "custom", "--claude"]),
+			parseCli(["work", "example", "--agent", "custom", "--claude"]),
 		).toThrow("cannot be combined")
 		expect(() => parseCli(["work", "prepare", "--print-command"])).toThrow(
 			"cannot be combined",
@@ -989,7 +989,7 @@ describe("strict CLI parsing", () => {
 				"release",
 				"--claimant",
 				"agent",
-				"--runner",
+				"--agent",
 				"opencode",
 				"--session-id",
 				"session",

package/src/cli-parser.ts

@@ -117,7 +117,7 @@ const mutationOptions = {
 const claimOptions = {
 	...outputOptions,
 	claimant: { type: "string" },
-	runner: { type: "string" },
+	agent: { type: "string" },
 	"session-id": { type: "string" },
 	revision: { type: "string" },
 	"expires-at": { type: "string" },
@@ -671,12 +671,12 @@ const commands = {
 		},
 		command: {
 			usage:
-				"agency claim <task-id> [phase-id] --claimant <id> --runner <id> --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]",
+				"agency claim <task-id> [phase-id] --claimant <id> --agent <id> --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]",
 			minArgs: 1,
 			maxArgs: 2,
 			options: [
 				"claimant",
-				"runner",
+				"agent",
 				"session-id",
 				"revision",
 				"expires-at",
@@ -684,7 +684,7 @@ const commands = {
 				"task",
 				"phase",
 			],
-			required: ["claimant", "runner", "session-id", "revision"],
+			required: ["claimant", "agent", "session-id", "revision"],
 		},
 	},
 	release: {
@@ -916,13 +916,13 @@ const commands = {
 	},
 	work: {
 		usage:
-			"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
+			"agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
 		options: {
 			...commonOptions,
 			...entitySelectorOptions,
 			json: { type: "boolean" },
 			"dry-run": { type: "boolean" },
-			runner: { type: "string" },
+			agent: { type: "string" },
 			auto: { type: "boolean" },
 			"print-command": { type: "boolean" },
 			opencode: { type: "boolean" },
@@ -932,7 +932,7 @@ const commands = {
 		},
 		command: {
 			usage:
-				"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
+				"agency work [<directory-or-task-id> | --epic <epic-id>] [--agent <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 2,
 			options: [
@@ -941,7 +941,7 @@ const commands = {
 				"epic",
 				"task",
 				"phase",
-				"runner",
+				"agent",
 				"auto",
 				"print-command",
 				"opencode",
@@ -951,8 +951,8 @@ const commands = {
 			],
 			conflicts: [
 				["opencode", "claude"],
-				["runner", "opencode"],
-				["runner", "claude"],
+				["agent", "opencode"],
+				["agent", "claude"],
 				["epic", "$positional"],
 			],
 		},
@@ -1689,7 +1689,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 				(parsed.values.epic ||
 					parsed.values.opencode ||
 					parsed.values.claude ||
-					parsed.values.runner ||
+					parsed.values.agent ||
 					parsed.values.auto ||
 					parsed.values["print-command"] ||
 					parsed.values.force))

package/src/cli.test.ts

@@ -192,7 +192,7 @@ describe("CLI", () => {
 					"claimed",
 					"--claimant",
 					"orchestrator",
-					"--runner",
+					"--agent",
 					"agent",
 					"--session-id",
 					"job-1",
@@ -205,7 +205,7 @@ describe("CLI", () => {
 		)
 		expect(claimed.claim).toMatchObject({
 			claimant: "orchestrator",
-			runner: "agent",
+			agent: "agent",
 			sessionId: "job-1",
 			state: "active",
 		})
@@ -216,7 +216,7 @@ describe("CLI", () => {
 				"claimed",
 				"--claimant",
 				"other",
-				"--runner",
+				"--agent",
 				"other-agent",
 				"--session-id",
 				"job-2",
@@ -232,7 +232,7 @@ describe("CLI", () => {
 			error: {
 				code: "CLAIM_CONFLICT",
 				retryable: true,
-				fields: { claim: { runner: "agent", sessionId: "job-1" } },
+				fields: { claim: { agent: "agent", sessionId: "job-1" } },
 			},
 		})
 
@@ -274,7 +274,7 @@ describe("CLI", () => {
 					"non-pr",
 					"--claimant",
 					"orchestrator",
-					"--runner",
+					"--agent",
 					"agent",
 					"--session-id",
 					"job-2",
@@ -1014,7 +1014,7 @@ status: open
 				`${JSON.stringify(
 					{
 						...agencyConfig,
-						runners: { noop: { command: ["true"] } },
+						agents: { noop: { command: ["true"] } },
 					},
 					null,
 					2,
@@ -1421,7 +1421,7 @@ status: open
 				await runCli(["task", "status", "example", "dropped", "--json"], root),
 			)
 			const blocked = await runCli(
-				["work", "--task", "example", "--runner", "noop"],
+				["work", "--task", "example", "--agent", "noop"],
 				root,
 			)
 			expect(blocked.exitCode).toBe(1)
@@ -1432,7 +1432,7 @@ status: open
 			).toBe("dropped")
 
 			const resumedTask = await runCli(
-				["work", "--task", "example", "--runner", "noop", "--force"],
+				["work", "--task", "example", "--agent", "noop", "--force"],
 				root,
 			)
 			expect(resumedTask).toMatchObject({ exitCode: 0, stderr: "" })
@@ -1457,7 +1457,7 @@ status: open
 					"pipeline",
 					"--phase",
 					"build",
-					"--runner",
+					"--agent",
 					"noop",
 					"--force",
 				],

package/src/commands/claim.ts

@@ -8,7 +8,7 @@ interface ClaimCommandOptions extends BaseCommandOptions {
 	readonly taskId?: string
 	readonly phaseId?: string
 	readonly claimant?: string
-	readonly runner?: string
+	readonly agent?: string
 	readonly sessionId?: string
 	readonly revision?: string
 	readonly expiresAt?: string
@@ -29,10 +29,10 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 		}
 		if (
 			options.operation === "claim" &&
-			(!options.claimant || !options.runner)
+			(!options.claimant || !options.agent)
 		) {
 			return yield* Effect.fail(
-				new Error("Claimant and runner identities are required"),
+				new Error("Claimant and agent identities are required"),
 			)
 		}
 		if (options.noPullRequest && !options.summary?.trim()) {
@@ -67,7 +67,7 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 						{
 							...common,
 							claimant: options.claimant!,
-							runner: options.runner!,
+							agent: options.agent!,
 							...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
 						},
 						cwd,
@@ -101,9 +101,9 @@ export const claimCommand = (options: ClaimCommandOptions) =>
 	})
 
 export const claimHelp = `
-Usage: agency claim <task-id> [phase-id] --claimant <id> --runner <id> --session-id <id> --revision <sha256>
+Usage: agency claim <task-id> [phase-id] --claimant <id> --agent <id> --session-id <id> --revision <sha256>
 
-Claim an execution unit. Use distinct claimant and runner identities for delegated
+Claim an execution unit. Use distinct claimant and agent identities for delegated
 work. --expires-at accepts an optional future ISO-8601 timestamp.
 `
 

package/src/commands/doctor.test.ts

@@ -39,7 +39,7 @@ describe("doctor command", () => {
 			"agency.json",
 			JSON.stringify({
 				version: 2,
-				runners: {
+				agents: {
 					missing: {
 						command: ["definitely-not-installed"],
 						autoCommand: ["also-not-installed", "{prompt}"],
@@ -87,12 +87,12 @@ status: open
 					status: "pass",
 				}),
 				expect.objectContaining({
-					id: "integration.runner.missing",
+					id: "integration.agent.missing",
 					level: "error",
 					status: "fail",
 				}),
 				expect.objectContaining({
-					id: "integration.runner.missing.auto",
+					id: "integration.agent.missing.auto",
 					level: "error",
 					status: "fail",
 				}),