refactor(mcp-server): move task_foraging_report to foraging.ts

.changeset/move-task-foraging-report-to-foraging.md

@@ -0,0 +1,15 @@
+---
+'@colony/mcp-server': patch
+---
+
+Move `task_foraging_report` source location from `attention.ts` to `foraging.ts`
+
+The tool is part of the foraging surface (it wraps `ProposalSystem.foragingReport`
+and is conceptually paired with `examples_list` / `examples_query`), not the
+attention-inbox surface. It only lived in `attention.ts` as an accident of the
+pre-split monolithic `server.ts`.
+
+Pure code-location refactor. The MCP tool name, description, input schema, and
+handler body are byte-identical. `server.ts` registers it at the same call-site
+slot via a new `registerTaskForagingReport` named export, so the `listTools`
+ordering observed by inspectors stays unchanged.

apps/mcp-server/src/server.ts

@@ -13,6 +13,7 @@ import * as bridge from './tools/bridge.js';
 import type { ToolContext } from './tools/context.js';
 import * as drift from './tools/drift.js';
 import * as foraging from './tools/foraging.js';
+import { registerTaskForagingReport } from './tools/foraging.js';
 import * as handoff from './tools/handoff.js';
 import { createHeartbeatWrapper, installActiveSessionHeartbeat } from './tools/heartbeat.js';
 import * as hivemind from './tools/hivemind.js';
@@ -103,6 +104,10 @@ export function buildServer(
   proposal.register(server, ctx);
   profile.register(server, ctx);
   attention.register(server, ctx);
+  // task_foraging_report lives in foraging.ts (foraging surface) but stays in
+  // the slot it occupied when it was bundled inside attention.ts, so the
+  // listTools ordering above does not shift.
+  registerTaskForagingReport(server, ctx);
   bridge.register(server, ctx);
   message.register(server, ctx);
   relay.register(server, ctx);

apps/mcp-server/src/tools/attention.ts

@@ -1,4 +1,4 @@
-import { type AttentionInboxOptions, ProposalSystem, buildAttentionInbox } from '@colony/core';
+import { type AttentionInboxOptions, buildAttentionInbox } from '@colony/core';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { type ToolContext, defaultWrapHandler } from './context.js';
@@ -89,18 +89,4 @@ export function register(server: McpServer, ctx: ToolContext): void {
       return { content: [{ type: 'text', text: JSON.stringify(compact) }] };
     }),
   );
-
-  server.tool(
-    'task_foraging_report',
-    'Find proposed work on this repo branch before picking tasks. Lists pending proposals, promoted work, strength, and expired weak signals omitted.',
-    {
-      repo_root: z.string().min(1),
-      branch: z.string().min(1),
-    },
-    wrapHandler('task_foraging_report', async ({ repo_root, branch }) => {
-      const proposals = new ProposalSystem(store);
-      const report = proposals.foragingReport(repo_root, branch);
-      return { content: [{ type: 'text', text: JSON.stringify(report) }] };
-    }),
-  );
 }

apps/mcp-server/src/tools/foraging.ts

@@ -1,3 +1,4 @@
+import { ProposalSystem } from '@colony/core';
 import { buildIntegrationPlan, expandForagingConceptQuery } from '@colony/foraging';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
@@ -76,6 +77,28 @@ export function register(server: McpServer, ctx: ToolContext): void {
   );
 }
 
+// Registered separately from the examples_* surface so server.ts can keep
+// task_foraging_report in the slot it occupied before the attention.ts split,
+// preserving the MCP inspector / snapshot ordering noted in server.ts.
+export function registerTaskForagingReport(server: McpServer, ctx: ToolContext): void {
+  const wrapHandler = ctx.wrapHandler ?? defaultWrapHandler;
+  const { store } = ctx;
+
+  server.tool(
+    'task_foraging_report',
+    'Find proposed work on this repo branch before picking tasks. Lists pending proposals, promoted work, strength, and expired weak signals omitted.',
+    {
+      repo_root: z.string().min(1),
+      branch: z.string().min(1),
+    },
+    wrapHandler('task_foraging_report', async ({ repo_root, branch }) => {
+      const proposals = new ProposalSystem(store);
+      const report = proposals.foragingReport(repo_root, branch);
+      return { content: [{ type: 'text', text: JSON.stringify(report) }] };
+    }),
+  );
+}
+
 export function expandForagingQuery(query: string): string {
   return expandForagingConceptQuery(query);
 }

openspec/changes/agent-claude-move-task-foraging-report-to-foraging-ts-2026-05-14-21-12/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-14

openspec/changes/agent-claude-move-task-foraging-report-to-foraging-ts-2026-05-14-21-12/notes.md

@@ -0,0 +1,20 @@
+# agent-claude-move-task-foraging-report-to-foraging-ts-2026-05-14-21-12 (minimal / T1)
+
+Branch: `agent/claude/move-task-foraging-report-to-foraging-ts-2026-05-14-21-12`
+
+Move `task_foraging_report` from `apps/mcp-server/src/tools/attention.ts` to
+`apps/mcp-server/src/tools/foraging.ts` (where it belongs alongside
+`examples_list` / `examples_query` / `examples_integrate_plan`). Pure code-
+location refactor: same MCP tool name, description, schema, handler body.
+`server.ts` calls a new `registerTaskForagingReport` named export at
+attention's old slot, so `listTools` ordering is preserved.
+
+## Handoff
+
+- Handoff: change=`agent-claude-move-task-foraging-report-to-foraging-ts-2026-05-14-21-12`; branch=`agent/claude/move-task-foraging-report-to-foraging-ts-2026-05-14-21-12`; scope=`apps/mcp-server only`; action=`finish via PR after user sign-off on the local diff`.
+
+## Cleanup
+
+- [ ] Run: `gx branch finish --branch agent/claude/move-task-foraging-report-to-foraging-ts-2026-05-14-21-12 --base main --via-pr --wait-for-merge --cleanup`
+- [ ] Record PR URL + `MERGED` state in the completion handoff.
+- [ ] Confirm sandbox worktree is gone (`git worktree list`, `git branch -a`).