@markjaquith/agency 2.19.0 → 2.20.0

package/README.md

@@ -10,7 +10,7 @@ or write.
 - [Bun](https://bun.sh) 1.0 or newer
 - Git
 - [GitHub CLI](https://cli.github.com/) for `agency pr create`
-- OpenCode or Claude Code for `agency work`
+- OpenCode, Claude Code, or a configured runner for `agency work`
 
 ## Installation
 
@@ -145,6 +145,41 @@ The configured command applies only to the writable checkout. Supplemental
 read-only repositories remain detached Git worktrees at their declared refs so
 they do not acquire writable branches.
 
+### Agent Runners
+
+OpenCode and Claude Code are built-in runner presets. Select either preset or a
+configured runner with `agency work --runner <name>`. A launch is fresh unless
+`AGENCY_SESSION_ID` is already set; resumed launches use the runner's
+`resumeCommand` when configured. The built-in presets use `--continue` only for
+resumed launches.
+
+Custom runners are direct argv commands, never shell snippets:
+
+```json
+{
+	"version": 2,
+	"runners": {
+		"custom": {
+			"command": ["my-agent", "--prompt", "{prompt}"],
+			"resumeCommand": ["my-agent", "resume", "{sessionId}", "{prompt}"],
+			"environment": { "MY_AGENT_TARGET": "{target}" }
+		}
+	}
+}
+```
+
+Available placeholders are `{prompt}`, `{workbase}`, `{target}`, `{task}`,
+`{phase}`, `{claimant}`, `{sessionId}`, and `{claimRevision}`. Task and phase
+placeholders are empty when they do not apply. If `resumeCommand` is omitted,
+the fresh command is also used for resumed sessions.
+
+Every runner receives the same `AGENCY_RUNNER`, `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.
+`--print-command` prints the exact cwd and argv plus non-secret environment keys
+without launching the runner.
+
 ### Custom Chooser Command
 
 Interactive selection uses a native numbered chooser by default. To use an
@@ -500,9 +535,9 @@ replaced with a revision-guarded claim.
 
 `agency work` claims an execution unit before launching its agent. Set
 `AGENCY_CLAIMANT`, `AGENCY_RUNNER`, or `AGENCY_SESSION_ID` to supply orchestrator
-identities; otherwise Agency derives them from the user, selected agent, and
-process. The launched agent receives `AGENCY_SESSION_ID` and
-`AGENCY_CLAIM_REVISION` for a later release or finish operation.
+identities; otherwise Agency derives them from the user and process. The selected
+runner name is recorded on the claim. The launched agent receives the normalized
+runner environment documented above for a later release or finish operation.
 
 ### Archive
 
@@ -520,7 +555,7 @@ before moving files, refuses dirty worktrees, and preserves branches.
 ### Work and Pull Requests
 
 ```text
-agency work [<directory> | --epic <epic-id>] [--opencode | --claude]
+agency work [<directory> | --epic <epic-id>] [--runner <name>] [--print-command]
 agency work prepare [target] [--dry-run] [--json]
 agency pr create <task-id> [phase-id] [--draft] [--json]
 ```
@@ -531,6 +566,10 @@ workbase, Agency first presents the registered workbases, then the selected
 workbase's hierarchy. If `fzf` is not installed, Agency prints the available
 choices and asks for an explicit directory.
 
+OpenCode is the default runner, with automatic Claude fallback when neither is
+explicitly selected. `--opencode` and `--claude` remain aliases for requiring
+their built-in presets.
+
 `agency work prepare` resolves an execution unit and creates or reuses its
 writable and reference worktrees without launching an agent or changing status.
 Its JSON result includes document and checkout paths, resolved commits, actions,

package/cli.ts

@@ -419,6 +419,8 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					opencode: options.opencode,
 					claude: options.claude,
+					runner: options.runner,
+					printCommand: options["print-command"],
 					force: options.force,
 					inputAllowed: options.inputAllowed,
 					cwd: options.cwd,

package/package.json

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

package/skills/agency/SKILL.md

@@ -279,7 +279,10 @@ agency work --epic <epic-id>
 agency work --task <task-id> [--phase <phase-id>] --workbase <selector>
 ```
 
-Use `--opencode` or `--claude` to require a specific agent. This command fetches
+Use `--runner <name>` to select a configured runner or the built-in `opencode`
+and `claude` presets. `--opencode` and `--claude` remain shorthand. Use
+`--print-command` to inspect the resolved cwd, argv, and non-secret environment
+without launching. This command fetches
 repositories for execution targets, creates or reuses their worktrees, and
 replaces the current process with the selected agent. With no directory it opens
 an `fzf` picker containing the workbase hierarchy. Pass `.`, or another

package/src/cli-parser.test.ts

@@ -321,6 +321,22 @@ describe("strict CLI parsing", () => {
 		)
 	})
 
+	test("accepts runner selection and command inspection for work", () => {
+		expect(
+			parseCli(["work", "example", "--runner", "custom", "--print-command"]),
+		).toMatchObject({
+			commandName: "work",
+			args: ["example"],
+			values: { runner: "custom", "print-command": true },
+		})
+		expect(() =>
+			parseCli(["work", "example", "--runner", "custom", "--claude"]),
+		).toThrow("cannot be combined")
+		expect(() => parseCli(["work", "prepare", "--print-command"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("accepts repeatable graph filters and rejects output conflicts", () => {
 		expect(
 			parseCli([

package/src/cli-parser.ts

@@ -439,19 +439,21 @@ const commands = {
 	},
 	work: {
 		usage:
-			"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
+			"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] | agency work prepare [target] [--dry-run] [--json]",
 		options: {
 			...commonOptions,
 			...entitySelectorOptions,
 			json: { type: "boolean" },
 			"dry-run": { type: "boolean" },
+			runner: { type: "string" },
+			"print-command": { type: "boolean" },
 			opencode: { type: "boolean" },
 			claude: { type: "boolean" },
 			force: { type: "boolean" },
 		},
 		command: {
 			usage:
-				"agency work [<directory-or-task-id> | --epic <epic-id>] | agency work prepare [target] [--dry-run] [--json]",
+				"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] | agency work prepare [target] [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 2,
 			options: [
@@ -460,12 +462,16 @@ const commands = {
 				"epic",
 				"task",
 				"phase",
+				"runner",
+				"print-command",
 				"opencode",
 				"claude",
 				"force",
 			],
 			conflicts: [
 				["opencode", "claude"],
+				["runner", "opencode"],
+				["runner", "claude"],
 				["epic", "$positional"],
 			],
 		},
@@ -998,6 +1004,8 @@ export function parseCli(args: readonly string[]): ParsedCli {
 				(parsed.values.epic ||
 					parsed.values.opencode ||
 					parsed.values.claude ||
+					parsed.values.runner ||
+					parsed.values["print-command"] ||
 					parsed.values.force))
 		) {
 			throw usageError(

package/src/commands/work.test.ts

@@ -47,8 +47,16 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 interface HarnessOptions {
 	readonly workspace?: ExecutionWorkspace
 	readonly materializeError?: Error
-	readonly available?: Partial<Record<"opencode" | "claude", boolean>>
+	readonly available?: Readonly<Record<string, boolean>>
 	readonly chooserCommand?: readonly string[]
+	readonly runners?: Record<
+		string,
+		{
+			command: readonly [string, ...string[]]
+			resumeCommand?: readonly [string, ...string[]]
+			environment?: Record<string, string>
+		}
+	>
 	readonly multiPhaseTasks?: readonly string[]
 	readonly epicRecords?: readonly any[]
 	readonly taskRecords?: readonly any[]
@@ -72,6 +80,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		args: readonly string[]
 		cwd: string
 	}> = []
+	const launchEnvironments: Array<Readonly<Record<string, string>>> = []
 	const materializeOptions: Array<
 		Parameters<WorktreeService["materialize"]>[3]
 	> = []
@@ -105,6 +114,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				config: {
 					version: 2 as const,
 					chooserCommand: options.chooserCommand,
+					runners: options.runners,
 				},
 			}),
 	}
@@ -204,7 +214,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		isDirectory: (path: string) =>
 			Effect.succeed(options.existingDirectories?.includes(path) ?? true),
 		runCommand: (args: readonly string[]) => {
-			const cli = args[1] as "opencode" | "claude"
+			const cli = args[1]!
 			events.push(`probe:${cli}`)
 			probes.push(cli)
 			return Effect.succeed({
@@ -214,9 +224,15 @@ const createHarness = (options: HarnessOptions = {}) => {
 			})
 		},
 	}
-	const launch = (cli: string, args: readonly string[], cwd: string) => {
+	const launch = (
+		cli: string,
+		args: readonly string[],
+		cwd: string,
+		environment: Readonly<Record<string, string>>,
+	) => {
 		events.push(`launch:${cli}`)
 		launches.push({ cli, args, cwd })
+		launchEnvironments.push(environment)
 	}
 	const defaultPick: PickWorkTarget = () => Effect.succeed(null)
 	const defaultPickWorkbase: PickWorkbase = () => Effect.succeed(null)
@@ -257,6 +273,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		events,
 		probes,
 		launches,
+		launchEnvironments,
 		materializeOptions,
 		statusUpdates,
 		shownTasks,
@@ -353,7 +370,6 @@ describe("work command", () => {
 			cli: "opencode",
 			args: [
 				"opencode",
-				"--continue",
 				"--prompt",
 				"Work on the epic. Read /workbase/epics/delivery/EPIC.md.",
 			],
@@ -403,7 +419,6 @@ describe("work command", () => {
 			cli: "opencode",
 			args: [
 				"opencode",
-				"--continue",
 				"--prompt",
 				"Work on the task. Read /workbase/tasks/delivery/TASK.md.",
 			],
@@ -429,7 +444,6 @@ describe("work command", () => {
 			cli: "opencode",
 			args: [
 				"opencode",
-				"--continue",
 				"--prompt",
 				"Start the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
 			],
@@ -596,7 +610,7 @@ describe("work command", () => {
 
 		await expect(
 			harness.run({ taskId: "example", opencode: true, claude: true }),
-		).rejects.toThrow("Cannot use both --opencode and --claude")
+		).rejects.toThrow("Cannot combine --runner, --opencode, and --claude")
 		expect(harness.events).toEqual([])
 	})
 
@@ -624,7 +638,6 @@ describe("work command", () => {
 				cli: "opencode",
 				args: [
 					"opencode",
-					"--continue",
 					"--prompt",
 					"Start the task. Read /workbase/tasks/example/TASK.md.",
 				],
@@ -638,14 +651,18 @@ describe("work command", () => {
 		])
 	})
 
-	test("continues OpenCode with explicit task and phase context", async () => {
+	test("resumes OpenCode deterministically when a session identity exists", async () => {
 		const harness = createHarness({ workspace: multiPhaseWorkspace })
-
-		await harness.run({
-			taskId: "example",
-			phaseId: "implementation",
-			opencode: true,
-		})
+		process.env.AGENCY_SESSION_ID = "existing-session"
+		try {
+			await harness.run({
+				taskId: "example",
+				phaseId: "implementation",
+				opencode: true,
+			})
+		} finally {
+			delete process.env.AGENCY_SESSION_ID
+		}
 
 		expect(harness.launches[0]).toEqual({
 			cli: "opencode",
@@ -659,6 +676,78 @@ describe("work command", () => {
 		})
 	})
 
+	test("expands a named runner with shared context and claim identity", async () => {
+		const harness = createHarness({
+			available: { codex: true },
+			runners: {
+				custom: {
+					command: ["codex", "--task", "{task}", "{prompt}"],
+					environment: {
+						CUSTOM_TARGET: "{target}",
+						AGENCY_TARGET: "cannot-override",
+					},
+				},
+			},
+		})
+
+		await harness.run({ taskId: "example", runner: "custom" })
+
+		expect(harness.probes).toEqual(["codex"])
+		expect(harness.launches[0]).toEqual({
+			cli: "codex",
+			args: [
+				"codex",
+				"--task",
+				"example",
+				"Start the task. Read /workbase/tasks/example/TASK.md.",
+			],
+			cwd: singlePhaseWorkspace.writablePath,
+		})
+		expect(harness.launchEnvironments[0]).toMatchObject({
+			AGENCY_RUNNER: "custom",
+			AGENCY_CLAIMANT: process.env.USER ?? "agency",
+			AGENCY_WORKBASE: "/workbase",
+			AGENCY_TARGET: "execution-unit:task/example",
+			AGENCY_TASK_ID: "example",
+			AGENCY_PHASE_ID: "",
+			AGENCY_CLAIM_REVISION: "1".repeat(64),
+			CUSTOM_TARGET: "execution-unit:task/example",
+		})
+	})
+
+	test("prints the exact command contract without launching and omits secrets", async () => {
+		const harness = createHarness({
+			available: { agent: true },
+			runners: {
+				custom: {
+					command: ["agent", "{prompt}"],
+					environment: {
+						VISIBLE: "{task}",
+						API_TOKEN: "do-not-print",
+					},
+				},
+			},
+		})
+
+		const output = await captureLogs(() =>
+			harness.run({
+				taskId: "example",
+				runner: "custom",
+				printCommand: true,
+			}),
+		)
+		const printed = JSON.parse(output.join("\n"))
+
+		expect(harness.launches).toEqual([])
+		expect(printed.cwd).toBe(singlePhaseWorkspace.writablePath)
+		expect(printed.argv).toEqual([
+			"agent",
+			"Start the task. Read /workbase/tasks/example/TASK.md.",
+		])
+		expect(printed.environment.VISIBLE).toBe("example")
+		expect(printed.environment.API_TOKEN).toBeUndefined()
+	})
+
 	test("automatically falls back to Claude", async () => {
 		const harness = createHarness({ available: { opencode: false } })
 
@@ -729,7 +818,7 @@ describe("work command", () => {
 			verboseHarness.run({ taskId: "example", verbose: true }),
 		)
 		expect(verboseLogs).toEqual([
-			"Launching command: opencode --continue --prompt 'Start the task. Read /workbase/tasks/example/TASK.md.' (cwd: /workbase/tasks/example/code/agency)",
+			"Launching command: opencode --prompt 'Start the task. Read /workbase/tasks/example/TASK.md.' (cwd: /workbase/tasks/example/code/agency)",
 		])
 		expect(verboseHarness.materializeOptions[0]?.verbose).toBe(true)
 

package/src/commands/work.ts

@@ -23,6 +23,11 @@ import {
 	resolveWorkbase,
 	type PickWorkbase,
 } from "../workbase/workbase-choice"
+import {
+	printableEnvironment,
+	resolveRunnerCommand,
+	runnerEnvironment,
+} from "../workbase/runner-command"
 
 interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -31,10 +36,17 @@ interface WorkOptions extends BaseCommandOptions {
 	readonly epicId?: string
 	readonly opencode?: boolean
 	readonly claude?: boolean
+	readonly runner?: string
+	readonly printCommand?: boolean
 	readonly force?: boolean
 }
 
-type LaunchAgent = (cli: string, args: readonly string[], cwd: string) => void
+type LaunchAgent = (
+	cli: string,
+	args: readonly string[],
+	cwd: string,
+	environment: Readonly<Record<string, string>>,
+) => void
 
 const formatCommand = (args: readonly string[]) =>
 	args
@@ -68,13 +80,15 @@ export const work = (
 	pickBase: PickWorkbase = pickWorkbase,
 ) =>
 	Effect.gen(function* () {
-		if (options.opencode && options.claude) {
+		if (
+			(options.opencode && options.claude) ||
+			(options.runner && (options.opencode || options.claude))
+		) {
 			return yield* Effect.fail(
-				new Error("Cannot use both --opencode and --claude"),
+				new Error("Cannot combine --runner, --opencode, and --claude"),
 			)
 		}
-		const previousSessionId = process.env.AGENCY_SESSION_ID
-		const previousClaimRevision = process.env.AGENCY_CLAIM_REVISION
+		const previousEnvironment = { ...process.env }
 		if (
 			options.epicId &&
 			(options.directory || options.taskId || options.phaseId)
@@ -104,6 +118,7 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
+		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null
 		if (options.epicId) {
@@ -199,7 +214,6 @@ export const work = (
 					new Error("No ready work targets found in this workbase"),
 				)
 			}
-			const { config } = yield* workbase.loadConfig(root)
 			target = yield* pick(choices, config.chooserCommand)
 			if (!target) return
 		}
@@ -233,13 +247,49 @@ export const work = (
 			launchPath = workspace.writablePath
 		}
 
-		const requested = options.claude ? "claude" : "opencode"
-		let cli = requested
+		const explicitlyRequested = Boolean(
+			options.runner ||
+			options.opencode ||
+			options.claude ||
+			process.env.AGENCY_RUNNER,
+		)
+		let runner =
+			options.runner ??
+			process.env.AGENCY_RUNNER ??
+			(options.claude ? "claude" : "opencode")
+		const claimant = process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency"
+		const sessionId =
+			process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
+		const resume = process.env.AGENCY_SESSION_ID !== undefined
+		let claimRevision = ""
+		let variables = {
+			prompt,
+			workbase: root,
+			target: targetNodeId(target),
+			task: target.kind === "epic" ? "" : target.taskId,
+			phase: target.kind === "phase" ? target.phaseId : "",
+			claimant,
+			sessionId,
+			claimRevision,
+		}
+		let resolved = resolveRunnerCommand(
+			runner,
+			config.runners,
+			variables,
+			resume,
+		)
+		let cli = resolved.argv[0]!
 		let available = yield* fs.runCommand(["which", cli], {
 			captureOutput: true,
 		})
-		if (available.exitCode !== 0 && !options.opencode && !options.claude) {
-			cli = "claude"
+		if (
+			available.exitCode !== 0 &&
+			!explicitlyRequested &&
+			runner === "opencode"
+		) {
+			runner = "claude"
+			resolved = resolveRunnerCommand(runner, config.runners, variables, resume)
+			cli = resolved.argv[0]!
 			available = yield* fs.runCommand(["which", cli], { captureOutput: true })
 		}
 		if (available.exitCode !== 0) {
@@ -251,36 +301,55 @@ export const work = (
 		) {
 			const phaseId = target.kind === "phase" ? target.phaseId : undefined
 			const current = yield* claims.inspect(target.taskId, phaseId, root)
-			const sessionId =
-				process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
 			const acquired = yield* claims.claim(
 				{
 					taskId: target.taskId,
 					...(phaseId ? { phaseId } : {}),
-					claimant: process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency",
-					runner: process.env.AGENCY_RUNNER ?? cli,
+					claimant,
+					runner,
 					sessionId,
 					revision: current.revision,
 				},
 				root,
 			)
-			process.env.AGENCY_SESSION_ID = sessionId
-			process.env.AGENCY_CLAIM_REVISION = acquired.revision
+			claimRevision = acquired.revision
 		}
 
-		const args =
-			cli === "opencode" ? ["--continue", "--prompt", prompt] : [prompt]
+		variables = { ...variables, claimRevision }
+		resolved = resolveRunnerCommand(runner, config.runners, variables, resume)
+		cli = resolved.argv[0]!
+		const environment = {
+			...resolved.environment,
+			...runnerEnvironment(runner, variables),
+		}
+		if (options.printCommand) {
+			log(
+				JSON.stringify(
+					{
+						cwd: launchPath,
+						argv: resolved.argv,
+						environment: printableEnvironment(environment),
+					},
+					null,
+					2,
+				),
+			)
+			return
+		}
+		for (const [key, value] of Object.entries(environment)) {
+			process.env[key] = value
+		}
 		verboseLog(
-			`Launching command: ${formatCommand([cli, ...args])} (cwd: ${launchPath})`,
+			`Launching command: ${formatCommand(resolved.argv)} (cwd: ${launchPath})`,
 		)
 		try {
-			launch(cli, [cli, ...args], launchPath)
+			launch(cli, resolved.argv, launchPath, environment)
 		} finally {
-			if (previousSessionId === undefined) delete process.env.AGENCY_SESSION_ID
-			else process.env.AGENCY_SESSION_ID = previousSessionId
-			if (previousClaimRevision === undefined)
-				delete process.env.AGENCY_CLAIM_REVISION
-			else process.env.AGENCY_CLAIM_REVISION = previousClaimRevision
+			for (const key of Object.keys(environment)) {
+				const previous = previousEnvironment[key]
+				if (previous === undefined) delete process.env[key]
+				else process.env[key] = previous
+			}
 		}
 	})
 
@@ -344,7 +413,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 	})
 
 export const help = `
-Usage: agency work [<directory-or-task-id> | --epic <epic-id>]
+Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>]
        agency work prepare [target] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
@@ -362,8 +431,10 @@ Options:
   --phase <id>         Work on a phase selected with --task
   --workbase <target>  Select a workbase by ID, name, or path
   --cwd <path>         Resolve context from a specific directory
-  --opencode           Require OpenCode
-  --claude             Require Claude Code
+  --runner <name>      Select a configured runner or built-in preset
+  --print-command      Print cwd, argv, and non-secret environment without launch
+  --opencode           Require the OpenCode preset
+  --claude             Require the Claude Code preset
   --force              Override readiness and terminal-state guards
   --no-input           Never open an interactive selector
 

package/src/services/WorkbaseService.test.ts

@@ -235,6 +235,25 @@ describe("WorkbaseService", () => {
 		).rejects.toThrow("{worktree}")
 	})
 
+	test("rejects an unknown runner command placeholder", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				runners: { custom: { command: ["agent", "{unknown}"] } },
+			}),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.discover(root)),
+				),
+			),
+		).rejects.toThrow("{unknown}")
+	})
+
 	test("validates a workbase with an epic and multi-phase task", async () => {
 		await write(root, "agency.json", '{"version":2}\n')
 		await mkdir(join(root, "repos/agency"), { recursive: true })

package/src/services/WorkbaseService.ts

@@ -21,6 +21,7 @@ import {
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import { validateRunners } from "../workbase/runner-command"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -277,6 +278,17 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								try {
+									validateRunners(decoded.value.runners)
+								} catch (cause) {
+									return yield* new WorkbaseConfigError({
+										path: configPath,
+										message:
+											cause instanceof Error
+												? cause.message
+												: "Invalid runner configuration",
+									})
+								}
 								return current
 							}
 						}

package/src/workbase/runner-command.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test"
+import {
+	printableEnvironment,
+	resolveRunnerCommand,
+	runnerEnvironment,
+	validateRunners,
+} from "./runner-command"
+
+const variables = {
+	prompt: "Read the task.",
+	workbase: "/workbase",
+	target: "execution-unit:phase/task/build",
+	task: "task",
+	phase: "build",
+	claimant: "orchestrator",
+	sessionId: "session-1",
+	claimRevision: "revision-1",
+}
+
+describe("runner commands", () => {
+	test("uses deterministic fresh and resume commands for built-in presets", () => {
+		expect(
+			resolveRunnerCommand("opencode", undefined, variables, false).argv,
+		).toEqual(["opencode", "--prompt", "Read the task."])
+		expect(
+			resolveRunnerCommand("opencode", undefined, variables, true).argv,
+		).toEqual(["opencode", "--continue", "--prompt", "Read the task."])
+		expect(
+			resolveRunnerCommand("claude", undefined, variables, true).argv,
+		).toEqual(["claude", "--continue", "Read the task."])
+	})
+
+	test("expands configured argv and environment without a shell", () => {
+		const resolved = resolveRunnerCommand(
+			"custom",
+			{
+				custom: {
+					command: ["agent", "--target={target}", "{prompt}"],
+					environment: { CUSTOM_SESSION: "{sessionId}" },
+				},
+			},
+			variables,
+			false,
+		)
+
+		expect(resolved).toEqual({
+			argv: [
+				"agent",
+				"--target=execution-unit:phase/task/build",
+				"Read the task.",
+			],
+			environment: { CUSTOM_SESSION: "session-1" },
+		})
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			validateRunners({ custom: { command: ["agent", "{unknown}"] } }),
+		).toThrow("Unknown runner 'custom' placeholder: {unknown}")
+	})
+
+	test("provides normalized Agency environment and filters secret values", () => {
+		const environment = {
+			...runnerEnvironment("custom", variables),
+			VISIBLE: "yes",
+			ACCESS_TOKEN: "secret",
+		}
+
+		expect(environment).toMatchObject({
+			AGENCY_RUNNER: "custom",
+			AGENCY_CLAIMANT: "orchestrator",
+			AGENCY_TARGET: "execution-unit:phase/task/build",
+			AGENCY_TASK_ID: "task",
+			AGENCY_PHASE_ID: "build",
+		})
+		expect(printableEnvironment(environment).VISIBLE).toBe("yes")
+		expect(printableEnvironment(environment).ACCESS_TOKEN).toBeUndefined()
+	})
+})

package/src/workbase/runner-command.ts

@@ -0,0 +1,118 @@
+import type { WorkbaseConfig } from "./schemas"
+
+export interface RunnerCommandVariables {
+	readonly prompt: string
+	readonly workbase: string
+	readonly target: string
+	readonly task: string
+	readonly phase: string
+	readonly claimant: string
+	readonly sessionId: string
+	readonly claimRevision: string
+}
+
+interface RunnerDefinition {
+	readonly command: readonly string[]
+	readonly resumeCommand?: readonly string[]
+	readonly environment?: Readonly<Record<string, string>>
+}
+
+const PLACEHOLDERS = new Set<keyof RunnerCommandVariables>([
+	"prompt",
+	"workbase",
+	"target",
+	"task",
+	"phase",
+	"claimant",
+	"sessionId",
+	"claimRevision",
+])
+
+const BUILTIN_RUNNERS: Readonly<Record<string, RunnerDefinition>> = {
+	opencode: {
+		command: ["opencode", "--prompt", "{prompt}"],
+		resumeCommand: ["opencode", "--continue", "--prompt", "{prompt}"],
+	},
+	claude: {
+		command: ["claude", "{prompt}"],
+		resumeCommand: ["claude", "--continue", "{prompt}"],
+	},
+}
+
+const validateTemplate = (runner: string, value: string) => {
+	for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+		const placeholder = match[1]!
+		if (!PLACEHOLDERS.has(placeholder as keyof RunnerCommandVariables)) {
+			throw new Error(
+				`Unknown runner '${runner}' placeholder: {${placeholder}}`,
+			)
+		}
+	}
+}
+
+export const validateRunners = (runners: WorkbaseConfig["runners"]): void => {
+	for (const [name, runner] of Object.entries(runners ?? {})) {
+		for (const value of [
+			...runner.command,
+			...(runner.resumeCommand ?? []),
+			...Object.values(runner.environment ?? {}),
+		]) {
+			validateTemplate(name, value)
+		}
+	}
+}
+
+const expand = (value: string, variables: RunnerCommandVariables) =>
+	value.replaceAll(
+		/\{([^{}]+)\}/g,
+		(match, placeholder: string) =>
+			variables[placeholder as keyof RunnerCommandVariables] ?? match,
+	)
+
+export const resolveRunnerCommand = (
+	name: string,
+	configured: WorkbaseConfig["runners"],
+	variables: RunnerCommandVariables,
+	resume: boolean,
+) => {
+	validateRunners(configured)
+	const definition = configured?.[name] ?? BUILTIN_RUNNERS[name]
+	if (!definition) throw new Error(`Unknown runner: ${name}`)
+	const template =
+		resume && definition.resumeCommand
+			? definition.resumeCommand
+			: definition.command
+	const argv = template.map((argument) => expand(argument, variables))
+	const environment = Object.fromEntries(
+		Object.entries(definition.environment ?? {}).map(([key, value]) => [
+			key,
+			expand(value, variables),
+		]),
+	)
+	return { argv, environment }
+}
+
+export const runnerEnvironment = (
+	runner: string,
+	variables: RunnerCommandVariables,
+): Record<string, string> => ({
+	AGENCY_RUNNER: runner,
+	AGENCY_CLAIMANT: variables.claimant,
+	AGENCY_SESSION_ID: variables.sessionId,
+	AGENCY_CLAIM_REVISION: variables.claimRevision,
+	AGENCY_WORKBASE: variables.workbase,
+	AGENCY_TARGET: variables.target,
+	AGENCY_TASK_ID: variables.task,
+	AGENCY_PHASE_ID: variables.phase,
+	AGENCY_PROMPT: variables.prompt,
+})
+
+const SECRET_NAME =
+	/(secret|token|password|credential|api[_-]?key|private[_-]?key)/i
+
+export const printableEnvironment = (environment: Record<string, string>) =>
+	Object.fromEntries(
+		Object.entries(environment)
+			.filter(([key]) => !SECRET_NAME.test(key))
+			.sort(([left], [right]) => left.localeCompare(right)),
+	)

package/src/workbase/schemas.test.ts

@@ -78,6 +78,32 @@ describe("body-of-work descriptions", () => {
 	})
 })
 
+describe("runner configuration", () => {
+	test("accepts named argv commands with resume commands and environment", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			runners: {
+				custom: {
+					command: ["agent", "{prompt}"],
+					resumeCommand: ["agent", "resume", "{sessionId}"],
+					environment: { CUSTOM_TARGET: "{target}" },
+				},
+			},
+		})
+
+		expect(config.runners?.custom?.command).toEqual(["agent", "{prompt}"])
+	})
+
+	test("rejects shell strings in place of argv arrays", () => {
+		expect(() =>
+			Schema.decodeUnknownSync(WorkbaseConfig)({
+				version: 2,
+				runners: { custom: { command: "agent {prompt}" } },
+			}),
+		).toThrow()
+	})
+})
+
 describe("work status", () => {
 	const supportedStatuses: Record<WorkStatus, true> = {
 		open: true,

package/src/workbase/schemas.ts

@@ -1,6 +1,9 @@
 import { Schema } from "@effect/schema"
 
 const NonEmptyString = Schema.String.pipe(Schema.minLength(1))
+const EnvironmentName = NonEmptyString.pipe(
+	Schema.pattern(/^[A-Za-z_][A-Za-z0-9_]*$/),
+)
 
 const Description = Schema.optional(NonEmptyString)
 
@@ -52,6 +55,18 @@ export const WorkbaseConfig = Schema.Struct({
 	version: Schema.Literal(2),
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+	runners: Schema.optional(
+		Schema.Record({
+			key: EntityId,
+			value: Schema.Struct({
+				command: Schema.NonEmptyArray(NonEmptyString),
+				resumeCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+				environment: Schema.optional(
+					Schema.Record({ key: EnvironmentName, value: Schema.String }),
+				),
+			}),
+		}),
+	),
 })
 
 export const LegacyWorkbaseRegistry = Schema.Struct({