@markjaquith/agency 2.66.0 → 2.68.0

package/README.md

@@ -54,8 +54,10 @@ workbase/
   .opencode/
     opencode.jsonc         # managed @agency subagent, instructions, and reference
     tui.jsonc              # managed TUI plugin registration
-    plugin/agency-repository-skills.ts # managed workbase access and checkout skills
+    plugins/agency-repository-skills.ts # managed workbase access and checkout skills
     tui/agency-debug.ts    # managed /agency-debug TUI diagnostic
+  .pi/
+    extensions/agency-workbase.ts # managed workbase context and checkout skills
   agency.json              # tracked config and portable repository declarations
   repos/                   # ignored local materializations
     frontend/              # bare Git repository or symlink
@@ -83,11 +85,11 @@ workbase/
 ```
 
 Agency keeps discovery and other observational commands read-only. Run
-`agency integration status` to inspect `.agency/AGENTS.md` and
-`.opencode/opencode.jsonc`, `.opencode/tui.jsonc`, and their managed plugin
-files, then `agency integration sync` to create missing files or refresh
-checksum-safe managed files. Customized files are reported but never
-overwritten. Sync also removes checksum-valid retired managed artifacts while
+`agency integration status` to inspect `.agency/AGENTS.md`, the managed
+OpenCode configuration and plugins, and `.pi/extensions/agency-workbase.ts`,
+then `agency integration sync` to create missing files or refresh checksum-safe
+managed files. Customized files are reported but never overwritten. Sync also
+removes checksum-valid retired managed artifacts while
 preserving customized files at their former paths. The root
 `AGENTS.md` is user-owned and is not inspected or modified by Agency.
 
@@ -119,10 +121,23 @@ 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.
+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.
 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`.
 
+Pi discovers the managed project extension automatically when launched from
+the workbase root after the project is trusted. When launching Pi from a task,
+phase, or epic directory, pass the managed file with `--extension`, for example
+`pi -e /path/to/workbase/.pi/extensions/agency-workbase.ts`. The extension loads
+the managed Agency instructions into Pi's system prompt, advertises the complete
+workbase, and exposes skills from the writable checkout's `.claude/skills`,
+`.agents/skills`, `.opencode/{skill,skills}`, and `.pi/skills` directories.
+Agency context still determines write authority; reference checkouts remain
+read-only.
+
 Repository aliases, the version-control backend, and canonical fetch remotes are
 declared in tracked `agency.json`; local clones and symlinks remain ignored under
 `repos/{alias}`. A declaration contains no local path, symlink target, checkout,
@@ -406,11 +421,14 @@ working directory so the workbase `AGENTS.md` and managed OpenCode config are
 discovered normally.
 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
+`.opencode/{skill,skills}` directories to `skills.paths`. The managed 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 launches and Pi
+launches with the managed extension loaded 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
-plain OpenCode. Other checkout-local configuration is not composed.
+plain OpenCode or Pi. Other checkout-local configuration is not composed.
 `--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.66.0",
+  "version": "2.68.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/cli.test.ts

@@ -642,6 +642,7 @@ exit 23
 			{ name: "opencode-plugin", state: "managed" },
 			{ name: "opencode-tui", state: "managed" },
 			{ name: "opencode-tui-plugin", state: "managed" },
+			{ name: "pi-extension", state: "managed" },
 		])
 
 		const synced = parseJson(
@@ -653,6 +654,7 @@ exit 23
 			{ name: "opencode-plugin", state: "managed", changed: false },
 			{ name: "opencode-tui", state: "managed", changed: false },
 			{ name: "opencode-tui-plugin", state: "managed", changed: false },
+			{ name: "pi-extension", state: "managed", changed: false },
 		])
 	})
 

package/src/commands/init.test.ts

@@ -74,7 +74,7 @@ describe("init command", () => {
 			await Bun.file(join(root, ".opencode/command/agency.md")).exists(),
 		).toBe(false)
 		const plugin = await Bun.file(
-			join(root, ".opencode/plugin/agency-repository-skills.ts"),
+			join(root, ".opencode/plugins/agency-repository-skills.ts"),
 		).text()
 		expect(plugin).toContain("AGENCY_WRITABLE_CHECKOUT")
 		expect(plugin).toContain("config.skills.paths")
@@ -89,6 +89,12 @@ describe("init command", () => {
 		expect(tuiPlugin).toContain('slashName: "agency-debug"')
 		expect(tuiPlugin).toContain("api.ui.toast")
 		expect(tuiPlugin).not.toContain("chat.message")
+		const piExtension = await Bun.file(
+			join(root, ".pi/extensions/agency-workbase.ts"),
+		).text()
+		expect(piExtension).toContain('pi.on("resources_discover"')
+		expect(piExtension).toContain('pi.on("before_agent_start"')
+		expect(piExtension).toContain("AGENCY_WRITABLE_CHECKOUT")
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/integration.test.ts

@@ -51,6 +51,11 @@ describe("integration command", () => {
 					state: "missing",
 					remediation: expect.stringContaining("integration sync"),
 				},
+				{
+					name: "pi-extension",
+					state: "missing",
+					remediation: expect.stringContaining("integration sync"),
+				},
 			],
 		})
 	})
@@ -87,7 +92,7 @@ OpenCode config: missing
   Action: Run 'agency integration sync' to install Agency instructions and whole-workbase OpenCode access.
 
 OpenCode workbase plugin: missing
-  Path: .opencode/plugin/agency-repository-skills.ts
+  Path: .opencode/plugins/agency-repository-skills.ts
   The managed OpenCode workbase plugin needs synchronization.
   Action: Run 'agency integration sync' to provide workbase access and expose writable-checkout skills in OpenCode.
 
@@ -99,7 +104,12 @@ OpenCode TUI config: missing
 OpenCode /agency-debug: missing
   Path: .opencode/tui/agency-debug.ts
   The managed OpenCode TUI diagnostic companion needs synchronization.
-  Action: Run 'agency integration sync' to install /agency-debug.`)
+  Action: Run 'agency integration sync' to install /agency-debug.
+
+Pi workbase extension: missing
+  Path: .pi/extensions/agency-workbase.ts
+  The managed Pi workbase extension needs synchronization.
+  Action: Run 'agency integration sync' to provide workbase context and expose writable-checkout skills in Pi.`)
 	})
 
 	test("explicitly synchronizes integration files", async () => {
@@ -113,6 +123,7 @@ OpenCode /agency-debug: missing
 			{ name: "opencode-plugin", state: "managed", changed: true },
 			{ name: "opencode-tui", state: "managed", changed: true },
 			{ name: "opencode-tui-plugin", state: "managed", changed: true },
+			{ name: "pi-extension", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(true)
@@ -124,7 +135,7 @@ OpenCode /agency-debug: missing
 		).toBe(false)
 		expect(
 			await Bun.file(
-				join(root, ".opencode/plugin/agency-repository-skills.ts"),
+				join(root, ".opencode/plugins/agency-repository-skills.ts"),
 			).exists(),
 		).toBe(true)
 		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).exists()).toBe(
@@ -133,6 +144,9 @@ OpenCode /agency-debug: missing
 		expect(
 			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).exists(),
 		).toBe(true)
+		expect(
+			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).exists(),
+		).toBe(true)
 	})
 
 	test("formats integration sync results for people", async () => {
@@ -151,7 +165,7 @@ OpenCode config: synced
   Agency's managed OpenCode launch config is ready to load Agency instructions and provide whole-workbase read access.
 
 OpenCode workbase plugin: synced
-  Path: .opencode/plugin/agency-repository-skills.ts
+  Path: .opencode/plugins/agency-repository-skills.ts
   Agency's managed OpenCode plugin provides whole-workbase access and exposes writable-checkout skills.
 
 OpenCode TUI config: synced
@@ -160,6 +174,10 @@ OpenCode TUI config: synced
 
 OpenCode /agency-debug: synced
   Path: .opencode/tui/agency-debug.ts
-  Agency's managed OpenCode TUI diagnostic companion is current.`)
+  Agency's managed OpenCode TUI diagnostic companion is current.
+
+Pi workbase extension: synced
+  Path: .pi/extensions/agency-workbase.ts
+  Agency's managed Pi extension provides whole-workbase context and exposes writable-checkout skills.`)
 	})
 })

package/src/commands/integration.ts

@@ -18,6 +18,7 @@ interface IntegrationResult {
 			| "opencode-plugin"
 			| "opencode-tui"
 			| "opencode-tui-plugin"
+			| "pi-extension"
 		readonly path: string
 		readonly state: string
 		readonly diagnostic: string
@@ -32,6 +33,7 @@ const integrationNames = {
 	"opencode-plugin": "OpenCode workbase plugin",
 	"opencode-tui": "OpenCode TUI config",
 	"opencode-tui-plugin": "OpenCode /agency-debug",
+	"pi-extension": "Pi workbase extension",
 } as const
 
 const logHumanResult = (
@@ -89,10 +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. 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.
+launches load the managed instructions and project config at runtime. Managed
+OpenCode and Pi extensions provide whole-workbase context and writable-checkout
+skills, and the /agency-debug TUI diagnostic reports OpenCode integration state
+without changing Agency write authority.
 
 Subcommands:
   status  Report file state, access diagnostics, and safe remediation

package/src/services/IntegrationService.test.ts

@@ -16,6 +16,10 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
+import {
+	canUpdateManagedWorkbasePiExtension,
+	managedWorkbasePiExtension,
+} from "../workbase/pi-extension-file"
 import { IntegrationService } from "./IntegrationService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -65,6 +69,7 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
 		])
 		expect(await Bun.file(join(root, ".agency/AGENTS.md")).exists()).toBe(false)
 
@@ -72,7 +77,7 @@ describe("IntegrationService", () => {
 		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode)
 		await write(
 			root,
-			".opencode/plugin/agency-repository-skills.ts",
+			".opencode/plugins/agency-repository-skills.ts",
 			managedWorkbaseOpencodePlugin,
 		)
 		await write(root, ".opencode/tui.jsonc", managedWorkbaseOpencodeTui)
@@ -81,12 +86,18 @@ describe("IntegrationService", () => {
 			".opencode/tui/agency-debug.ts",
 			managedWorkbaseOpencodeTuiPlugin,
 		)
+		await write(
+			root,
+			".pi/extensions/agency-workbase.ts",
+			managedWorkbasePiExtension,
+		)
 		expect((await status(root)).files.map(({ state }) => state)).toEqual([
 			"managed",
 			"managed",
 			"managed",
 			"managed",
 			"managed",
+			"managed",
 		])
 	})
 
@@ -104,6 +115,7 @@ describe("IntegrationService", () => {
 			"missing",
 			"missing",
 			"missing",
+			"missing",
 		])
 	})
 
@@ -126,6 +138,15 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"process.env.AGENCY_WRITABLE_CHECKOUT",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'import type { Plugin, PluginModule } from "@opencode-ai/plugin/v1"',
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"export const AgencyPlugin = plugin",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain('id: "agency"')
+		expect(managedWorkbaseOpencodePlugin).toContain("setup,")
+		expect(managedWorkbaseOpencodePlugin).toContain("server: plugin")
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			'["agency", "context", ".", "--compact", "--json"]',
 		)
@@ -199,6 +220,131 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
+	test("generates a Pi extension with workbase context and checkout skills", async () => {
+		expect(managedWorkbasePiExtension).toContain(
+			'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
+		)
+		expect(managedWorkbasePiExtension).toContain('pi.on("resources_discover"')
+		expect(managedWorkbasePiExtension).toContain('pi.on("before_agent_start"')
+		expect(managedWorkbasePiExtension).toContain(
+			'join(checkout, ".agents", "skills")',
+		)
+		expect(managedWorkbasePiExtension).toContain(
+			'join(checkout, CONFIG_DIR_NAME, "skills")',
+		)
+		expect(managedWorkbasePiExtension).toContain(
+			"The complete Agency workbase is available",
+		)
+		expect(managedWorkbasePiExtension).toContain(
+			"Agency context remains the authority for writes",
+		)
+		expect(
+			canUpdateManagedWorkbasePiExtension(managedWorkbasePiExtension),
+		).toBe(true)
+		expect(
+			canUpdateManagedWorkbasePiExtension(
+				managedWorkbasePiExtension.replace("resources_discover", "discover"),
+			),
+		).toBe(false)
+
+		const taskDirectory = join(root, "tasks/example")
+		const checkoutPath = join(taskDirectory, "code/agency")
+		await write(root, ".agency/AGENTS.md", "# Managed Agency instructions\n")
+		await write(
+			root,
+			"tasks/example/TASK.md",
+			"---\nrepo: agency\nstatus: working\n---\n",
+		)
+		await write(
+			root,
+			"tasks/example/code/agency/.agents/skills/example/SKILL.md",
+			"---\nname: example\ndescription: Example.\n---\n",
+		)
+		await write(
+			root,
+			"tasks/example/code/agency/.pi/skills/pi-example/SKILL.md",
+			"---\nname: pi-example\ndescription: Pi example.\n---\n",
+		)
+		const path = join(root, ".pi/extensions/agency-workbase.ts")
+		await write(
+			root,
+			".pi/extensions/agency-workbase.ts",
+			managedWorkbasePiExtension.replace(
+				'import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"',
+				'const CONFIG_DIR_NAME = ".pi"\ntype ExtensionAPI = any',
+			),
+		)
+
+		const contextResponse = JSON.stringify({
+			version: 1,
+			ok: true,
+			result: {
+				workbase: { root },
+				target: {
+					kind: "task",
+					taskId: "example",
+					path: join(taskDirectory, "TASK.md"),
+				},
+				authority: {
+					mode: "execution",
+					writable: { checkoutPath },
+				},
+				documents: { task: { data: { status: "working" } } },
+				validation: { valid: true, warnings: [] },
+			},
+		})
+		const handlers = new Map<string, (...args: any[]) => any>()
+		const pi = {
+			exec: async () => ({ code: 0, stdout: contextResponse, stderr: "" }),
+			on: (name: string, handler: (...args: any[]) => any) => {
+				handlers.set(name, handler)
+			},
+		}
+		const previousTarget = process.env.AGENCY_TARGET
+		const previousWorkbase = process.env.AGENCY_WORKBASE
+		const previousCheckout = process.env.AGENCY_WRITABLE_CHECKOUT
+		delete process.env.AGENCY_WORKBASE
+		delete process.env.AGENCY_WRITABLE_CHECKOUT
+		process.env.AGENCY_TARGET = "execution-unit:task/example"
+		try {
+			const generated = await import(
+				`${pathToFileURL(path).href}?pi-extension=${Date.now()}`
+			)
+			generated.default(pi)
+			const resources = await handlers.get("resources_discover")?.({
+				cwd: taskDirectory,
+				reason: "startup",
+			})
+			expect(resources.skillPaths).toEqual([
+				join(checkoutPath, ".agents/skills"),
+				join(checkoutPath, ".pi/skills"),
+			])
+
+			const prompt = await handlers.get("before_agent_start")?.(
+				{ systemPrompt: "Base prompt" },
+				{ cwd: taskDirectory },
+			)
+			expect(prompt.systemPrompt).toContain("# Managed Agency instructions")
+			expect(prompt.systemPrompt).toContain(
+				`The complete Agency workbase is available at ${root}`,
+			)
+			expect(prompt.systemPrompt).toContain(
+				"active worker for execution-unit:task/example",
+			)
+			expect(prompt.systemPrompt).toContain(
+				`${checkoutPath} as the default implementation directory`,
+			)
+		} finally {
+			if (previousTarget === undefined) delete process.env.AGENCY_TARGET
+			else process.env.AGENCY_TARGET = previousTarget
+			if (previousWorkbase === undefined) delete process.env.AGENCY_WORKBASE
+			else process.env.AGENCY_WORKBASE = previousWorkbase
+			if (previousCheckout === undefined)
+				delete process.env.AGENCY_WRITABLE_CHECKOUT
+			else process.env.AGENCY_WRITABLE_CHECKOUT = previousCheckout
+		}
+	})
+
 	const testWorkerIdentity = async ({
 		target,
 		launchTarget,
@@ -276,7 +422,12 @@ describe("IntegrationService", () => {
 				task: "example",
 				phase,
 			})
-			const hooks = await generated.default({ directory: root } as never)
+			expect(generated.default).toMatchObject({
+				id: "agency",
+				setup: expect.any(Function),
+				server: generated.AgencyPlugin,
+			})
+			const hooks = await generated.AgencyPlugin({ directory: root } as never)
 			await hooks["chat.message"]!(
 				{ sessionID: "worker-session" } as never,
 				{
@@ -351,6 +502,52 @@ describe("IntegrationService", () => {
 			phase: "build",
 		}))
 
+	test("registers the workbase reference through the OpenCode V2 API", async () => {
+		const path = join(root, ".opencode/plugins/agency-repository-skills.ts")
+		await write(
+			root,
+			".opencode/plugins/agency-repository-skills.ts",
+			managedWorkbaseOpencodePlugin,
+		)
+		const generated = await import(`${pathToFileURL(path).href}?v2-setup`)
+		let reference:
+			| {
+					name: string
+					source: { type: string; path: string; description: string }
+			  }
+			| undefined
+
+		await generated.default.setup({
+			reference: {
+				transform: async (callback: (references: unknown) => void) =>
+					callback({
+						list: () => [],
+						add: (
+							name: string,
+							source: {
+								type: string
+								path: string
+								description: string
+							},
+						) => {
+							reference = { name, source }
+						},
+					}),
+			},
+			skill: { transform: async () => {} },
+		})
+
+		expect(reference).toEqual({
+			name: "workbase",
+			source: {
+				type: "local",
+				path: root,
+				description:
+					"Complete Agency workbase context; write authority still comes only from agency context",
+			},
+		})
+	})
+
 	test("registers a TUI-only /agency-debug diagnostic", async () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))
 		expect(config).toEqual({
@@ -673,6 +870,7 @@ describe("IntegrationService", () => {
 			{ name: "opencode-plugin", state: "managed", changed: true },
 			{ name: "opencode-tui", state: "managed", changed: true },
 			{ name: "opencode-tui-plugin", state: "managed", changed: true },
+			{ name: "pi-extension", state: "managed", changed: true },
 		])
 		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
 			customRootAgents,
@@ -688,7 +886,7 @@ describe("IntegrationService", () => {
 		).toBe(false)
 		expect(
 			await Bun.file(
-				join(root, ".opencode/plugin/agency-repository-skills.ts"),
+				join(root, ".opencode/plugins/agency-repository-skills.ts"),
 			).text(),
 		).toBe(managedWorkbaseOpencodePlugin)
 		expect(await Bun.file(join(root, ".opencode/tui.jsonc")).text()).toBe(
@@ -697,6 +895,9 @@ describe("IntegrationService", () => {
 		expect(
 			await Bun.file(join(root, ".opencode/tui/agency-debug.ts")).text(),
 		).toBe(managedWorkbaseOpencodeTuiPlugin)
+		expect(
+			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
+		).toBe(managedWorkbasePiExtension)
 
 		await unlink(join(root, ".agency/AGENTS.md"))
 		const second = await sync(root)
@@ -761,6 +962,50 @@ describe("IntegrationService", () => {
 		})
 	})
 
+	test("migrates a checksum-valid plugin from the legacy singular path", async () => {
+		const legacyPath = join(
+			root,
+			".opencode/plugin/agency-repository-skills.ts",
+		)
+		const pluginPath = join(
+			root,
+			".opencode/plugins/agency-repository-skills.ts",
+		)
+		await write(
+			root,
+			".opencode/plugin/agency-repository-skills.ts",
+			managedWorkbaseOpencodePlugin,
+		)
+
+		const result = await sync(root)
+
+		expect(result.files[2]).toMatchObject({
+			name: "opencode-plugin",
+			path: pluginPath,
+			state: "managed",
+			changed: true,
+		})
+		expect(await Bun.file(pluginPath).text()).toBe(
+			managedWorkbaseOpencodePlugin,
+		)
+		expect(await Bun.file(legacyPath).exists()).toBe(false)
+	})
+
+	test("preserves a user-owned Pi extension", async () => {
+		const custom = "export default function customPiExtension() {}\n"
+		await write(root, ".pi/extensions/agency-workbase.ts", custom)
+
+		const result = await sync(root)
+		expect(result.files[5]).toMatchObject({
+			name: "pi-extension",
+			state: "customized",
+			changed: false,
+		})
+		expect(
+			await Bun.file(join(root, ".pi/extensions/agency-workbase.ts")).text(),
+		).toBe(custom)
+	})
+
 	test("preserves user-owned TUI config and diagnostic plugin", async () => {
 		const customConfig = '{"theme":"custom"}\n'
 		const customPlugin =

package/src/services/IntegrationService.ts

@@ -23,6 +23,10 @@ import {
 	canUpdateManagedWorkbaseOpencodeTuiPlugin,
 	managedWorkbaseOpencodeTuiPlugin,
 } from "../workbase/opencode-tui-plugin-file"
+import {
+	canUpdateManagedWorkbasePiExtension,
+	managedWorkbasePiExtension,
+} from "../workbase/pi-extension-file"
 
 type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
 
@@ -33,6 +37,7 @@ interface IntegrationFileStatus {
 		| "opencode-plugin"
 		| "opencode-tui"
 		| "opencode-tui-plugin"
+		| "pi-extension"
 	readonly path: string
 	readonly state: IntegrationFileState
 	readonly diagnostic: string
@@ -131,6 +136,26 @@ const describe = (
 							"Run 'agency integration sync' to install /agency-debug.",
 					}
 	}
+	if (name === "pi-extension") {
+		return state === "managed"
+			? {
+					diagnostic:
+						"Agency's managed Pi extension provides whole-workbase context and exposes writable-checkout skills.",
+					remediation: null,
+				}
+			: state === "customized"
+				? {
+						diagnostic:
+							"A user-owned Pi workbase extension is present and was preserved.",
+						remediation: null,
+					}
+				: {
+						diagnostic:
+							"The managed Pi workbase extension needs synchronization.",
+						remediation:
+							"Run 'agency integration sync' to provide workbase context and expose writable-checkout skills in Pi.",
+					}
+	}
 
 	return state === "missing" || state === "drifted"
 		? {
@@ -179,17 +204,23 @@ const inspect = (root: string) =>
 		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
 		const tuiPath = join(opencodeDirectory, "tui.jsonc")
 		const tuiJsonPath = join(opencodeDirectory, "tui.json")
-		const pluginPath = join(
+		const legacyPluginPath = join(
 			opencodeDirectory,
 			"plugin",
 			"agency-repository-skills.ts",
 		)
-		const pluralPluginPath = join(
+		const pluginPath = join(
 			opencodeDirectory,
 			"plugins",
 			"agency-repository-skills.ts",
 		)
 		const tuiPluginPath = join(opencodeDirectory, "tui", "agency-debug.ts")
+		const piExtensionPath = join(
+			root,
+			".pi",
+			"extensions",
+			"agency-workbase.ts",
+		)
 		const files: IntegrationFileStatus[] = []
 
 		files.push(
@@ -229,11 +260,6 @@ const inspect = (root: string) =>
 
 		if ((yield* fs.readSymlinkTarget(pluginPath)) !== null) {
 			files.push(fileStatus("opencode-plugin", pluginPath, "customized"))
-		} else if (
-			(yield* fs.readSymlinkTarget(pluralPluginPath)) !== null ||
-			(yield* fs.exists(pluralPluginPath))
-		) {
-			files.push(fileStatus("opencode-plugin", pluralPluginPath, "customized"))
 		} else if (yield* fs.exists(pluginPath)) {
 			files.push(
 				classify(
@@ -244,6 +270,20 @@ const inspect = (root: string) =>
 					canUpdateManagedWorkbaseOpencodePlugin,
 				),
 			)
+		} else if (
+			(yield* fs.readSymlinkTarget(legacyPluginPath)) !== null ||
+			(yield* fs.exists(legacyPluginPath))
+		) {
+			const legacyContent =
+				(yield* fs.readSymlinkTarget(legacyPluginPath)) === null
+					? yield* fs.readFile(legacyPluginPath)
+					: null
+			files.push(
+				legacyContent !== null &&
+					canUpdateManagedWorkbaseOpencodePlugin(legacyContent)
+					? fileStatus("opencode-plugin", pluginPath, "missing")
+					: fileStatus("opencode-plugin", legacyPluginPath, "customized"),
+			)
 		} else {
 			files.push(fileStatus("opencode-plugin", pluginPath, "missing"))
 		}
@@ -285,6 +325,22 @@ const inspect = (root: string) =>
 			files.push(fileStatus("opencode-tui-plugin", tuiPluginPath, "missing"))
 		}
 
+		if ((yield* fs.readSymlinkTarget(piExtensionPath)) !== null) {
+			files.push(fileStatus("pi-extension", piExtensionPath, "customized"))
+		} else if (yield* fs.exists(piExtensionPath)) {
+			files.push(
+				classify(
+					"pi-extension",
+					piExtensionPath,
+					yield* fs.readFile(piExtensionPath),
+					managedWorkbasePiExtension,
+					canUpdateManagedWorkbasePiExtension,
+				),
+			)
+		} else {
+			files.push(fileStatus("pi-extension", piExtensionPath, "missing"))
+		}
+
 		return files
 	})
 
@@ -319,6 +375,23 @@ const canRemoveLegacyOpencodeCommand = (root: string) =>
 		return createHash("sha256").update(canonical).digest("hex") === match[1]
 	})
 
+const canRemoveLegacyOpencodePlugin = (root: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const path = join(
+			root,
+			".opencode",
+			"plugin",
+			"agency-repository-skills.ts",
+		)
+		if (
+			(yield* fs.readSymlinkTarget(path)) !== null ||
+			!(yield* fs.exists(path))
+		)
+			return false
+		return canUpdateManagedWorkbaseOpencodePlugin(yield* fs.readFile(path))
+	})
+
 export class IntegrationService extends Effect.Service<IntegrationService>()(
 	"IntegrationService",
 	{
@@ -343,6 +416,8 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 						) && (yield* canRemoveLegacyAgents(root))
 					const removeLegacyOpencodeCommand =
 						yield* canRemoveLegacyOpencodeCommand(root)
+					const removeLegacyOpencodePlugin =
+						yield* canRemoveLegacyOpencodePlugin(root)
 					const files: IntegrationSyncFile[] = []
 
 					for (const status of statuses) {
@@ -356,17 +431,20 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 								yield* fs.createDirectory(join(root, ".opencode"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencode)
 							} else if (status.name === "opencode-plugin") {
-								yield* fs.createDirectory(join(root, ".opencode", "plugin"))
+								yield* fs.createDirectory(join(root, ".opencode", "plugins"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodePlugin)
 							} else if (status.name === "opencode-tui") {
 								yield* fs.createDirectory(join(root, ".opencode"))
 								yield* fs.writeFile(status.path, managedWorkbaseOpencodeTui)
-							} else {
+							} else if (status.name === "opencode-tui-plugin") {
 								yield* fs.createDirectory(join(root, ".opencode", "tui"))
 								yield* fs.writeFile(
 									status.path,
 									managedWorkbaseOpencodeTuiPlugin,
 								)
+							} else {
+								yield* fs.createDirectory(join(root, ".pi", "extensions"))
+								yield* fs.writeFile(status.path, managedWorkbasePiExtension)
 							}
 						}
 						files.push({
@@ -376,11 +454,19 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 								needsWrite ? "managed" : status.state,
 							),
 							changed:
-								needsWrite || (status.name === "agents" && removeLegacyAgents),
+								needsWrite ||
+								(status.name === "agents" && removeLegacyAgents) ||
+								(status.name === "opencode-plugin" &&
+									removeLegacyOpencodePlugin),
 						})
 					}
 
 					if (removeLegacyAgents) yield* fs.deleteFile(join(root, "AGENTS.md"))
+					if (removeLegacyOpencodePlugin) {
+						yield* fs.deleteFile(
+							join(root, ".opencode", "plugin", "agency-repository-skills.ts"),
+						)
+					}
 					if (removeLegacyOpencodeCommand) {
 						yield* fs.deleteFile(
 							join(root, ".opencode", "command", "agency.md"),

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

@@ -8,7 +8,8 @@ const checksum = (content: string) =>
 
 const body = `import { existsSync, readFileSync } from "node:fs"
 import { dirname, join, resolve, sep } from "node:path"
-import type { Plugin } from "@opencode-ai/plugin"
+import { fileURLToPath } from "node:url"
+import type { Plugin, PluginModule } from "@opencode-ai/plugin/v1"
 
 const workerLaunchPattern = /^Agency worker launch target: ([^.\\s]+)\\./
 
@@ -20,6 +21,20 @@ type AgencyContext = {
   phase?: string
 }
 
+type V2PluginContext = {
+  reference: {
+    transform(callback: (references: {
+      list(): readonly (readonly [string, unknown])[]
+      add(name: string, source: { type: "local"; path: string; description: string }): void
+    }) => void): Promise<unknown>
+  }
+  skill: {
+    transform(callback: (skills: {
+      source(source: { type: "directory"; path: string }): void
+    }) => void): Promise<unknown>
+  }
+}
+
 const contextTarget = (result: Record<string, any>): string | undefined => {
   const target = result.target
   if (target?.kind === "epic") return \`epic:\${target.epicId}\`
@@ -69,6 +84,15 @@ const discoverCheckout = (directory: string, root: string | undefined) => {
   }
 }
 
+const checkoutSkillPaths = (checkout: string | undefined) => checkout
+  ? [
+      join(checkout, ".claude", "skills"),
+      join(checkout, ".agents", "skills"),
+      join(checkout, ".opencode", "skill"),
+      join(checkout, ".opencode", "skills"),
+    ].filter(existsSync)
+  : []
+
 const agencyContext = async (
   directory: string,
   useEnvironmentTarget = true,
@@ -141,12 +165,7 @@ const plugin: Plugin = async ({ directory }) => {
 
       if (!checkout) return
 
-      const paths = [
-        join(checkout, ".claude", "skills"),
-        join(checkout, ".agents", "skills"),
-        join(checkout, ".opencode", "skill"),
-        join(checkout, ".opencode", "skills"),
-      ].filter(existsSync).map((path) => \`\${path}\${sep}.\`)
+      const paths = checkoutSkillPaths(checkout).map((path) => \`\${path}\${sep}.\`)
       if (paths.length === 0) return
 
       config.skills ??= {}
@@ -186,7 +205,31 @@ const plugin: Plugin = async ({ directory }) => {
   }
 }
 
-export default plugin
+export const AgencyPlugin = plugin
+
+const setup = async (context: V2PluginContext) => {
+  const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
+  await context.reference.transform((references) => {
+    if (references.list().some(([name]) => name === "workbase")) return
+    references.add("workbase", {
+      type: "local",
+      path: root,
+      description: "Complete Agency workbase context; write authority still comes only from agency context",
+    })
+  })
+
+  const paths = checkoutSkillPaths(process.env.AGENCY_WRITABLE_CHECKOUT)
+  if (paths.length === 0) return
+  await context.skill.transform((skills) => {
+    for (const path of paths) skills.source({ type: "directory", path })
+  })
+}
+
+export default {
+  id: "agency",
+  setup,
+  server: plugin,
+} satisfies PluginModule & { setup: (context: V2PluginContext) => Promise<void> }
 `
 
 const renderManagedWorkbaseOpencodePlugin = (content: string) =>

package/src/workbase/pi-extension-file.ts

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto"
+
+const managedHeaderPattern =
+	/^\/\/ agency-managed: sha256=([a-f0-9]{64})\r?\n\r?\n/
+
+const checksum = (content: string) =>
+	createHash("sha256").update(content).digest("hex")
+
+const body = `import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent"
+
+type AgencyContext = {
+  root?: string
+  checkout?: string
+  target?: string
+}
+
+const contextTarget = (result: Record<string, any>): string | undefined => {
+  const target = result.target
+  if (target?.kind === "epic") return \`epic:\${target.epicId}\`
+  if (target?.kind === "phase") {
+    return \`execution-unit:phase/\${target.taskId}/\${target.phaseId}\`
+  }
+  if (target?.kind === "task") {
+    return result.authority?.mode === "execution"
+      ? \`execution-unit:task/\${target.taskId}\`
+      : \`task:\${target.taskId}\`
+  }
+}
+
+const discoverWorkbase = (directory: string) => {
+  let current = directory
+  while (true) {
+    if (existsSync(join(current, "agency.json"))) return current
+    const parent = dirname(current)
+    if (parent === current) return
+    current = parent
+  }
+}
+
+const discoverCheckout = (directory: string, root: string | undefined) => {
+  if (!root) return
+  let current = directory
+  while (current.startsWith(root)) {
+    for (const name of ["PHASE.md", "TASK.md"]) {
+      const document = join(current, name)
+      if (!existsSync(document)) continue
+      const repo = readFileSync(document, "utf8").match(/^repo:\\s*([^\\s]+)\\s*$/m)?.[1]
+      if (!repo) return
+      const checkout = join(current, "code", repo.replace(/^['\"]|['\"]$/g, ""))
+      return existsSync(checkout) ? checkout : undefined
+    }
+    if (current === root) return
+    current = dirname(current)
+  }
+}
+
+const agencyContext = async (
+  pi: ExtensionAPI,
+  directory: string,
+): Promise<AgencyContext | undefined> => {
+  const task = process.env.AGENCY_TASK_ID
+  const phase = process.env.AGENCY_PHASE_ID
+  const args = task
+    ? ["context", "--task", task, ...(phase ? ["--phase", phase] : []), "--compact", "--json"]
+    : ["context", ".", "--compact", "--json"]
+  const command = await pi.exec("agency", args, { timeout: 5000 })
+  if (command.code !== 0) return
+  const envelope = JSON.parse(command.stdout)
+  if (envelope.ok !== true) return
+  const result = envelope.result ?? {}
+  const target = contextTarget(result)
+  const document = result.target?.path
+  const status = result.documents?.phase?.data?.status ?? result.documents?.task?.data?.status
+  if (
+    result.validation?.valid !== true ||
+    !target ||
+    !document ||
+    dirname(document) !== resolve(directory) ||
+    (target.startsWith("execution-unit:") &&
+      (!result.authority?.writable?.checkoutPath || status !== "working"))
+  ) return
+  return {
+    root: result.workbase?.root,
+    checkout: result.authority?.writable?.checkoutPath,
+    target,
+  }
+}
+
+const extension = (pi: ExtensionAPI) => {
+  const contexts = new Map<string, Promise<AgencyContext | undefined>>()
+  const runtimeContext = (directory: string) => {
+    let context = contexts.get(directory)
+    if (!context) {
+      context = agencyContext(pi, directory).catch(() => undefined)
+      contexts.set(directory, context)
+    }
+    return context
+  }
+
+  pi.on("resources_discover", async (event) => {
+    const context = await runtimeContext(event.cwd)
+    const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(event.cwd)
+    const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(event.cwd, root)
+    if (!checkout) return
+
+    const skillPaths = [
+      join(checkout, ".claude", "skills"),
+      join(checkout, ".agents", "skills"),
+      join(checkout, ".opencode", "skill"),
+      join(checkout, ".opencode", "skills"),
+      join(checkout, CONFIG_DIR_NAME, "skills"),
+    ].filter(existsSync)
+    if (skillPaths.length === 0) return
+    return { skillPaths: [...new Set(skillPaths)] }
+  })
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const context = await runtimeContext(ctx.cwd)
+    const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(ctx.cwd)
+    if (!root) return
+    const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(ctx.cwd, root)
+    const instructionsPath = join(root, ".agency", "AGENTS.md")
+    const instructions = existsSync(instructionsPath)
+      ? readFileSync(instructionsPath, "utf8").trim()
+      : undefined
+    const activeTarget = process.env.AGENCY_TARGET
+    const worker = activeTarget && context?.target === activeTarget
+      ? \`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 \${root}. Use absolute paths under that root when workbase context is needed. Agency context remains the authority for writes.\`
+    const implementation = checkout
+      ? \`Pi remains rooted in the task or phase directory for Agency instructions and context. Treat \${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.\`
+      : undefined
+
+    return {
+      systemPrompt: [event.systemPrompt, instructions, access, worker, implementation]
+        .filter(Boolean)
+        .join("\\n\\n"),
+    }
+  })
+}
+
+export default extension
+`
+
+const renderManagedWorkbasePiExtension = (content: string) =>
+	`// agency-managed: sha256=${checksum(content)}\n\n${content}`
+
+export const managedWorkbasePiExtension = renderManagedWorkbasePiExtension(body)
+
+export const canUpdateManagedWorkbasePiExtension = (content: string) => {
+	const match = content.match(managedHeaderPattern)
+	if (!match?.[1]) return false
+
+	return checksum(content.slice(match[0].length)) === match[1]
+}