@markjaquith/agency 2.63.0 → 2.65.0

package/README.md

@@ -246,6 +246,55 @@ Supplemental read-only repositories remain detached Git worktrees at their
 declared refs so they do not acquire writable branches. Jj workbases always use
 jj workspaces and ignore this Git-specific customization.
 
+### Custom Jj Workspace Command
+
+Jj workbases normally create managed workspaces with `jj workspace add`. Set
+`workspaceCreateCommand` to an argv template when another tool should create or
+adopt a prepared workspace directly at Agency's destination:
+
+```json
+{
+	"version": 2,
+	"vcs": "jj",
+	"workspaceCreateCommand": [
+		"my-prewarm-tool",
+		"adopt",
+		"--repo",
+		"{repo}",
+		"--destination",
+		"{workspace}",
+		"--name",
+		"{name}",
+		"--revision",
+		"{revision}"
+	]
+}
+```
+
+Available placeholders are:
+
+- `{repo}`: absolute repository alias path under `repos/`
+- `{workspace}`: absolute managed workspace path Agency requires
+- `{name}`: unique jj workspace name Agency requires
+- `{revision}`: exact commit the new working copy must be based on
+- `{kind}`: `writable` or `reference`
+- `{requestedRef}`: configured branch, reference, or review commit
+
+`{repo}`, `{workspace}`, `{name}`, and `{revision}` are required. Agency invokes
+the command directly without a shell and sets matching `AGENCY_REPO`,
+`AGENCY_WORKSPACE`, `AGENCY_WORKSPACE_NAME`, `AGENCY_REVISION`,
+`AGENCY_CHECKOUT_KIND`, and `AGENCY_REQUESTED_REF` environment variables. The
+command applies to each new jj checkout and must leave `{workspace}` registered
+under `{name}` with its working-copy parent at `{revision}`. This lets a prewarm
+tool move or adopt a prepared workspace without first paying for Agency's normal
+full checkout.
+
+Agency validates the registration, name, path, and revision before running any
+`postCheckoutCommand`. A failed command or validation removes a partially
+created workspace when possible and otherwise reports manual recovery. Resume
+restoration continues to use Agency's built-in exact-target recovery path.
+Git workbases ignore this jj-specific customization.
+
 ### Post-checkout Commands
 
 Each repository declaration may provide a VCS-neutral `postCheckoutCommand` argv
@@ -267,8 +316,8 @@ shell, with the new checkout as its working directory:
 The hook runs for each newly created managed checkout, including writable and
 reference checkouts, after Git worktree or jj workspace creation has completed
 and Agency has validated the checkout. It does not run for a reused checkout or
-for inspection-only commands. A custom `worktreeCreateCommand` completes and is
-validated before this hook runs.
+for inspection-only commands. A custom `worktreeCreateCommand` or
+`workspaceCreateCommand` completes and is validated before this hook runs.
 
 Available placeholders and matching environment variables are:
 
@@ -517,12 +566,13 @@ pull request, dropping, reopening, or archiving. Cancelling either chooser makes
 no changes, and the command refreshes the graph before dispatch so a stale
 selection cannot act on changed work.
 
-Use `--epic <id>`, `--task <id>`, or `--task <id> --phase <id>` to skip work-item
-selection. `--dry-run` still prompts for an action but prints the exact Agency
-command instead of executing it. `--json` never prompts or executes; it returns
-matching targets, status and readiness details, document revisions, and each
-available action's command argv. With no selector, JSON includes every active
-work item.
+Use an existing directory, a positional task ID, `--epic <id>`, `--task <id>`,
+or `--task <id> --phase <id>` to skip work-item selection. For example,
+`agency act .` selects the current task or phase. `--dry-run` still prompts for
+an action but prints the exact Agency command instead of executing it. `--json`
+never prompts or executes; it returns matching targets, status and readiness
+details, document revisions, and each available action's command argv. With no
+selector, JSON includes every active work item.
 
 `--auto` is included in generated or executed work commands, and `--draft` is
 included in generated or executed pull request commands.

package/cli-main.ts

@@ -177,10 +177,11 @@ const VERSION = packageJson.version
 // Define commands
 const commands: Record<string, Command> = {
 	act: {
-		run: async (_args: string[], options: Record<string, any>) => {
+		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) return console.log(actHelp)
 			await runCommand(
 				act({
+					directory: args[0],
 					auto: options.auto,
 					draft: options.draft,
 					dryRun: options["dry-run"],

package/package.json

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

package/src/cli-parser.test.ts

@@ -31,7 +31,10 @@ describe("strict CLI parsing", () => {
 			},
 		})
 		expect(parseCli(["act", "--json"]).values.json).toBe(true)
-		expectUsageError(["act", "task-id"], "agency act")
+		expect(parseCli(["act", "task-id"]).args).toEqual(["task-id"])
+		expect(parseCli(["act", "."]).args).toEqual(["."])
+		expectUsageError(["act", "one", "two"], "agency act")
+		expectUsageError(["act", ".", "--task", "example"], "agency act")
 		expectUsageError(["act", "--phase", "build"], "agency act")
 		expectUsageError(
 			["act", "--epic", "roadmap", "--task", "example"],

package/src/cli-parser.ts

@@ -148,7 +148,7 @@ const commands = {
 	},
 	act: {
 		usage:
-			"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+			"agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
@@ -158,9 +158,9 @@ const commands = {
 		},
 		command: {
 			usage:
-				"agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
+				"agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]",
 			minArgs: 0,
-			maxArgs: 0,
+			maxArgs: 1,
 			options: ["epic", "task", "phase", "dry-run", "json", "auto", "draft"],
 			conflicts: [
 				["dry-run", "json"],
@@ -1198,7 +1198,7 @@ function applyEntitySelectors(
 			spec.usage,
 		)
 	}
-	if (commandName === "work" || commandName === "context") {
+	if (["act", "work", "context"].includes(commandName)) {
 		if (
 			positionals.length >
 			(commandName === "work" && positionals[0] === "prepare" ? 1 : 0)

package/src/commands/act.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureLogs,
@@ -118,6 +119,100 @@ describe("act command", () => {
 		expect(await readTaskStatus("example")).toBe("open")
 	})
 
+	test("resolves a positional path and task ID without prompting for an item", async () => {
+		await createTask("example")
+		await mkdir(join(root, "tasks/example/code/agency"), { recursive: true })
+		for (const options of [
+			{ cwd: join(root, "tasks/example"), directory: "." },
+			{ cwd: join(root, "tasks/example"), directory: "code/agency" },
+			{ cwd: root, directory: "example" },
+		]) {
+			const prompts: string[] = []
+			await runTestEffect(
+				act(
+					{ ...options, inputAllowed: true, dryRun: true, silent: true },
+					scriptedInteraction(["drop"], (prompt) => prompts.push(prompt)),
+				),
+			)
+			expect(prompts).toEqual(["Act on task example"])
+		}
+	})
+
+	test("resolves a positional phase path without prompting for an item", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["multi"],
+				multiPhase: true,
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "create",
+				args: ["multi", "build"],
+				repo: "agency",
+				branch: "task/multi-build",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		const prompts: string[] = []
+		await runTestEffect(
+			act(
+				{
+					cwd: join(root, "tasks/multi/phases/build"),
+					directory: ".",
+					inputAllowed: true,
+					dryRun: true,
+					silent: true,
+				},
+				scriptedInteraction(["drop"], (prompt) => prompts.push(prompt)),
+			),
+		)
+
+		expect(prompts).toEqual(["Act on phase multi/build"])
+	})
+
+	test("orders owned items hierarchically and omits items without actions", async () => {
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["multi"],
+				multiPhase: true,
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "create",
+				args: ["multi", "build"],
+				repo: "agency",
+				branch: "task/multi-build",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		let choices: readonly Choice<unknown>[] = []
+		await runTestEffect(
+			act(
+				{ cwd: root, inputAllowed: true },
+				scriptedInteraction([null], (_prompt, offered) => {
+					choices = offered
+				}),
+			),
+		)
+
+		expect(choices.map((choice) => [choice.value, choice.depth])).toEqual([
+			["task:multi", 0],
+			["phase:multi/build", 1],
+		])
+	})
+
 	test("returns structured actions and argv for agents", async () => {
 		await createTask("example")
 		const logs = await captureLogs(() =>

package/src/commands/act.ts

@@ -1,6 +1,8 @@
 import { Effect } from "effect"
+import { isAbsolute, relative, resolve, sep } from "node:path"
 import type { GraphNode } from "../graph-schema"
 import { isTerminalStatus } from "../readiness"
+import { FileSystemService } from "../services/FileSystemService"
 import { GraphService } from "../services/GraphService"
 import { WorkbaseService } from "../services/WorkbaseService"
 import type { BaseCommandOptions } from "../utils/command"
@@ -29,6 +31,7 @@ export interface ActInteraction {
 }
 
 interface ActOptions extends BaseCommandOptions {
+	readonly directory?: string
 	readonly auto?: boolean
 	readonly draft?: boolean
 	readonly dryRun?: boolean
@@ -49,13 +52,49 @@ const entityDescription = (node: EntityNode) =>
 		? ` - ${node.data.description}`
 		: ""
 
+const orderedEntities = (
+	nodes: readonly EntityNode[],
+	edges: readonly {
+		readonly kind: string
+		readonly from: string
+		readonly to: string
+	}[],
+) => {
+	const byId = new Map(nodes.map((node) => [node.id, node]))
+	const children = new Map<string, EntityNode[]>()
+	const owned = new Set<string>()
+	for (const edge of edges) {
+		if (edge.kind !== "owns") continue
+		const parent = byId.get(edge.from)
+		const child = byId.get(edge.to)
+		if (!parent || !child) continue
+		children.set(edge.from, [...(children.get(edge.from) ?? []), child])
+		owned.add(child.id)
+	}
+
+	const ordered: { readonly node: EntityNode; readonly depth: number }[] = []
+	const append = (node: EntityNode, depth: number) => {
+		ordered.push({ node, depth })
+		for (const child of children.get(node.id) ?? []) append(child, depth + 1)
+	}
+	for (const node of nodes) {
+		if (!owned.has(node.id)) append(node, 0)
+	}
+	return ordered
+}
+
 const entityChoices = (
 	nodes: readonly EntityNode[],
+	edges: readonly {
+		readonly kind: string
+		readonly from: string
+		readonly to: string
+	}[],
 ): readonly Choice<string>[] =>
-	nodes.map((node, index) => ({
+	orderedEntities(nodes, edges).map(({ node, depth }, index) => ({
 		key: String(index),
 		label: `[${node.status}] ${node.kind} ${node.key}${entityDescription(node)}`,
-		depth: node.kind === "phase" ? 1 : 0,
+		depth,
 		segments: [
 			{ text: `[${node.status}] `, color: macchiato.overlay1 },
 			{ text: `${node.kind} `, color: macchiato.sapphire },
@@ -229,6 +268,26 @@ const selectedEntityKey = (options: ActOptions) =>
 				? `task:${options.taskId}`
 				: undefined
 
+const pathEntityKey = (
+	directory: string | undefined,
+	isDirectory: boolean,
+	root: string,
+	startPath: string,
+) => {
+	if (!directory) return undefined
+	if (!isDirectory) return `task:${directory}`
+	const path = relative(root, startPath)
+	const parts =
+		!path || isAbsolute(path) || path.startsWith(`..${sep}`)
+			? []
+			: path.split(sep)
+	if (parts[0] === "epics" && parts[1]) return `epic:${parts[1]}`
+	if (parts[0] !== "tasks" || !parts[1]) return undefined
+	return parts[2] === "phases" && parts[3]
+		? `phase:${parts[1]}/${parts[3]}`
+		: `task:${parts[1]}`
+}
+
 const sameActions = (
 	left: readonly Choice<ActAction>[],
 	right: readonly Choice<ActAction>[],
@@ -250,11 +309,19 @@ export const act = (
 			)
 		}
 		const cwd = options.cwd ?? process.cwd()
+		const fs = yield* FileSystemService
 		const workbase = yield* WorkbaseService
 		const graphs = yield* GraphService
 		const { log } = createLoggers(options)
-		const { config } = yield* workbase.loadConfig(cwd)
-		const graph = yield* graphs.get({ cwd })
+		const directoryPath = options.directory
+			? resolve(cwd, options.directory)
+			: undefined
+		const isDirectory = directoryPath
+			? yield* fs.isDirectory(directoryPath)
+			: false
+		const startPath = isDirectory && directoryPath ? directoryPath : cwd
+		const { root, config } = yield* workbase.loadConfig(startPath)
+		const graph = yield* graphs.get({ cwd: root })
 		const nodes = graph.nodes.filter(
 			(node): node is EntityNode =>
 				node.kind === "epic" || node.kind === "task" || node.kind === "phase",
@@ -269,7 +336,9 @@ export const act = (
 			)
 		}
 
-		const requestedKey = selectedEntityKey(options)
+		const requestedKey =
+			selectedEntityKey(options) ??
+			pathEntityKey(options.directory, isDirectory, root, startPath)
 		const matchingNodes = requestedKey
 			? nodes.filter((node) => entityKey(node) === requestedKey)
 			: nodes
@@ -293,11 +362,21 @@ export const act = (
 			return
 		}
 
+		const selectableNodes = nodes.filter(
+			(node) => actionChoices(node, graph.nodes).length > 0,
+		)
+		if (!requestedKey && selectableNodes.length === 0) {
+			return yield* Effect.fail(
+				new Error(
+					"No work items with available actions found in this workbase",
+				),
+			)
+		}
 		const selectedKey =
 			requestedKey ??
 			(yield* interaction.select(
 				"Act on",
-				entityChoices(nodes),
+				entityChoices(selectableNodes, graph.edges),
 				config.chooserCommand,
 			))
 		if (selectedKey === null) return
@@ -424,10 +503,12 @@ export const act = (
 	})
 
 export const help = `
-Usage: agency act [--epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]
+Usage: agency act [<directory-or-task-id> | --epic <id> | --task <id> [--phase <id>]] [--dry-run | --json] [--auto] [--draft]
 
 Interactively choose an active work item and a state-aware lifecycle action.
-Selectors skip work-item selection. --dry-run prints the selected action's exact
+An existing positional directory selects its containing epic, task, or phase;
+otherwise the positional value is a task ID. Selectors skip work-item selection.
+--dry-run prints the selected action's exact
 Agency command without executing it. --json lists targets, available actions,
 and command argv without prompting or executing.
 

package/src/services/DoctorService.ts

@@ -173,6 +173,15 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 									] as const,
 								]
 							: []),
+						...(config.workspaceCreateCommand
+							? [
+									[
+										"integration.workspace-create",
+										config.workspaceCreateCommand,
+										"Workspace creator",
+									] as const,
+								]
+							: []),
 						...Object.entries(config.repositories ?? {}).flatMap(
 							([alias, repository]) =>
 								repository.postCheckoutCommand

package/src/services/IntegrationService.test.ts

@@ -174,6 +174,18 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"Do not invoke agency work for this target",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"as the default implementation directory",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Set each tool's working directory to that checkout when supported",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Run Agency lifecycle and context commands from the task or phase directory",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"reference checkouts reported by Agency context are read-only",
+		)
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			".map((path) => `${path}${sep}.`)",
 		)
@@ -187,23 +199,39 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
-	test("binds validated worker identity to an OpenCode session", async () => {
+	const testWorkerIdentity = async ({
+		target,
+		launchTarget,
+		phase,
+	}: {
+		readonly target:
+			| { readonly kind: "task"; readonly taskId: string }
+			| {
+					readonly kind: "phase"
+					readonly taskId: string
+					readonly phaseId: string
+			  }
+		readonly launchTarget: string
+		readonly phase?: string
+	}) => {
 		const path = join(root, "agency-repository-skills.ts")
+		const checkoutPath = join(root, "code/agency")
 		const contextResponse = JSON.stringify({
 			version: 1,
 			ok: true,
 			result: {
 				workbase: { root },
 				target: {
-					kind: "task",
-					taskId: "example",
-					path: join(root, "TASK.md"),
+					...target,
+					path: join(root, phase ? "PHASE.md" : "TASK.md"),
 				},
 				authority: {
 					mode: "execution",
-					writable: { checkoutPath: join(root, "tasks/example/code/agency") },
+					writable: { checkoutPath },
 				},
-				documents: { task: { data: { status: "working" } } },
+				documents: phase
+					? { phase: { data: { status: "working" } } }
+					: { task: { data: { status: "working" } } },
 				validation: { valid: true, warnings: [] },
 			},
 		})
@@ -225,27 +253,28 @@ describe("IntegrationService", () => {
 			}) as ReturnType<typeof Bun.spawn>) as typeof Bun.spawn
 		try {
 			const generated = await import(
-				`${pathToFileURL(path).href}?worker-identity`
+				`${pathToFileURL(path).href}?worker-identity=${encodeURIComponent(launchTarget)}`
 			)
 			expect(
 				generated.workerLaunchTarget([
 					{
 						type: "text",
-						text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+						text: `Agency worker launch target: ${launchTarget}. Start the task.`,
 					},
 				]),
-			).toBe("execution-unit:task/example")
+			).toBe(launchTarget)
 			expect(generated.workerLaunchTarget(undefined)).toBeUndefined()
 			expect(
 				generated.contextTarget({
-					target: { kind: "task", taskId: "example" },
+					target,
 					authority: { mode: "execution" },
 				}),
-			).toBe("execution-unit:task/example")
+			).toBe(launchTarget)
 			expect(await generated.agencyContext(root)).toMatchObject({
 				root,
-				target: "execution-unit:task/example",
+				target: launchTarget,
 				task: "example",
+				phase,
 			})
 			const hooks = await generated.default({ directory: root } as never)
 			await hooks["chat.message"]!(
@@ -254,7 +283,7 @@ describe("IntegrationService", () => {
 					parts: [
 						{
 							type: "text",
-							text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+							text: `Agency worker launch target: ${launchTarget}. Start the task.`,
 						},
 					],
 				} as never,
@@ -276,11 +305,17 @@ describe("IntegrationService", () => {
 				{ sessionID: "worker-session" } as never,
 				system,
 			)
-			expect(system.system).toEqual([
-				expect.stringContaining(
-					"active worker for execution-unit:task/example",
-				),
-			])
+			expect(system.system).toHaveLength(1)
+			expect(system.system[0]).toContain(`active worker for ${launchTarget}`)
+			expect(system.system[0]).toContain(
+				`${checkoutPath} as the default implementation directory`,
+			)
+			expect(system.system[0]).toContain(
+				"Run Agency lifecycle and context commands from the task or phase directory",
+			)
+			expect(system.system[0]).toContain(
+				"reference checkouts reported by Agency context are read-only",
+			)
 			const mismatchedSystem = { system: [] as string[] }
 			await hooks["experimental.chat.system.transform"]!(
 				{ sessionID: "mismatched-session" } as never,
@@ -292,15 +327,29 @@ describe("IntegrationService", () => {
 			await hooks["shell.env"]!({ sessionID: "worker-session" } as never, shell)
 			expect(shell.env).toMatchObject({
 				AGENCY_SESSION_ID: "worker-session",
-				AGENCY_TARGET: "execution-unit:task/example",
+				AGENCY_TARGET: launchTarget,
 				AGENCY_WORKBASE: root,
 				AGENCY_TASK_ID: "example",
-				AGENCY_WRITABLE_CHECKOUT: join(root, "tasks/example/code/agency"),
+				AGENCY_WRITABLE_CHECKOUT: checkoutPath,
 			})
+			if (phase) expect(shell.env.AGENCY_PHASE_ID).toBe(phase)
 		} finally {
 			Bun.spawn = originalSpawn
 		}
-	})
+	}
+
+	test("binds validated task worker identity to an OpenCode session", () =>
+		testWorkerIdentity({
+			target: { kind: "task", taskId: "example" },
+			launchTarget: "execution-unit:task/example",
+		}))
+
+	test("binds validated phase worker identity to an OpenCode session", () =>
+		testWorkerIdentity({
+			target: { kind: "phase", taskId: "example", phaseId: "build" },
+			launchTarget: "execution-unit:phase/example/build",
+			phase: "build",
+		}))
 
 	test("registers a TUI-only /agency-debug diagnostic", async () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))

package/src/services/WorkbaseService.test.ts

@@ -371,6 +371,26 @@ status: done
 		).rejects.toThrow("{worktree}")
 	})
 
+	test("rejects an invalid workspace command template", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: ["tool", "{repo}", "{workspace}", "{name}"],
+			}),
+		)
+
+		await expect(
+			runTestEffect(
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.discover(root)),
+				),
+			),
+		).rejects.toThrow("{revision}")
+	})
+
 	test("rejects an unknown post-checkout command placeholder", async () => {
 		await write(
 			root,

package/src/services/WorkbaseService.ts

@@ -20,6 +20,7 @@ import {
 	type WorkbaseRegistration,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
+import { validateWorkspaceCreateCommand } from "../workbase/workspace-command"
 import { validatePostCheckoutCommand } from "../workbase/checkout-command"
 import { validateRunners } from "../workbase/runner-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
@@ -275,6 +276,21 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								if (decoded.value.workspaceCreateCommand) {
+									try {
+										validateWorkspaceCreateCommand(
+											decoded.value.workspaceCreateCommand,
+										)
+									} catch (cause) {
+										return yield* new WorkbaseConfigError({
+											path: configPath,
+											message:
+												cause instanceof Error
+													? cause.message
+													: "Invalid workspaceCreateCommand",
+										})
+									}
+								}
 								for (const [alias, repository] of Object.entries(
 									decoded.value.repositories ?? {},
 								)) {

package/src/services/WorktreeService.test.ts

@@ -319,6 +319,198 @@ describe("WorktreeService", () => {
 		expect(await Bun.file(workspace.writablePath!).exists()).toBe(false)
 	})
 
+	test("uses a custom jj workspace creator before the post-checkout hook", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: [
+					"sh",
+					"-c",
+					'jj -R "$1" workspace add --name "$3" -r "$4" "$2" && printf "%s\\n%s\\n" "$AGENCY_CHECKOUT_KIND" "$AGENCY_REQUESTED_REF" > "$2/creator-finished"',
+					"workspace-creator",
+					"{repo}",
+					"{workspace}",
+					"{name}",
+					"{revision}",
+					"{kind}",
+					"{requestedRef}",
+				],
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: [
+							"sh",
+							"-c",
+							'test -f creator-finished && printf "post-checkout" > hook-finished',
+						],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-custom",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-custom",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-custom", undefined, root),
+				),
+			),
+		)
+		expect(
+			await Bun.file(join(workspace.writablePath!, "creator-finished")).text(),
+		).toBe("writable\ntask/jj-custom\n")
+		expect(
+			await Bun.file(join(workspace.writablePath!, "hook-finished")).text(),
+		).toBe("post-checkout")
+		expect(workspace.operations[0]).toMatchObject({
+			action: "create-workspace",
+			command: expect.arrayContaining(["writable", "task/jj-custom"]),
+			status: "completed",
+		})
+	})
+
+	test("rolls back a jj workspace partially created by a custom command", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: [
+					"sh",
+					"-c",
+					'jj -R "$1" workspace add --name "$3" -r "$4" "$2" && echo adoption-failed >&2; exit 7',
+					"workspace-creator",
+					"{repo}",
+					"{workspace}",
+					"{name}",
+					"{revision}",
+				],
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-custom-failure",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-custom-failure",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspacePath = join(root, "tasks/jj-custom-failure/code/agency")
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("jj-custom-failure", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("adoption-failed")
+		expect(await Bun.file(workspacePath).exists()).toBe(false)
+		expect(
+			await jjOutput(["workspace", "list", "-T", 'name ++ "\\n"'], repository),
+		).not.toContain("agency-jj-custom-failure-task-agency")
+	})
+
+	test("rejects and rolls back a custom jj workspace at the wrong revision", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		const hookMarker = join(root, "wrong-revision-hook")
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				vcs: "jj",
+				workspaceCreateCommand: [
+					"sh",
+					"-c",
+					'jj -R "$1" workspace add --name "$3" -r "root()" "$2"',
+					"workspace-creator",
+					"{repo}",
+					"{workspace}",
+					"{name}",
+					"{revision}",
+				],
+				repositories: {
+					agency: {
+						remote: "https://example.com/agency.git",
+						postCheckoutCommand: ["sh", "-c", 'touch "$1"', "hook", hookMarker],
+					},
+				},
+			}),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-custom-wrong-revision",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-custom-wrong-revision",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspacePath = join(
+			root,
+			"tasks/jj-custom-wrong-revision/code/agency",
+		)
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("jj-custom-wrong-revision", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("failed validation")
+		expect(await Bun.file(workspacePath).exists()).toBe(false)
+		expect(await Bun.file(hookMarker).exists()).toBe(false)
+	})
+
 	test("suspends and resumes the exact jj working-copy target", async () => {
 		if (!Bun.which("jj")) return
 		const repository = join(root, "repos/agency")

package/src/services/WorktreeService.ts

@@ -8,6 +8,10 @@ import {
 	expandWorktreeCreateCommand,
 	worktreeCommandEnvironment,
 } from "../workbase/worktree-command"
+import {
+	expandWorkspaceCreateCommand,
+	workspaceCommandEnvironment,
+} from "../workbase/workspace-command"
 import {
 	expandPostCheckoutCommand,
 	postCheckoutCommandEnvironment,
@@ -1157,7 +1161,7 @@ const materializeJj = (options: {
 		const created: {
 			repositoryPath: string
 			workspacePath: string
-			workspaceName: string
+			workspaceName: string | null
 		}[] = []
 		const resumePath = jjResumePath(options.taskPath, options.phasePath)
 		const resume = yield* readJjResumeState(resumePath)
@@ -1227,9 +1231,14 @@ const materializeJj = (options: {
 				const canonicalPath = exists
 					? yield* fs.realPath(workspacePath)
 					: resolve(workspacePath)
-				const registered = (yield* backend.listWorkspaces(repositoryPath)).find(
+				const registeredWorkspaces =
+					yield* backend.listWorkspaces(repositoryPath)
+				const registered = registeredWorkspaces.find(
 					(workspace) => workspace.path === canonicalPath,
 				)
+				const registeredByName = registeredWorkspaces.find(
+					(workspace) => workspace.name === workspaceName,
+				)
 				if (exists && !registered && resumeCheckout) {
 					const residual = yield* inspectJjResidual(
 						options.root,
@@ -1256,6 +1265,11 @@ const materializeJj = (options: {
 						message: `Workspace registry contains a missing checkout at ${workspacePath}`,
 					})
 				}
+				if (!exists && registeredByName) {
+					return yield* new WorktreeError({
+						message: `Jj workspace name '${workspaceName}' is already registered at ${registeredByName.path}`,
+					})
+				}
 				if (exists && registered) {
 					const actualCommit = resumeCheckout
 						? ((yield* jjIdentity(workspacePath, "@"))?.commitId ?? null)
@@ -1313,7 +1327,7 @@ const materializeJj = (options: {
 					})
 				}
 
-				const command = [
+				const defaultCommand = [
 					"jj",
 					"-R",
 					repositoryPath,
@@ -1325,6 +1339,36 @@ const materializeJj = (options: {
 					revision,
 					workspacePath,
 				]
+				const workspaceVariables = {
+					repo: repositoryPath,
+					workspace: workspacePath,
+					name: workspaceName,
+					revision,
+					kind:
+						"branch" in checkout
+							? ("writable" as const)
+							: ("reference" as const),
+					requestedRef: requestedRevision,
+				}
+				let command = defaultCommand
+				let commandEnvironment: Record<string, string> | undefined
+				if (options.config.workspaceCreateCommand && !resumeCheckout) {
+					try {
+						command = expandWorkspaceCreateCommand(
+							options.config.workspaceCreateCommand,
+							workspaceVariables,
+						)
+						commandEnvironment = workspaceCommandEnvironment(workspaceVariables)
+					} catch (cause) {
+						return yield* new WorktreeError({
+							message:
+								cause instanceof Error
+									? cause.message
+									: "Invalid workspaceCreateCommand",
+							cause,
+						})
+					}
+				}
 				operations.push({
 					action: "create-workspace",
 					repo: checkout.repo,
@@ -1353,6 +1397,38 @@ const materializeJj = (options: {
 							workspaceName,
 							commitId: resumeCheckout.commitId,
 						})
+					} else if (options.config.workspaceCreateCommand) {
+						verboseLog(`Running workspace command: ${formatCommand(command)}`)
+						const result = yield* fs.runCommand(command, {
+							cwd: repositoryPath,
+							captureOutput: true,
+							forwardOutput: forwardCommandOutput,
+							env: commandEnvironment,
+						})
+						const createdPath = yield* fs.isDirectory(workspacePath)
+						const canonicalCreatedPath = createdPath
+							? yield* fs.realPath(workspacePath)
+							: resolve(workspacePath)
+						const registeredAfterCommand = (yield* backend.listWorkspaces(
+							repositoryPath,
+						)).find((workspace) => workspace.path === canonicalCreatedPath)
+						if (createdPath || registeredAfterCommand) {
+							created.push({
+								repositoryPath,
+								workspacePath,
+								workspaceName: registeredAfterCommand?.name ?? null,
+							})
+						}
+						if (result.exitCode !== 0) {
+							return yield* new WorktreeError({
+								message: `Failed to create jj workspace for '${checkout.repo}': ${result.stderr.trim() || result.stdout.trim()}`,
+							})
+						}
+						if (!createdPath) {
+							return yield* new WorktreeError({
+								message: `Workspace command did not create ${workspacePath}`,
+							})
+						}
 					} else {
 						yield* backend.createWorkspace({
 							repositoryPath,
@@ -1362,7 +1438,9 @@ const materializeJj = (options: {
 							...("branch" in checkout ? { branch: checkout.branch } : {}),
 						})
 					}
-					created.push({ repositoryPath, workspacePath, workspaceName })
+					if (!options.config.workspaceCreateCommand || resumeCheckout) {
+						created.push({ repositoryPath, workspacePath, workspaceName })
+					}
 					const canonicalWorkspacePath = yield* fs.realPath(workspacePath)
 					const registeredAfterCreate = (yield* backend.listWorkspaces(
 						repositoryPath,
@@ -1370,7 +1448,10 @@ const materializeJj = (options: {
 					const head = resumeCheckout
 						? ((yield* jjIdentity(workspacePath, "@"))?.commitId ?? null)
 						: yield* backend.workspaceHead(workspacePath)
-					if (!registeredAfterCreate || head !== revision) {
+					if (
+						registeredAfterCreate?.name !== workspaceName ||
+						head !== revision
+					) {
 						return yield* new WorktreeError({
 							message: `Created jj workspace for '${checkout.repo}' failed validation`,
 						})
@@ -1445,16 +1526,18 @@ const materializeJj = (options: {
 					const rolledBack: string[] = []
 					const manualRecovery: string[] = []
 					for (const workspace of [...created].reverse()) {
-						const removed = yield* backend
-							.removeWorkspace({
-								repositoryPath: workspace.repositoryPath,
-								workspacePath: workspace.workspacePath,
-								workspaceName: workspace.workspaceName,
-							})
-							.pipe(
-								Effect.as(true),
-								Effect.catchAll(() => Effect.succeed(false)),
-							)
+						const removed = yield* (
+							workspace.workspaceName
+								? backend.removeWorkspace({
+										repositoryPath: workspace.repositoryPath,
+										workspacePath: workspace.workspacePath,
+										workspaceName: workspace.workspaceName,
+									})
+								: fs.deleteDirectory(workspace.workspacePath)
+						).pipe(
+							Effect.as(true),
+							Effect.catchAll(() => Effect.succeed(false)),
+						)
 						if (removed)
 							rolledBack.push(`create-workspace ${workspace.workspaceName}`)
 						else

package/src/workbase/opencode-plugin-file.ts

@@ -164,7 +164,12 @@ const plugin: Plugin = async ({ directory }) => {
       const context = workerSessions.get(sessionID)
       if (!context?.target) return
       output.system.push(
-        \`Agency verified this OpenCode session as the active worker for \${context.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+        [
+          \`Agency verified this OpenCode session as the active worker for \${context.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+          context.checkout
+            ? \`OpenCode remains rooted in the task or phase directory for Agency instructions and context. Treat \${context.checkout} as the default implementation directory: use it for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Set each tool's working directory to that checkout when supported; otherwise use absolute paths. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.\`
+            : undefined,
+        ].filter(Boolean).join(" "),
       )
     },
     "shell.env": async ({ sessionID }, output) => {

package/src/workbase/schemas.test.ts

@@ -257,6 +257,25 @@ describe("repository post-checkout configuration", () => {
 	})
 })
 
+describe("workspace creation configuration", () => {
+	test("accepts a jj workspace argv command", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			vcs: "jj",
+			workspaceCreateCommand: [
+				"prewarm",
+				"adopt",
+				"{repo}",
+				"{workspace}",
+				"{name}",
+				"{revision}",
+			],
+		})
+
+		expect(config.workspaceCreateCommand?.[0]).toBe("prewarm")
+	})
+})
+
 describe("runner configuration", () => {
 	test("accepts named argv commands with resume commands and environment", () => {
 		const config = Schema.decodeUnknownSync(WorkbaseConfig)({

package/src/workbase/schemas.ts

@@ -109,6 +109,7 @@ export const WorkbaseConfig = Schema.Struct({
 	),
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+	workspaceCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	runners: Schema.optional(
 		Schema.Record({
 			key: EntityId,

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

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test"
+import {
+	expandWorkspaceCreateCommand,
+	workspaceCommandEnvironment,
+} from "./workspace-command"
+
+const variables = {
+	repo: "/work/repos/app",
+	workspace: "/work/tasks/example/code/app",
+	name: "agency-example-task-app",
+	revision: "0123456789abcdef",
+	kind: "writable" as const,
+	requestedRef: "task/example",
+}
+
+describe("workspace command templates", () => {
+	test("expands argv placeholders without shell interpolation", () => {
+		expect(
+			expandWorkspaceCreateCommand(
+				[
+					"tool",
+					"--repo={repo}",
+					"--workspace={workspace}",
+					"--name={name}",
+					"--revision={revision}",
+					"{kind}",
+					"{requestedRef}",
+				],
+				variables,
+			),
+		).toEqual([
+			"tool",
+			"--repo=/work/repos/app",
+			"--workspace=/work/tasks/example/code/app",
+			"--name=agency-example-task-app",
+			"--revision=0123456789abcdef",
+			"writable",
+			"task/example",
+		])
+	})
+
+	test("requires creation identity placeholders", () => {
+		expect(() =>
+			expandWorkspaceCreateCommand(
+				["tool", "{repo}", "{workspace}", "{name}"],
+				variables,
+			),
+		).toThrow("{revision}")
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			expandWorkspaceCreateCommand(
+				["tool", "{repo}", "{workspace}", "{name}", "{revision}", "{base}"],
+				variables,
+			),
+		).toThrow("{base}")
+	})
+
+	test("provides equivalent environment variables", () => {
+		expect(workspaceCommandEnvironment(variables)).toEqual({
+			AGENCY_REPO: variables.repo,
+			AGENCY_WORKSPACE: variables.workspace,
+			AGENCY_WORKSPACE_NAME: variables.name,
+			AGENCY_REVISION: variables.revision,
+			AGENCY_CHECKOUT_KIND: variables.kind,
+			AGENCY_REQUESTED_REF: variables.requestedRef,
+		})
+	})
+})

package/src/workbase/workspace-command.ts

@@ -0,0 +1,63 @@
+interface WorkspaceCommandVariables {
+	readonly repo: string
+	readonly workspace: string
+	readonly name: string
+	readonly revision: string
+	readonly kind: "writable" | "reference"
+	readonly requestedRef: string
+}
+
+const REQUIRED_PLACEHOLDERS = ["repo", "workspace", "name", "revision"] as const
+const PLACEHOLDERS = new Set([
+	"repo",
+	"workspace",
+	"name",
+	"revision",
+	"kind",
+	"requestedRef",
+])
+
+export const validateWorkspaceCreateCommand = (command: readonly string[]) => {
+	const template = command.join("\u0000")
+	for (const placeholder of REQUIRED_PLACEHOLDERS) {
+		if (!template.includes(`{${placeholder}}`)) {
+			throw new Error(
+				`workspaceCreateCommand must include the {${placeholder}} placeholder`,
+			)
+		}
+	}
+	for (const argument of command) {
+		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
+			const placeholder = match[1]!
+			if (!PLACEHOLDERS.has(placeholder)) {
+				throw new Error(
+					`Unknown workspaceCreateCommand placeholder: {${placeholder}}`,
+				)
+			}
+		}
+	}
+}
+
+export const expandWorkspaceCreateCommand = (
+	command: readonly string[],
+	variables: WorkspaceCommandVariables,
+): string[] => {
+	validateWorkspaceCreateCommand(command)
+
+	return command.map((argument) =>
+		argument.replaceAll(/\{([^{}]+)\}/g, (match, placeholder: string) => {
+			return variables[placeholder as keyof WorkspaceCommandVariables] ?? match
+		}),
+	)
+}
+
+export const workspaceCommandEnvironment = (
+	variables: WorkspaceCommandVariables,
+): Record<string, string> => ({
+	AGENCY_REPO: variables.repo,
+	AGENCY_WORKSPACE: variables.workspace,
+	AGENCY_WORKSPACE_NAME: variables.name,
+	AGENCY_REVISION: variables.revision,
+	AGENCY_CHECKOUT_KIND: variables.kind,
+	AGENCY_REQUESTED_REF: variables.requestedRef,
+})