@markjaquith/agency 3.10.1 → 3.11.0

package/README.md

@@ -140,7 +140,8 @@ whether the server plugin registered writable-checkout skills. It uses a native
 toast and does not submit a prompt to an LLM. When no writable checkout skill
 directory is available, server initialization is reported as indeterminate
 rather than inferred from plugin discovery.
-OpenCode discovers the config and plugin from task and epic launch directories.
+OpenCode discovers the config and plugin from Agency launch directories and
+their ancestors.
 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.
@@ -394,9 +395,13 @@ 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.
+For execution units, the built-in `pi` agent and the `opencode2` and `opencode`
+agents running OpenCode V2 launch from the authoritative writable checkout so
+their project and Git interfaces reflect the implementation repository.
+OpenCode V1 stops configuration discovery at the checkout's Git root, so V1
+launches remain rooted in the task or phase directory. Epic and multi-phase task orchestration remains
+rooted in its Agency document directory. Ancestor discovery still supplies the
+workbase `AGENTS.md` and managed OpenCode config.
 Agency's managed OpenCode plugin grants the active workbase external-directory
 access and exposes existing checkout-local `.claude/skills`, `.agents/skills`,
 and `.opencode/{skill,skills}` definitions. V1 adds those source directories to
@@ -406,8 +411,9 @@ 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
-resolve a materialized execution-unit
-checkout through `agency context`. A multi-phase
+from a task or phase directory resolve a materialized execution-unit checkout
+through `agency context` and instruct the agent to change to it before
+implementation or Git operations. A multi-phase
 task root has no single checkout, so launch from its phase directory when using
 plain OpenCode or Pi. Other checkout-local configuration is not composed.
 `--print-command` prints the cwd, command template, and non-secret environment

package/package.json

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

package/pi-extensions/agency.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from "node:fs"
-import { dirname, join, resolve } from "node:path"
+import { dirname, join, resolve, sep } from "node:path"
 
 type ExtensionAPI = {
 	exec: (
@@ -26,7 +26,9 @@ type ExtensionAPI = {
 type AgencyContext = {
 	root?: string
 	checkout?: string
+	documentDirectory?: string
 	target?: string
+	working?: boolean
 }
 
 const contextTarget = (result: Record<string, any>): string | undefined => {
@@ -78,14 +80,18 @@ const agencyContext = async (
 		result.workbase?.root !== root ||
 		!target ||
 		(target.startsWith("execution-unit:") &&
-			(!result.authority?.writable?.checkoutPath || status !== "working"))
+			!result.authority?.writable?.checkoutPath)
 	)
 		return
 
 	return {
 		root,
 		checkout: result.authority?.writable?.checkoutPath,
+		documentDirectory: result.target?.path
+			? dirname(result.target.path)
+			: undefined,
 		target,
+		working: status === "working",
 	}
 }
 
@@ -150,12 +156,27 @@ export default function agencyExtension(pi: ExtensionAPI) {
 				: undefined
 			const activeTarget = process.env.AGENCY_TARGET
 			const worker =
-				activeTarget && context.target === activeTarget
+				activeTarget && context.target === activeTarget && context.working
 					? `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 ${context.root}. Use absolute paths under that root when workbase context is needed. Agency context remains the authority for writes.`
-			const implementation = context.checkout
-				? `Pi remains rooted in the task or phase directory for Agency instructions and context. Treat ${context.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.`
+			const checkout = context.checkout ? resolve(context.checkout) : undefined
+			const current = resolve(ctx.cwd)
+			const repository =
+				checkout &&
+				(current === checkout || current.startsWith(`${checkout}${sep}`))
+			const implementation = checkout
+				? [
+						repository
+							? `Pi is rooted in Agency's authoritative writable checkout at ${checkout}. Use this directory for source reads, edits, Git status and other Git operations, builds, tests, and formatting.`
+							: `Agency's authoritative writable checkout is ${checkout}. Before doing implementation work or Git operations, change the working directory to that checkout. Set each tool's working directory to it when supported; otherwise use absolute paths.`,
+						context.documentDirectory
+							? `Run Agency lifecycle commands from ${context.documentDirectory}; agency context may also be queried from the checkout.`
+							: undefined,
+						"Any reference checkouts reported by Agency context are read-only.",
+					]
+						.filter(Boolean)
+						.join(" ")
 				: undefined
 
 			return {

package/src/commands/work.ts

@@ -37,7 +37,10 @@ import {
 	readValidationEvidence,
 } from "../workbase/execution-contract"
 import { ValidationFailedError } from "./validate"
-import { prepareOpenCodeLaunch } from "../workbase/opencode-launch"
+import {
+	openCodeDiscoversAncestorConfig,
+	prepareOpenCodeLaunch,
+} from "../workbase/opencode-launch"
 
 export interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -378,6 +381,15 @@ export const work = (
 			options.auto,
 		)
 		cli = resolved.argv[0]!
+		if (writablePath && !config.agents?.[agent]) {
+			if (
+				agent === "pi" ||
+				((agent === "opencode2" || agent === "opencode") &&
+					(yield* openCodeDiscoversAncestorConfig(cli)))
+			) {
+				launchPath = writablePath
+			}
+		}
 		const environment = {
 			...resolved.environment,
 			...agentEnvironment(agent, variables),

package/src/utils/interactive.js

@@ -81,6 +81,8 @@ var createReadlineEditing = (getInput, onInput) => {
 };
 var InteractiveTextPrompt = (props) => {
   let input;
+  const dimensions = useTerminalDimensions();
+  const inputWidth = () => dimensions().width + 1;
   const editing = createReadlineEditing(() => input);
   useKeyboard((key) => {
     if (key.propagationStopped)
@@ -110,6 +112,7 @@ var InteractiveTextPrompt = (props) => {
     _$setProp(_el$, "flexDirection", "column");
     _$setProp(_el$, "width", "100%");
     _$setProp(_el$, "height", "100%");
+    _$setProp(_el$, "overflow", "hidden");
     _$insert(_el$, (() => {
       var _c$ = _$memo(() => !!(props.fullScreen && !props.embedded));
       return () => _c$() && [(() => {
@@ -152,17 +155,18 @@ var InteractiveTextPrompt = (props) => {
     _$setProp(_el$4, "flexShrink", 0);
     _$insert(_el$4, () => props.embedded ? "enter submit | shift-enter newline | esc clear/back" : "enter submit | shift-enter newline | esc cancel");
     _$effect((_p$) => {
-      var _v$ = macchiato.base, _v$2 = macchiato.blue, _v$3 = props.fullScreen ? 0 : 2, _v$4 = props.fullScreen ? 1 : 0, _v$5 = macchiato.mantle, _v$6 = macchiato.surface0, _v$7 = macchiato.text, _v$8 = macchiato.text, _v$9 = macchiato.blue, _v$0 = macchiato.overlay1;
+      var _v$ = macchiato.base, _v$2 = macchiato.blue, _v$3 = inputWidth(), _v$4 = props.fullScreen ? 0 : 2, _v$5 = props.fullScreen ? 1 : 0, _v$6 = macchiato.mantle, _v$7 = macchiato.surface0, _v$8 = macchiato.text, _v$9 = macchiato.text, _v$0 = macchiato.blue, _v$1 = macchiato.overlay1;
       _v$ !== _p$.e && (_p$.e = _$setProp(_el$, "backgroundColor", _v$, _p$.e));
       _v$2 !== _p$.t && (_p$.t = _$setProp(_el$2, "fg", _v$2, _p$.t));
-      _v$3 !== _p$.a && (_p$.a = _$setProp(_el$3, "height", _v$3, _p$.a));
-      _v$4 !== _p$.o && (_p$.o = _$setProp(_el$3, "flexGrow", _v$4, _p$.o));
-      _v$5 !== _p$.i && (_p$.i = _$setProp(_el$3, "backgroundColor", _v$5, _p$.i));
-      _v$6 !== _p$.n && (_p$.n = _$setProp(_el$3, "focusedBackgroundColor", _v$6, _p$.n));
-      _v$7 !== _p$.s && (_p$.s = _$setProp(_el$3, "textColor", _v$7, _p$.s));
-      _v$8 !== _p$.h && (_p$.h = _$setProp(_el$3, "focusedTextColor", _v$8, _p$.h));
-      _v$9 !== _p$.r && (_p$.r = _$setProp(_el$3, "cursorColor", _v$9, _p$.r));
-      _v$0 !== _p$.d && (_p$.d = _$setProp(_el$4, "fg", _v$0, _p$.d));
+      _v$3 !== _p$.a && (_p$.a = _$setProp(_el$3, "width", _v$3, _p$.a));
+      _v$4 !== _p$.o && (_p$.o = _$setProp(_el$3, "height", _v$4, _p$.o));
+      _v$5 !== _p$.i && (_p$.i = _$setProp(_el$3, "flexGrow", _v$5, _p$.i));
+      _v$6 !== _p$.n && (_p$.n = _$setProp(_el$3, "backgroundColor", _v$6, _p$.n));
+      _v$7 !== _p$.s && (_p$.s = _$setProp(_el$3, "focusedBackgroundColor", _v$7, _p$.s));
+      _v$8 !== _p$.h && (_p$.h = _$setProp(_el$3, "textColor", _v$8, _p$.h));
+      _v$9 !== _p$.r && (_p$.r = _$setProp(_el$3, "focusedTextColor", _v$9, _p$.r));
+      _v$0 !== _p$.d && (_p$.d = _$setProp(_el$3, "cursorColor", _v$0, _p$.d));
+      _v$1 !== _p$.l && (_p$.l = _$setProp(_el$4, "fg", _v$1, _p$.l));
       return _p$;
     }, {
       e: undefined,
@@ -174,7 +178,8 @@ var InteractiveTextPrompt = (props) => {
       s: undefined,
       h: undefined,
       r: undefined,
-      d: undefined
+      d: undefined,
+      l: undefined
     });
     return _el$;
   })();
@@ -497,15 +502,15 @@ var InteractiveSelectPrompt = (props) => {
               })()
             }), null);
             _$effect((_p$) => {
-              var _v$24 = index === selected() ? macchiato.text : macchiato.subtext0, _v$25 = index === selected() ? macchiato.surface1 : background(), _v$26 = {
+              var _v$25 = index === selected() ? macchiato.text : macchiato.subtext0, _v$26 = index === selected() ? macchiato.surface1 : background(), _v$27 = {
                 fg: index === selected() ? macchiato.blue : undefined
-              }, _v$27 = {
+              }, _v$28 = {
                 fg: macchiato.overlay1
               };
-              _v$24 !== _p$.e && (_p$.e = _$setProp(_el$26, "fg", _v$24, _p$.e));
-              _v$25 !== _p$.t && (_p$.t = _$setProp(_el$26, "bg", _v$25, _p$.t));
-              _v$26 !== _p$.a && (_p$.a = _$setProp(_el$27, "style", _v$26, _p$.a));
-              _v$27 !== _p$.o && (_p$.o = _$setProp(_el$28, "style", _v$27, _p$.o));
+              _v$25 !== _p$.e && (_p$.e = _$setProp(_el$26, "fg", _v$25, _p$.e));
+              _v$26 !== _p$.t && (_p$.t = _$setProp(_el$26, "bg", _v$26, _p$.t));
+              _v$27 !== _p$.a && (_p$.a = _$setProp(_el$27, "style", _v$27, _p$.a));
+              _v$28 !== _p$.o && (_p$.o = _$setProp(_el$28, "style", _v$28, _p$.o));
               return _p$;
             }, {
               e: undefined,
@@ -517,9 +522,9 @@ var InteractiveSelectPrompt = (props) => {
           })();
         })());
         _$effect((_p$) => {
-          var _v$22 = rowHeight(), _v$23 = index === selected() ? macchiato.surface1 : background();
-          _v$22 !== _p$.e && (_p$.e = _$setProp(_el$19, "height", _v$22, _p$.e));
-          _v$23 !== _p$.t && (_p$.t = _$setProp(_el$19, "backgroundColor", _v$23, _p$.t));
+          var _v$23 = rowHeight(), _v$24 = index === selected() ? macchiato.surface1 : background();
+          _v$23 !== _p$.e && (_p$.e = _$setProp(_el$19, "height", _v$23, _p$.e));
+          _v$24 !== _p$.t && (_p$.t = _$setProp(_el$19, "backgroundColor", _v$24, _p$.t));
           return _p$;
         }, {
           e: undefined,
@@ -529,20 +534,20 @@ var InteractiveSelectPrompt = (props) => {
       })()
     }));
     _$effect((_p$) => {
-      var _v$1 = background(), _v$10 = brandHeight(), _v$11 = macchiato.blue, _v$12 = macchiato.blue, _v$13 = props.active === false ? macchiato.mantle : props.embedded ? macchiato.surface1 : macchiato.surface0, _v$14 = props.active !== false, _v$15 = macchiato.overlay0, _v$16 = macchiato.mantle, _v$17 = props.embedded ? macchiato.surface1 : macchiato.surface0, _v$18 = macchiato.text, _v$19 = macchiato.text, _v$20 = macchiato.blue, _v$21 = gapHeight();
-      _v$1 !== _p$.e && (_p$.e = _$setProp(_el$8, "backgroundColor", _v$1, _p$.e));
-      _v$10 !== _p$.t && (_p$.t = _$setProp(_el$9, "height", _v$10, _p$.t));
-      _v$11 !== _p$.a && (_p$.a = _$setProp(_el$0, "fg", _v$11, _p$.a));
-      _v$12 !== _p$.o && (_p$.o = _$setProp(_el$10, "fg", _v$12, _p$.o));
-      _v$13 !== _p$.i && (_p$.i = _$setProp(_el$12, "backgroundColor", _v$13, _p$.i));
-      _v$14 !== _p$.n && (_p$.n = _$setProp(_el$13, "focused", _v$14, _p$.n));
-      _v$15 !== _p$.s && (_p$.s = _$setProp(_el$13, "placeholderColor", _v$15, _p$.s));
-      _v$16 !== _p$.h && (_p$.h = _$setProp(_el$13, "backgroundColor", _v$16, _p$.h));
-      _v$17 !== _p$.r && (_p$.r = _$setProp(_el$13, "focusedBackgroundColor", _v$17, _p$.r));
-      _v$18 !== _p$.d && (_p$.d = _$setProp(_el$13, "textColor", _v$18, _p$.d));
-      _v$19 !== _p$.l && (_p$.l = _$setProp(_el$13, "focusedTextColor", _v$19, _p$.l));
-      _v$20 !== _p$.u && (_p$.u = _$setProp(_el$13, "cursorColor", _v$20, _p$.u));
-      _v$21 !== _p$.c && (_p$.c = _$setProp(_el$14, "height", _v$21, _p$.c));
+      var _v$10 = background(), _v$11 = brandHeight(), _v$12 = macchiato.blue, _v$13 = macchiato.blue, _v$14 = props.active === false ? macchiato.mantle : props.embedded ? macchiato.surface1 : macchiato.surface0, _v$15 = props.active !== false, _v$16 = macchiato.overlay0, _v$17 = macchiato.mantle, _v$18 = props.embedded ? macchiato.surface1 : macchiato.surface0, _v$19 = macchiato.text, _v$20 = macchiato.text, _v$21 = macchiato.blue, _v$22 = gapHeight();
+      _v$10 !== _p$.e && (_p$.e = _$setProp(_el$8, "backgroundColor", _v$10, _p$.e));
+      _v$11 !== _p$.t && (_p$.t = _$setProp(_el$9, "height", _v$11, _p$.t));
+      _v$12 !== _p$.a && (_p$.a = _$setProp(_el$0, "fg", _v$12, _p$.a));
+      _v$13 !== _p$.o && (_p$.o = _$setProp(_el$10, "fg", _v$13, _p$.o));
+      _v$14 !== _p$.i && (_p$.i = _$setProp(_el$12, "backgroundColor", _v$14, _p$.i));
+      _v$15 !== _p$.n && (_p$.n = _$setProp(_el$13, "focused", _v$15, _p$.n));
+      _v$16 !== _p$.s && (_p$.s = _$setProp(_el$13, "placeholderColor", _v$16, _p$.s));
+      _v$17 !== _p$.h && (_p$.h = _$setProp(_el$13, "backgroundColor", _v$17, _p$.h));
+      _v$18 !== _p$.r && (_p$.r = _$setProp(_el$13, "focusedBackgroundColor", _v$18, _p$.r));
+      _v$19 !== _p$.d && (_p$.d = _$setProp(_el$13, "textColor", _v$19, _p$.d));
+      _v$20 !== _p$.l && (_p$.l = _$setProp(_el$13, "focusedTextColor", _v$20, _p$.l));
+      _v$21 !== _p$.u && (_p$.u = _$setProp(_el$13, "cursorColor", _v$21, _p$.u));
+      _v$22 !== _p$.c && (_p$.c = _$setProp(_el$14, "height", _v$22, _p$.c));
       return _p$;
     }, {
       e: undefined,
@@ -605,12 +610,12 @@ var InteractiveTabbedPrompt = (props) => {
         _$insert(_el$38, () => index() === active() ? "\u258E" : " ");
         _$insert(_el$37, () => ` ${tab.label}  `, null);
         _$effect((_p$) => {
-          var _v$30 = index() === active() ? macchiato.text : macchiato.overlay1, _v$31 = index() === active() ? macchiato.base : macchiato.surface0, _v$32 = {
+          var _v$31 = index() === active() ? macchiato.text : macchiato.overlay1, _v$32 = index() === active() ? macchiato.base : macchiato.surface0, _v$33 = {
             fg: macchiato.blue
           };
-          _v$30 !== _p$.e && (_p$.e = _$setProp(_el$37, "fg", _v$30, _p$.e));
-          _v$31 !== _p$.t && (_p$.t = _$setProp(_el$37, "bg", _v$31, _p$.t));
-          _v$32 !== _p$.a && (_p$.a = _$setProp(_el$38, "style", _v$32, _p$.a));
+          _v$31 !== _p$.e && (_p$.e = _$setProp(_el$37, "fg", _v$31, _p$.e));
+          _v$32 !== _p$.t && (_p$.t = _$setProp(_el$37, "bg", _v$32, _p$.t));
+          _v$33 !== _p$.a && (_p$.a = _$setProp(_el$38, "style", _v$33, _p$.a));
           return _p$;
         }, {
           e: undefined,
@@ -702,9 +707,9 @@ var InteractiveTabbedPrompt = (props) => {
       });
     })(), null);
     _$effect((_p$) => {
-      var _v$28 = macchiato.surface0, _v$29 = macchiato.base;
-      _v$28 !== _p$.e && (_p$.e = _$setProp(_el$30, "backgroundColor", _v$28, _p$.e));
-      _v$29 !== _p$.t && (_p$.t = _$setProp(_el$35, "backgroundColor", _v$29, _p$.t));
+      var _v$29 = macchiato.surface0, _v$30 = macchiato.base;
+      _v$29 !== _p$.e && (_p$.e = _$setProp(_el$30, "backgroundColor", _v$29, _p$.e));
+      _v$30 !== _p$.t && (_p$.t = _$setProp(_el$35, "backgroundColor", _v$30, _p$.t));
       return _p$;
     }, {
       e: undefined,
@@ -769,9 +774,9 @@ var createInteractiveSession = async (onCancel = () => {}, initialTabs = []) =>
       _$setProp(_el$40, "height", "100%");
       _$insert(_el$41, () => props.prompt);
       _$effect((_p$) => {
-        var _v$33 = macchiato.base, _v$34 = macchiato.text;
-        _v$33 !== _p$.e && (_p$.e = _$setProp(_el$40, "backgroundColor", _v$33, _p$.e));
-        _v$34 !== _p$.t && (_p$.t = _$setProp(_el$41, "fg", _v$34, _p$.t));
+        var _v$34 = macchiato.base, _v$35 = macchiato.text;
+        _v$34 !== _p$.e && (_p$.e = _$setProp(_el$40, "backgroundColor", _v$34, _p$.e));
+        _v$35 !== _p$.t && (_p$.t = _$setProp(_el$41, "fg", _v$35, _p$.t));
         return _p$;
       }, {
         e: undefined,

package/src/workbase/AGENTS.md

@@ -303,9 +303,12 @@ before launching an agent.
 
 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 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`.
+`agency context`. Pi and OpenCode V2 execution units launched by `agency work`
+are rooted in the authoritative writable checkout so their project and Git
+status reflect the implementation repository; OpenCode V1 remains rooted in the
+task or phase directory. Orchestration remains rooted in its
+Agency document directory. The managed integrations resolve the writable
+checkout from launch context or `agency context`, guide task-directory sessions
+to use it for implementation, and expose its supported skill directories through
+the applicable plugin API; this does not make other checkout-local configuration
+authoritative. Agents must follow the authority reported by `agency context`.

package/src/workbase/opencode-launch.ts

@@ -15,6 +15,21 @@ const Admitted = Schema.Struct({
 	}),
 })
 
+// V1 stops config discovery at the Git root, so a checkout-rooted V1 launch
+// would miss the workbase's managed OpenCode config and plugin.
+export const openCodeDiscoversAncestorConfig = (cli: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const result = yield* fs.runCommand([cli, "--version"], {
+			captureOutput: true,
+			timeoutMs: 60_000,
+		})
+		return (
+			result.exitCode === 0 &&
+			/^(?:opencode\s+v?)?2\./.test(result.stdout.trim())
+		)
+	}).pipe(Effect.orElseSucceed(() => false))
+
 // V2's TUI --prompt only seeds the composer. Submit through the same CLI's
 // authenticated service connection, then attach without a prompt. Reloading or
 // reconnecting the TUI cannot replay the launch input. Only built-in Agency

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

@@ -27,6 +27,7 @@ const workerLaunchPattern = /^Agency worker launch target: ([^.\\s]+)\\./
 type AgencyContext = {
   root?: string
   checkout?: string
+  documentDirectory?: string
   target?: string
   task?: string
   phase?: string
@@ -139,9 +140,27 @@ const skillInfo = (path: string) => {
   }
 }
 
+const implementationInstructions = (
+  client: "OpenCode" | "Pi",
+  context: AgencyContext | undefined,
+  directory: string,
+) => {
+  if (!context?.checkout) return
+  const checkout = resolve(context.checkout)
+  const current = resolve(directory)
+  const repository = current === checkout || current.startsWith(\`\${checkout}\${sep}\`)
+    ? \`\${client} is rooted in Agency's authoritative writable checkout at \${checkout}. Use this directory for source reads, edits, Git status and other Git operations, builds, tests, and formatting.\`
+    : \`Agency's authoritative writable checkout is \${checkout}. Before doing implementation work or Git operations, change the working directory to that checkout. Set each tool's working directory to it when supported; otherwise use absolute paths.\`
+  const lifecycle = context.documentDirectory
+    ? \`Run Agency lifecycle commands from \${context.documentDirectory}; agency context may also be queried from the checkout. Any reference checkouts reported by Agency context are read-only.\`
+    : "Any reference checkouts reported by Agency context are read-only."
+  return \`\${repository} \${lifecycle}\`
+}
+
 const agencyContext = async (
   directory: string,
   useEnvironmentTarget = true,
+  requireWorking = false,
 ): Promise<AgencyContext | undefined> => {
   const task = useEnvironmentTarget ? process.env.AGENCY_TASK_ID : undefined
   const phase = useEnvironmentTarget ? process.env.AGENCY_PHASE_ID : undefined
@@ -161,18 +180,26 @@ const agencyContext = async (
   const result = envelope.result ?? {}
   const target = contextTarget(result)
   const document = result.target?.path
+  const checkout = result.authority?.writable?.checkoutPath
   const status = result.documents?.phase?.data?.status ?? result.documents?.task?.data?.status
+  const current = resolve(directory)
+  const documentDirectory = document ? dirname(document) : undefined
+  const matchesLocation =
+    documentDirectory === current ||
+    (checkout &&
+      (current === resolve(checkout) || current.startsWith(\`\${resolve(checkout)}\${sep}\`)))
   if (
     result.validation?.valid !== true ||
     !target ||
     !document ||
-    dirname(document) !== resolve(directory) ||
-    (target.startsWith("execution-unit:") &&
+    !matchesLocation ||
+    (requireWorking && target.startsWith("execution-unit:") &&
       (!result.authority?.writable?.checkoutPath || status !== "working"))
   ) return
   return {
     root: result.workbase?.root,
-    checkout: result.authority?.writable?.checkoutPath,
+    checkout,
+    documentDirectory,
     target,
     task: result.target?.taskId,
     phase: result.target?.phaseId,
@@ -181,10 +208,11 @@ const agencyContext = async (
 
 const plugin: V1Plugin = async ({ directory }) => {
   const workerSessions = new Map<string, AgencyContext>()
+  const locationContext = agencyContext(directory, false).catch(() => undefined)
 
   return {
     config: async (config: any) => {
-      const context = await agencyContext(directory).catch(() => undefined)
+      const context = await locationContext
       const root = process.env.AGENCY_WORKBASE ?? context?.root ?? discoverWorkbase(directory)
       const checkout = process.env.AGENCY_WRITABLE_CHECKOUT ?? context?.checkout ?? discoverCheckout(directory, root)
 
@@ -220,7 +248,7 @@ const plugin: V1Plugin = async ({ directory }) => {
     "chat.message": async ({ sessionID }: { sessionID: string }, output: any) => {
       const launchTarget = workerLaunchTarget(output.parts)
       if (!launchTarget) return
-      const context = await agencyContext(directory, false).catch(() => undefined)
+      const context = await agencyContext(directory, false, true).catch(() => undefined)
       if (context?.target !== launchTarget) return
       workerSessions.set(sessionID, context)
     },
@@ -229,16 +257,16 @@ const plugin: V1Plugin = async ({ directory }) => {
       output: any,
     ) => {
       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.\`,
-          context.checkout
-            ? \`OpenCode remains rooted in the task or phase directory for Agency instructions and context. Treat \${context.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(" "),
-      )
+      const worker = workerSessions.get(sessionID)
+      const context = worker ?? await locationContext
+      const implementation = implementationInstructions("OpenCode", context, directory)
+      if (!worker?.target && !implementation) return
+      output.system.push([
+        worker?.target
+          ? \`Agency verified this OpenCode session as the active worker for \${worker.target}. Perform the assigned work directly. Do not invoke agency work for this target or launch a replacement worker.\`
+          : undefined,
+        implementation,
+      ].filter(Boolean).join(" "))
     },
     "shell.env": async ({ sessionID }: { sessionID?: string }, output: any) => {
       if (!sessionID) return
@@ -259,7 +287,7 @@ export const AgencyPlugin = plugin
 
 const setup = async (context: V2PluginContext) => {
   const directory = context.location.directory
-  const agency = await agencyContext(directory).catch(() => undefined)
+  const agency = await agencyContext(directory, false).catch(() => undefined)
   const root = agency?.root ?? resolve(dirname(fileURLToPath(import.meta.url)), "../..")
   const instructionsPath = join(root, ".agency", "AGENTS.md")
   const instructions = existsSync(instructionsPath)
@@ -302,23 +330,21 @@ const setup = async (context: V2PluginContext) => {
   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)
+    const current = await agencyContext(directory, false, true).catch(() => undefined)
     if (!current || current.target !== launchTarget) return
     workerSessions.set(event.sessionID, current)
   })
+  const implementation = implementationInstructions("OpenCode", agency, directory)
   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(" "),
-    })
+    const text = [
+      current?.target
+        ? \`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.\`
+        : undefined,
+      implementationInstructions("OpenCode", current, directory) ?? implementation,
+    ].filter(Boolean).join(" ")
+    if (text) event.system.push({ type: "text", text })
   })
 }