@markjaquith/agency 3.3.0 → 3.4.0

package/README.md

@@ -364,16 +364,22 @@ before acting; a matching worker performs the task directly and must not invoke
 generated prompts when their document paths, current directory, and active valid
 context all agree. External session state is not part of this identity contract.
 The managed OpenCode plugin validates the marker against Agency context, binds it
-to the receiving OpenCode session, injects an explicit active-worker system
-instruction, and restores Agency identity for that session's shell environment.
-This session bridge is necessary because an OpenCode client can attach to a
-long-lived server process that did not inherit the client's launch environment.
+to the receiving OpenCode session, and injects an explicit active-worker system
+instruction. Its V1 integration also restores Agency identity for that session's
+shell environment. OpenCode V2's shell hook is location-scoped and does not
+identify the invoking session, so Agency deliberately avoids leaking one
+session's worker identity into another; the validated marker and injected system
+instruction remain the V2 fallback when the long-lived server did not inherit
+the client's launch environment.
 The `opencode2` and `opencode` agents remain rooted in their task or epic
 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`. The global Pi
+access and exposes existing checkout-local `.claude/skills`, `.agents/skills`,
+and `.opencode/{skill,skills}` definitions. V1 adds those source directories to
+`skills.paths`; V2 registers their discovered skill definitions through the
+plugin API and injects the managed Agency instructions through a session context
+hook. The global 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 and Pi launches

package/package.json

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

package/src/services/WorktreeService.ts

@@ -16,6 +16,7 @@ import {
 import type { RepositoryReference } from "../workbase/schemas"
 import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
+import { createProgress } from "../utils/progress"
 import { withWorktreeLocks } from "./WorktreeLock"
 import { VersionControlService } from "./VersionControlService"
 import type {
@@ -257,7 +258,12 @@ const runPostCheckoutHook = (options: {
 const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 
 const originRef = (ref: string) =>
-	ref.replace(/^refs\/remotes\/origin\//, "").replace(/^origin\//, "")
+	ref
+		.replace(/^refs\/remotes\/origin\//, "")
+		.replace(/^origin\//, "")
+		.replace(/^refs\/heads\//, "")
+
+const gitFetchTimeoutMs = 4 * 60 * 1000
 
 interface MaterializeOptions extends BaseCommandOptions {
 	readonly force?: boolean
@@ -882,6 +888,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
 					const { verboseLog } = createLoggers(options)
+					const progress = createProgress({
+						silent: options.silent || options.json,
+					})
 					const forwardCommandOutput =
 						options.verbose === true && !options.silent && !options.json
 					const { root, config } = yield* workbase.loadConfig(startPath)
@@ -1046,7 +1055,10 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												"origin",
 												originRef(executionBase),
 											],
-											{ captureOutput: true },
+											{
+												captureOutput: true,
+												timeoutMs: gitFetchTimeoutMs,
+											},
 										)
 										if (
 											remoteBase.exitCode !== 0 ||
@@ -1102,7 +1114,10 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											"origin",
 											originRef(checkout.ref),
 										],
-										{ captureOutput: true },
+										{
+											captureOutput: true,
+											timeoutMs: gitFetchTimeoutMs,
+										},
 									)
 									if (remote.exitCode === 0 && remote.stdout.trim())
 										commit = remote.stdout.trim().split(/\s+/)[0]
@@ -1165,7 +1180,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									})
 								}
 
-								const fetchOrigin = (ref?: string) =>
+								const fetchOrigin = (ref: string) =>
 									Effect.gen(function* () {
 										const remote = yield* fs.runCommand(
 											[
@@ -1185,7 +1200,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											repositoryPath,
 											"fetch",
 											"origin",
-											...(ref ? [ref] : []),
+											ref,
 										]
 										if (options.dryRun) {
 											operations.push({
@@ -1197,14 +1212,19 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											return false
 										}
 
+										const status = `Fetching '${ref}' for '${alias}'`
+										progress.start(`${status}...`)
 										const fetch = yield* fs.runCommand(command, {
 											captureOutput: true,
+											timeoutMs: gitFetchTimeoutMs,
 										})
 										if (fetch.exitCode !== 0) {
+											progress.fail(`${status} failed`)
 											return yield* new WorktreeError({
 												message: `Failed to fetch '${alias}': ${fetch.stderr}`,
 											})
 										}
+										progress.succeed(`${status} complete`)
 										operations.push({
 											action: "fetch",
 											repo: alias,
@@ -1321,7 +1341,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											message: `Worktree registry contains a missing checkout at ${checkoutPath}`,
 										})
 									}
-									yield* fetchOrigin()
+									yield* fetchOrigin(originRef(executionBase))
 
 									let args: string[]
 									let env: Record<string, string> | undefined

package/src/workbase/AGENTS.md

@@ -207,10 +207,11 @@ recursively launch. External session state is never part of worker identity. If
 the prompt and context disagree, stop and ask the user rather than launching.
 
 For OpenCode, Agency's managed plugin validates the generated marker against
-`agency context`, binds that identity to the OpenCode session, injects an
-active-worker system instruction, and supplies Agency identity to that session's
-shell environment. This avoids relying on the environment of OpenCode's
-long-lived server process.
+`agency context`, binds that identity to the OpenCode session, and injects an
+active-worker system instruction. The V1 integration also supplies Agency
+identity to that session's shell environment. OpenCode V2's shell hook does not
+identify the invoking session, so the plugin does not leak one session's identity
+into another and instead retains the validated prompt fallback.
 
 ## Closeout
 
@@ -238,9 +239,11 @@ a refinement loop, or pausing or handing off completed implementation work):
 
 `agency integration status` reports `managed`, `drifted`, `customized`, or
 `missing` generated files. Agency keeps these instructions in
-`.agency/AGENTS.md`, and its managed OpenCode config loads them automatically.
+`.agency/AGENTS.md`, and its managed OpenCode integration loads them automatically.
 It also installs a managed server plugin that exposes skills from the
-authoritative writable checkout and an explicitly registered TUI companion
+authoritative writable checkout. In OpenCode V2 it injects these managed
+instructions through a session context hook because configured instruction paths
+are not currently loaded. The V1 integration also registers a TUI companion
 providing `/agency-debug` without submitting an LLM prompt.
 The workbase-root `AGENTS.md`, when present, belongs entirely to the workbase
 owner and composes with these instructions through OpenCode's normal discovery.
@@ -253,7 +256,7 @@ OpenCode can access the complete workbase tree, but this filesystem permission
 does not expand Agency write authority beyond the checkout reported by
 `agency context`. OpenCode remains rooted in the task or epic directory so the
 workbase instructions and config compose normally. The managed plugin resolves
-the writable checkout from launch context or `agency context`, then adds its
-supported skill directories through `skills.paths`; this does not make other
-checkout-local OpenCode configuration authoritative. Agents must follow the
-authority reported by `agency context`.
+the writable checkout from launch context or `agency context`, then exposes its
+supported skill directories through the applicable OpenCode plugin API; this
+does not make other checkout-local OpenCode configuration authoritative. Agents
+must follow the authority reported by `agency context`.

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

@@ -6,10 +6,21 @@ const managedHeaderPattern =
 const checksum = (content: string) =>
 	createHash("sha256").update(content).digest("hex")
 
-const body = `import { existsSync, readFileSync } from "node:fs"
-import { dirname, join, resolve, sep } from "node:path"
+const body = `import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { basename, dirname, extname, join, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
-import type { Plugin, PluginModule } from "@opencode-ai/plugin/v1"
+type V1Plugin = (input: { directory: string }) => Promise<Record<string, any>>
+type V2PluginContext = {
+  location: { directory: string }
+  reference: { transform(callback: (editor: any) => void): Promise<unknown> }
+  skill: { transform(callback: (editor: any) => void): Promise<unknown> }
+  permission: {
+    hook(name: "evaluate", callback: (event: any) => void): Promise<unknown>
+  }
+  session: {
+    hook(name: string, callback: (event: any) => void): Promise<unknown>
+  }
+}
 
 const workerLaunchPattern = /^Agency worker launch target: ([^.\\s]+)\\./
 
@@ -21,20 +32,6 @@ 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}\`
@@ -93,6 +90,54 @@ const checkoutSkillPaths = (checkout: string | undefined) => checkout
     ].filter(existsSync)
   : []
 
+const skillFiles = (source: string) => {
+  const files: string[] = []
+  const visit = (directory: string, root = false) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name)
+      if (entry.isDirectory()) visit(path)
+      else if (
+        entry.isFile() &&
+        (entry.name === "SKILL.md" || (root && extname(entry.name) === ".md"))
+      ) files.push(path)
+    }
+  }
+  visit(source, true)
+  return files
+}
+
+const unquote = (value: string) => {
+  const trimmed = value.trim()
+  if (
+    trimmed.length >= 2 &&
+    ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'")))
+  ) return trimmed.slice(1, -1)
+  return trimmed
+}
+
+const skillInfo = (location: string) => {
+  const raw = readFileSync(location, "utf8")
+  const match = raw.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n?/)
+  const frontmatter = match?.[1] ?? ""
+  const scalar = (name: string) => {
+    const value = frontmatter.match(new RegExp(
+      "^" + name + "[ \\t]*:[ \\t]*(.+)$", "m",
+    ))?.[1]
+    return value ? unquote(value) : undefined
+  }
+  const id = basename(location) === "SKILL.md"
+    ? basename(dirname(location))
+    : basename(location, extname(location))
+  return {
+    id,
+    name: scalar("name") ?? id,
+    description: scalar("description"),
+    location,
+    content: match ? raw.slice(match[0].length) : raw,
+  }
+}
+
 const agencyContext = async (
   directory: string,
   useEnvironmentTarget = true,
@@ -133,11 +178,11 @@ const agencyContext = async (
   }
 }
 
-const plugin: Plugin = async ({ directory }) => {
+const plugin: V1Plugin = async ({ directory }) => {
   const workerSessions = new Map<string, AgencyContext>()
 
   return {
-    config: async (config) => {
+    config: async (config: any) => {
       const context = await agencyContext(directory).catch(() => undefined)
       const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(directory)
       const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(directory, root)
@@ -171,14 +216,17 @@ const plugin: Plugin = async ({ directory }) => {
       config.skills ??= {}
       config.skills.paths = [...new Set([...(config.skills.paths ?? []), ...paths])]
     },
-    "chat.message": async ({ sessionID }, output) => {
+    "chat.message": async ({ sessionID }: { sessionID: string }, output: any) => {
       const launchTarget = workerLaunchTarget(output.parts)
       if (!launchTarget) return
       const context = await agencyContext(directory, false).catch(() => undefined)
       if (context?.target !== launchTarget) return
       workerSessions.set(sessionID, context)
     },
-    "experimental.chat.system.transform": async ({ sessionID }, output) => {
+    "experimental.chat.system.transform": async (
+      { sessionID }: { sessionID?: string },
+      output: any,
+    ) => {
       if (!sessionID) return
       const context = workerSessions.get(sessionID)
       if (!context?.target) return
@@ -191,7 +239,7 @@ const plugin: Plugin = async ({ directory }) => {
         ].filter(Boolean).join(" "),
       )
     },
-    "shell.env": async ({ sessionID }, output) => {
+    "shell.env": async ({ sessionID }: { sessionID?: string }, output: any) => {
       if (!sessionID) return
       const context = workerSessions.get(sessionID)
       if (!context?.target) return
@@ -209,9 +257,17 @@ const plugin: Plugin = async ({ directory }) => {
 export const AgencyPlugin = plugin
 
 const setup = async (context: V2PluginContext) => {
-  const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
+  const directory = context.location.directory
+  const agency = await agencyContext(directory).catch(() => undefined)
+  const root = agency?.root ?? resolve(dirname(fileURLToPath(import.meta.url)), "../..")
+  const instructionsPath = join(root, ".agency", "AGENTS.md")
+  const instructions = existsSync(instructionsPath)
+    ? readFileSync(instructionsPath, "utf8")
+    : undefined
   await context.reference.transform((references) => {
-    if (references.list().some(([name]) => name === "workbase")) return
+    if (
+      references.list().some(([name]: [string, unknown]) => name === "workbase")
+    ) return
     references.add("workbase", {
       type: "local",
       path: root,
@@ -219,10 +275,49 @@ const setup = async (context: V2PluginContext) => {
     })
   })
 
-  const paths = checkoutSkillPaths(process.env.AGENCY_WRITABLE_CHECKOUT)
-  if (paths.length === 0) return
+  const paths = checkoutSkillPaths(
+    process.env.AGENCY_WRITABLE_CHECKOUT ??
+      agency?.checkout ??
+      discoverCheckout(directory, root),
+  )
   await context.skill.transform((skills) => {
-    for (const path of paths) skills.source({ type: "directory", path })
+    for (const path of paths) {
+      for (const location of skillFiles(path)) {
+        skills.add(skillInfo(location) as unknown as Parameters<typeof skills.add>[0])
+      }
+    }
+  })
+
+  const workerSessions = new Map<string, AgencyContext>()
+  await context.permission.hook("evaluate", (event) => {
+    if (
+      event.action === "external_directory" &&
+      event.resources.every((resource: string) => {
+        const path = resolve(resource)
+        return path === root || path.startsWith(root + sep)
+      })
+    ) event.effect = "allow"
+  })
+  await context.session.hook("prompt", async (event) => {
+    const launchTarget = event.prompt.text.match(workerLaunchPattern)?.[1]
+    if (!launchTarget) return
+    const current = await agencyContext(directory, false).catch(() => undefined)
+    if (!current || current.target !== launchTarget) return
+    workerSessions.set(event.sessionID, current)
+  })
+  await context.session.hook("context", (event) => {
+    if (instructions) event.system.push({ type: "text", text: instructions })
+    const current = workerSessions.get(event.sessionID)
+    if (!current?.target) return
+    event.system.push({
+      type: "text",
+      text: [
+        \`Agency verified this OpenCode session as the active worker for \${current.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+        current.checkout
+          ? \`OpenCode remains rooted in the task or phase directory for Agency instructions and context. Treat \${current.checkout} as the default implementation directory: use it for source reads, edits, repository status, builds, tests, formatting, and other repository-local commands. Set each tool's working directory to that checkout when supported; otherwise use absolute paths. Run Agency lifecycle and context commands from the task or phase directory. Any reference checkouts reported by Agency context are read-only.\`
+          : undefined,
+      ].filter(Boolean).join(" "),
+    })
   })
 }
 
@@ -230,7 +325,7 @@ export default {
   id: "agency",
   setup,
   server: plugin,
-} satisfies PluginModule & { setup: (context: V2PluginContext) => Promise<void> }
+}
 `
 
 const renderManagedWorkbaseOpencodePlugin = (content: string) =>