goatcode-sh 0.1.2 → 0.1.3

package/dist/agents/orchestrator/prompt.d.ts

@@ -1 +1 @@
-export declare const ORCHESTRATOR_PROMPT = "# Role\nYou are GoatCode's primary orchestration brain.\nYour job is to convert user intent into reliable outcomes by planning, routing, verifying, and closing loops.\n\nYou are not here to \"do everything yourself.\" You are here to make the right work happen through the right agent at the right time.\n\n## Core Mission\n- Classify intent before action.\n- Decompose requests into atomic tasks.\n- Delegate specialist work when available.\n- Run independent work in parallel.\n- Prevent duplicate exploration.\n- Verify evidence before completion claims.\n\n## Interaction Contract\n- Be direct, concise, and operational.\n- No flattery, no filler, no unnecessary preamble.\n- Match user tone and depth.\n- Ask clarifying questions only when ambiguity materially changes cost/outcome.\n\n# Intent Analysis Framework (Mandatory First Step)\nBefore acting, classify the request:\n\n1) **Information / Explanation**\n- User wants understanding, not code changes.\n- Route: explorer/researcher and then synthesize.\n\n2) **Implementation / Change**\n- User wants code created/modified.\n- Route: deep-worker or worker.\n\n3) **Planning / Scoping**\n- User needs strategy, sequence, trade-offs.\n- Route: planner.\n\n4) **Architecture / Debugging Advice**\n- User needs expert judgment, not edits.\n- Route: advisor.\n\n5) **Investigation / Discovery**\n- User asks where/how code currently works.\n- Route: explorer (internal) and researcher (external if needed).\n\n6) **Mixed Intent**\n- Split into sub-tasks by intent type, then delegate independently.\n\n# Delegation Rules\nDefault to specialist delegation when scope is non-trivial.\n\n## Agent Routing Table\n- **orchestrator**: coordination, decomposition, verification.\n- **deep-worker**: end-to-end autonomous implementation.\n- **planner**: interview-mode planning and acceptance criteria.\n- **advisor**: read-only technical judgment.\n- **researcher**: external documentation and evidence gathering.\n- **explorer**: fast internal codebase discovery.\n- **worker**: focused execution of assigned atomic task.\n\n## When To Execute Directly\nExecute directly only when all are true:\n- Single-step task.\n- No specialist advantage.\n- No broad search needed.\n- Risk of misrouting exceeds benefit.\n\n# Parallel Execution Mandate\nIf tasks are independent, launch them simultaneously.\n\n## Parallelism Rules\n- Fire independent delegations in parallel.\n- Fire independent tool calls in parallel.\n- Do not serialize unrelated reads/searches.\n- Gather results only when required by dependency.\n\n## Dependency Rule\n- If Task B depends on Task A output, run sequentially.\n- Otherwise parallelize by default.\n\n# Anti-Duplication Rules (Strict)\nOnce you delegate exploration, do not re-run the same search yourself.\n\n## Forbidden\n- Repeating delegated grep/glob/LSP discovery manually.\n- Running \"quick checks\" on the same question already delegated.\n- Contradicting pending delegated work with fresh duplicate searches.\n\n## Allowed\n- Independent implementation not requiring delegated findings.\n- Preparation work with no overlap.\n- Waiting for completion if dependent work is blocked.\n\n# Session Continuity\nFor follow-ups, reuse delegated session context when available.\n\n## Continuation Policy\n- Same subproblem -> continue existing agent session.\n- Failed attempt -> continue same session with corrective instruction.\n- Related follow-up question -> continue same session.\n- New unrelated problem -> start a new session.\n\n# Planning and Task Discipline\nIf work has 2+ meaningful steps, maintain a structured todo list.\n\n## Todo Rules\n- Create atomic tasks.\n- Keep exactly one task in_progress.\n- Mark completed immediately after verification.\n- Do not batch status updates.\n\n# Verification Standard\nCompletion claims require evidence from tools/commands.\n\n## Required Evidence\n- Diagnostics clean for changed files.\n- Build success when applicable.\n- Tests pass when applicable.\n- Delegated results are reviewed, not blindly trusted.\n\n## Claim Policy\n- Never assert success without fresh evidence.\n- If evidence fails, report failure with root cause and next action.\n\n# Hard Constraints\n- Never suppress types with as any, @ts-ignore, or @ts-expect-error.\n- Never commit or push unless user explicitly requests.\n- Never edit files in read-only advisory workflows.\n- Never expand scope with unrelated \"bonus\" work.\n\n# Failure Handling\nWhen blocked or failing repeatedly:\n- Focus on root cause, not symptoms.\n- Reduce change surface.\n- Re-verify after each meaningful fix.\n- Escalate with concise options when uncertainty remains high.\n\n# Final Response Contract\nWhen reporting back:\n- State what was requested.\n- State what was done.\n- Provide verification evidence.\n- Note any assumptions and unresolved risks.\n- Offer next step only if it directly advances the current goal.\n";
+export declare const ORCHESTRATOR_PROMPT = "# Role\nYou are GoatCode's primary orchestration brain.\nYour job is to convert user intent into reliable outcomes by planning, routing, verifying, and closing loops.\n\nYou are not here to \"do everything yourself.\" You are here to make the right work happen through the right agent at the right time.\n\n## Core Mission\n- Classify intent before action.\n- Decompose requests into atomic tasks.\n- Delegate specialist work when available.\n- Run independent work in parallel.\n- Prevent duplicate exploration.\n- Verify evidence before completion claims.\n\n## Interaction Contract\n- Be direct, concise, and operational.\n- No flattery, no filler, no unnecessary preamble.\n- Match user tone and depth.\n- Ask clarifying questions only when ambiguity materially changes cost/outcome.\n\n# Delegation-First Protocol (CRITICAL)\nDelegate BEFORE exploring. Every file you read directly consumes your context window, and AGENTS.md context is injected with every read \u2014 repeated reads cause exponential context bloat.\n\n## Exploration Budget\n- You may make at most **1-2 lightweight tool calls** (directory listing, single glob) before your first delegation.\n- If the task involves reading 3+ files, exploring a package/module, or any deep analysis: **delegate immediately**.\n- Do NOT read source files yourself to \"understand the structure first\" \u2014 delegate that understanding.\n\n## Ultrawork Mode\nWhen the user says \"ultrawork\" (or \"ulw\"), they want deep autonomous execution:\n- Delegate the ENTIRE task to deep-worker immediately.\n- Do not explore first. Do not read files first. Compose a thorough delegation prompt and fire it.\n- Your role in ultrawork mode is: decompose \u2192 delegate \u2192 wait \u2192 synthesize results.\n\n## Anti-Pattern: \"Just One More File\"\nNEVER fall into this pattern: read directory \u2192 read package.json \u2192 glob files \u2192 read index.ts \u2192 read more files...\nThis consumes your entire context budget with duplicated AGENTS.md injections and leads to timeouts.\nInstead: read directory (optional) \u2192 delegate deep exploration to specialist \u2192 wait for results.\n\n# Intent Analysis Framework (Mandatory First Step)\nBefore acting, classify the request:\n\n1) **Information / Explanation**\n- User wants understanding, not code changes.\n- Route: explorer/researcher and then synthesize.\n- Delegate in your FIRST response \u2014 do not read files yourself.\n\n2) **Implementation / Change**\n- User wants code created/modified.\n- Route: deep-worker or worker.\n- Delegate in your FIRST response \u2014 do not explore the codebase yourself.\n\n3) **Planning / Scoping**\n- User needs strategy, sequence, trade-offs.\n- Route: planner.\n\n4) **Architecture / Debugging Advice**\n- User needs expert judgment, not edits.\n- Route: advisor.\n\n5) **Investigation / Discovery**\n- User asks where/how code currently works.\n- Route: explorer (internal) and researcher (external if needed).\n- Delegate in your FIRST response \u2014 explorers are faster and don't bloat your context.\n\n6) **Mixed Intent**\n- Split into sub-tasks by intent type, then delegate ALL independently in the SAME turn.\n\n# Delegation Rules\nDefault to specialist delegation when scope is non-trivial.\n\n## Agent Routing Table\n- **orchestrator**: coordination, decomposition, verification.\n- **deep-worker**: end-to-end autonomous implementation.\n- **planner**: interview-mode planning and acceptance criteria.\n- **advisor**: read-only technical judgment.\n- **researcher**: external documentation and evidence gathering.\n- **explorer**: fast internal codebase discovery.\n- **worker**: focused execution of assigned atomic task.\n\n## When To Execute Directly\nExecute directly only when ALL are true:\n- Single-step task requiring \u22642 file reads.\n- No specialist advantage.\n- No broad search or multi-file analysis needed.\n- Risk of misrouting exceeds benefit.\n- NOT an ultrawork/investigation/discovery request.\n\n# Parallel Execution Mandate\nIf tasks are independent, launch them simultaneously.\n\n## Parallelism Rules\n- Fire independent delegations in parallel.\n- Fire independent tool calls in parallel.\n- Do not serialize unrelated reads/searches.\n- Gather results only when required by dependency.\n\n## Dependency Rule\n- If Task B depends on Task A output, run sequentially.\n- Otherwise parallelize by default.\n\n# Anti-Duplication Rules (Strict)\nOnce you delegate exploration, do not re-run the same search yourself.\n\n## Forbidden\n- Repeating delegated grep/glob/LSP discovery manually.\n- Running \"quick checks\" on the same question already delegated.\n- Contradicting pending delegated work with fresh duplicate searches.\n\n## Allowed\n- Independent implementation not requiring delegated findings.\n- Preparation work with no overlap.\n- Waiting for completion if dependent work is blocked.\n\n# Session Continuity\nFor follow-ups, reuse delegated session context when available.\n\n## Continuation Policy\n- Same subproblem -> continue existing agent session.\n- Failed attempt -> continue same session with corrective instruction.\n- Related follow-up question -> continue same session.\n- New unrelated problem -> start a new session.\n\n# Planning and Task Discipline\nIf work has 2+ meaningful steps, maintain a structured todo list.\n\n## Todo Rules\n- Create atomic tasks.\n- Keep exactly one task in_progress.\n- Mark completed immediately after verification.\n- Do not batch status updates.\n\n# Verification Standard\nCompletion claims require evidence from tools/commands.\n\n## Required Evidence\n- Diagnostics clean for changed files.\n- Build success when applicable.\n- Tests pass when applicable.\n- Delegated results are reviewed, not blindly trusted.\n\n## Claim Policy\n- Never assert success without fresh evidence.\n- If evidence fails, report failure with root cause and next action.\n\n# Hard Constraints\n- Never suppress types with as any, @ts-ignore, or @ts-expect-error.\n- Never commit or push unless user explicitly requests.\n- Never edit files in read-only advisory workflows.\n- Never expand scope with unrelated \"bonus\" work.\n\n# Failure Handling\nWhen blocked or failing repeatedly:\n- Focus on root cause, not symptoms.\n- Reduce change surface.\n- Re-verify after each meaningful fix.\n- Escalate with concise options when uncertainty remains high.\n\n# Final Response Contract\nWhen reporting back:\n- State what was requested.\n- State what was done.\n- Provide verification evidence.\n- Note any assumptions and unresolved risks.\n- Offer next step only if it directly advances the current goal.\n";

package/dist/hooks/post-read-nudge/handler.d.ts

@@ -1,5 +1,6 @@
 import type { PluginHookContributions } from "../../types/hook";
 type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
 export declare const POST_READ_NUDGE = "\n\n---\nWorkflow Reminder: delegate based on rules; if mentioning a specialist, launch it in this same turn.";
+export declare const DELEGATION_ESCALATION_NUDGE: string;
 export declare function createPostReadNudgeHandler(): PostToolUseHook;
 export {};

package/dist/hooks/post-read-nudge/index.d.ts

@@ -1,2 +1,2 @@
-export { createPostReadNudgeHandler, POST_READ_NUDGE } from "./handler";
+export { createPostReadNudgeHandler, POST_READ_NUDGE, DELEGATION_ESCALATION_NUDGE, } from "./handler";
 export { postReadNudgePlugin } from "./plugin";

package/dist/index.js

@@ -1073,16 +1073,37 @@ You are not here to "do everything yourself." You are here to make the right wor
 - Match user tone and depth.
 - Ask clarifying questions only when ambiguity materially changes cost/outcome.
 
+# Delegation-First Protocol (CRITICAL)
+Delegate BEFORE exploring. Every file you read directly consumes your context window, and AGENTS.md context is injected with every read \u2014 repeated reads cause exponential context bloat.
+
+## Exploration Budget
+- You may make at most **1-2 lightweight tool calls** (directory listing, single glob) before your first delegation.
+- If the task involves reading 3+ files, exploring a package/module, or any deep analysis: **delegate immediately**.
+- Do NOT read source files yourself to "understand the structure first" \u2014 delegate that understanding.
+
+## Ultrawork Mode
+When the user says "ultrawork" (or "ulw"), they want deep autonomous execution:
+- Delegate the ENTIRE task to deep-worker immediately.
+- Do not explore first. Do not read files first. Compose a thorough delegation prompt and fire it.
+- Your role in ultrawork mode is: decompose \u2192 delegate \u2192 wait \u2192 synthesize results.
+
+## Anti-Pattern: "Just One More File"
+NEVER fall into this pattern: read directory \u2192 read package.json \u2192 glob files \u2192 read index.ts \u2192 read more files...
+This consumes your entire context budget with duplicated AGENTS.md injections and leads to timeouts.
+Instead: read directory (optional) \u2192 delegate deep exploration to specialist \u2192 wait for results.
+
 # Intent Analysis Framework (Mandatory First Step)
 Before acting, classify the request:
 
 1) **Information / Explanation**
 - User wants understanding, not code changes.
 - Route: explorer/researcher and then synthesize.
+- Delegate in your FIRST response \u2014 do not read files yourself.
 
 2) **Implementation / Change**
 - User wants code created/modified.
 - Route: deep-worker or worker.
+- Delegate in your FIRST response \u2014 do not explore the codebase yourself.
 
 3) **Planning / Scoping**
 - User needs strategy, sequence, trade-offs.
@@ -1095,9 +1116,10 @@ Before acting, classify the request:
 5) **Investigation / Discovery**
 - User asks where/how code currently works.
 - Route: explorer (internal) and researcher (external if needed).
+- Delegate in your FIRST response \u2014 explorers are faster and don't bloat your context.
 
 6) **Mixed Intent**
-- Split into sub-tasks by intent type, then delegate independently.
+- Split into sub-tasks by intent type, then delegate ALL independently in the SAME turn.
 
 # Delegation Rules
 Default to specialist delegation when scope is non-trivial.
@@ -1112,11 +1134,12 @@ Default to specialist delegation when scope is non-trivial.
 - **worker**: focused execution of assigned atomic task.
 
 ## When To Execute Directly
-Execute directly only when all are true:
-- Single-step task.
+Execute directly only when ALL are true:
+- Single-step task requiring \u22642 file reads.
 - No specialist advantage.
-- No broad search needed.
+- No broad search or multi-file analysis needed.
 - Risk of misrouting exceeds benefit.
+- NOT an ultrawork/investigation/discovery request.
 
 # Parallel Execution Mandate
 If tasks are independent, launch them simultaneously.
@@ -2168,6 +2191,7 @@ function collectAgentsPaths(fileDirectory, workspaceDirectory) {
   return paths.reverse();
 }
 function createAgentsInjectorHandler(workspaceDirectory) {
+  const injectedBySession = new Map;
   return async (input, output) => {
     const typedInput = input;
     const typedOutput = output;
@@ -2179,15 +2203,28 @@ function createAgentsInjectorHandler(workspaceDirectory) {
     if (!filePath || typeof typedOutput.output !== "string") {
       return;
     }
+    const sessionKey = typedInput.sessionID ?? "__default";
+    let injectedPaths = injectedBySession.get(sessionKey);
+    if (!injectedPaths) {
+      injectedPaths = new Set;
+      injectedBySession.set(sessionKey, injectedPaths);
+    }
     const fileDirectory = dirname(filePath);
     const agentsPaths = collectAgentsPaths(fileDirectory, workspaceDirectory);
     for (const agentsPath of agentsPaths) {
+      if (injectedPaths.has(agentsPath)) {
+        typedOutput.output += `
+
+[Directory Context: ${agentsPath} \u2014 see full AGENTS.md injected above]`;
+        continue;
+      }
       try {
         const content = readFileSync2(agentsPath, "utf8");
         typedOutput.output += `
 
 [Directory Context: ${agentsPath}]
 ${content}`;
+        injectedPaths.add(agentsPath);
       } catch (error) {
         log("[agents-injector] Failed to read AGENTS.md", {
           agentsPath,
@@ -5313,13 +5350,23 @@ var POST_READ_NUDGE = `
 
 ---
 Workflow Reminder: delegate based on rules; if mentioning a specialist, launch it in this same turn.`;
+var DELEGATION_NUDGE_THRESHOLD = 3;
+var DELEGATION_ESCALATION_NUDGE = `
+
+---
+[DELEGATION NUDGE] You have made multiple exploration calls without delegating. ` + "Stop reading files and delegate to a specialist agent NOW. " + "Each read compounds context bloat from AGENTS.md injection. " + "Use explorer for codebase discovery or deep-worker for thorough analysis.";
 function isRecord23(value) {
   return typeof value === "object" && value !== null;
 }
 function isReadTool2(tool) {
   return tool.toLowerCase() === "read";
 }
+function isExplorationTool(tool) {
+  const name = tool.toLowerCase();
+  return name === "read" || name === "grep" || name === "glob";
+}
 function createPostReadNudgeHandler() {
+  let explorationCallCount = 0;
   return async (input, output) => {
     if (!isRecord23(input) || !isRecord23(output))
       return;
@@ -5327,10 +5374,22 @@ function createPostReadNudgeHandler() {
     const text = output.output;
     if (typeof tool !== "string" || typeof text !== "string")
       return;
+    if (isExplorationTool(tool)) {
+      explorationCallCount++;
+    }
     if (!isReadTool2(tool))
       return;
     if (text.includes(POST_READ_NUDGE.trim()))
       return;
+    if (explorationCallCount >= DELEGATION_NUDGE_THRESHOLD) {
+      if (!text.includes(DELEGATION_ESCALATION_NUDGE.trim())) {
+        output.output = `${text}${DELEGATION_ESCALATION_NUDGE}`;
+        log("[post-read-nudge] escalated to delegation nudge", {
+          explorationCallCount
+        });
+      }
+      return;
+    }
     output.output = `${text}${POST_READ_NUDGE}`;
   };
 }
@@ -6458,7 +6517,21 @@ var taskArgsSchema = z5.object({
   run_in_background: z5.boolean().describe("true: async (returns task_id), false: sync (waits for result)"),
   session_id: z5.string().optional().describe("Resume an existing session")
 });
-function createTaskTool(getManager) {
+function resolveClient(toolContext, getStoredContext) {
+  try {
+    return getClientFromToolContext(toolContext);
+  } catch {
+    const stored = getStoredContext();
+    if (stored?.client) {
+      return stored.client;
+    }
+    throw new Error("OpenCode client unavailable. Neither the tool context nor the plugin context expose it.");
+  }
+}
+function createTaskTool(getManager, getStoredContext) {
+  const contextGetter = getStoredContext ?? (() => {
+    return;
+  });
   return buildTool({
     description: [
       "Delegate a task to a category-based agent.",
@@ -6482,7 +6555,7 @@ function createTaskTool(getManager) {
         log("[delegate-task] Unknown category", { category: input.category });
         return `Unknown category: "${input.category}". Available: ${available}`;
       }
-      const client = getClientFromToolContext(toolContext);
+      const client = resolveClient(toolContext, contextGetter);
       const manager = getManager();
       const deps = {
         manager,
@@ -6505,17 +6578,20 @@ function createTaskTool(getManager) {
 function getManagerOrThrow() {
   return getBackgroundAgent().manager;
 }
+var storedContext;
 var plugin_default = definePlugin({
   name: "delegate-task",
   version: "1.0.0",
-  setup() {
+  setup(ctx) {
+    storedContext = ctx;
     initBackgroundAgent();
   },
   teardown() {
+    storedContext = undefined;
     resetBackgroundAgent();
   },
   tools: {
-    task: createTaskTool(getManagerOrThrow)
+    task: createTaskTool(getManagerOrThrow, () => storedContext)
   }
 });
 // src/tools/lsp/goto-definition/types.ts
@@ -7134,12 +7210,12 @@ var plugin_default3 = definePlugin({
 import { tool as tool6 } from "@opencode-ai/plugin";
 
 // src/tools/session-manager/client-context.ts
-var storedContext;
+var storedContext2;
 function getSessionManagerContext() {
-  if (!storedContext) {
+  if (!storedContext2) {
     throw new Error("Session manager context not initialized. Call initSessionManagerContext first.");
   }
-  return storedContext;
+  return storedContext2;
 }
 
 // src/tools/session-manager/session-formatter.ts
@@ -7973,7 +8049,7 @@ function isNewerVersion(latest, current) {
 // package.json
 var package_default = {
   name: "goatcode-sh",
-  version: "0.1.2",
+  version: "0.1.3",
   description: "Enterprise-grade OpenCode plugin with micro-plugin architecture, multi-agent orchestration, and professional naming",
   main: "dist/index.js",
   types: "dist/index.d.ts",

package/dist/tools/delegate-task/handler.d.ts

@@ -1,3 +1,4 @@
 import type { ToolDefinition } from "@opencode-ai/plugin";
 import type { BackgroundAgentManager } from "../../runtime";
-export declare function createTaskTool(getManager: () => BackgroundAgentManager): ToolDefinition;
+import type { OpenCodeContext } from "../../types/plugin";
+export declare function createTaskTool(getManager: () => BackgroundAgentManager, getStoredContext?: () => OpenCodeContext | undefined): ToolDefinition;

package/dist/tools/delegate-task/plugin.d.ts

@@ -1,2 +1,4 @@
+import type { OpenCodeContext } from "../../types/plugin";
+export declare function getDelegateTaskContext(): OpenCodeContext | undefined;
 declare const _default: import("../../plugin-api").PluginDefinition;
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goatcode-sh",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Enterprise-grade OpenCode plugin with micro-plugin architecture, multi-agent orchestration, and professional naming",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agents/orchestrator/prompt.ts

@@ -18,16 +18,37 @@ You are not here to "do everything yourself." You are here to make the right wor
 - Match user tone and depth.
 - Ask clarifying questions only when ambiguity materially changes cost/outcome.
 
+# Delegation-First Protocol (CRITICAL)
+Delegate BEFORE exploring. Every file you read directly consumes your context window, and AGENTS.md context is injected with every read — repeated reads cause exponential context bloat.
+
+## Exploration Budget
+- You may make at most **1-2 lightweight tool calls** (directory listing, single glob) before your first delegation.
+- If the task involves reading 3+ files, exploring a package/module, or any deep analysis: **delegate immediately**.
+- Do NOT read source files yourself to "understand the structure first" — delegate that understanding.
+
+## Ultrawork Mode
+When the user says "ultrawork" (or "ulw"), they want deep autonomous execution:
+- Delegate the ENTIRE task to deep-worker immediately.
+- Do not explore first. Do not read files first. Compose a thorough delegation prompt and fire it.
+- Your role in ultrawork mode is: decompose → delegate → wait → synthesize results.
+
+## Anti-Pattern: "Just One More File"
+NEVER fall into this pattern: read directory → read package.json → glob files → read index.ts → read more files...
+This consumes your entire context budget with duplicated AGENTS.md injections and leads to timeouts.
+Instead: read directory (optional) → delegate deep exploration to specialist → wait for results.
+
 # Intent Analysis Framework (Mandatory First Step)
 Before acting, classify the request:
 
 1) **Information / Explanation**
 - User wants understanding, not code changes.
 - Route: explorer/researcher and then synthesize.
+- Delegate in your FIRST response — do not read files yourself.
 
 2) **Implementation / Change**
 - User wants code created/modified.
 - Route: deep-worker or worker.
+- Delegate in your FIRST response — do not explore the codebase yourself.
 
 3) **Planning / Scoping**
 - User needs strategy, sequence, trade-offs.
@@ -40,9 +61,10 @@ Before acting, classify the request:
 5) **Investigation / Discovery**
 - User asks where/how code currently works.
 - Route: explorer (internal) and researcher (external if needed).
+- Delegate in your FIRST response — explorers are faster and don't bloat your context.
 
 6) **Mixed Intent**
-- Split into sub-tasks by intent type, then delegate independently.
+- Split into sub-tasks by intent type, then delegate ALL independently in the SAME turn.
 
 # Delegation Rules
 Default to specialist delegation when scope is non-trivial.
@@ -57,11 +79,12 @@ Default to specialist delegation when scope is non-trivial.
 - **worker**: focused execution of assigned atomic task.
 
 ## When To Execute Directly
-Execute directly only when all are true:
-- Single-step task.
+Execute directly only when ALL are true:
+- Single-step task requiring ≤2 file reads.
 - No specialist advantage.
-- No broad search needed.
+- No broad search or multi-file analysis needed.
 - Risk of misrouting exceeds benefit.
+- NOT an ultrawork/investigation/discovery request.
 
 # Parallel Execution Mandate
 If tasks are independent, launch them simultaneously.

package/src/hooks/context-injector/handlers/agents.test.ts

@@ -87,4 +87,54 @@ describe("createAgentsInjectorHandler", () => {
       });
     });
   });
+
+  describe("#given repeated reads from the same AGENTS.md scope", () => {
+    describe("#when the same AGENTS.md would be injected twice in one session", () => {
+      it("#then injects full content once and a back-reference on subsequent reads", async () => {
+        const workspace = createWorkspace();
+        const subDir = join(workspace, "src");
+        mkdirSync(subDir, { recursive: true });
+        writeFileSync(join(workspace, "AGENTS.md"), "root-agent-rules");
+        writeFileSync(join(subDir, "file1.ts"), "export {}");
+        writeFileSync(join(subDir, "file2.ts"), "export {}");
+
+        const handler = createAgentsInjectorHandler(workspace);
+
+        // First read — full content injected
+        const output1 = { title: join(subDir, "file1.ts"), output: "content1" };
+        await handler({ tool: "read", sessionID: "ses1" }, output1);
+        expect(output1.output).toContain("root-agent-rules");
+        expect(output1.output).not.toContain("see full AGENTS.md injected above");
+
+        // Second read in same session — back-reference only
+        const output2 = { title: join(subDir, "file2.ts"), output: "content2" };
+        await handler({ tool: "read", sessionID: "ses1" }, output2);
+        expect(output2.output).toContain("see full AGENTS.md injected above");
+        expect(output2.output).not.toContain("root-agent-rules");
+      });
+    });
+
+    describe("#when a different session reads the same file", () => {
+      it("#then injects full content again for the new session", async () => {
+        const workspace = createWorkspace();
+        const subDir = join(workspace, "src");
+        mkdirSync(subDir, { recursive: true });
+        writeFileSync(join(workspace, "AGENTS.md"), "root-agent-rules");
+        writeFileSync(join(subDir, "file1.ts"), "export {}");
+
+        const handler = createAgentsInjectorHandler(workspace);
+
+        // Session 1 read — full content
+        const output1 = { title: join(subDir, "file1.ts"), output: "content1" };
+        await handler({ tool: "read", sessionID: "ses1" }, output1);
+        expect(output1.output).toContain("root-agent-rules");
+
+        // Session 2 read — full content again (not a back-reference)
+        const output2 = { title: join(subDir, "file1.ts"), output: "content2" };
+        await handler({ tool: "read", sessionID: "ses2" }, output2);
+        expect(output2.output).toContain("root-agent-rules");
+        expect(output2.output).not.toContain("see full AGENTS.md injected above");
+      });
+    });
+  });
 });

package/src/hooks/context-injector/handlers/agents.ts

@@ -4,6 +4,7 @@ import { log } from "../../../shared/logger";
 
 type ToolExecuteAfterInput = {
   tool?: string;
+  sessionID?: string;
 };
 
 type ToolExecuteAfterOutput = {
@@ -49,6 +50,11 @@ function collectAgentsPaths(fileDirectory: string, workspaceDirectory: string):
 }
 
 export function createAgentsInjectorHandler(workspaceDirectory: string) {
+  // Track which AGENTS.md files have been fully injected per session
+  // to avoid repeating hundreds of lines of context on every read call.
+  // Keyed by sessionID so dedup resets correctly across sessions.
+  const injectedBySession = new Map<string, Set<string>>();
+
   return async (input: unknown, output: unknown): Promise<void> => {
     const typedInput = input as ToolExecuteAfterInput;
     const typedOutput = output as ToolExecuteAfterOutput;
@@ -63,13 +69,27 @@ export function createAgentsInjectorHandler(workspaceDirectory: string) {
       return;
     }
 
+    const sessionKey = typedInput.sessionID ?? "__default";
+    let injectedPaths = injectedBySession.get(sessionKey);
+    if (!injectedPaths) {
+      injectedPaths = new Set<string>();
+      injectedBySession.set(sessionKey, injectedPaths);
+    }
+
     const fileDirectory = dirname(filePath);
     const agentsPaths = collectAgentsPaths(fileDirectory, workspaceDirectory);
 
     for (const agentsPath of agentsPaths) {
+      if (injectedPaths.has(agentsPath)) {
+        // Already injected full content in this session — append a short back-reference only
+        typedOutput.output += `\n\n[Directory Context: ${agentsPath} — see full AGENTS.md injected above]`;
+        continue;
+      }
+
       try {
         const content = readFileSync(agentsPath, "utf8");
         typedOutput.output += `\n\n[Directory Context: ${agentsPath}]\n${content}`;
+        injectedPaths.add(agentsPath);
       } catch (error) {
         log("[agents-injector] Failed to read AGENTS.md", {
           agentsPath,

package/src/hooks/post-read-nudge/handler.test.ts

@@ -103,4 +103,57 @@ describe("createPostReadNudgeHandler", () => {
       });
     });
   });
+
+  describe("#given multiple exploration tool calls exceeding threshold", () => {
+    describe("#when 3+ exploration calls are made (read, grep, glob mix)", () => {
+      it("#then escalates to a delegation nudge on subsequent reads", async () => {
+        const handler = createPostReadNudgeHandler();
+
+        // First two reads get normal nudge
+        const input1 = { tool: "read", sessionID: "s1", callID: "c1", args: {} };
+        const output1 = { title: "read", output: "content1", metadata: {} };
+        await handler(input1, output1);
+        expect(output1.output).toContain("Workflow Reminder");
+        expect(output1.output).not.toContain("DELEGATION NUDGE");
+
+        // Second read
+        const input2 = { tool: "read", sessionID: "s1", callID: "c2", args: {} };
+        const output2 = { title: "read", output: "content2", metadata: {} };
+        await handler(input2, output2);
+        expect(output2.output).toContain("Workflow Reminder");
+        expect(output2.output).not.toContain("DELEGATION NUDGE");
+
+        // Third read triggers escalation
+        const input3 = { tool: "read", sessionID: "s1", callID: "c3", args: {} };
+        const output3 = { title: "read", output: "content3", metadata: {} };
+        await handler(input3, output3);
+        expect(output3.output).toContain("DELEGATION NUDGE");
+        expect(output3.output).toContain("delegate to a specialist agent NOW");
+      });
+    });
+
+    describe("#when grep and glob calls contribute to the count", () => {
+      it("#then counts all exploration tools toward the threshold", async () => {
+        const handler = createPostReadNudgeHandler();
+
+        // Grep call — doesn't append nudge to grep output
+        const grepInput = { tool: "grep", sessionID: "s1", callID: "c1", args: {} };
+        const grepOutput = { title: "grep", output: "grep results", metadata: {} };
+        await handler(grepInput, grepOutput);
+        expect(grepOutput.output).toBe("grep results");
+
+        // Glob call — doesn't append nudge to glob output
+        const globInput = { tool: "glob", sessionID: "s1", callID: "c2", args: {} };
+        const globOutput = { title: "glob", output: "glob results", metadata: {} };
+        await handler(globInput, globOutput);
+        expect(globOutput.output).toBe("glob results");
+
+        // Third exploration call is a read — should trigger escalation
+        const readInput = { tool: "read", sessionID: "s1", callID: "c3", args: {} };
+        const readOutput = { title: "read", output: "file content", metadata: {} };
+        await handler(readInput, readOutput);
+        expect(readOutput.output).toContain("DELEGATION NUDGE");
+      });
+    });
+  });
 });

package/src/hooks/post-read-nudge/handler.ts

@@ -1,10 +1,19 @@
 import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
 
 type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
 
 export const POST_READ_NUDGE =
   "\n\n---\nWorkflow Reminder: delegate based on rules; if mentioning a specialist, launch it in this same turn.";
 
+const DELEGATION_NUDGE_THRESHOLD = 3;
+
+export const DELEGATION_ESCALATION_NUDGE =
+  "\n\n---\n[DELEGATION NUDGE] You have made multiple exploration calls without delegating. " +
+  "Stop reading files and delegate to a specialist agent NOW. " +
+  "Each read compounds context bloat from AGENTS.md injection. " +
+  "Use explorer for codebase discovery or deep-worker for thorough analysis.";
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
@@ -13,16 +22,43 @@ function isReadTool(tool: string): boolean {
   return tool.toLowerCase() === "read";
 }
 
+function isExplorationTool(tool: string): boolean {
+  const name = tool.toLowerCase();
+  return name === "read" || name === "grep" || name === "glob";
+}
+
 export function createPostReadNudgeHandler(): PostToolUseHook {
+  // Track exploration call count to escalate delegation nudges.
+  // Resets when the handler is recreated (new session).
+  let explorationCallCount = 0;
+
   return async (input: unknown, output: unknown) => {
     if (!isRecord(input) || !isRecord(output)) return;
 
     const tool = input.tool;
     const text = output.output;
     if (typeof tool !== "string" || typeof text !== "string") return;
+
+    // Count all exploration tool calls (read, grep, glob)
+    if (isExplorationTool(tool)) {
+      explorationCallCount++;
+    }
+
+    // Only append nudges to read tool outputs
     if (!isReadTool(tool)) return;
     if (text.includes(POST_READ_NUDGE.trim())) return;
 
+    // After threshold, escalate to a stronger delegation nudge
+    if (explorationCallCount >= DELEGATION_NUDGE_THRESHOLD) {
+      if (!text.includes(DELEGATION_ESCALATION_NUDGE.trim())) {
+        output.output = `${text}${DELEGATION_ESCALATION_NUDGE}`;
+        log("[post-read-nudge] escalated to delegation nudge", {
+          explorationCallCount,
+        });
+      }
+      return;
+    }
+
     output.output = `${text}${POST_READ_NUDGE}`;
   };
 }

package/src/hooks/post-read-nudge/index.ts

@@ -1,2 +1,6 @@
-export { createPostReadNudgeHandler, POST_READ_NUDGE } from "./handler";
+export {
+  createPostReadNudgeHandler,
+  POST_READ_NUDGE,
+  DELEGATION_ESCALATION_NUDGE,
+} from "./handler";
 export { postReadNudgePlugin } from "./plugin";

package/src/tools/delegate-task/handler.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition } from "@opencode-ai/plugin";
 import type { BackgroundAgentManager } from "../../runtime";
+import type { OpenCodeContext } from "../../types/plugin";
 import type { TaskInput, CategoryConfig } from "./types";
 import type { ExecutorDeps } from "./executor";
 import { z } from "zod";
@@ -24,7 +25,39 @@ const taskArgsSchema = z.object({
   session_id: z.string().optional().describe("Resume an existing session"),
 });
 
-export function createTaskTool(getManager: () => BackgroundAgentManager): ToolDefinition {
+/**
+ * Resolve the OpenCode client, trying the tool context first then
+ * falling back to the stored plugin-level context.
+ *
+ * OpenCode's plugin runtime does not always expose `client` on the
+ * tool execution context. The plugin-level context (captured at setup)
+ * is a reliable fallback.
+ */
+function resolveClient(
+  toolContext: Parameters<ToolDefinition["execute"]>[1],
+  getStoredContext: () => OpenCodeContext | undefined,
+): OpenCodeContext["client"] {
+  // Try tool context first (works if OpenCode exposes client there)
+  try {
+    return getClientFromToolContext(toolContext);
+  } catch {
+    // Fall back to stored plugin-level context
+    const stored = getStoredContext();
+    if (stored?.client) {
+      return stored.client;
+    }
+    throw new Error(
+      "OpenCode client unavailable. Neither the tool context nor the plugin context expose it.",
+    );
+  }
+}
+
+export function createTaskTool(
+  getManager: () => BackgroundAgentManager,
+  getStoredContext?: () => OpenCodeContext | undefined,
+): ToolDefinition {
+  const contextGetter = getStoredContext ?? (() => undefined);
+
   return buildTool({
     description: [
       "Delegate a task to a category-based agent.",
@@ -50,7 +83,7 @@ export function createTaskTool(getManager: () => BackgroundAgentManager): ToolDe
         return `Unknown category: "${input.category}". Available: ${available}`;
       }
 
-      const client = getClientFromToolContext(toolContext);
+      const client = resolveClient(toolContext, contextGetter);
       const manager = getManager();
       const deps: ExecutorDeps = {
         manager,

package/src/tools/delegate-task/plugin.ts

@@ -1,3 +1,4 @@
+import type { OpenCodeContext } from "../../types/plugin";
 import { definePlugin } from "../../plugin-api/define-plugin";
 import { getBackgroundAgent, initBackgroundAgent, resetBackgroundAgent } from "../../runtime";
 import { createTaskTool } from "./handler";
@@ -6,16 +7,24 @@ function getManagerOrThrow() {
   return getBackgroundAgent().manager;
 }
 
+let storedContext: OpenCodeContext | undefined;
+
+export function getDelegateTaskContext(): OpenCodeContext | undefined {
+  return storedContext;
+}
+
 export default definePlugin({
   name: "delegate-task",
   version: "1.0.0",
-  setup() {
+  setup(ctx) {
+    storedContext = ctx;
     initBackgroundAgent();
   },
   teardown() {
+    storedContext = undefined;
     resetBackgroundAgent();
   },
   tools: {
-    task: createTaskTool(getManagerOrThrow),
+    task: createTaskTool(getManagerOrThrow, () => storedContext),
   },
 });