@markjaquith/agency 3.10.2 → 3.12.0

package/README.md

@@ -140,7 +140,8 @@ whether the server plugin registered writable-checkout skills. It uses a native
 toast and does not submit a prompt to an LLM. When no writable checkout skill
 directory is available, server initialization is reported as indeterminate
 rather than inferred from plugin discovery.
-OpenCode discovers the config and plugin from task and epic launch directories.
+OpenCode discovers the config and plugin from Agency launch directories and
+their ancestors.
 The plugin uses OpenCode's plural discovery directory and exports both the V1
 server function and the `opencode2` module wrapper. Integration sync migrates a
 checksum-valid legacy singular-path plugin and preserves customized files.
@@ -186,6 +187,48 @@ Existing version 2 workbases without `repositories` remain valid. Run
 unambiguous. Workbase configuration may also provide a custom writable-worktree
 creation command.
 
+### Custom Branch Names
+
+Set `branchNameCommand` to an argv template to choose the branch recorded for a
+new execution unit when `--branch` is omitted:
+
+```json
+{
+	"version": 2,
+	"branchNameCommand": ["wt-resolve-new-branch-name", "{ticket}"]
+}
+```
+
+Agency invokes the command directly, without a shell, from the workbase root and
+uses its trimmed stdout as the branch name. The command has 120 seconds to
+finish. A non-zero exit, empty output, timeout, or output rejected by
+`git check-ref-format --branch` fails creation without falling back. Explicit
+`--branch` always wins. Multi-phase task containers and review tasks do not have
+writable branches and therefore do not invoke this command.
+
+Available placeholders are:
+
+| Placeholder      | Value                                              |
+| ---------------- | -------------------------------------------------- |
+| `{id}`           | ID of the task or phase being created              |
+| `{ticket}`       | Task ticket URL, or `{id}` when there is no ticket |
+| `{ticketUrl}`    | Task ticket URL, or an empty string when absent    |
+| `{repo}`         | Writable repository alias                          |
+| `{base}`         | Base branch                                        |
+| `{workbaseRoot}` | Absolute workbase root                             |
+| `{taskId}`       | Task ID                                            |
+| `{phaseId}`      | Phase ID, or an empty string when creating a task  |
+
+Resolver failures are reported with the `BRANCH_NAME_COMMAND_FAILED` error code
+in JSON output.
+
+Matching `AGENCY_ID`, `AGENCY_TICKET`, `AGENCY_TICKET_URL`, `AGENCY_REPO`,
+`AGENCY_BASE`, `AGENCY_WORKBASE_ROOT`, `AGENCY_TASK_ID`, and `AGENCY_PHASE_ID`
+environment variables are also set. Without `branchNameCommand`, task branches
+remain `task/<id>` and phase branches default to `task/<task-id>-<phase-id>`.
+Callers should omit `--branch` when they want the workbase policy; do not pass a
+hard-coded value merely to reproduce Agency's built-in default.
+
 ### Custom Worktree Command
 
 Git workbases create worktrees with Git. Set `worktreeCreateCommand` to an
@@ -394,9 +437,13 @@ identify the invoking session, so Agency deliberately avoids leaking one
 session's worker identity into another; the validated marker and injected system
 instruction remain the V2 fallback when the long-lived server did not inherit
 the client's launch environment.
-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.
+For execution units, the built-in `pi` agent and the `opencode2` and `opencode`
+agents running OpenCode V2 launch from the authoritative writable checkout so
+their project and Git interfaces reflect the implementation repository.
+OpenCode V1 stops configuration discovery at the checkout's Git root, so V1
+launches remain rooted in the task or phase directory. Epic and multi-phase task orchestration remains
+rooted in its Agency document directory. Ancestor discovery still supplies the
+workbase `AGENTS.md` and managed OpenCode config.
 Agency's managed OpenCode plugin grants the active workbase external-directory
 access and exposes existing checkout-local `.claude/skills`, `.agents/skills`,
 and `.opencode/{skill,skills}` definitions. V1 adds those source directories to
@@ -406,8 +453,9 @@ hook. The global Pi
 extension provides equivalent whole-workbase context and additionally discovers
 checkout-local `.pi/skills` through Pi's `resources_discover` lifecycle.
 `agency work` supplies the checkout directly; plain OpenCode and Pi launches
-resolve a materialized execution-unit
-checkout through `agency context`. A multi-phase
+from a task or phase directory resolve a materialized execution-unit checkout
+through `agency context` and instruct the agent to change to it before
+implementation or Git operations. 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 cwd, command template, and non-secret environment

package/package.json

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

package/pi-extensions/agency.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs"
-import { dirname, join, resolve } from "node:path"
+import { dirname, join, resolve, sep } from "node:path"
 
 type ExtensionAPI = {
 	exec: (
@@ -26,7 +26,9 @@ type ExtensionAPI = {
 type AgencyContext = {
 	root?: string
 	checkout?: string
+	documentDirectory?: string
 	target?: string
+	working?: boolean
 }
 
 const contextTarget = (result: Record<string, any>): string | undefined => {
@@ -78,14 +80,18 @@ const agencyContext = async (
 		result.workbase?.root !== root ||
 		!target ||
 		(target.startsWith("execution-unit:") &&
-			(!result.authority?.writable?.checkoutPath || status !== "working"))
+			!result.authority?.writable?.checkoutPath)
 	)
 		return
 
 	return {
 		root,
 		checkout: result.authority?.writable?.checkoutPath,
+		documentDirectory: result.target?.path
+			? dirname(result.target.path)
+			: undefined,
 		target,
+		working: status === "working",
 	}
 }
 
@@ -150,12 +156,27 @@ export default function agencyExtension(pi: ExtensionAPI) {
 				: undefined
 			const activeTarget = process.env.AGENCY_TARGET
 			const worker =
-				activeTarget && context.target === activeTarget
+				activeTarget && context.target === activeTarget && context.working
 					? `Agency verified this Pi session as the active worker for ${activeTarget}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.`
 					: undefined
 			const access = `The complete Agency workbase is available at ${context.root}. Use absolute paths under that root when workbase context is needed. Agency context remains the authority for writes.`
-			const implementation = context.checkout
-				? `Pi remains rooted in the task or phase directory for Agency instructions and context. Treat ${context.checkout} as the default implementation directory for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.`
+			const checkout = context.checkout ? resolve(context.checkout) : undefined
+			const current = resolve(ctx.cwd)
+			const repository =
+				checkout &&
+				(current === checkout || current.startsWith(`${checkout}${sep}`))
+			const implementation = checkout
+				? [
+						repository
+							? `Pi is rooted in Agency's authoritative writable checkout at ${checkout}. Use this directory for source reads, edits, Git status and other Git operations, builds, tests, and formatting.`
+							: `Agency's authoritative writable checkout is ${checkout}. Before doing implementation work or Git operations, change the working directory to that checkout. Set each tool's working directory to it when supported; otherwise use absolute paths.`,
+						context.documentDirectory
+							? `Run Agency lifecycle commands from ${context.documentDirectory}; agency context may also be queried from the checkout.`
+							: undefined,
+						"Any reference checkouts reported by Agency context are read-only.",
+					]
+						.filter(Boolean)
+						.join(" ")
 				: undefined
 
 			return {

package/src/act-schema.ts

@@ -49,6 +49,19 @@ const EntityFields = {
 }
 
 export const ActDiscovery = Schema.Struct({
+	creationDefaults: Schema.Struct({
+		branch: Schema.Union(
+			Schema.Struct({
+				configured: Schema.Literal(true),
+				guidance: Schema.String,
+			}),
+			Schema.Struct({
+				configured: Schema.Literal(false),
+				task: Schema.String,
+				phase: Schema.String,
+			}),
+		),
+	}),
 	workbase: Schema.Struct({
 		root: Schema.String,
 		repositories: Argv,

package/src/cli-parser.ts

@@ -573,7 +573,7 @@ const commands = {
 		subcommands: {
 			new: {
 				usage:
-					"agency phase new <task-id> <phase-id> --repo <alias> --branch <name> --base <name> [options] [--work [--auto]]",
+					"agency phase new <task-id> <phase-id> --repo <alias> --base <name> [--branch <name>] [options] [--work [--auto]]",
 				minArgs: 2,
 				maxArgs: 2,
 				options: [
@@ -596,7 +596,7 @@ const commands = {
 			},
 			create: {
 				usage:
-					"agency phase create <task-id> <phase-id> --repo <alias> --branch <name> --base <name> [options]",
+					"agency phase create <task-id> <phase-id> --repo <alias> --base <name> [--branch <name>] [options]",
 				minArgs: 2,
 				maxArgs: 2,
 				options: [

package/src/commands/act.ts

@@ -160,6 +160,21 @@ const shellCommand = (argv: readonly string[]) =>
 				: `'${arg.replaceAll("'", `'\\''`)}'`,
 		)
 		.join(" ")
+const creationDefaults = (config: {
+	readonly branchNameCommand?: readonly string[]
+}) => ({
+	branch: config.branchNameCommand
+		? {
+				configured: true as const,
+				guidance:
+					"Omit --branch to use the workbase branchNameCommand; pass it only for an explicit override.",
+			}
+		: {
+				configured: false as const,
+				task: "task/<id>",
+				phase: "task/<task-id>-<phase-id>",
+			},
+})
 const available = (action: ActAction) => !action.blockedReason
 const checkoutState = (inspection: {
 	readonly checkouts: readonly {
@@ -463,6 +478,7 @@ const actStep = (
 			log(
 				JSON.stringify(
 					yield* Schema.decodeUnknown(ActDiscovery)({
+						creationDefaults: creationDefaults(config),
 						workbase: {
 							root,
 							repositories: graph.nodes
@@ -772,6 +788,8 @@ or exits from the front screen; Ctrl-C quits. A recap is printed when you exit.
 An existing directory or file selects its containing epic, task, or phase.
 A workbase path opens Workbase actions. Otherwise the positional value is a
 task ID. Selectors skip item selection.
+JSON discovery includes creation defaults identifying when callers should omit
+--branch so the workbase branchNameCommand can choose it.
 
 Options:
   --action <id>         Start an action or filter discovery (IDs from --json)

package/src/commands/phase.ts

@@ -7,6 +7,8 @@ import { getWorkViews } from "../work-view"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
 import { GraphMutationService } from "../services/GraphMutationService"
 import { work as startWork, type StartWork } from "./work"
+import { TaskService } from "../services/TaskService"
+import { resolveBranchName } from "../workbase/branch-name-command"
 
 interface PhaseOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -39,6 +41,7 @@ interface PhaseOptions extends BaseCommandOptions {
 export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 	Effect.gen(function* () {
 		const phases = yield* PhaseService
+		const tasks = yield* TaskService
 		const mutations = yield* GraphMutationService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
@@ -47,19 +50,26 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 		switch (options.subcommand) {
 			case "new":
 			case "create": {
-				if (
-					!taskId ||
-					!phaseId ||
-					!options.repo ||
-					!options.branch ||
-					!options.base
-				) {
+				if (!taskId || !phaseId || !options.repo || !options.base) {
 					return yield* Effect.fail(
 						new Error(
-							"Usage: agency phase create <task-id> <phase-id> --repo <alias> --branch <name> --base <name>",
+							"Usage: agency phase create <task-id> <phase-id> --repo <alias> --base <name> [--branch <name>]",
 						),
 					)
 				}
+				const parent = yield* tasks.show(taskId, cwd)
+				const branch =
+					options.branch ??
+					(yield* resolveBranchName({
+						id: phaseId,
+						taskId,
+						phaseId,
+						ticketUrl: parent.data.ticketUrl,
+						repo: options.repo,
+						base: options.base,
+						defaultBranch: `task/${taskId}-${phaseId}`,
+						startPath: cwd,
+					}))
 				const record = yield* phases.create(
 					{
 						taskId,
@@ -67,7 +77,7 @@ export const phase = (options: PhaseOptions, work: StartWork = startWork) =>
 						description: options.description,
 						repo: options.repo,
 						repos: parseRepositoryReferences(options.references),
-						branch: options.branch,
+						branch,
 						base: options.base,
 						dependsOn: options.dependsOn,
 						firstPhase: options.firstPhase,
@@ -311,7 +321,7 @@ Create options:
   --repo <alias>        Writable repository
   --reference <alias>:<ref>
                         Read-only repository reference; repeatable
-  --branch <name>       Working branch
+  --branch <name>       Working branch (default: configured resolver or task/<task>-<phase>)
   --base <name>         Base branch
   --depends-on <id>     Phase dependency; repeatable
   --first-phase <id>    Existing execution phase ID when converting a task

package/src/commands/task.ts

@@ -16,6 +16,7 @@ import {
 	buildValidationEvidence,
 	normalizeRecalledContext,
 } from "../workbase/execution-contract"
+import { resolveBranchName } from "../workbase/branch-name-command"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -188,6 +189,19 @@ export const task = (
 					}
 				}
 
+				const base = options.base ?? "main"
+				const branch =
+					multiPhase || options.branch
+						? options.branch
+						: yield* resolveBranchName({
+								id,
+								taskId: id,
+								ticketUrl,
+								repo: repo!,
+								base,
+								defaultBranch: `task/${id}`,
+								startPath: cwd,
+							})
 				const record = yield* tasks.create(
 					{
 						id,
@@ -197,8 +211,8 @@ export const task = (
 						multiPhase,
 						repo,
 						repos: parseRepositoryReferences(options.references),
-						branch: multiPhase ? undefined : (options.branch ?? `task/${id}`),
-						base: multiPhase ? undefined : (options.base ?? "main"),
+						branch: multiPhase ? undefined : branch,
+						base: multiPhase ? undefined : base,
 						purpose: options.purpose as "investigation" | undefined,
 					},
 					cwd,
@@ -275,10 +289,23 @@ export const task = (
 							cwd,
 						)
 					: undefined
+				const ticketUrl = options.ticketUrl?.trim() || null
+				const branch =
+					multiPhase || review || options.branch
+						? options.branch
+						: yield* resolveBranchName({
+								id,
+								taskId: id,
+								ticketUrl,
+								repo: repo!,
+								base,
+								defaultBranch: `task/${id}`,
+								startPath: cwd,
+							})
 				const record = yield* tasks.create(
 					{
 						id,
-						ticketUrl: options.ticketUrl?.trim() || null,
+						ticketUrl,
 						description: options.description?.trim() || undefined,
 						epic: options.epic,
 						multiPhase,
@@ -287,10 +314,7 @@ export const task = (
 						repos: review
 							? undefined
 							: parseRepositoryReferences(options.references),
-						branch:
-							multiPhase || review
-								? undefined
-								: (options.branch ?? `task/${id}`),
+						branch: multiPhase || review ? undefined : branch,
 						base: multiPhase || review ? undefined : base,
 						purpose: options.purpose as "investigation" | undefined,
 					},
@@ -337,18 +361,31 @@ export const task = (
 						new Error("Writable repository is required for task handoff"),
 					)
 				}
+				const ticketUrl = options.ticketUrl?.trim() || null
+				const base = options.base ?? "main"
+				const branch =
+					options.branch ??
+					(yield* resolveBranchName({
+						id,
+						taskId: id,
+						ticketUrl,
+						repo: options.repo,
+						base,
+						defaultBranch: `task/${id}`,
+						startPath: cwd,
+					}))
 				const output = yield* tasks.handoff(
 					{
 						sourceTaskId,
 						sourcePhaseId: options.sourcePhase,
 						id,
-						ticketUrl: options.ticketUrl?.trim() || null,
+						ticketUrl,
 						description: options.description?.trim() || undefined,
 						epic: options.epic,
 						repo: options.repo,
 						repos: parseRepositoryReferences(options.references),
-						branch: options.branch ?? `task/${id}`,
-						base: options.base ?? "main",
+						branch,
+						base,
 					},
 					cwd,
 				)
@@ -591,7 +628,7 @@ Create options:
   --repo <alias>        Writable repository
   --reference <alias>:<ref>
                         Read-only repository reference; repeatable
-  --branch <name>       Working branch (default: task/<id>)
+  --branch <name>       Working branch (default: configured resolver or task/<id>)
   --base <name>         Base branch (default: main)
 	--context-repo <alias> Recalled repository; must agree with --repo
 	--context-base <name>  Recalled base; must agree with --base

package/src/commands/work.ts

@@ -37,7 +37,10 @@ import {
 	readValidationEvidence,
 } from "../workbase/execution-contract"
 import { ValidationFailedError } from "./validate"
-import { prepareOpenCodeLaunch } from "../workbase/opencode-launch"
+import {
+	openCodeDiscoversAncestorConfig,
+	prepareOpenCodeLaunch,
+} from "../workbase/opencode-launch"
 
 export interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -378,6 +381,15 @@ export const work = (
 			options.auto,
 		)
 		cli = resolved.argv[0]!
+		if (writablePath && !config.agents?.[agent]) {
+			if (
+				agent === "pi" ||
+				((agent === "opencode2" || agent === "opencode") &&
+					(yield* openCodeDiscoversAncestorConfig(cli)))
+			) {
+				launchPath = writablePath
+			}
+		}
 		const environment = {
 			...resolved.environment,
 			...agentEnvironment(agent, variables),

package/src/protocol.ts

@@ -113,6 +113,12 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 		retryable: false,
 		remediation: "Resolve workbase validation errors before reconciling.",
 	},
+	BranchNameCommandError: {
+		code: "BRANCH_NAME_COMMAND_FAILED",
+		retryable: false,
+		remediation:
+			"Fix the workbase branchNameCommand or pass an explicit --branch.",
+	},
 	ProcessError: { code: "PROCESS_ERROR", retryable: true },
 	ProtocolOutputError: {
 		code: "PROTOCOL_OUTPUT_ERROR",

package/src/services/WorkbaseService.ts

@@ -22,6 +22,7 @@ import {
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
 import { validatePostCheckoutCommand } from "../workbase/checkout-command"
+import { validateBranchNameCommand } from "../workbase/branch-name-template"
 import { validateAgents } from "../workbase/agent-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
 import { validateDelivery } from "../workbase/delivery-command"
@@ -329,6 +330,19 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
+								if (decoded.value.branchNameCommand) {
+									try {
+										validateBranchNameCommand(decoded.value.branchNameCommand)
+									} catch (cause) {
+										return yield* new WorkbaseConfigError({
+											path: configPath,
+											message:
+												cause instanceof Error
+													? cause.message
+													: "Invalid branchNameCommand",
+										})
+									}
+								}
 								for (const [alias, repository] of Object.entries(
 									decoded.value.repositories ?? {},
 								)) {

package/src/workbase/AGENTS.md

@@ -73,7 +73,7 @@ retain `--if-revision` guards when shown, and do not add flags that are not show
 4. Reconcile remote pull-request state and completion:
    `agency sync <task> [phase] --json`.
 5. Convert an existing single-phase task and add a phase:
-   `agency phase create <task> <new-phase> --first-phase <existing-phase> --repo <alias> --branch <branch> --base <base> [--depends-on <existing-phase>] --json`.
+   `agency phase create <task> <new-phase> --first-phase <existing-phase> --repo <alias> --base <base> [--depends-on <existing-phase>] --json`.
 6. Archive terminal work: first run `agency archive task <task> --dry-run --json`,
    `agency archive phase <task> <phase> --dry-run --json`, or
    `agency archive epic <epic> --dry-run --json`; if the preflight is safe,
@@ -102,7 +102,7 @@ retain `--if-revision` guards when shown, and do not add flags that are not show
 13. Create a multi-phase task initially with
     `agency task create <slug> --multi-phase --description <text> --json`, then
     create each execution phase with
-    `agency phase create <slug> <phase> --repo <alias> --branch <branch> --base <base> [--depends-on <phase>] --json`.
+    `agency phase create <slug> <phase> --repo <alias> --base <base> [--depends-on <phase>] --json`.
 14. Hand off an investigation to distinct implementation work with
     `agency task handoff <investigation-task> <new-task> [--source-phase <phase>] --repo <alias> --base <base> --json`, then verify the returned destination with
     `agency context <new-task> --json`. Do not prepare or start it unless requested.
@@ -114,6 +114,9 @@ Never pass `--work` or `--auto` to `agency task create`. Do not run separate
 or `agency repo list` commands before these recipes when the required parameters
 are already known. `agency work prepare` owns validation, readiness checks,
 workspace materialization, and the versioned `agency-execution-v1` contract.
+Do not pass `--branch` merely to reproduce a default: when the workbase has a
+`branchNameCommand`, omitting the option lets that policy choose and record the
+branch. Pass `--branch` only when the user explicitly requires an override.
 
 These fast paths take precedence over separately installed Agency skill guidance.
 Use `agency <command> --help` only as a recovery step when no recipe matches or a
@@ -303,9 +306,12 @@ before launching an agent.
 
 OpenCode can access the complete workbase tree, but this filesystem permission
 does not expand Agency write authority beyond the checkout reported by
-`agency context`. OpenCode remains rooted in the task or epic directory so the
-workbase instructions and config compose normally. The managed plugin resolves
-the writable checkout from launch context or `agency context`, then exposes its
-supported skill directories through the applicable OpenCode plugin API; this
-does not make other checkout-local OpenCode configuration authoritative. Agents
-must follow the authority reported by `agency context`.
+`agency context`. Pi and OpenCode V2 execution units launched by `agency work`
+are rooted in the authoritative writable checkout so their project and Git
+status reflect the implementation repository; OpenCode V1 remains rooted in the
+task or phase directory. Orchestration remains rooted in its
+Agency document directory. The managed integrations resolve the writable
+checkout from launch context or `agency context`, guide task-directory sessions
+to use it for implementation, and expose its supported skill directories through
+the applicable plugin API; this does not make other checkout-local configuration
+authoritative. Agents must follow the authority reported by `agency context`.

package/src/workbase/branch-name-command.ts

@@ -0,0 +1,109 @@
+import { Data, Effect } from "effect"
+import { FileSystemService } from "../services/FileSystemService"
+import { WorkbaseService } from "../services/WorkbaseService"
+import {
+	expandBranchNameCommand,
+	type BranchNameVariables,
+} from "./branch-name-template"
+
+class BranchNameCommandError extends Data.TaggedError(
+	"BranchNameCommandError",
+)<{
+	readonly message: string
+	readonly command: readonly string[]
+	readonly exitCode?: number
+	readonly branch?: string
+}> {}
+
+const TIMEOUT_MS = 120_000
+
+const commandEnvironment = (
+	variables: BranchNameVariables,
+): Record<string, string> =>
+	Object.fromEntries(
+		Object.entries(variables).map(([name, value]) => [
+			`AGENCY_${name.replaceAll(/([a-z])([A-Z])/g, "$1_$2").toUpperCase()}`,
+			value,
+		]),
+	)
+
+interface ResolveBranchNameInput {
+	readonly id: string
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly ticketUrl?: string | null
+	readonly repo: string
+	readonly base: string
+	readonly defaultBranch: string
+	readonly startPath?: string
+}
+
+export const resolveBranchName = (input: ResolveBranchNameInput) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+		const { root, config } = yield* workbase.loadConfig(
+			input.startPath ?? process.cwd(),
+		)
+		if (!config.branchNameCommand) return input.defaultBranch
+
+		const variables: BranchNameVariables = {
+			id: input.id,
+			ticket: input.ticketUrl || input.id,
+			ticketUrl: input.ticketUrl || "",
+			repo: input.repo,
+			base: input.base,
+			workbaseRoot: root,
+			taskId: input.taskId,
+			phaseId: input.phaseId ?? "",
+		}
+		const command = expandBranchNameCommand(config.branchNameCommand, variables)
+		const result = yield* fs
+			.runCommand(command, {
+				cwd: root,
+				captureOutput: true,
+				env: commandEnvironment(variables),
+				timeoutMs: TIMEOUT_MS,
+			})
+			.pipe(
+				Effect.mapError(
+					(error) =>
+						new BranchNameCommandError({
+							message: `branchNameCommand could not run: ${error.cause instanceof Error ? error.cause.message : error.message}`,
+							command,
+						}),
+				),
+			)
+		if (result.exitCode !== 0) {
+			return yield* Effect.fail(
+				new BranchNameCommandError({
+					message: `branchNameCommand failed with exit code ${result.exitCode}${result.stderr ? `: ${result.stderr}` : ""}`,
+					command,
+					exitCode: result.exitCode,
+				}),
+			)
+		}
+		const branch = result.stdout.trim()
+		if (!branch) {
+			return yield* Effect.fail(
+				new BranchNameCommandError({
+					message: "branchNameCommand produced an empty branch name",
+					command,
+				}),
+			)
+		}
+		const checked = yield* fs.runCommand(
+			["git", "check-ref-format", "--branch", branch],
+			{ cwd: root, captureOutput: true },
+		)
+		if (checked.exitCode !== 0) {
+			return yield* Effect.fail(
+				new BranchNameCommandError({
+					message: `branchNameCommand produced invalid Git branch name '${branch}'`,
+					command,
+					branch,
+				}),
+			)
+		}
+		return branch
+	})

package/src/workbase/branch-name-template.ts

@@ -0,0 +1,48 @@
+export interface BranchNameVariables {
+	readonly id: string
+	readonly ticket: string
+	readonly ticketUrl: string
+	readonly repo: string
+	readonly base: string
+	readonly workbaseRoot: string
+	readonly taskId: string
+	readonly phaseId: string
+}
+
+const PLACEHOLDERS = new Set<keyof BranchNameVariables>([
+	"id",
+	"ticket",
+	"ticketUrl",
+	"repo",
+	"base",
+	"workbaseRoot",
+	"taskId",
+	"phaseId",
+])
+
+export const validateBranchNameCommand = (command: readonly string[]) => {
+	for (const argument of command) {
+		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
+			const placeholder = match[1]!
+			if (!PLACEHOLDERS.has(placeholder as keyof BranchNameVariables)) {
+				throw new Error(
+					`Unknown branchNameCommand placeholder: {${placeholder}}`,
+				)
+			}
+		}
+	}
+}
+
+export const expandBranchNameCommand = (
+	command: readonly string[],
+	variables: BranchNameVariables,
+): string[] => {
+	validateBranchNameCommand(command)
+	return command.map((argument) =>
+		argument.replaceAll(
+			/\{([^{}]+)\}/g,
+			(match, placeholder: string) =>
+				variables[placeholder as keyof BranchNameVariables] ?? match,
+		),
+	)
+}

package/src/workbase/opencode-launch.ts

@@ -15,6 +15,21 @@ const Admitted = Schema.Struct({
 	}),
 })
 
+// V1 stops config discovery at the Git root, so a checkout-rooted V1 launch
+// would miss the workbase's managed OpenCode config and plugin.
+export const openCodeDiscoversAncestorConfig = (cli: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const result = yield* fs.runCommand([cli, "--version"], {
+			captureOutput: true,
+			timeoutMs: 60_000,
+		})
+		return (
+			result.exitCode === 0 &&
+			/^(?:opencode\s+v?)?2\./.test(result.stdout.trim())
+		)
+	}).pipe(Effect.orElseSucceed(() => false))
+
 // V2's TUI --prompt only seeds the composer. Submit through the same CLI's
 // authenticated service connection, then attach without a prompt. Reloading or
 // reconnecting the TUI cannot replay the launch input. Only built-in Agency

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

@@ -27,6 +27,7 @@ const workerLaunchPattern = /^Agency worker launch target: ([^.\\s]+)\\./
 type AgencyContext = {
   root?: string
   checkout?: string
+  documentDirectory?: string
   target?: string
   task?: string
   phase?: string
@@ -139,9 +140,27 @@ const skillInfo = (path: string) => {
   }
 }
 
+const implementationInstructions = (
+  client: "OpenCode" | "Pi",
+  context: AgencyContext | undefined,
+  directory: string,
+) => {
+  if (!context?.checkout) return
+  const checkout = resolve(context.checkout)
+  const current = resolve(directory)
+  const repository = current === checkout || current.startsWith(\`\${checkout}\${sep}\`)
+    ? \`\${client} is rooted in Agency's authoritative writable checkout at \${checkout}. Use this directory for source reads, edits, Git status and other Git operations, builds, tests, and formatting.\`
+    : \`Agency's authoritative writable checkout is \${checkout}. Before doing implementation work or Git operations, change the working directory to that checkout. Set each tool's working directory to it when supported; otherwise use absolute paths.\`
+  const lifecycle = context.documentDirectory
+    ? \`Run Agency lifecycle commands from \${context.documentDirectory}; agency context may also be queried from the checkout. Any reference checkouts reported by Agency context are read-only.\`
+    : "Any reference checkouts reported by Agency context are read-only."
+  return \`\${repository} \${lifecycle}\`
+}
+
 const agencyContext = async (
   directory: string,
   useEnvironmentTarget = true,
+  requireWorking = false,
 ): Promise<AgencyContext | undefined> => {
   const task = useEnvironmentTarget ? process.env.AGENCY_TASK_ID : undefined
   const phase = useEnvironmentTarget ? process.env.AGENCY_PHASE_ID : undefined
@@ -161,18 +180,26 @@ const agencyContext = async (
   const result = envelope.result ?? {}
   const target = contextTarget(result)
   const document = result.target?.path
+  const checkout = result.authority?.writable?.checkoutPath
   const status = result.documents?.phase?.data?.status ?? result.documents?.task?.data?.status
+  const current = resolve(directory)
+  const documentDirectory = document ? dirname(document) : undefined
+  const matchesLocation =
+    documentDirectory === current ||
+    (checkout &&
+      (current === resolve(checkout) || current.startsWith(\`\${resolve(checkout)}\${sep}\`)))
   if (
     result.validation?.valid !== true ||
     !target ||
     !document ||
-    dirname(document) !== resolve(directory) ||
-    (target.startsWith("execution-unit:") &&
+    !matchesLocation ||
+    (requireWorking && target.startsWith("execution-unit:") &&
       (!result.authority?.writable?.checkoutPath || status !== "working"))
   ) return
   return {
     root: result.workbase?.root,
-    checkout: result.authority?.writable?.checkoutPath,
+    checkout,
+    documentDirectory,
     target,
     task: result.target?.taskId,
     phase: result.target?.phaseId,
@@ -181,10 +208,11 @@ const agencyContext = async (
 
 const plugin: V1Plugin = async ({ directory }) => {
   const workerSessions = new Map<string, AgencyContext>()
+  const locationContext = agencyContext(directory, false).catch(() => undefined)
 
   return {
     config: async (config: any) => {
-      const context = await agencyContext(directory).catch(() => undefined)
+      const context = await locationContext
       const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(directory)
       const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(directory, root)
 
@@ -220,7 +248,7 @@ const plugin: V1Plugin = async ({ directory }) => {
     "chat.message": async ({ sessionID }: { sessionID: string }, output: any) => {
       const launchTarget = workerLaunchTarget(output.parts)
       if (!launchTarget) return
-      const context = await agencyContext(directory, false).catch(() => undefined)
+      const context = await agencyContext(directory, false, true).catch(() => undefined)
       if (context?.target !== launchTarget) return
       workerSessions.set(sessionID, context)
     },
@@ -229,16 +257,16 @@ const plugin: V1Plugin = async ({ directory }) => {
       output: any,
     ) => {
       if (!sessionID) return
-      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.\`,
-          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(" "),
-      )
+      const worker = workerSessions.get(sessionID)
+      const context = worker ?? await locationContext
+      const implementation = implementationInstructions("OpenCode", context, directory)
+      if (!worker?.target && !implementation) return
+      output.system.push([
+        worker?.target
+          ? \`Agency verified this OpenCode session as the active worker for \${worker.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`
+          : undefined,
+        implementation,
+      ].filter(Boolean).join(" "))
     },
     "shell.env": async ({ sessionID }: { sessionID?: string }, output: any) => {
       if (!sessionID) return
@@ -259,7 +287,7 @@ export const AgencyPlugin = plugin
 
 const setup = async (context: V2PluginContext) => {
   const directory = context.location.directory
-  const agency = await agencyContext(directory).catch(() => undefined)
+  const agency = await agencyContext(directory, false).catch(() => undefined)
   const root = agency?.root ?? resolve(dirname(fileURLToPath(import.meta.url)), "../..")
   const instructionsPath = join(root, ".agency", "AGENTS.md")
   const instructions = existsSync(instructionsPath)
@@ -302,23 +330,21 @@ const setup = async (context: V2PluginContext) => {
   await context.session.hook("prompt", async (event) => {
     const launchTarget = event.prompt.text.match(workerLaunchPattern)?.[1]
     if (!launchTarget) return
-    const current = await agencyContext(directory, false).catch(() => undefined)
+    const current = await agencyContext(directory, false, true).catch(() => undefined)
     if (!current || current.target !== launchTarget) return
     workerSessions.set(event.sessionID, current)
   })
+  const implementation = implementationInstructions("OpenCode", agency, directory)
   await context.session.hook("context", (event) => {
     if (instructions) event.system.push({ type: "text", text: instructions })
     const current = workerSessions.get(event.sessionID)
-    if (!current?.target) return
-    event.system.push({
-      type: "text",
-      text: [
-        \`Agency verified this OpenCode session as the active worker for \${current.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
-        current.checkout
-          ? \`OpenCode remains rooted in the task or phase directory for Agency instructions and context. Treat \${current.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(" "),
-    })
+    const text = [
+      current?.target
+        ? \`Agency verified this OpenCode session as the active worker for \${current.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`
+        : undefined,
+      implementationInstructions("OpenCode", current, directory) ?? implementation,
+    ].filter(Boolean).join(" ")
+    if (text) event.system.push({ type: "text", text })
   })
 }
 

package/src/workbase/schemas.ts

@@ -107,6 +107,7 @@ export const WorkbaseConfig = Schema.Struct({
 		Schema.Record({ key: RepositoryAlias, value: RepositoryDeclaration }),
 	),
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+	branchNameCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	agents: Schema.optional(
 		Schema.Record({