Prove the family emphasis reaches the declared tools

Prove the family emphasis reaches the declared tools

An integration test pins ThreadReplySource.toolDefinitions() carrying
the gemini-family emphasis, the resolver tests cover more model names
and the unlisted-tool case, and the gemini shell emphasis gains
general ranged-read guidance: read only the region needed, prefer
offset/limit ranged reads over whole-file dumps. General efficiency
language only — nothing task- or benchmark-specific (issue #36).

Built by a Devin child through the openagents coder's delegate tool;
tests re-run before landing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GoYpb8FEmdxVErsv7ABCYi

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GoYpb8FEmdxVErsv7ABCYi

Deploy story

What this commit did to the running system — joined from the forge receipt chain, the part a commit page elsewhere cannot show.

Not deployed through the forge lane

No push, promotion, build, or deploy receipt references this commit (receipts are scanned over a bounded recent window). Changes shipped by full node replacement carry their proof in the release gate receipt instead.

Changed files

modified packages/openagents-cli/src/coder-tool-families.ts
modified packages/openagents-cli/test/coder-thread.test.ts
modified packages/openagents-cli/test/coder-tool-families.test.ts

Diff

3 files changed, +35 -3

      " IMPORTANT: batch independent commands into ONE call joined with && — " +
      "each separate call replays the whole conversation to the model, so ten " +
      "one-line calls cost several times what one composite call costs. Never " +
      "run one small inspection per call.",
      "run one small inspection per call. Read only the region you need; prefer " +
      "offset/limit ranged reads or summaries over whole-file dumps, which are " +
      "token-inefficient.",
  },
  local: {
    shell:

import { afterEach, describe, expect, it, vi } from "vitest";

import type { ReplyChunk } from "../src/coder-session.js";
import { openThread, resolveProxyUrl, ThreadUnavailable, type ThreadReplySource } from "../src/coder-thread.js";
import { openThread, resolveProxyUrl, ThreadReplySource, ThreadUnavailable } from "../src/coder-thread.js";
import { Redacted } from "effect";
import { shellTool } from "../src/coder-tools.js";
import { ThreadTranscriptWriter } from "../src/coder-transcript.js";

const ORIGIN = "https://openagents.test";

  });
});

describe("ThreadReplySource toolDefinitions", () => {
  it("carries the gemini family emphasis on the shell tool", () => {
    const source = new ThreadReplySource({
      origin: ORIGIN,
      accountToken: ACCOUNT_TOKEN,
      threadId: THREAD_ID,
      grantToken: Redacted.make(GRANT_TOKEN),
      proxyUrl: `${ORIGIN}/api/inference/proxy`,
      model: "gemini-3.7-flash",
      budget: { calls: 256, totalTokens: 1_000_000, costMicrousd: 2_000_000 },
    });
    source.useTools([shellTool(process.cwd())]);

    const defs = source.toolDefinitions() as ReadonlyArray<{
      function: { name: string; description: string };
    }>;
    const shell = defs.find((tool) => tool.function.name === "shell");
    expect(shell).toBeDefined();
    expect(shell?.function.description).toContain("batch independent commands into ONE call");
    expect(shell?.function.description).toContain("offset/limit ranged reads");
  });
});

describe("resolveProxyUrl", () => {
  it("resolves the grant's path against the client's origin", () => {
    expect(

describe("toolFamilyOf", () => {
  it("names the gemini family by model prefix", () => {
    expect(toolFamilyOf("gemini-3.7-flash")).toBe("gemini");
    expect(toolFamilyOf("gemini-2.0-flash")).toBe("gemini");
    expect(toolFamilyOf("gemini-3.5-flash")).toBe("gemini");
  });


  it("defaults everything else, including absence", () => {
    expect(toolFamilyOf("gpt-5.6-luna")).toBe("default");
    expect(toolFamilyOf("ox-alpha")).toBe("default");
    expect(toolFamilyOf("claude-3-5-sonnet")).toBe("default");
    expect(toolFamilyOf(undefined)).toBe("default");
  });
});

describe("declaredDescription", () => {
  it("adds batching emphasis to shell for the gemini family", () => {
  it("adds batching and ranged-read emphasis to shell for the gemini family", () => {
    const declared = declaredDescription(tool("shell"), "gemini");
    expect(declared.startsWith("Base description.")).toBe(true);
    expect(declared).toContain("batch independent commands into ONE call");
    expect(declared).toContain("offset/limit ranged reads");
  });

  it("adds the latency emphasis to shell for the local family", () => {

  it("leaves the default family and unlisted tools at the base", () => {
    expect(declaredDescription(tool("shell"), "default")).toBe("Base description.");
    expect(declaredDescription(tool("skill"), "gemini")).toBe("Base description.");
    expect(declaredDescription(tool("unknown_tool"), "gemini")).toBe("Base description.");
    expect(declaredDescription(tool("shell"), "gemini")).not.toBe("Base description.");
  });
});

50	50		`" IMPORTANT: batch independent commands into ONE call joined with && — " +`
51	51		`"each separate call replays the whole conversation to the model, so ten " +`
52	52		`"one-line calls cost several times what one composite call costs. Never " +`
53		-	`"run one small inspection per call.",`
	53	+	`"run one small inspection per call. Read only the region you need; prefer " +`
	54	+	`"offset/limit ranged reads or summaries over whole-file dumps, which are " +`
	55	+	`"token-inefficient.",`
54	56		`},`
55	57		`local: {`
56	58		`shell:`

1	1		`import { afterEach, describe, expect, it, vi } from "vitest";`
2	2
3	3		`import type { ReplyChunk } from "../src/coder-session.js";`
4		-	`import { openThread, resolveProxyUrl, ThreadUnavailable, type ThreadReplySource } from "../src/coder-thread.js";`
	4	+	`import { openThread, resolveProxyUrl, ThreadReplySource, ThreadUnavailable } from "../src/coder-thread.js";`
	5	+	`import { Redacted } from "effect";`
	6	+	`import { shellTool } from "../src/coder-tools.js";`
5	7		`import { ThreadTranscriptWriter } from "../src/coder-transcript.js";`
6	8
7	9		`const ORIGIN = "https://openagents.test";`

1044	1046		`});`
1045	1047		`});`
1046	1048
	1049	+	`describe("ThreadReplySource toolDefinitions", () => {`
	1050	+	`it("carries the gemini family emphasis on the shell tool", () => {`
	1051	+	`const source = new ThreadReplySource({`
	1052	+	`origin: ORIGIN,`
	1053	+	`accountToken: ACCOUNT_TOKEN,`
	1054	+	`threadId: THREAD_ID,`
	1055	+	`grantToken: Redacted.make(GRANT_TOKEN),`
	1056	+	proxyUrl: `${ORIGIN}/api/inference/proxy`,
	1057	+	`model: "gemini-3.7-flash",`
	1058	+	`budget: { calls: 256, totalTokens: 1_000_000, costMicrousd: 2_000_000 },`
	1059	+	`});`
	1060	+	`source.useTools([shellTool(process.cwd())]);`
	1061	+
	1062	+	`const defs = source.toolDefinitions() as ReadonlyArray<{`
	1063	+	`function: { name: string; description: string };`
	1064	+	`}>;`
	1065	+	`const shell = defs.find((tool) => tool.function.name === "shell");`
	1066	+	`expect(shell).toBeDefined();`
	1067	+	`expect(shell?.function.description).toContain("batch independent commands into ONE call");`
	1068	+	`expect(shell?.function.description).toContain("offset/limit ranged reads");`
	1069	+	`});`
	1070	+	`});`
	1071	+
1047	1072		`describe("resolveProxyUrl", () => {`
1048	1073		`it("resolves the grant's path against the client's origin", () => {`
1049	1074		`expect(`

13	13		`describe("toolFamilyOf", () => {`
14	14		`it("names the gemini family by model prefix", () => {`
15	15		`expect(toolFamilyOf("gemini-3.7-flash")).toBe("gemini");`
	16	+	`expect(toolFamilyOf("gemini-2.0-flash")).toBe("gemini");`
16	17		`expect(toolFamilyOf("gemini-3.5-flash")).toBe("gemini");`
17	18		`});`
18	19

23	24		`it("defaults everything else, including absence", () => {`
24	25		`expect(toolFamilyOf("gpt-5.6-luna")).toBe("default");`
25	26		`expect(toolFamilyOf("ox-alpha")).toBe("default");`
	27	+	`expect(toolFamilyOf("claude-3-5-sonnet")).toBe("default");`
26	28		`expect(toolFamilyOf(undefined)).toBe("default");`
27	29		`});`
28	30		`});`
29	31
30	32		`describe("declaredDescription", () => {`
31		-	`it("adds batching emphasis to shell for the gemini family", () => {`
	33	+	`it("adds batching and ranged-read emphasis to shell for the gemini family", () => {`
32	34		`const declared = declaredDescription(tool("shell"), "gemini");`
33	35		`expect(declared.startsWith("Base description.")).toBe(true);`
34	36		`expect(declared).toContain("batch independent commands into ONE call");`
	37	+	`expect(declared).toContain("offset/limit ranged reads");`
35	38		`});`
36	39
37	40		`it("adds the latency emphasis to shell for the local family", () => {`

41	44		`it("leaves the default family and unlisted tools at the base", () => {`
42	45		`expect(declaredDescription(tool("shell"), "default")).toBe("Base description.");`
43	46		`expect(declaredDescription(tool("skill"), "gemini")).toBe("Base description.");`
	47	+	`expect(declaredDescription(tool("unknown_tool"), "gemini")).toBe("Base description.");`
	48	+	`expect(declaredDescription(tool("shell"), "gemini")).not.toBe("Base description.");`
44	49		`});`
45	50		`});`