forge-delegate 1.0.3 → 1.0.4

package/README.md

@@ -91,16 +91,16 @@ rate-limited; switch anytime with `forge-delegate config set --model <m>`.
 | Tool | What it does | Context cost |
 |---|---|---|
 | `ask_model` | One-shot question to any model (direct API, no file access) | Small |
-| `delegate` | Model works **autonomously** in the **background** (recommended) — returns a job id instantly; poll `check_delegation` | Tiny |
-| `delegate_sync` | Send a task + optional files to a model agent running via opencode; returns the result inline in your context | Medium |
+| `delegate` | Model works **autonomously** via opencode's own tool loop — inline by default; `background:true` returns a job id to poll via `check_delegation` | Tiny→Medium |
 | `check_delegation` | Poll a background job (or list all with no id) | Tiny |
 | `list_models` | List local/keyless, direct-API, and agentic models | Small |
 | `get_delegate_config` | Read current configuration (default model, directory, autoApprove, profiles) | Tiny |
 | `set_delegate_config` | Change configuration at runtime — no reinstall | Tiny |
 
 `delegate` is the token-saver: the external model gets its own tool loop executed by
-opencode locally. File contents never touch your main agent's context. The delegation runs as a
-detached background process, so the MCP call returns instantly.
+opencode locally. File contents never touch your main agent's context. Fast tasks return
+inline; long ones are auto-backgrounded by Claude Code (past ~2 min) or run detached with
+`background:true` — so the delegation never blocks your session.
 
 ## When to delegate
 

package/docs/DELEGATION.md

@@ -30,8 +30,8 @@ Unsure → keep it.
 | Need | Tool |
 |---|---|
 | Quick one-shot question, no file access needed | `ask_model` |
-| A self-contained task with concrete code output, inline | `delegate_sync` |
-| Autonomous multi-file work, don't want to block (recommended) | `delegate` + `check_delegation` |
+| A self-contained coding task (inline; auto-backgrounds past ~2 min in Claude Code) | `delegate` |
+| Parallel fan-out or fire-and-forget | `delegate` with `background:true` + `check_delegation` |
 | See what's available | `list_models` |
 
 ## Cost policy (non-negotiable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-delegate",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "MCP server that relays coding work to other AI models (DeepSeek, Gemini, OpenAI, Ollama) so Claude Code saves tokens",
   "type": "module",
   "bin": {

package/server.mjs

@@ -28,12 +28,12 @@ const RUNS_DIR = join(homedir(), ".forge-delegate", "runs");
 const INSTRUCTIONS = `forge-delegate gives you a crew of external AI models to delegate coding work to. Hand off the high-volume, low-risk work (boilerplate, tests, lint/type fixes, mechanical edits) to a cheap or free model and keep the expensive agent focused on architecture and judgment calls.
 
 COST POLICY — MANDATORY, NON-NEGOTIABLE:
-The user pays per delegated call on a budget plan. You MUST pick only cheap or free models for EVERY delegation (ask_model, delegate_sync, delegate). NEVER pick top-tier, premium, flagship, or frontier models — not even "just this once" or for hard tasks. If a task seems too hard for a cheap model, split it into smaller delegated steps instead of upgrading. Run list_models and prefer free/cheap models (deepseek flash tiers, free opencode models, local ollama).
+The user pays per delegated call on a budget plan. You MUST pick only cheap or free models for EVERY delegation (ask_model, delegate). NEVER pick top-tier, premium, flagship, or frontier models — not even "just this once" or for hard tasks. If a task seems too hard for a cheap model, split it into smaller delegated steps instead of upgrading. Run list_models and prefer free/cheap models (deepseek flash tiers, free opencode models, local ollama).
 
 Routing:
 - Quick one-shot questions → ask_model (direct API, no file access).
-- Multi-file edits/refactors/tests → delegate (background, recommended) or delegate_sync (inline).
-- delegate returns a job id instantly; poll check_delegation for the result.
+- Multi-file edits/refactors/tests → delegate (inline by default; Claude Code auto-backgrounds calls past 2 min).
+- Parallel or fire-and-forget → delegate with background:true (returns a job id instantly); poll check_delegation for the result.
 - Follow-ups on a delegated area: pass the returned session id as continue_session.
 - Omit model/directory to use the configured defaults (get_delegate_config); change them anytime with set_delegate_config — never reinstall.
 - Never paste large files into your own context for delegation — delegate and let the agent read files itself.
@@ -120,7 +120,7 @@ server.tool(
 
 server.tool(
   "ask_model",
-  "Send a one-shot prompt to an external AI model and get its raw response. Fast direct API call; the model has NO file access and CANNOT take actions. For work requiring tools/files use delegate (background) or delegate_sync (inline) instead. model defaults to the configured defaultModel.",
+  "Send a one-shot prompt to an external AI model and get its raw response. Fast direct API call; the model has NO file access and CANNOT take actions. For work requiring tools/files use delegate instead. model defaults to the configured defaultModel.",
   {
     model: z.string().optional().describe("provider/model, e.g. deepseek/deepseek-v4-flash, ollama:llama3 (defaults to config defaultModel)"),
     prompt: z.string(),
@@ -136,21 +136,34 @@ server.tool(
 );
 
 server.tool(
-  "delegate_sync",
-  "Delegate a coding task to another AI model running as a full agent (via local opencode): it can read your project and answer with concrete code. Runs INLINE (foreground) — the result is returned in your context when done. Prefer `delegate` (background) to keep your context small. Optionally attach specific files. model/directory/agent/autoApprove default from config.",
+  "delegate",
+  "Delegate a coding task to another AI model running as a full agent (via local opencode): it reads your project, explores, and writes concrete code in its own tool loop — invisible to the caller's context. Runs INLINE by default (the result is returned in your context when done; Claude Code auto-backgrounds calls running past 2 minutes). Pass background:true to run detached and return a job id instantly, then poll check_delegation for the result — use that for parallel fan-out or hosts that block on long calls. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Optionally attach specific files in inline mode. model/directory/agent/autoApprove default from config.",
   {
     model: z.string().optional().describe("provider/model format, e.g. opencode/mimo-v2.5-free (defaults to config defaultModel)"),
     task: z.string(),
-    files: z.array(z.string()).optional(),
+    files: z.array(z.string()).optional().describe("specific files to attach (inline mode)"),
+    background: z.boolean().optional().describe("run detached and return a job id (default false)"),
+    continue_session: z.string().optional().describe("session id returned by a previous delegation"),
     directory: z.string().optional().describe("absolute path to run in (defaults to config defaultDirectory, else server cwd)"),
     agent: z.string().optional().describe("opencode agent to use (defaults to config defaultAgent)"),
     autoApprove: z.boolean().optional().describe("auto-approve permissions (defaults to config autoApprove, true)"),
     profile: z.string().optional().describe("named config profile to apply"),
   },
-  async ({ model, task, files, directory, agent, autoApprove, profile }) => {
+  async ({ model, task, files, background, continue_session, directory, agent, autoApprove, profile }) => {
     const r = resolveConfig({ model, directory, agent, autoApprove, profile });
     if (!r.model) return { content: [{ type: "text", text: "ERROR: no model specified and no defaultModel configured. Call set_delegate_config or pass model." }], isError: true };
-    return withUsage("delegate_sync", r.model, async () => {
+    if (background) {
+      return withUsage("delegate", r.model, async () => {
+        const id = await startBackgroundJob(r.model, task, {
+          sessionId: continue_session,
+          directory: r.directory,
+          agent: r.agent,
+          autoApprove: r.autoApprove,
+        });
+        return `Started background job ${id}. Poll with check_delegation(id: "${id}").`;
+      });
+    }
+    return withUsage("delegate", r.model, async () => {
       const res = await opencodeRun(r.model, task, {
         files,
         directory: r.directory,
@@ -163,33 +176,6 @@ server.tool(
   }
 );
 
-server.tool(
-  "delegate",
-  "Fully delegate a coding task to another AI model working autonomously on this project (via local opencode): it explores, reads, edits and creates files in its own loop — invisible to the caller's context. Runs in the BACKGROUND (recommended): returns a job id instantly, poll check_delegation for the result. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Use this over delegate_sync to keep the caller's context small. model/directory/agent/autoApprove default from config.",
-  {
-    model: z.string().optional().describe("provider/model format, e.g. opencode/mimo-v2.5-free (defaults to config defaultModel)"),
-    task: z.string(),
-    continue_session: z.string().optional().describe("session id returned by a previous delegation"),
-    directory: z.string().optional().describe("absolute path to run in (defaults to config defaultDirectory, else server cwd)"),
-    agent: z.string().optional().describe("opencode agent to use (defaults to config defaultAgent)"),
-    autoApprove: z.boolean().optional().describe("auto-approve permissions (defaults to config autoApprove, true)"),
-    profile: z.string().optional().describe("named config profile to apply"),
-  },
-  async ({ model, task, continue_session, directory, agent, autoApprove, profile }) => {
-    const r = resolveConfig({ model, directory, agent, autoApprove, profile });
-    if (!r.model) return { content: [{ type: "text", text: "ERROR: no model specified and no defaultModel configured. Call set_delegate_config or pass model." }], isError: true };
-    return withUsage("delegate", r.model, async () => {
-      const id = await startBackgroundJob(r.model, task, {
-        sessionId: continue_session,
-        directory: r.directory,
-        agent: r.agent,
-        autoApprove: r.autoApprove,
-      });
-      return `Started background job ${id}. Poll with check_delegation(id: "${id}").`;
-    });
-  }
-);
-
 server.tool(
   "check_delegation",
   "Check status of a background delegation job: running/completed plus output so far. Call with no id to list all jobs.",