@markjaquith/agency 2.54.3 → 2.54.4

package/README.md

@@ -276,6 +276,19 @@ Execution-unit runners also receive `AGENCY_WRITABLE_CHECKOUT` with the
 authoritative writable checkout path.
 `AGENCY_CLAIM_REVISION` is empty for local `agency work` launches.
 `AGENCY_PROMPT` is empty unless `--auto` is set.
+Autonomous prompts begin `Agency worker launch target: <target>.`, carrying the
+same canonical target as `AGENCY_TARGET`. This is the process-local fallback for
+runner clients that attach to a long-lived process and lose launch environment
+variables. A worker must verify either signal against `agency context . --json`
+before acting; a matching worker performs the task directly and must not invoke
+`agency work` for the same target. Managed guidance also fails safe for older
+generated prompts when their document paths, current directory, and active valid
+context all agree. Herdr 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.
 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 grants the active workbase external-directory

package/package.json

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

package/src/cli.test.ts

@@ -1177,7 +1177,7 @@ status: open
 					cwd: contract.cwd,
 					env: environment,
 				})
-				expect(probe.exitCode).toBe(0)
+				expect(probe.exitCode, probe.stderr.toString()).toBe(0)
 				const agent = JSON.parse(probe.stdout.toString())
 				expect(agent.permission).toEqual(
 					expect.arrayContaining([

package/src/commands/work.test.ts

@@ -98,6 +98,8 @@ const createHarness = (options: HarnessOptions = {}) => {
 		cwd: string
 	}> = []
 	const launchEnvironments: Array<Readonly<Record<string, string>>> = []
+	const launchProcessEnvironments: Array<Record<string, string | undefined>> =
+		[]
 	const materializeOptions: Array<
 		Parameters<WorktreeService["materialize"]>[3]
 	> = []
@@ -265,6 +267,11 @@ const createHarness = (options: HarnessOptions = {}) => {
 		events.push(`launch:${cli}`)
 		launches.push({ cli, args, cwd })
 		launchEnvironments.push(environment)
+		launchProcessEnvironments.push({
+			AGENCY_SESSION_ID: process.env.AGENCY_SESSION_ID,
+			AGENCY_TARGET: process.env.AGENCY_TARGET,
+			AGENCY_PROMPT: process.env.AGENCY_PROMPT,
+		})
 		if (options.launchError) throw options.launchError
 	}
 	const defaultPick: PickWorkTarget = () => Effect.succeed(null)
@@ -307,6 +314,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 		probes,
 		launches,
 		launchEnvironments,
+		launchProcessEnvironments,
 		materializeOptions,
 		statusUpdates,
 		taskStatuses,
@@ -484,7 +492,7 @@ describe("work command", () => {
 			args: [
 				"opencode",
 				"--prompt",
-				"Work on the epic. Read /workbase/epics/delivery/EPIC.md.",
+				"Agency worker launch target: epic:delivery. Work on the epic. Read /workbase/epics/delivery/EPIC.md.",
 			],
 			cwd: "/workbase/epics/delivery",
 		})
@@ -538,7 +546,7 @@ describe("work command", () => {
 			args: [
 				"opencode",
 				"--prompt",
-				"Work on the task. Read /workbase/tasks/delivery/TASK.md.",
+				"Agency worker launch target: task:delivery. Work on the task. Read /workbase/tasks/delivery/TASK.md.",
 			],
 			cwd: "/workbase/tasks/delivery",
 		})
@@ -565,7 +573,7 @@ describe("work command", () => {
 			args: [
 				"opencode",
 				"--prompt",
-				"Start the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
+				"Agency worker launch target: execution-unit:phase/example/implementation. Start the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
 			],
 			cwd: phaseDirectory,
 		})
@@ -797,11 +805,17 @@ describe("work command", () => {
 		expect(harness.launches[0]?.args).toEqual([
 			"opencode",
 			"--prompt",
-			"Start the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
 		])
 		expect(harness.launchEnvironments[0]?.AGENCY_PROMPT).toBe(
-			"Start the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
 		)
+		expect(harness.launchProcessEnvironments[0]).toEqual({
+			AGENCY_SESSION_ID: harness.launchEnvironments[0]?.AGENCY_SESSION_ID,
+			AGENCY_TARGET: "execution-unit:task/example",
+			AGENCY_PROMPT:
+				"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
+		})
 	})
 
 	test("continues existing work with the resume command", async () => {
@@ -813,10 +827,10 @@ describe("work command", () => {
 			"opencode",
 			"--continue",
 			"--prompt",
-			"Continue the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Continue the task. Read /workbase/tasks/example/TASK.md.",
 		])
 		expect(harness.launchEnvironments[0]?.AGENCY_PROMPT).toBe(
-			"Continue the task. Read /workbase/tasks/example/TASK.md.",
+			"Agency worker launch target: execution-unit:task/example. Continue the task. Read /workbase/tasks/example/TASK.md.",
 		)
 	})
 
@@ -840,7 +854,7 @@ describe("work command", () => {
 				"opencode",
 				"--continue",
 				"--prompt",
-				"Continue the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
+				"Agency worker launch target: execution-unit:phase/example/implementation. Continue the task. Read /workbase/tasks/example/TASK.md and /workbase/tasks/example/phases/implementation/PHASE.md.",
 			],
 			cwd: phaseDirectory,
 		})
@@ -870,7 +884,7 @@ describe("work command", () => {
 				"codex",
 				"--task",
 				"example",
-				"Start the task. Read /workbase/tasks/example/TASK.md.",
+				"Agency worker launch target: execution-unit:task/example. Start the task. Read /workbase/tasks/example/TASK.md.",
 			],
 			cwd: taskDirectory,
 		})

package/src/commands/work.ts

@@ -264,6 +264,7 @@ export const work = (
 			launchPath = dirname(workspace.phasePath ?? workspace.taskPath)
 			writablePath = workspace.writablePath ?? undefined
 		}
+		prompt = `Agency worker launch target: ${targetNodeId(target)}. ${prompt}`
 
 		const explicitlyRequested = Boolean(
 			options.runner ||

package/src/services/IntegrationService.test.ts

@@ -129,6 +129,36 @@ describe("IntegrationService", () => {
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			"config.skills.paths = [...new Set",
 		)
+		expect(managedWorkbaseOpencodePlugin).toContain('"chat.message"')
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"if (!Array.isArray(parts)) return",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			'"experimental.chat.system.transform"',
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain('"shell.env"')
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"if (context?.target !== launchTarget) return",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"agencyContext(directory, false)",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"result.validation?.valid !== true",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"dirname(document) !== resolve(directory)",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"!result.authority?.writable?.checkoutPath",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain('status !== "working"')
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"output.env.AGENCY_SESSION_ID = sessionID",
+		)
+		expect(managedWorkbaseOpencodePlugin).toContain(
+			"Do not invoke agency work for this target",
+		)
 		expect(managedWorkbaseOpencodePlugin).toContain(
 			".map((path) => `${path}${sep}.`)",
 		)
@@ -142,6 +172,121 @@ describe("IntegrationService", () => {
 		).toBe(false)
 	})
 
+	test("binds validated worker identity to an OpenCode session", async () => {
+		const path = join(root, "agency-repository-skills.ts")
+		const contextResponse = JSON.stringify({
+			version: 1,
+			ok: true,
+			result: {
+				workbase: { root },
+				target: {
+					kind: "task",
+					taskId: "example",
+					path: join(root, "TASK.md"),
+				},
+				authority: {
+					mode: "execution",
+					writable: { checkoutPath: join(root, "tasks/example/code/agency") },
+				},
+				documents: { task: { data: { status: "working" } } },
+				validation: { valid: true, warnings: [] },
+			},
+		})
+		await Bun.write(
+			path,
+			managedWorkbaseOpencodePlugin
+				.replace("const contextTarget =", "export const contextTarget =")
+				.replace("const agencyContext =", "export const agencyContext =")
+				.replace(
+					"const workerLaunchTarget =",
+					"export const workerLaunchTarget =",
+				),
+		)
+		const originalSpawn = Bun.spawn
+		Bun.spawn = (() =>
+			({
+				stdout: new Response(contextResponse).body!,
+				exited: Promise.resolve(0),
+			}) as ReturnType<typeof Bun.spawn>) as typeof Bun.spawn
+		try {
+			const generated = await import(
+				`${pathToFileURL(path).href}?worker-identity`
+			)
+			expect(
+				generated.workerLaunchTarget([
+					{
+						type: "text",
+						text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+					},
+				]),
+			).toBe("execution-unit:task/example")
+			expect(generated.workerLaunchTarget(undefined)).toBeUndefined()
+			expect(
+				generated.contextTarget({
+					target: { kind: "task", taskId: "example" },
+					authority: { mode: "execution" },
+				}),
+			).toBe("execution-unit:task/example")
+			expect(await generated.agencyContext(root)).toMatchObject({
+				root,
+				target: "execution-unit:task/example",
+				task: "example",
+			})
+			const hooks = await generated.default({ directory: root } as never)
+			await hooks["chat.message"]!(
+				{ sessionID: "worker-session" } as never,
+				{
+					parts: [
+						{
+							type: "text",
+							text: "Agency worker launch target: execution-unit:task/example. Start the task.",
+						},
+					],
+				} as never,
+			)
+			await hooks["chat.message"]!(
+				{ sessionID: "mismatched-session" } as never,
+				{
+					parts: [
+						{
+							type: "text",
+							text: "Agency worker launch target: execution-unit:task/other. Start the task.",
+						},
+					],
+				} as never,
+			)
+
+			const system = { system: [] as string[] }
+			await hooks["experimental.chat.system.transform"]!(
+				{ sessionID: "worker-session" } as never,
+				system,
+			)
+			expect(system.system).toEqual([
+				expect.stringContaining(
+					"active worker for execution-unit:task/example",
+				),
+			])
+			const mismatchedSystem = { system: [] as string[] }
+			await hooks["experimental.chat.system.transform"]!(
+				{ sessionID: "mismatched-session" } as never,
+				mismatchedSystem,
+			)
+			expect(mismatchedSystem.system).toEqual([])
+
+			const shell = { env: {} as Record<string, string> }
+			await hooks["shell.env"]!({ sessionID: "worker-session" } as never, shell)
+			expect(shell.env).toMatchObject({
+				AGENCY_SESSION_ID: "worker-session",
+				AGENCY_TARGET: "execution-unit:task/example",
+				AGENCY_WORKBASE: root,
+				AGENCY_TASK_ID: "example",
+				AGENCY_WRITABLE_CHECKOUT: join(root, "tasks/example/code/agency"),
+			})
+		} finally {
+			Bun.spawn = originalSpawn
+		}
+	})
+
 	test("registers a TUI-only /agency-debug diagnostic", async () => {
 		const config = JSON.parse(managedBody(managedWorkbaseOpencodeTui))
 		expect(config).toEqual({
@@ -268,6 +413,11 @@ describe("IntegrationService", () => {
 		expect(body).toContain("Preserve parent backlinks")
 		expect(body).toContain("dirty-worktree, active-claim, revision")
 		expect(body).toContain("`agency work` is the human launch flow")
+		expect(body).toContain("Agency worker launch target: <target>.")
+		expect(body).toContain("environment variables and a generated")
+		expect(body).toContain("the initial instruction is a generated")
+		expect(body).toContain("Herdr state is never part of worker identity")
+		expect(body).toMatch(/If the prompt\s+and context disagree/)
 		expect(body).toContain("marks execution work")
 		expect(body).toContain("without creating a claim")
 		expect(body).toContain("formatting, type checks, build, dead-code checks")

package/src/workbase/AGENTS.md

@@ -76,6 +76,28 @@ task launches remain orchestration-only. External orchestrators instead claim
 an execution unit, launch and monitor their runner separately, and finish or
 release the claim with the current document revision.
 
+An Agency-launched runner receives process-local worker identity through both
+the `AGENCY_SESSION_ID` and `AGENCY_TARGET` environment variables and a generated
+prompt beginning `Agency worker launch target: <target>.` Treat either form as
+launch evidence only after `agency context . --json` confirms the same target,
+document paths, valid context, and expected write authority. Once confirmed,
+perform the assigned work directly and never invoke `agency work` to start the
+same target again.
+
+Some runner clients attach to a long-lived process and may not preserve launch
+environment variables. If the variables and prompt marker are absent, fail safe
+when the initial instruction is a generated `Start`, `Continue`, or `Work on`
+prompt whose absolute document paths match the current directory and the active,
+valid `agency context`: treat the process as the current worker and do not
+recursively launch. Herdr 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.
+
 ## Closeout
 
 An execution unit remains `working` after implementation is committed and while

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

@@ -7,9 +7,41 @@ const checksum = (content: string) =>
 	createHash("sha256").update(content).digest("hex")
 
 const body = `import { existsSync, readFileSync } from "node:fs"
-import { dirname, join, sep } from "node:path"
+import { dirname, join, resolve, sep } from "node:path"
 import type { Plugin } from "@opencode-ai/plugin"
 
+const workerLaunchPattern = /^Agency worker launch target: ([^.\\s]+)\\./
+
+type AgencyContext = {
+  root?: string
+  checkout?: string
+  target?: string
+  task?: string
+  phase?: 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 workerLaunchTarget = (parts: unknown) => {
+  if (!Array.isArray(parts)) return
+  const text = parts
+    .filter((part) => part.type === "text")
+    .map((part) => part.text ?? "")
+    .join("\\n")
+  return text.match(workerLaunchPattern)?.[1]
+}
+
 const discoverWorkbase = (directory: string) => {
   let current = directory
   while (true) {
@@ -37,64 +69,117 @@ const discoverCheckout = (directory: string, root: string | undefined) => {
   }
 }
 
-const agencyContext = async (directory: string) => {
-  const task = process.env.AGENCY_TASK_ID
-  const phase = process.env.AGENCY_PHASE_ID
+const agencyContext = async (
+  directory: string,
+  useEnvironmentTarget = true,
+): Promise<AgencyContext | undefined> => {
+  const task = useEnvironmentTarget ? process.env.AGENCY_TASK_ID : undefined
+  const phase = useEnvironmentTarget ? process.env.AGENCY_PHASE_ID : undefined
   const args = task
     ? ["agency", "context", "--task", task, ...(phase ? ["--phase", phase] : []), "--compact", "--json"]
     : ["agency", "context", ".", "--compact", "--json"]
-  const child = Bun.spawn(args, { cwd: directory, stdout: "pipe", stderr: "ignore" })
+  const child = Bun.spawn(args, {
+    cwd: directory,
+    env: process.env,
+    stdout: "pipe",
+    stderr: "ignore",
+  })
   const output = await new Response(child.stdout).text()
   if ((await child.exited) !== 0) return
   const envelope = JSON.parse(output)
   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: envelope.result?.workbase?.root as string | undefined,
-    checkout: envelope.result?.authority?.writable?.checkoutPath as string | undefined,
+    root: result.workbase?.root,
+    checkout: result.authority?.writable?.checkoutPath,
+    target,
+    task: result.target?.taskId,
+    phase: result.target?.phaseId,
   }
 }
 
-const plugin: Plugin = async ({ directory }) => ({
-  config: async (config) => {
-    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)
-
-    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,
+const plugin: Plugin = async ({ directory }) => {
+  const workerSessions = new Map<string, AgencyContext>()
+
+  return {
+    config: async (config) => {
+      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)
+
+      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 = [
-      join(checkout, ".claude", "skills"),
-      join(checkout, ".agents", "skills"),
-      join(checkout, ".opencode", "skill"),
-      join(checkout, ".opencode", "skills"),
-    ].filter(existsSync).map((path) => \`\${path}\${sep}.\`)
-    if (paths.length === 0) return
-
-    config.skills ??= {}
-    config.skills.paths = [...new Set([...(config.skills.paths ?? []), ...paths])]
-  },
-})
+      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}.\`)
+      if (paths.length === 0) return
+
+      config.skills ??= {}
+      config.skills.paths = [...new Set([...(config.skills.paths ?? []), ...paths])]
+    },
+    "chat.message": async ({ sessionID }, output) => {
+      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) => {
+      if (!sessionID) return
+      const context = workerSessions.get(sessionID)
+      if (!context?.target) return
+      output.system.push(
+        \`Agency verified this OpenCode session as the active worker for \${context.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`,
+      )
+    },
+    "shell.env": async ({ sessionID }, output) => {
+      if (!sessionID) return
+      const context = workerSessions.get(sessionID)
+      if (!context?.target) return
+      output.env.AGENCY_SESSION_ID = sessionID
+      output.env.AGENCY_TARGET = context.target
+      if (context.root) output.env.AGENCY_WORKBASE = context.root
+      if (context.checkout) output.env.AGENCY_WRITABLE_CHECKOUT = context.checkout
+      if (context.task) output.env.AGENCY_TASK_ID = context.task
+      if (context.phase) output.env.AGENCY_PHASE_ID = context.phase
+    },
+  }
+}
 
 export default plugin
 `

package/src/workbase/runner-command.test.ts

@@ -95,9 +95,12 @@ describe("runner commands", () => {
 		expect(environment).toMatchObject({
 			AGENCY_RUNNER: "custom",
 			AGENCY_CLAIMANT: "orchestrator",
+			AGENCY_SESSION_ID: "session-1",
+			AGENCY_WORKBASE: "/workbase",
 			AGENCY_TARGET: "execution-unit:phase/task/build",
 			AGENCY_TASK_ID: "task",
 			AGENCY_PHASE_ID: "build",
+			AGENCY_PROMPT: "Read the task.",
 		})
 		expect(printableEnvironment(environment).VISIBLE).toBe("yes")
 		expect(printableEnvironment(environment).ACCESS_TOKEN).toBeUndefined()