@markjaquith/agency 2.30.0 → 2.31.0

package/README.md

@@ -37,13 +37,19 @@ For development, run `bun link` from this repository.
 Entity IDs come from directory names. Structured metadata lives in YAML 1.2
 frontmatter; prose below it supplies human and agent context.
 
+New epic, task, and phase documents use the same core prose sections:
+`Outcome` states the intended result, `Plan` describes the current approach, and
+`Important Decisions` preserves consequential choices and their rationale. These
+sections are creation defaults rather than validation requirements, so existing
+and customized documents remain valid.
+
 ## Workbase Layout
 
 ```text
 workbase/
   AGENTS.md                # managed workbase instructions
   .opencode/
-    opencode.jsonc         # managed task and epic references
+    opencode.jsonc         # managed whole-workbase reference
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -76,11 +82,13 @@ Agency keeps discovery and other observational commands read-only. Run
 files or refresh checksum-safe managed files. Customized files are reported but
 never overwritten.
 
-The OpenCode config advertises only the task and epic directories as documented
-references. OpenCode automatically grants those references scoped
-external-directory access, so Agency does not add blanket permission rules that
-could hide missing tool permissions. References provide context and never expand
-the write authority reported by `agency context`.
+The OpenCode config advertises the complete workbase as one portable relative
+reference. `agency work` sets `OPENCODE_CONFIG` to the managed file and injects
+runtime-only absolute rules that allow external access across the workbase while
+denying edits outside the execution unit's writable checkout. This makes the
+config effective from nested task and phase Git checkouts without persisting a
+machine-specific path or granting access outside the workbase. Bash and Agency
+operations must still follow the write authority reported by `agency context`.
 
 Repository aliases and canonical fetch remotes are declared in tracked
 `agency.json`; local bare clones and symlinks remain ignored under
@@ -201,6 +209,10 @@ 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.
+The `opencode` runner additionally receives `OPENCODE_CONFIG` for the workbase's
+managed integration and `OPENCODE_CONFIG_CONTENT` with runtime-only,
+workbase-scoped access and edit rules. These values keep the Git-synced config
+portable while providing whole-workbase read access at every launch location.
 `--print-command` prints the exact cwd and argv plus non-secret environment keys
 without launching the runner.
 

package/package.json

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

package/skills/agency/SKILL.md

@@ -132,6 +132,11 @@ integration files, then selects work and checks readiness. For an execution unit
 it materializes managed checkouts, claims the unit, marks it working, and starts
 the selected built-in or configured runner. Epic and multi-phase task launches
 start in orchestration context without materializing or claiming execution work.
+OpenCode launches expose the managed config file and inject runtime-only access
+rules scoped to the workbase. These grant visibility from orchestration
+directories and nested execution checkouts while denying direct edits outside
+the writable checkout. They do not make the Git-synced config machine-specific
+or replace write authority from `agency context`.
 
 An agent already running in an Agency checkout must not call `agency work` to
 start itself again. It should inspect context, perform the assigned work, and

package/skills/agency/references/commands.md

@@ -26,7 +26,9 @@ checkout descendants, or a task ID. Complete output includes prose and Git
 details; `--compact` intentionally omits them. `graph` computes readiness before
 applying filters. `doctor` discovers required tools, integrations, repositories,
 refs, worktrees, permissions, drift, and optional runner capabilities. `sync` is
-observational unless `--apply` is explicit.
+observational unless `--apply` is explicit. Integration status includes safe
+remediation when customized OpenCode config prevents Agency from guaranteeing
+whole-workbase access.
 
 Where `[filters]` appears, use repeatable `--status <status>` and `--repository
 <alias>`, plus `--ready` or `--blocked` and `--pr` or `--no-pr`. Each pair is
@@ -155,6 +157,9 @@ agency pr create <task-id> [phase-id] [--draft] [--force] [--json]
 `work` is a launch flow, not an active-agent step. It synchronizes managed
 integration files before launch. Execution targets are materialized and claimed;
 epics and multi-phase tasks launch in orchestration context without those steps.
+The OpenCode runner receives a runtime managed-config path plus absolute access
+and edit rules scoped to the workbase; none are persisted, and `context` still
+defines write authority.
 `--print-command` suppresses only the final launch, so execution targets are still
 materialized and claimed before the command is printed. `work prepare`
 materializes without launching or changing status. Destructive remove and

package/skills/agency/references/recipes.md

@@ -89,7 +89,9 @@ agency work tasks/checkout/phases/api
 
 `agency work` is intentionally last: it synchronizes managed integration files,
 checks readiness, materializes worktrees, creates a claim, marks this execution
-unit working, and launches the runner.
+unit working, and launches the runner. OpenCode receives whole-workbase read
+visibility through runtime-only config and permission values; this does not
+expand the writable checkout reported by `agency context`.
 
 ## Active Agent: Execute Assigned Work
 

package/src/cli.test.ts

@@ -829,6 +829,223 @@ status: open
 		).toBe("example\n")
 	})
 
+	test.skipIf(Bun.which("opencode") === null)(
+		"provides effective whole-workbase OpenCode access from every launch topology",
+		async () => {
+			const parent = await createTempDir()
+			tempDirs.push(parent)
+			const root = join(parent, "workbase")
+			const source = join(parent, "source")
+			expect(
+				Bun.spawnSync(["git", "init", "--initial-branch=main", source])
+					.exitCode,
+			).toBe(0)
+			await Bun.write(join(source, "README.md"), "example\n")
+			for (const args of [
+				["config", "user.email", "test@example.com"],
+				["config", "user.name", "Test"],
+				["add", "README.md"],
+				["-c", "commit.gpgsign=false", "commit", "-m", "initial"],
+			]) {
+				expect(Bun.spawnSync(["git", "-C", source, ...args]).exitCode).toBe(0)
+			}
+
+			parseJson(await runCli(["init", root, "--json"], parent))
+			parseJson(
+				await runCli(["repo", "link", "agency", source, "--json"], root),
+			)
+			parseJson(
+				await runCli(
+					[
+						"epic",
+						"create",
+						"delivery",
+						"--ticket-url",
+						"https://example.com/delivery",
+						"--repo",
+						"agency:main",
+						"--json",
+					],
+					root,
+				),
+			)
+			for (const [id, branch] of [
+				["example", "feat/example"],
+				["sibling", "feat/sibling"],
+			] as const) {
+				parseJson(
+					await runCli(
+						[
+							"task",
+							"create",
+							id,
+							"--repo",
+							"agency",
+							"--branch",
+							branch,
+							"--base",
+							"main",
+							"--epic",
+							"delivery",
+							"--json",
+						],
+						root,
+					),
+				)
+			}
+			parseJson(
+				await runCli(
+					["task", "create", "pipeline", "--multi-phase", "--json"],
+					root,
+				),
+			)
+			parseJson(
+				await runCli(
+					[
+						"phase",
+						"create",
+						"pipeline",
+						"build",
+						"--repo",
+						"agency",
+						"--branch",
+						"feat/pipeline-build",
+						"--base",
+						"main",
+						"--json",
+					],
+					root,
+				),
+			)
+
+			const taskWorkspace = parseJson(
+				await runCli(["work", "prepare", "example", "--json"], root),
+			)
+			const phaseWorkspace = parseJson(
+				await runCli(
+					[
+						"work",
+						"prepare",
+						"--task",
+						"pipeline",
+						"--phase",
+						"build",
+						"--json",
+					],
+					root,
+				),
+			)
+			const synced = parseJson(
+				await runCli(["integration", "sync", "--json"], root),
+			)
+			expect(
+				synced.files.every((file: { changed: boolean }) => !file.changed),
+			).toBe(true)
+
+			const workbaseRoot = await realpath(root)
+			const config = await Bun.file(
+				join(workbaseRoot, ".opencode/opencode.jsonc"),
+			).text()
+			expect(config).not.toContain(workbaseRoot)
+			const documents = [
+				join(workbaseRoot, "tasks/example/TASK.md"),
+				join(workbaseRoot, "epics/delivery/EPIC.md"),
+				join(workbaseRoot, "tasks/sibling/TASK.md"),
+			]
+			for (const document of documents) {
+				expect(await Bun.file(document).exists()).toBe(true)
+			}
+
+			const launches = [
+				{
+					args: ["--task", "example"],
+					cwd: taskWorkspace.writablePath,
+					writable: true,
+				},
+				{
+					args: ["--task", "pipeline", "--phase", "build"],
+					cwd: phaseWorkspace.writablePath,
+					writable: true,
+				},
+				{
+					args: ["--epic", "delivery"],
+					cwd: join(workbaseRoot, "epics/delivery"),
+					writable: false,
+				},
+				{
+					args: ["--task", "pipeline"],
+					cwd: join(workbaseRoot, "tasks/pipeline"),
+					writable: false,
+				},
+			]
+			for (const launch of launches) {
+				const printed = await runCli(
+					["work", ...launch.args, "--opencode", "--print-command", "--force"],
+					root,
+				)
+				expect(printed.exitCode).toBe(0)
+				expect(printed.stderr).toBe("")
+				const contract = JSON.parse(printed.stdout)
+				expect(contract.cwd).toBe(launch.cwd)
+				expect(contract.environment.OPENCODE_CONFIG).toBe(
+					join(workbaseRoot, ".opencode/opencode.jsonc"),
+				)
+				const environment = {
+					...process.env,
+					...contract.environment,
+					XDG_CONFIG_HOME: isolatedConfigHome,
+					OPENCODE_DISABLE_EXTERNAL_SKILLS: "1",
+				}
+				const probe = Bun.spawnSync(["opencode", "debug", "agent", "build"], {
+					cwd: contract.cwd,
+					env: environment,
+				})
+				expect(probe.exitCode).toBe(0)
+				const agent = JSON.parse(probe.stdout.toString())
+				expect(agent.permission).toEqual(
+					expect.arrayContaining([
+						expect.objectContaining({
+							permission: "external_directory",
+							pattern: join(workbaseRoot, "**"),
+							action: "allow",
+						}),
+					]),
+				)
+				expect(agent.permission).toEqual(
+					expect.arrayContaining([
+						expect.objectContaining({
+							permission: "edit",
+							pattern: launch.writable ? "../**" : "*",
+							action: "deny",
+						}),
+					]),
+				)
+
+				if (launch === launches[0]) {
+					for (const document of documents) {
+						const read = Bun.spawnSync(
+							[
+								"opencode",
+								"debug",
+								"agent",
+								"build",
+								"--tool",
+								"read",
+								"--params",
+								JSON.stringify({ filePath: document }),
+							],
+							{ cwd: contract.cwd, env: environment },
+						)
+						expect(read.exitCode).toBe(0)
+						const result = JSON.parse(read.stdout.toString())
+						expect(result.result.output).toContain(`<path>${document}</path>`)
+					}
+				}
+			}
+		},
+		30_000,
+	)
+
 	test("envelopes help and version output in machine mode", async () => {
 		const help = await runCli(["status", "--help", "--json"])
 		expect(parseJson(help)).toContain("Usage: agency status")

package/src/commands/doctor.test.ts

@@ -129,6 +129,28 @@ status: open
 		)
 	})
 
+	test("warns when customized OpenCode config cannot guarantee access", async () => {
+		const custom = '{"references":{}}\n'
+		await write(root, ".opencode/opencode.jsonc", custom)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(doctor({ cwd: root, json: true })),
+		)
+		const check = JSON.parse(logs[0]!).checks.find(
+			(value: { id: string }) => value.id === "integration.file.opencode",
+		)
+
+		expect(check).toMatchObject({
+			level: "warning",
+			status: "fail",
+			message: expect.stringContaining("cannot guarantee whole-workbase"),
+			remediation: expect.stringContaining("global config"),
+		})
+		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
+			custom,
+		)
+	})
+
 	test("is safe when the workbase is read-only", async () => {
 		for (const path of [
 			join(root, "agency.json"),

package/src/commands/init.test.ts

@@ -38,9 +38,10 @@ describe("init command", () => {
 			join(root, ".opencode/opencode.jsonc"),
 		).text()
 		const config = JSON.parse(opencode.slice(opencode.indexOf("\n\n") + 2))
-		expect(config.permission.external_directory).toEqual({
-			"../**": "allow",
+		expect(config.references).toEqual({
+			workbase: expect.objectContaining({ path: ".." }),
 		})
+		expect(config.permission).toBeUndefined()
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureLogs,
@@ -29,11 +30,30 @@ describe("integration command", () => {
 			root,
 			files: [
 				{ name: "agents", state: "missing" },
-				{ name: "opencode", state: "missing" },
+				{
+					name: "opencode",
+					state: "missing",
+					diagnostic: expect.stringContaining("cannot load"),
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
 
+	test("explains remediation for customized OpenCode config", async () => {
+		await mkdir(join(root, ".opencode"))
+		await Bun.write(
+			join(root, ".opencode", "opencode.json"),
+			'{"model":"test/model"}\n',
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(integration({ subcommand: "status", cwd: root })),
+		)
+
+		expect(logs.join("\n")).toContain("cannot guarantee whole-workbase")
+		expect(logs.join("\n")).toContain("global config")
+	})
+
 	test("explicitly synchronizes integration files", async () => {
 		const logs = await captureLogs(() =>
 			runTestEffect(integration({ subcommand: "sync", cwd: root, json: true })),

package/src/commands/integration.ts

@@ -22,7 +22,8 @@ export const integration = (options: IntegrationOptions) =>
 					return
 				}
 				for (const file of result.files) {
-					log(`${file.name}\t${file.state}\t${file.path}`)
+					log(`${file.name}\t${file.state}\t${file.path}\t${file.diagnostic}`)
+					if (file.remediation) log(`  Remediation: ${file.remediation}`)
 				}
 				return
 			}
@@ -35,8 +36,9 @@ export const integration = (options: IntegrationOptions) =>
 				}
 				for (const file of result.files) {
 					log(
-						`${file.name}\t${file.changed ? "synced" : file.state}\t${file.path}`,
+						`${file.name}\t${file.changed ? "synced" : file.state}\t${file.path}\t${file.diagnostic}`,
 					)
+					if (file.remediation) log(`  Remediation: ${file.remediation}`)
 				}
 				return
 			}
@@ -51,10 +53,12 @@ export const integration = (options: IntegrationOptions) =>
 export const help = `
 Usage: agency integration <subcommand>
 
-Inspect or explicitly synchronize managed agent integration files.
+Inspect or explicitly synchronize managed agent integration files. OpenCode
+launches load the managed file at runtime to provide whole-workbase read
+access without changing Agency write authority.
 
 Subcommands:
-  status  Report managed, customized, missing, and drifted files
+  status  Report file state, access diagnostics, and safe remediation
   sync    Create or update checksum-safe managed files
 
 Options:

package/src/commands/work.test.ts

@@ -67,6 +67,7 @@ interface HarnessOptions {
 	readonly existingDirectories?: readonly string[]
 	readonly guardError?: Error
 	readonly readyTargetIds?: readonly string[]
+	readonly opencodeIntegrationState?: "managed" | "customized"
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
@@ -215,7 +216,15 @@ const createHarness = (options: HarnessOptions = {}) => {
 	const integrations = {
 		sync: () => {
 			integrationSyncs += 1
-			return Effect.succeed({ root: "/workbase", files: [] })
+			return Effect.succeed({
+				root: "/workbase",
+				files: [
+					{
+						name: "opencode",
+						state: options.opencodeIntegrationState ?? "managed",
+					},
+				],
+			})
 		},
 	}
 	const fs = {
@@ -395,6 +404,23 @@ describe("work command", () => {
 			],
 			cwd: "/workbase/epics/delivery",
 		})
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
+		expect(
+			JSON.parse(harness.launchEnvironments[0]!.OPENCODE_CONFIG_CONTENT!),
+		).toEqual({
+			permission: {
+				external_directory: { "/workbase/**": "allow" },
+				edit: { "*": "deny" },
+			},
+			agent: {
+				build: { permission: { edit: { "*": "deny" } } },
+				plan: { permission: { edit: { "*": "deny" } } },
+				general: { permission: { edit: { "*": "deny" } } },
+				explore: { permission: { edit: { "*": "deny" } } },
+			},
+		})
 	})
 
 	test("resolves an existing positional path before treating it as a task ID", async () => {
@@ -444,6 +470,9 @@ describe("work command", () => {
 			],
 			cwd: "/workbase/tasks/delivery",
 		})
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 	})
 
 	test("infers a phase from a nested checkout directory", async () => {
@@ -472,6 +501,9 @@ describe("work command", () => {
 		expect(harness.statusUpdates).toEqual([
 			"phase:example:implementation:working",
 		])
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 	})
 
 	test("infers a single-phase task from a nested checkout directory", async () => {
@@ -485,6 +517,9 @@ describe("work command", () => {
 
 		expect(harness.events[0]).toBe("materialize")
 		expect(harness.launches[0]?.cwd).toBe(singlePhaseWorkspace.writablePath)
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 	})
 
 	test("selects a target when no directory is provided", async () => {
@@ -665,6 +700,9 @@ describe("work command", () => {
 			},
 		])
 		expect(harness.statusUpdates).toEqual(["task:example:working"])
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
 		expect(harness.progressUpdates).toEqual([
 			"start:Preparing workspace...",
 			"succeed:Workspace ready",
@@ -768,6 +806,40 @@ describe("work command", () => {
 		expect(printed.environment.API_TOKEN).toBeUndefined()
 	})
 
+	test("prints the runtime OpenCode integration config", async () => {
+		const harness = createHarness()
+		const output = await captureLogs(() =>
+			harness.run({ taskId: "example", opencode: true, printCommand: true }),
+		)
+		const printed = JSON.parse(output.join("\n"))
+
+		expect(printed.environment.OPENCODE_CONFIG).toBe(
+			"/workbase/.opencode/opencode.jsonc",
+		)
+		expect(JSON.parse(printed.environment.OPENCODE_CONFIG_CONTENT)).toEqual({
+			permission: {
+				external_directory: { "/workbase/**": "allow" },
+				edit: { "../**": "deny" },
+			},
+			agent: {
+				build: { permission: { edit: { "../**": "deny" } } },
+				plan: { permission: { edit: { "../**": "deny" } } },
+				general: { permission: { edit: { "../**": "deny" } } },
+				explore: { permission: { edit: { "../**": "deny" } } },
+			},
+		})
+	})
+
+	test("does not override customized OpenCode access policy", async () => {
+		const harness = createHarness({ opencodeIntegrationState: "customized" })
+		await harness.run({ taskId: "example", opencode: true })
+
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
+		expect(
+			harness.launchEnvironments[0]?.OPENCODE_CONFIG_CONTENT,
+		).toBeUndefined()
+	})
+
 	test("automatically falls back to Claude", async () => {
 		const harness = createHarness({ available: { opencode: false } })
 
@@ -779,6 +851,7 @@ describe("work command", () => {
 			args: ["claude", "Start the task. Read /workbase/tasks/example/TASK.md."],
 			cwd: singlePhaseWorkspace.writablePath,
 		})
+		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
 	})
 
 	test("does not fall back when OpenCode is explicitly required", async () => {

package/src/commands/work.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
 import { WorktreeService } from "../services/WorktreeService"
 import { FileSystemService } from "../services/FileSystemService"
@@ -120,7 +120,10 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
-		yield* integrations.sync(root)
+		const integration = yield* integrations.sync(root)
+		const managedOpencode = integration.files.some(
+			(file) => file.name === "opencode" && file.state === "managed",
+		)
 		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null
@@ -325,6 +328,25 @@ export const work = (
 			...resolved.environment,
 			...runnerEnvironment(runner, variables),
 		}
+		if (runner === "opencode" && managedOpencode) {
+			environment.OPENCODE_CONFIG = join(root, ".opencode", "opencode.jsonc")
+			const execution =
+				target.kind === "phase" ||
+				(target.kind === "task" && !target.multiPhase)
+			const edit = { [execution ? "../**" : "*"]: "deny" as const }
+			environment.OPENCODE_CONFIG_CONTENT = JSON.stringify({
+				permission: {
+					external_directory: { [join(root, "**")]: "allow" },
+					edit,
+				},
+				agent: {
+					build: { permission: { edit } },
+					plan: { permission: { edit } },
+					general: { permission: { edit } },
+					explore: { permission: { edit } },
+				},
+			})
+		}
 		if (options.printCommand) {
 			log(
 				JSON.stringify(
@@ -422,7 +444,8 @@ Usage: agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>]
 Launch an agent for an epic, task, or phase. With no directory, select one
 interactively. A positional argument resolves as a directory first, then as a task
 ID. Use '.' for the current directory. Outside a workbase, select a registered
-workbase first.
+workbase first. OpenCode launches receive whole-workbase read access through the
+runtime environment; Agency context remains authoritative for writes.
 
 The prepare subcommand resolves and materializes an execution workspace without
 launching an agent or changing lifecycle status. --dry-run reports planned Git

package/src/services/DoctorService.ts

@@ -242,15 +242,20 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 
 					const integrationStatus = yield* integrations.status(root)
 					for (const file of integrationStatus.files) {
-						const failed = file.state === "missing" || file.state === "drifted"
+						const failed =
+							file.state === "missing" ||
+							file.state === "drifted" ||
+							(file.name === "opencode" && file.state === "customized")
 						add({
 							id: `integration.file.${file.name}`,
 							category: "integration",
-							level: file.state === "customized" ? "optional" : "warning",
+							level:
+								file.name === "agents" && file.state === "customized"
+									? "optional"
+									: "warning",
 							status: failed ? "fail" : "pass",
-							message: `${file.name} integration file is ${file.state}: ${file.path}`,
-							remediation:
-								"Run 'agency integration sync' to restore managed content.",
+							message: `${file.name} integration file is ${file.state}: ${file.path}. ${file.diagnostic}`,
+							remediation: file.remediation ?? undefined,
 						})
 					}
 

package/src/services/EpicService.test.ts

@@ -34,6 +34,9 @@ describe("EpicService", () => {
 
 		expect(created.content).toContain("ticketUrl:")
 		expect(created.content).toContain("tasks: []")
+		expect(created.content).toContain(
+			"# Workspace Orchestration\n\n## Outcome\n\nDescribe the epic outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 
 		const records = await runTestEffect(
 			EpicService.pipe(Effect.flatMap((service) => service.list(root))),

package/src/services/EpicService.ts

@@ -10,6 +10,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { documentRevision } from "../workbase/document-revision"
@@ -95,7 +96,7 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 					.join(" ")
 				const content = formatMarkdownDocument(
 					data,
-					`# ${title}\n\nDescribe the epic outcome.`,
+					formatWorkDocumentBody(title, "epic"),
 				)
 				yield* fs.writeFile(path, content)
 				return {

package/src/services/IntegrationService.test.ts

@@ -97,30 +97,55 @@ describe("IntegrationService", () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencode))
 
 		expect(config.references).toEqual({
-			tasks: {
-				path: "../tasks",
+			workbase: {
+				path: "..",
 				description:
-					"Agency task definitions and execution context; authority still comes from agency context",
+					"Complete Agency workbase context; write authority still comes only from agency context",
 			},
-			epics: {
-				path: "../epics",
-				description:
-					"Agency epic definitions and orchestration context; no implementation write authority",
-			},
-		})
-		expect(config.permission).toEqual({
-			external_directory: { "../**": "allow" },
 		})
+		expect(config.permission).toBeUndefined()
+		expect(managedBody(managedWorkbaseOpencode)).not.toContain(process.cwd())
 	})
 
 	test("treats an existing JSON OpenCode config as customized", async () => {
 		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
 
 		const result = await status(root)
-		expect(result.files[1]).toEqual({
+		expect(result.files[1]).toMatchObject({
 			name: "opencode",
 			path: join(root, ".opencode/opencode.json"),
 			state: "customized",
+			diagnostic: expect.stringContaining("cannot guarantee"),
+			remediation: expect.stringContaining("global config"),
+		})
+	})
+
+	test("treats a JSON config beside managed JSONC as customized", async () => {
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
+		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
+
+		const result = await status(root)
+		expect(result.files[1]).toMatchObject({
+			name: "opencode",
+			path: join(root, ".opencode/opencode.json"),
+			state: "customized",
+		})
+	})
+
+	test("reports actionable whole-workbase access diagnostics", async () => {
+		let result = await status(root)
+		expect(result.files[1]).toMatchObject({
+			state: "missing",
+			diagnostic: expect.stringContaining("cannot load"),
+			remediation: expect.stringContaining("integration sync"),
+		})
+
+		await write(root, ".opencode/opencode.jsonc", '{"model":"test/model"}\n')
+		result = await status(root)
+		expect(result.files[1]).toMatchObject({
+			state: "customized",
+			diagnostic: expect.stringContaining("cannot guarantee"),
+			remediation: expect.stringContaining("global config"),
 		})
 	})
 

package/src/services/IntegrationService.ts

@@ -17,28 +17,79 @@ interface IntegrationFileStatus {
 	readonly name: "agents" | "opencode"
 	readonly path: string
 	readonly state: IntegrationFileState
+	readonly diagnostic: string
+	readonly remediation: string | null
 }
 
 interface IntegrationSyncFile extends IntegrationFileStatus {
 	readonly changed: boolean
 }
 
+const describe = (
+	name: IntegrationFileStatus["name"],
+	state: IntegrationFileState,
+) => {
+	if (name === "opencode") {
+		if (state === "managed") {
+			return {
+				diagnostic:
+					"Agency's managed OpenCode launch config is ready to provide whole-workbase read access.",
+				remediation: null,
+			}
+		}
+		if (state === "customized") {
+			return {
+				diagnostic:
+					"Agency cannot guarantee whole-workbase read access from this customized OpenCode config.",
+				remediation:
+					"Back up and remove the customized file, run 'agency integration sync', then move any retained custom settings to OpenCode's global config.",
+			}
+		}
+		return {
+			diagnostic:
+				"Agency OpenCode launches cannot load current whole-workbase access.",
+			remediation:
+				"Run 'agency integration sync' to install whole-workbase OpenCode access.",
+		}
+	}
+
+	return state === "missing" || state === "drifted"
+		? {
+				diagnostic: "Managed workbase instructions need synchronization.",
+				remediation:
+					"Run 'agency integration sync' to restore managed instructions.",
+			}
+		: {
+				diagnostic:
+					state === "managed"
+						? "Managed workbase instructions are current."
+						: "Customized workbase instructions are preserved.",
+				remediation: null,
+			}
+}
+
+const fileStatus = (
+	name: IntegrationFileStatus["name"],
+	path: string,
+	state: IntegrationFileState,
+): IntegrationFileStatus => ({ name, path, state, ...describe(name, state) })
+
 const classify = (
 	name: IntegrationFileStatus["name"],
 	path: string,
 	content: string,
 	managed: string,
 	canUpdate: (content: string) => boolean,
-): IntegrationFileStatus => ({
-	name,
-	path,
-	state:
+): IntegrationFileStatus =>
+	fileStatus(
+		name,
+		path,
 		content === managed
 			? "managed"
 			: canUpdate(content)
 				? "drifted"
 				: "customized",
-})
+	)
 
 const inspect = (root: string) =>
 	Effect.gen(function* () {
@@ -51,7 +102,7 @@ const inspect = (root: string) =>
 
 		files.push(
 			(yield* fs.readSymlinkTarget(agentsPath)) !== null
-				? { name: "agents", path: agentsPath, state: "customized" }
+				? fileStatus("agents", agentsPath, "customized")
 				: (yield* fs.exists(agentsPath))
 					? classify(
 							"agents",
@@ -60,15 +111,16 @@ const inspect = (root: string) =>
 							managedWorkbaseAgents,
 							canUpdateManagedWorkbaseAgents,
 						)
-					: { name: "agents", path: agentsPath, state: "missing" },
+					: fileStatus("agents", agentsPath, "missing"),
 		)
 
 		if ((yield* fs.readSymlinkTarget(opencodePath)) !== null) {
-			files.push({
-				name: "opencode",
-				path: opencodePath,
-				state: "customized",
-			})
+			files.push(fileStatus("opencode", opencodePath, "customized"))
+		} else if (
+			(yield* fs.readSymlinkTarget(opencodeJsonPath)) !== null ||
+			(yield* fs.exists(opencodeJsonPath))
+		) {
+			files.push(fileStatus("opencode", opencodeJsonPath, "customized"))
 		} else if (yield* fs.exists(opencodePath)) {
 			files.push(
 				classify(
@@ -79,14 +131,8 @@ const inspect = (root: string) =>
 					canUpdateManagedWorkbaseOpencode,
 				),
 			)
-		} else if (yield* fs.exists(opencodeJsonPath)) {
-			files.push({
-				name: "opencode",
-				path: opencodeJsonPath,
-				state: "customized",
-			})
 		} else {
-			files.push({ name: "opencode", path: opencodePath, state: "missing" })
+			files.push(fileStatus("opencode", opencodePath, "missing"))
 		}
 
 		return files
@@ -123,8 +169,11 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							}
 						}
 						files.push({
-							...status,
-							state: changed ? "managed" : status.state,
+							...fileStatus(
+								status.name,
+								status.path,
+								changed ? "managed" : status.state,
+							),
 							changed,
 						})
 					}

package/src/services/PhaseService.ts

@@ -14,6 +14,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
@@ -196,7 +197,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						.join(" ")
 					const content = formatMarkdownDocument(
 						data,
-						`# ${title}\n\nDescribe the phase outcome.`,
+						formatWorkDocumentBody(title, "phase"),
 					)
 
 					if (!isMultiPhase) {
@@ -246,7 +247,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						const firstPhasePath = join(firstDirectory, "PHASE.md")
 						const firstContent = formatMarkdownDocument(
 							firstData,
-							`# ${firstTitle}\n\nDescribe the phase outcome.`,
+							formatWorkDocumentBody(firstTitle, "phase"),
 						)
 						const steps: TransactionStep[] = []
 						if (yield* fs.isDirectory(oldCodePath)) {

package/src/services/PullRequestService.test.ts

@@ -220,7 +220,10 @@ process.exit(${exitCode})
 		const original = await Bun.file(taskPath).text()
 		await Bun.write(
 			taskPath,
-			original.replace("# Example\n\nDescribe the task outcome.", body),
+			original.replace(
+				"# Example\n\n## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+				body,
+			),
 		)
 		const url = "https://github.com/example/agency/pull/42"
 		await writeFakeGh({ stdout: `${url}\n` })

package/src/services/TaskPhaseService.test.ts

@@ -33,7 +33,7 @@ describe("task and phase services", () => {
 				),
 			),
 		)
-		await runTestEffect(
+		const createdTask = await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
 					service.create(
@@ -51,6 +51,9 @@ describe("task and phase services", () => {
 				),
 			),
 		)
+		expect(createdTask.content).toContain(
+			"# Task One\n\n## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 
 		const epic = await runTestEffect(
 			EpicService.pipe(
@@ -159,6 +162,14 @@ describe("task and phase services", () => {
 			),
 		)
 		expect(phases.map((phase) => phase.id)).toEqual(["first", "second"])
+		const firstPhase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) => service.show("multi", "first", root)),
+			),
+		)
+		expect(firstPhase.content).toContain(
+			"# First\n\n## Outcome\n\nDescribe the phase outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 	})
 
 	test("converts a single-phase task when the existing phase ID is provided", async () => {
@@ -243,7 +254,9 @@ describe("task and phase services", () => {
 				{ id: "extra", dependsOn: ["implementation"] },
 			],
 		})
-		expect(task.content).toContain("Describe the task outcome.")
+		expect(task.content).toContain(
+			"## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions",
+		)
 
 		const firstPhase = await runTestEffect(
 			PhaseService.pipe(

package/src/services/TaskService.ts

@@ -13,6 +13,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
@@ -163,7 +164,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					.join(" ")
 				const content = formatMarkdownDocument(
 					data,
-					`# ${title}\n\nDescribe the task outcome.`,
+					formatWorkDocumentBody(title, "task"),
 				)
 				const writes: {
 					path: string

package/src/workbase/AGENTS.md

@@ -73,4 +73,7 @@ creates these files, and `agency work` reconciles them 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`.
+`agency context`. Agency launches expose the managed OpenCode config file at
+runtime and inject absolute access rules scoped to this workbase. Direct edits
+remain denied outside the writable checkout, and no machine-specific path is
+stored in the Git-synced config.

package/src/workbase/frontmatter.ts

@@ -81,3 +81,20 @@ export const parseFrontmatter = (content: string, path: string) =>
 
 export const formatMarkdownDocument = (data: object, body: string) =>
 	`---\n${stringify(data, { lineWidth: 0 }).trimEnd()}\n---\n\n${body.trim()}\n`
+
+export const formatWorkDocumentBody = (
+	title: string,
+	kind: "epic" | "task" | "phase",
+) => `# ${title}
+
+## Outcome
+
+Describe the ${kind} outcome.
+
+## Plan
+
+Describe the current approach.
+
+## Important Decisions
+
+Record consequential decisions and their rationale.`

package/src/workbase/opencode-file.ts

@@ -11,20 +11,10 @@ const body = () =>
 		{
 			$schema: "https://opencode.ai/config.json",
 			references: {
-				tasks: {
-					path: "../tasks",
+				workbase: {
+					path: "..",
 					description:
-						"Agency task definitions and execution context; authority still comes from agency context",
-				},
-				epics: {
-					path: "../epics",
-					description:
-						"Agency epic definitions and orchestration context; no implementation write authority",
-				},
-			},
-			permission: {
-				external_directory: {
-					"../**": "allow",
+						"Complete Agency workbase context; write authority still comes only from agency context",
 				},
 			},
 		},