@markjaquith/agency 2.67.0 → 2.68.0

package/README.md

@@ -56,6 +56,8 @@ workbase/
     tui.jsonc              # managed TUI plugin registration
     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.
 
@@ -126,6 +128,16 @@ 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,
@@ -409,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.67.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

@@ -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"),
+				},
 			],
 		})
 	})
@@ -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)
@@ -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 () => {
@@ -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)
 
@@ -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",
 		])
 	})
 
@@ -208,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,
@@ -733,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,
@@ -757,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)
@@ -850,6 +991,21 @@ describe("IntegrationService", () => {
 		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"
 		? {
@@ -190,6 +215,12 @@ const inspect = (root: string) =>
 			"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(
@@ -294,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
 	})
 
@@ -389,12 +436,15 @@ export class IntegrationService extends Effect.Service<IntegrationService>()(
 							} 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({

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]
+}