@markjaquith/agency 2.46.0 → 2.47.1

package/README.md

@@ -54,7 +54,7 @@ workbase/
     opencode.jsonc         # managed @agency subagent, instructions, and reference
     tui.jsonc              # managed TUI plugin registration
     command/agency.md      # managed /agency workflow command
-    plugin/agency-repository-skills.ts # managed checkout skill discovery
+    plugin/agency-repository-skills.ts # managed workbase access and checkout skills
     tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
@@ -99,7 +99,11 @@ The OpenCode config defines an `@agency` subagent for delegated workbase
 orchestration, loads Agency's hidden instructions in addition to any user-owned
 root `AGENTS.md`, advertises the complete workbase as one portable reference,
 and replaces the built-in Plan agent with `agency-plan`. That planning agent can
-update `TASK.md`, `PHASE.md`, and `EPIC.md` while other edits remain disabled.
+update `TASK.md`, `PHASE.md`, and `EPIC.md`, inspect the workbase through
+read-only Agency commands, and use explicit Agency CLI permissions to create or
+update planning structure. Its normal research tools and the complete Agency CLI
+remain available; managed Agency instructions and reported authority govern each
+operation.
 When the subagent launches work in another agent, it verifies that the runner
 started and returns without waiting for the task to finish.
 The TUI-only `/agency-debug` command reports TUI companion initialization and
@@ -107,9 +111,10 @@ 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 from task and epic launch directories. Agents
-receive whole-workbase visibility from that reference. Bash and Agency operations
-must still follow the write authority reported by `agency context`.
+OpenCode discovers the config and plugin from task and epic launch directories.
+The plugin grants whole-workbase access dynamically, while the portable
+reference advertises that context to agents. Bash and Agency operations must
+still follow the write authority reported by `agency context`.
 
 OpenCode also discovers a managed `/agency` command. Use `/agency status` for a
 read-only current-work summary, `/agency start [target]` to begin or resume work
@@ -248,8 +253,9 @@ authoritative writable checkout path.
 `AGENCY_PROMPT` is empty unless `--auto` is set.
 The `opencode` runner remains rooted in its task or epic working directory so
 the workbase `AGENTS.md` and managed OpenCode config are discovered normally.
-Agency's managed OpenCode plugin adds existing checkout-local `.claude/skills`,
-`.agents/skills`, and `.opencode/{skill,skills}` directories to `skills.paths`.
+Agency's managed OpenCode plugin grants the active workbase external-directory
+access and adds existing checkout-local `.claude/skills`, `.agents/skills`, and
+`.opencode/{skill,skills}` directories to `skills.paths`.
 `agency work` supplies the checkout directly; plain OpenCode launches resolve a
 materialized execution-unit checkout through `agency context`. A multi-phase
 task root has no single checkout, so launch from its phase directory when using

package/package.json

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

package/skills/agency/references/recipes.md

@@ -92,9 +92,8 @@ checks readiness, materializes worktrees, marks this execution unit working
 without a claim, and launches the runner. Run it again to relaunch unclaimed
 working work. The runner opens without a prompt by default; add `--auto` only
 when the generated context prompt should start autonomous execution.
-OpenCode receives whole-workbase read visibility through runtime-only config and
-permission values; this does not expand the writable checkout reported by
-`agency context`.
+OpenCode receives whole-workbase visibility through the managed project plugin;
+this does not expand the writable checkout reported by `agency context`.
 
 ## Active Agent: Execute Assigned Work
 

package/src/cli.test.ts

@@ -1059,13 +1059,7 @@ status: open
 				expect(contract.environment.AGENCY_WRITABLE_CHECKOUT).toBe(
 					launch.checkoutPath,
 				)
-				expect(
-					JSON.parse(contract.environment.OPENCODE_CONFIG_CONTENT),
-				).toEqual({
-					permission: {
-						external_directory: { [join(workbaseRoot, "*")]: "allow" },
-					},
-				})
+				expect(contract.environment.OPENCODE_CONFIG_CONTENT).toBeUndefined()
 				const environment = {
 					...process.env,
 					...contract.environment,
@@ -1093,6 +1087,9 @@ status: open
 				})
 				expect(configProbe.exitCode).toBe(0)
 				const effectiveConfig = JSON.parse(configProbe.stdout.toString())
+				expect(effectiveConfig.permission.external_directory).toMatchObject({
+					[join(workbaseRoot, "*")]: "allow",
+				})
 				expect(effectiveConfig.plugin_origins).toEqual(
 					expect.arrayContaining([
 						expect.objectContaining({
@@ -1218,9 +1215,11 @@ status: open
 					env: directEnvironment,
 				})
 				expect(configProbe.exitCode).toBe(0)
-				expect(
-					JSON.parse(configProbe.stdout.toString()).plugin_origins,
-				).toEqual(
+				const effectiveConfig = JSON.parse(configProbe.stdout.toString())
+				expect(effectiveConfig.permission.external_directory).toMatchObject({
+					[join(workbaseRoot, "*")]: "allow",
+				})
+				expect(effectiveConfig.plugin_origins).toEqual(
 					expect.arrayContaining([
 						expect.objectContaining({
 							spec: expect.stringContaining("agency-repository-skills.ts"),
@@ -1247,6 +1246,31 @@ status: open
 					)
 				}
 			}
+			const denied = Bun.spawnSync(["opencode", "debug", "agent", "build"], {
+				cwd: directDirectories[0],
+				env: {
+					...directEnvironment,
+					OPENCODE_CONFIG_CONTENT: JSON.stringify({
+						permission: { external_directory: { "*": "deny" } },
+					}),
+				},
+			})
+			expect(denied.exitCode).toBe(0)
+			const deniedRules = JSON.parse(denied.stdout.toString()).permission
+			const managedRule = deniedRules.findIndex(
+				(rule: any) =>
+					rule.permission === "external_directory" &&
+					rule.pattern === join(workbaseRoot, "*") &&
+					rule.action === "allow",
+			)
+			const userRule = deniedRules.findLastIndex(
+				(rule: any) =>
+					rule.permission === "external_directory" &&
+					rule.pattern === "*" &&
+					rule.action === "deny",
+			)
+			expect(managedRule).toBeGreaterThanOrEqual(0)
+			expect(userRule).toBeGreaterThan(managedRule)
 			for (const cwd of [
 				join(workbaseRoot, "tasks/example"),
 				join(workbaseRoot, "tasks/pipeline/phases/build"),
@@ -1325,7 +1349,7 @@ status: open
 				graph.nodes.find((node: any) => node.id === "task:pipeline").status,
 			).toBe("working")
 		},
-		90_000,
+		180_000,
 	)
 
 	test("envelopes help and version output in machine mode", async () => {

package/src/commands/init.test.ts

@@ -49,6 +49,9 @@ describe("init command", () => {
 		expect(config.agent["agency-plan"]).toMatchObject({
 			mode: "primary",
 			permission: {
+				bash: {
+					"agency *": "allow",
+				},
 				edit: {
 					"*": "deny",
 					"tasks/*/TASK.md": "allow",

package/src/commands/integration.test.ts

@@ -96,10 +96,10 @@ OpenCode /agency command: missing
   The managed OpenCode /agency command needs synchronization.
   Action: Run 'agency integration sync' to install the managed /agency command.
 
-OpenCode checkout skills: missing
+OpenCode workbase plugin: missing
   Path: .opencode/plugin/agency-repository-skills.ts
-  The managed OpenCode checkout-skill plugin needs synchronization.
-  Action: Run 'agency integration sync' to expose writable-checkout skills in OpenCode.
+  The managed OpenCode workbase plugin needs synchronization.
+  Action: Run 'agency integration sync' to provide workbase access and expose writable-checkout skills in OpenCode.
 
 OpenCode TUI config: missing
   Path: .opencode/tui.jsonc
@@ -165,9 +165,9 @@ OpenCode /agency command: synced
   Path: .opencode/command/agency.md
   Agency's managed OpenCode /agency command is current.
 
-OpenCode checkout skills: synced
+OpenCode workbase plugin: synced
   Path: .opencode/plugin/agency-repository-skills.ts
-  Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.
+  Agency's managed OpenCode plugin provides whole-workbase access and exposes writable-checkout skills.
 
 OpenCode TUI config: synced
   Path: .opencode/tui.jsonc

package/src/commands/integration.ts

@@ -31,7 +31,7 @@ const integrationNames = {
 	agents: "Agent instructions",
 	opencode: "OpenCode config",
 	"opencode-command": "OpenCode /agency command",
-	"opencode-plugin": "OpenCode checkout skills",
+	"opencode-plugin": "OpenCode workbase plugin",
 	"opencode-tui": "OpenCode TUI config",
 	"opencode-tui-plugin": "OpenCode /agency-debug",
 } as const
@@ -91,9 +91,10 @@ export const help = `
 Usage: agency integration <subcommand>
 
 Inspect or explicitly synchronize managed agent integration files. OpenCode
-launches load the managed instructions and project config at runtime, and expose
-the managed /agency command, writable-checkout skills, and /agency-debug TUI
-diagnostic, without changing Agency write authority.
+launches load the managed instructions and project config at runtime. The
+managed plugin provides whole-workbase access and writable-checkout skills, and
+the /agency-debug TUI diagnostic reports integration state without changing
+Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

package/src/commands/work.test.ts

@@ -45,10 +45,6 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 }
 
 const taskDirectory = "/workbase/tasks/example"
-const workbasePermission = JSON.stringify({
-	permission: { external_directory: { "/workbase/*": "allow" } },
-})
-
 interface HarnessOptions {
 	readonly workspace?: ExecutionWorkspace
 	readonly materializeError?: Error
@@ -74,7 +70,6 @@ interface HarnessOptions {
 	readonly guardError?: Error
 	readonly launchError?: Error
 	readonly workTargetIds?: readonly string[]
-	readonly opencodeIntegrationState?: "managed" | "customized"
 	readonly taskStatus?: "open" | "working" | "delegated" | "done" | "dropped"
 	readonly phaseStatus?: "open" | "working" | "delegated" | "done" | "dropped"
 	readonly taskStatuses?: Readonly<
@@ -237,7 +232,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				files: [
 					{
 						name: "opencode",
-						state: options.opencodeIntegrationState ?? "managed",
+						state: "managed",
 					},
 				],
 			})
@@ -490,9 +485,9 @@ describe("work command", () => {
 			cwd: "/workbase/epics/delivery",
 		})
 		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG).toBeUndefined()
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG_CONTENT).toBe(
-			workbasePermission,
-		)
+		expect(
+			harness.launchEnvironments[0]?.OPENCODE_CONFIG_CONTENT,
+		).toBeUndefined()
 	})
 
 	test("resolves an existing positional path before treating it as a task ID", async () => {
@@ -918,7 +913,7 @@ describe("work command", () => {
 		expect(harness.taskStatuses.example).toBe("done")
 	})
 
-	test("grants managed OpenCode launches absolute workbase access", async () => {
+	test("leaves managed OpenCode access to the project plugin", async () => {
 		const harness = createHarness()
 		const output = await captureLogs(() =>
 			harness.run({ taskId: "example", opencode: true, printCommand: true }),
@@ -926,7 +921,7 @@ describe("work command", () => {
 		const printed = JSON.parse(output.join("\n"))
 
 		expect(printed.environment.OPENCODE_CONFIG).toBeUndefined()
-		expect(printed.environment.OPENCODE_CONFIG_CONTENT).toBe(workbasePermission)
+		expect(printed.environment.OPENCODE_CONFIG_CONTENT).toBeUndefined()
 	})
 
 	test("provides the writable checkout to plugins without changing the project", async () => {
@@ -941,16 +936,6 @@ describe("work command", () => {
 		expect(harness.launchEnvironments[0]?.AGENCY_WRITABLE_CHECKOUT).toBe(
 			"/workbase/tasks/example/code/agency",
 		)
-		expect(harness.launchEnvironments[0]?.OPENCODE_CONFIG_CONTENT).toBe(
-			workbasePermission,
-		)
-	})
-
-	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()

package/src/commands/work.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
 import { WorktreeService } from "../services/WorktreeService"
 import { FileSystemService } from "../services/FileSystemService"
@@ -122,10 +122,7 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
-		const integration = yield* integrations.sync(root)
-		const managedOpencode = integration.files.some(
-			(file) => file.name === "opencode" && file.state === "managed",
-		)
+		yield* integrations.sync(root)
 		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null
@@ -337,13 +334,6 @@ export const work = (
 			...runnerEnvironment(runner, variables),
 		}
 		if (writablePath) environment.AGENCY_WRITABLE_CHECKOUT = writablePath
-		if (runner === "opencode" && managedOpencode) {
-			environment.OPENCODE_CONFIG_CONTENT = JSON.stringify({
-				permission: {
-					external_directory: { [join(root, "*")]: "allow" },
-				},
-			})
-		}
 		if (options.printCommand) {
 			log(
 				JSON.stringify(
@@ -490,8 +480,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. OpenCode launches receive whole-workbase read access through the
-runtime environment; Agency context remains authoritative for writes.
+workbase first. Managed OpenCode launches receive whole-workbase access through
+Agency's project plugin; 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/IntegrationService.test.ts

@@ -113,7 +113,7 @@ describe("IntegrationService", () => {
 		])
 	})
 
-	test("generates a dynamic repository skill plugin", () => {
+	test("generates a dynamic workbase plugin", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"process.env.AGENCY_WRITABLE_CHECKOUT",
 		)
@@ -129,6 +129,9 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			'join(checkout, ".opencode", "skills")',
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'config.permission.external_directory = { [join(root, "*")]: "allow" }',
+		)
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"config.skills.paths = [...new Set",
 		)
@@ -283,11 +286,14 @@ describe("IntegrationService", () => {
 			},
 			"agency-plan": {
 				description:
-					"Agency planning mode. May edit only Agency planning documents.",
+					"Agency planning mode. May update Agency plans and planning structure.",
 				mode: "primary",
 				prompt: expect.stringContaining("You are in Agency Plan mode"),
 				permission: {
 					question: "allow",
+					bash: {
+						"agency *": "allow",
+					},
 					edit: {
 						"*": "deny",
 						"tasks/*/TASK.md": "allow",
@@ -307,6 +313,23 @@ describe("IntegrationService", () => {
 		expect(config.agent.agency.prompt).toContain(
 			"return without waiting for the task to finish",
 		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"Start with `agency context . --json`",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"decompose it into independently deliverable tasks",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain("Use `--if-revision`")
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"available ticket tools",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"changing lifecycle state",
+		)
+		expect(config.agent["agency-plan"].prompt).toContain(
+			"Follow the managed Agency instructions and reported authority",
+		)
+		expect(config.agent["agency-plan"].permission.bash["*"]).toBeUndefined()
 		expect(config.references).toEqual({
 			workbase: {
 				path: "..",

package/src/services/IntegrationService.ts

@@ -97,7 +97,7 @@ const describe = (
 		return state === "managed"
 			? {
 					diagnostic:
-						"Agency's managed OpenCode plugin exposes writable-checkout skills to work-item sessions.",
+						"Agency's managed OpenCode plugin provides whole-workbase access and exposes writable-checkout skills.",
 					remediation: null,
 				}
 			: state === "customized"
@@ -108,9 +108,9 @@ const describe = (
 					}
 				: {
 						diagnostic:
-							"The managed OpenCode checkout-skill plugin needs synchronization.",
+							"The managed OpenCode workbase plugin needs synchronization.",
 						remediation:
-							"Run 'agency integration sync' to expose writable-checkout skills in OpenCode.",
+							"Run 'agency integration sync' to provide workbase access and expose writable-checkout skills in OpenCode.",
 					}
 	}
 	if (name === "opencode-tui") {

package/src/workbase/opencode-file.ts

@@ -8,7 +8,17 @@ const checksum = (content: string) =>
 
 const agencyPlanPrompt = `You are in Agency Plan mode. Think, read, search, and delegate exploration to construct a well-formed plan for the user's goal. Keep the plan comprehensive but concise, and ask clarifying questions when important tradeoffs or intent are unclear.
 
-You may edit TASK.md, PHASE.md, and EPIC.md to record the outcome, current approach, and important decisions. Do not edit any other file or use shell commands to modify the system.`
+Start with \`agency context . --json\`. Use its document paths and revisions, then inspect the graph, related epics, tasks, phases, linked tickets, and repository declarations needed to understand the work. Use machine-readable Agency output when available instead of inferring structure from directory names.
+
+When planning an epic, decompose it into independently deliverable tasks with explicit dependencies. Add phases only when one task genuinely requires multiple ordered delivery units. Reuse or update existing work instead of creating duplicate tasks or phases.
+
+Use the Agency CLI for full workbase orchestration when the plan requires it, including creating or updating related epics, tasks, and phases; moving tasks; maintaining dependencies; and changing lifecycle state. Use \`--if-revision\` with the revision returned by context for mutations that support it, and run \`agency validate\` after changing workbase structure. Use available ticket tools to inspect or update a linked external ticket when the plan requires it.
+
+You may edit TASK.md, PHASE.md, and EPIC.md to record the outcome, current approach, and important decisions. Do not edit any other file or use shell commands to modify the system. Follow the managed Agency instructions and reported authority for every Agency operation.`
+
+const agencyPlanBashPermissions = {
+	"agency *": "allow",
+}
 
 const body = () =>
 	`${JSON.stringify(
@@ -28,11 +38,12 @@ const body = () =>
 				},
 				"agency-plan": {
 					description:
-						"Agency planning mode. May edit only Agency planning documents.",
+						"Agency planning mode. May update Agency plans and planning structure.",
 					mode: "primary",
 					prompt: agencyPlanPrompt,
 					permission: {
 						question: "allow",
+						bash: agencyPlanBashPermissions,
 						edit: {
 							"*": "deny",
 							"tasks/*/TASK.md": "allow",

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

@@ -10,7 +10,7 @@ const body = `import { existsSync } from "node:fs"
 import { join, sep } from "node:path"
 import type { Plugin } from "@opencode-ai/plugin"
 
-const contextCheckout = async (directory: string) => {
+const agencyContext = async (directory: string) => {
   const task = process.env.AGENCY_TASK_ID
   const phase = process.env.AGENCY_PHASE_ID
   const args = task
@@ -21,14 +21,39 @@ const contextCheckout = async (directory: string) => {
   if ((await child.exited) !== 0) return
   const envelope = JSON.parse(output)
   if (envelope.ok !== true) return
-  return envelope.result?.authority?.writable?.checkoutPath as string | undefined
+  return {
+    root: envelope.result?.workbase?.root as string | undefined,
+    checkout: envelope.result?.authority?.writable?.checkoutPath as string | undefined,
+  }
 }
 
 const plugin: Plugin = async ({ directory }) => ({
   config: async (config) => {
-    const checkout =
-      process.env.AGENCY_WRITABLE_CHECKOUT ??
-      (await contextCheckout(directory).catch(() => undefined))
+    const context = await agencyContext(directory).catch(() => undefined)
+    const root = process.env.AGENCY_WORKBASE ?? context?.root
+    const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout
+
+    const reference = config.references?.workbase
+    if (
+      root &&
+      typeof reference === "object" &&
+      reference.path === ".." &&
+      reference.description ===
+        "Complete Agency workbase context; write authority still comes only from agency context" &&
+      typeof config.permission !== "string"
+    ) {
+      config.permission ??= {}
+      const external = config.permission.external_directory
+      if (external === undefined) {
+        config.permission.external_directory = { [join(root, "*")]: "allow" }
+      } else if (typeof external === "object") {
+        config.permission.external_directory = {
+          [join(root, "*")]: "allow",
+          ...external,
+        }
+      }
+    }
+
     if (!checkout) return
 
     const paths = [