@markjaquith/agency 2.47.0 → 2.47.2

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
@@ -111,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
@@ -252,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.47.0",
+  "version": "2.47.2",
   "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/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",
 		)
@@ -161,7 +164,14 @@ describe("IntegrationService", () => {
 		const module = await import(pathToFileURL(path).href)
 		let clientReads = 0
 
-		const runDiagnostic = async (paths: string[], ready = true) => {
+		const runDiagnostic = async (
+			paths: string[],
+			options: {
+				ready?: boolean
+				managedReference?: boolean
+				externalDirectory?: Record<string, string>
+			} = {},
+		) => {
 			let command:
 				| {
 						slashName?: string
@@ -175,7 +185,25 @@ describe("IntegrationService", () => {
 					clientReads += 1
 					throw new Error("diagnostic must not access the server client")
 				},
-				state: { ready, config: { skills: { paths } } },
+				state: {
+					ready: options.ready ?? true,
+					config: {
+						skills: { paths },
+						references: options.managedReference
+							? {
+									workbase: {
+										path: "..",
+										description:
+											"Complete Agency workbase context; write authority still comes only from agency context",
+									},
+								}
+							: undefined,
+						permission: options.externalDirectory
+							? { external_directory: options.externalDirectory }
+							: undefined,
+					},
+					path: { directory: join(root, "tasks", "example") },
+				},
 				keymap: {
 					registerLayer: (layer: { commands: (typeof command)[] }) => {
 						command = layer.commands[0]
@@ -199,6 +227,23 @@ describe("IntegrationService", () => {
 			variant: "success",
 			message: expect.stringContaining("Server plugin: initialized"),
 		})
+		expect(
+			await runDiagnostic([], {
+				managedReference: true,
+				externalDirectory: { [join(root, "*")]: "allow" },
+			}),
+		).toMatchObject({
+			variant: "success",
+			message: expect.stringContaining("workbase access registered"),
+		})
+		expect(
+			await runDiagnostic([], {
+				externalDirectory: { [join(root, "*")]: "allow" },
+			}),
+		).toMatchObject({
+			variant: "warning",
+			message: expect.stringContaining("Server plugin: indeterminate"),
+		})
 		expect(await runDiagnostic([])).toMatchObject({
 			variant: "warning",
 			message: expect.stringContaining("Server plugin: indeterminate"),

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-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 = [

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

@@ -6,10 +6,22 @@ const managedHeaderPattern =
 const checksum = (content: string) =>
 	createHash("sha256").update(content).digest("hex")
 
-const body = `import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+const body = `import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
 
 const serverMarker = /[\\\\/]\\.$/
 
+const findWorkbase = (start: string) => {
+  let directory = start
+  while (true) {
+    if (existsSync(join(directory, "agency.json"))) return directory
+    const parent = dirname(directory)
+    if (parent === directory) return
+    directory = parent
+  }
+}
+
 const tui: TuiPlugin = async (api) => {
   api.keymap.registerLayer({
     commands: [
@@ -21,14 +33,35 @@ const tui: TuiPlugin = async (api) => {
         namespace: "palette",
         slashName: "agency-debug",
         run() {
-          const paths = api.state.config.skills?.paths
-          const serverInitialized = paths?.some(
+          const config = api.state.config
+          const checkoutSkillsRegistered = config.skills?.paths?.some(
             (path) => typeof path === "string" && serverMarker.test(path),
           )
+          const reference = config.references?.workbase
+          const managedReference =
+            typeof reference === "object" &&
+            reference.path === ".." &&
+            reference.description ===
+              "Complete Agency workbase context; write authority still comes only from agency context"
+          const workbase = managedReference
+            ? findWorkbase(api.state.path.directory)
+            : undefined
+          const external =
+            typeof config.permission === "object"
+              ? config.permission.external_directory
+              : undefined
+          const workbaseAccessRegistered =
+            workbase !== undefined &&
+            typeof external === "object" &&
+            external[join(workbase, "*")] === "allow"
+          const serverInitialized =
+            checkoutSkillsRegistered || workbaseAccessRegistered
           const message = serverInitialized
-            ? "TUI companion: initialized. Server plugin: initialized; checkout skills registered."
+            ? checkoutSkillsRegistered
+              ? "TUI companion: initialized. Server plugin: initialized; checkout skills registered."
+              : "TUI companion: initialized. Server plugin: initialized; workbase access registered."
             : api.state.ready
-              ? "TUI companion: initialized. Server plugin: indeterminate; no checkout skill marker is present."
+              ? "TUI companion: initialized. Server plugin: indeterminate; no Agency config marker is present."
               : "TUI companion: initialized. Server plugin: indeterminate; server state is not ready."
 
           api.ui.toast({