From 34eb4e10a9cf6940059eb419a2d30d1f19d34823 Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Tue, 10 Nov 2026 14:41:10 +0200 Subject: [PATCH 1/8] feat(agents): deny six unused tools for Harden, Polish and Research Harden, Polish and Research start with six tools that none of their paths use. Each start uses tokens for these tools. They now deny Monitor, TaskStop, Workflow, Artifact, ListAgents and ReportFindings, as Code, Fix and Refactor do. - The six names join SHARED_DENYLIST (17 to 23 names). The Code-only extra list is gone. Code, Fix, Refactor and Research deny exactly the list. Harden and Polish add Skill and mcp__*. - The guard loops over every deny-list row and every shared name for the row, body and pin probes. A new check reports an allowlist agent that grants any shared deny name, with its own known-bad probe. - Five size ceilings rise by 85 bytes each: frontmatter deny lines only, no body text. research 5133 to 5218, research (curation off) 4773 to 4858, harden 4806 to 4891, harden (curation off) 4238 to 4323, polish 4495 to 4580. The size guard header states the either-way rule. Task: feat/778-worker-agents-deny-unused-tools Refs #778 --- src/assets/agents/harden.mds | 6 ++ src/assets/agents/polish.md | 6 ++ src/assets/agents/research.mds | 6 ++ tests/fixtures/agent-config.ts | 43 ++++----- tests/fixtures/numeric-floors.json | 30 +++---- tests/guards/agent-config.test.ts | 114 +++++++++++++++--------- tests/guards/other-agents-sizes.test.ts | 14 +-- 7 files changed, 132 insertions(+), 87 deletions(-) diff --git a/src/assets/agents/harden.mds b/src/assets/agents/harden.mds index 39095174..5b542aad 100644 --- a/src/assets/agents/harden.mds +++ b/src/assets/agents/harden.mds @@ -32,6 +32,12 @@ disallowedTools: - RemoteTrigger - PushNotification - DesignSync + - Monitor + - TaskStop + - Workflow + - Artifact + - ListAgents + - ReportFindings - Skill - mcp__* --- diff --git a/src/assets/agents/polish.md b/src/assets/agents/polish.md index a102a526..aabda4b4 100644 --- a/src/assets/agents/polish.md +++ b/src/assets/agents/polish.md @@ -24,6 +24,12 @@ disallowedTools: - RemoteTrigger - PushNotification - DesignSync + - Monitor + - TaskStop + - Workflow + - Artifact + - ListAgents + - ReportFindings - Skill - mcp__* --- diff --git a/src/assets/agents/research.mds b/src/assets/agents/research.mds index 5ae6a7f7..497a0d24 100644 --- a/src/assets/agents/research.mds +++ b/src/assets/agents/research.mds @@ -30,6 +30,12 @@ disallowedTools: - RemoteTrigger - PushNotification - DesignSync + - Monitor + - TaskStop + - Workflow + - Artifact + - ListAgents + - ReportFindings omitClaudeMd: true --- diff --git a/tests/fixtures/agent-config.ts b/tests/fixtures/agent-config.ts index a4164a88..f55309f4 100644 --- a/tests/fixtures/agent-config.ts +++ b/tests/fixtures/agent-config.ts @@ -84,14 +84,22 @@ export interface AgentConfigRow { * `disallowedTools` removes MCP names, and the denylist agents that keep their * user-environment MCP and web access (Code, Fix, Refactor and Research) must not * lose them, so every name is written out. A denied name the runtime does not expose - * is assumed to be a no-op. Git and Tracker are not denylist agents: they hold an - * allowlist and reach their tracker servers through whole-server entries the installer - * stamps (D-GIT-ROW, D-TRACKER-ROW). + * is assumed to be a no-op (verified 2026-11-09, Claude Code 2.1.319). Git and Tracker + * are not denylist agents: they hold an allowlist and reach their tracker servers + * through whole-server entries the installer stamps (D-GIT-ROW, D-TRACKER-ROW). * - * Research denies exactly this list. Code, Fix and Refactor deny it plus - * CODE_FAMILY_DENY_EXTRA. Harden and Polish deny it plus `Skill`, and `mcp__*` as - * their own `extra` (D-SCAN-IN-CODE): the only wildcards a denylist may hold, which - * MCP_DENY_AGENTS names. + * Code, Fix, Refactor and Research deny exactly this list. Harden and Polish deny it plus + * `Skill`, and `mcp__*` as their own `extra` (D-SCAN-IN-CODE): the only wildcards a denylist + * may hold, which MCP_DENY_AGENTS names. + * + * The six names after DesignSync are unused by all six agents, and each start pays tokens for + * every tool it lists. Workflow starts agents and ListAgents finds agents to message; none of + * these agents starts, stops or messages one. TaskStop stops a background run and Monitor waits + * on one; these agents run commands in the foreground (Harden runs one changed test file) or run + * none (Polish). Artifact publishes a page; none of them does. ReportFindings reports review + * findings; Harden reports in its final message and Research writes its findings to OUTPUT_PATH + * with Write. Workflow, TaskStop, ListAgents and Artifact stay members whatever their measured + * cost. */ export const SHARED_DENYLIST: readonly string[] = [ 'Agent', @@ -111,19 +119,6 @@ export const SHARED_DENYLIST: readonly string[] = [ 'RemoteTrigger', 'PushNotification', 'DesignSync', -]; - -/** - * The tools Code, Fix and Refactor deny beyond SHARED_DENYLIST, because no path of these agents - * uses them. Workflow starts agents and ListAgents finds agents to message; these agents start - * and message no agent. TaskStop stops a background run and Monitor waits on one; these agents - * run commands in the foreground. Artifact publishes a page and ReportFindings reports review - * findings; these agents do neither. Workflow and TaskStop are fixed members whatever their - * measured cost. Each name is spelled out, with no wildcard, no `mcp__` name, no WebFetch and no - * WebSearch. A name the runtime does not expose is a no-op (verified 2026-11-09, Claude Code - * 2.1.319). - */ -export const CODE_FAMILY_DENY_EXTRA: readonly string[] = [ 'Monitor', 'TaskStop', 'Workflow', @@ -137,7 +132,7 @@ export const CODE_FAMILY_DENY_EXTRA: readonly string[] = [ * step needs them (today Code, Fix, Refactor and Research). `collectDenylistViolations` reports a * deny of WebFetch, WebSearch or any `mcp__` name for all agents. This set lists the built-in * tools these agents keep, WebFetch and WebSearch included, and no `mcp__` name. No name here is - * on SHARED_DENYLIST or CODE_FAMILY_DENY_EXTRA. + * on SHARED_DENYLIST. */ export const DENY_AGENT_KEEP: readonly string[] = [ 'Bash', @@ -248,7 +243,7 @@ export const AGENT_CONFIG: Readonly> = { code: { model: 'sonnet', effort: 'high', - policy: { kind: 'deny', extra: CODE_FAMILY_DENY_EXTRA }, + policy: { kind: 'deny', extra: [] }, omitClaudeMd: false, skills: null, digest: [], @@ -262,7 +257,7 @@ export const AGENT_CONFIG: Readonly> = { fix: { model: 'sonnet', effort: 'high', - policy: { kind: 'deny', extra: CODE_FAMILY_DENY_EXTRA }, + policy: { kind: 'deny', extra: [] }, omitClaudeMd: false, skills: null, digest: [], @@ -270,7 +265,7 @@ export const AGENT_CONFIG: Readonly> = { refactor: { model: 'sonnet', effort: 'high', - policy: { kind: 'deny', extra: CODE_FAMILY_DENY_EXTRA }, + policy: { kind: 'deny', extra: [] }, omitClaudeMd: false, skills: null, digest: [], diff --git a/tests/fixtures/numeric-floors.json b/tests/fixtures/numeric-floors.json index 592d43ce..3bc12b61 100644 --- a/tests/fixtures/numeric-floors.json +++ b/tests/fixtures/numeric-floors.json @@ -1334,19 +1334,19 @@ }, { "id": "research-body-max", - "ceiling": 5133, - "pattern": "['research', 'on', 5_133],", + "ceiling": 5218, + "pattern": "['research', 'on', 5_218],", "occurrences": 1, "sourceFile": "tests/guards/other-agents-sizes.test.ts", - "description": "The Research agent body of the curation-on build, dist/agents/research.md, in bytes. Every turn of every Research spawn reads it (opus, two to five spawns per /research run). Added by #718 (lean other targets) at 5,184, after the cut from 6,300. Lowered by #706 (lean descriptions, the rest) to 5133." + "description": "The Research agent body of the curation-on build, dist/agents/research.md, in bytes. Every turn of every Research spawn reads it (opus, two to five spawns per /research run). Added by #718 (lean other targets) at 5,184, after the cut from 6,300. Lowered by #706 (lean descriptions, the rest) to 5133. Raised by #778 from 5133 to 5218, the measured size with no headroom: six frontmatter deny lines, no body text." }, { "id": "research-body-curation-off-max", - "ceiling": 4773, - "pattern": "['research', 'off', 4_773],", + "ceiling": 4858, + "pattern": "['research', 'off', 4_858],", "occurrences": 1, "sourceFile": "tests/guards/other-agents-sizes.test.ts", - "description": "The Research agent body of the curation-off build, dist/curation-off/agents/research.md, in bytes. Added by #718 (lean other targets) at 4,824, after the cut from 5,794. Lowered by #706 (lean descriptions, the rest) to 4773." + "description": "The Research agent body of the curation-off build, dist/curation-off/agents/research.md, in bytes. Added by #718 (lean other targets) at 4,824, after the cut from 5,794. Lowered by #706 (lean descriptions, the rest) to 4773. Raised by #778 from 4773 to 4858, the measured size with no headroom: six frontmatter deny lines, no body text, with the curation-on build." }, { "id": "evaluate-body-max", @@ -1406,27 +1406,27 @@ }, { "id": "harden-body-max", - "ceiling": 4806, - "pattern": "['harden', 'on', 4_806],", + "ceiling": 4891, + "pattern": "['harden', 'on', 4_891],", "occurrences": 1, "sourceFile": "tests/guards/other-agents-sizes.test.ts", - "description": "The Harden agent body of the curation-on build, dist/agents/harden.md, in bytes. Every turn of every Harden spawn reads it (opus; /implement and /self-review spawn it). Added at its measured 5,047 so that it can not grow back. Lowered by #706 (lean always-loaded descriptions) to 5011, and by #756 (lean plans) to 4998: the missing-test rule names the acceptance-criterion and never-cut paths, and cuts in the same body paid for it. Lowered to 4940 when the missing-test rule gained the fallback of each behaviour the diff adds; two restated lines of the same body paid for it with room left. Lowered to 4931 for #756 when the body gained the ACCEPTANCE_CRITERIA and KNOWN_LIMITS input line with its never-cut clause: the pillar names the output template lists again, the honest-assessment principle that the BLOCKED rules state, the commit message the commit step states and the sentence that caps the two narrative output lists paid for it. Lowered to 4806 by #756, the measured size with no headroom: the Output section lost its Workflow return pin and the status return field." + "description": "The Harden agent body of the curation-on build, dist/agents/harden.md, in bytes. Every turn of every Harden spawn reads it (opus; /implement and /self-review spawn it). Added at its measured 5,047 so that it can not grow back. Lowered by #706 (lean always-loaded descriptions) to 5011, and by #756 (lean plans) to 4998: the missing-test rule names the acceptance-criterion and never-cut paths, and cuts in the same body paid for it. Lowered to 4940 when the missing-test rule gained the fallback of each behaviour the diff adds; two restated lines of the same body paid for it with room left. Lowered to 4931 for #756 when the body gained the ACCEPTANCE_CRITERIA and KNOWN_LIMITS input line with its never-cut clause: the pillar names the output template lists again, the honest-assessment principle that the BLOCKED rules state, the commit message the commit step states and the sentence that caps the two narrative output lists paid for it. Lowered to 4806 by #756, the measured size with no headroom: the Output section lost its Workflow return pin and the status return field. Raised by #778 from 4806 to 4891, the measured size with no headroom: six frontmatter deny lines, no body text." }, { "id": "harden-body-curation-off-max", - "ceiling": 4238, - "pattern": "['harden', 'off', 4_238],", + "ceiling": 4323, + "pattern": "['harden', 'off', 4_323],", "occurrences": 1, "sourceFile": "tests/guards/other-agents-sizes.test.ts", - "description": "The Harden agent body of the curation-off build, dist/curation-off/agents/harden.md, in bytes. Added at its measured 4,479 so that it can not grow back. Lowered by #706 (lean always-loaded descriptions) to 4443, and by #756 (lean plans) to 4430, with the curation-on build. Lowered to 4372 with the curation-on build. Lowered to 4363 with the curation-on build for #756. Lowered to 4238 by #756 with the curation-on build." + "description": "The Harden agent body of the curation-off build, dist/curation-off/agents/harden.md, in bytes. Added at its measured 4,479 so that it can not grow back. Lowered by #706 (lean always-loaded descriptions) to 4443, and by #756 (lean plans) to 4430, with the curation-on build. Lowered to 4372 with the curation-on build. Lowered to 4363 with the curation-on build for #756. Lowered to 4238 by #756 with the curation-on build. Raised by #778 from 4238 to 4323, the measured size with no headroom: six frontmatter deny lines, no body text, with the curation-on build." }, { "id": "polish-body-max", - "ceiling": 4495, - "pattern": "['polish', 'on', 4_495],", + "ceiling": 4580, + "pattern": "['polish', 'on', 4_580],", "occurrences": 1, "sourceFile": "tests/guards/other-agents-sizes.test.ts", - "description": "The Polish agent body, src/assets/agents/polish.md, in bytes. It is hand-authored, with one build. Every turn of every Polish spawn reads it (sonnet; /implement, /resolve and /self-review spawn it). Added at its measured 4,537 so that it can not grow back. Lowered by #706 (lean always-loaded descriptions) to 4495." + "description": "The Polish agent body, src/assets/agents/polish.md, in bytes. It is hand-authored, with one build. Every turn of every Polish spawn reads it (sonnet; /implement, /resolve and /self-review spawn it). Added at its measured 4,537 so that it can not grow back. Lowered by #706 (lean always-loaded descriptions) to 4495. Raised by #778 from 4495 to 4580, the measured size with no headroom: six frontmatter deny lines, no body text." } ] } diff --git a/tests/guards/agent-config.test.ts b/tests/guards/agent-config.test.ts index eb220f7a..07818c5c 100644 --- a/tests/guards/agent-config.test.ts +++ b/tests/guards/agent-config.test.ts @@ -70,7 +70,6 @@ import { CODE_AGENT_TYPES, ROOT, codeSlugOf, resolveAgentSource, splitFrontmatte import { loadShippedAgentDefaults } from '../../src/core/agent-models.js'; import { AGENT_CONFIG, - CODE_FAMILY_DENY_EXTRA, DEBUG_FOCUS_SKILLS, DENY_AGENT_KEEP, KEEP_AGENTS, @@ -82,6 +81,17 @@ import { const SKILLS_DIR = path.join(ROOT, 'src', 'assets', 'skills'); const COMMANDS_DIR = path.join(ROOT, 'src', 'assets', 'commands'); +/** + * The slugs of the AGENT_CONFIG rows with a deny policy, derived like KEEP_AGENTS, never listed: + * a new deny-list row is covered by every loop over this set without an edit here. + */ +const DENY_AGENTS: readonly string[] = Object.entries(AGENT_CONFIG) + .filter(([, row]) => row.policy.kind === 'deny') + .map(([slug]) => slug); + +/** The names SHARED_DENYLIST holds after DesignSync, which every deny-list agent denies in that order. */ +const ADDED_SIX: readonly string[] = SHARED_DENYLIST.slice(SHARED_DENYLIST.indexOf('DesignSync') + 1); + /** The frontmatter keys an agent file may carry; a misspelt key would silently ship nothing. */ const KNOWN_KEYS: readonly string[] = [ 'name', @@ -226,7 +236,8 @@ function collectRowViolations(name: string, fm: AgentFrontmatter, row: AgentConf * D-SCAN-IN-CODE: the one wildcard a denylist may hold is `mcp__*`, on an agent named in * MCP_DENY_AGENTS; every other wildcard, a named MCP tool, and any WebFetch or WebSearch deny * is still reported, and an allowlist never holds a wildcard. An agent in KEEP_AGENTS keeps - * every tool in DENY_AGENT_KEEP, so a deny of one is reported too. + * every tool in DENY_AGENT_KEEP, so a deny of one is reported too. An allowlist that grants + * any name on SHARED_DENYLIST is reported: every deny-list agent denies that name. */ function collectDenylistViolations(name: string, fm: AgentFrontmatter): string[] { const out: string[] = []; @@ -234,6 +245,7 @@ function collectDenylistViolations(name: string, fm: AgentFrontmatter): string[] const isAllowedWildcard = (tool: string): boolean => tool === 'mcp__*' && mcpWildcardAllowed; for (const tool of fm.tools ?? []) { if (tool.includes('*')) out.push(`${name}.md: "${tool}" is a wildcard; spell every tool name out`); + else if (SHARED_DENYLIST.includes(tool)) out.push(`${name}.md: grants "${tool}", which every deny-list agent denies`); } for (const tool of fm.disallowedTools ?? []) { if (tool.includes('*') && !isAllowedWildcard(tool)) { @@ -272,7 +284,7 @@ function collectCompletenessViolations(registered: readonly string[], table: rea */ const TOOL_VOCABULARY: readonly string[] = [ ...new Set([ - 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash', 'Skill', 'Monitor', 'ToolSearch', 'TaskStop', + 'Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash', 'Skill', 'ToolSearch', 'StructuredOutput', 'WebFetch', 'WebSearch', ...SHARED_DENYLIST, ...Object.values(AGENT_CONFIG).flatMap(row => (row.policy.kind === 'deny' ? row.policy.extra : [])), ]), @@ -547,23 +559,23 @@ describe('the table: every agent ships its row (D-AGENT-CONFIG-TABLE)', () => { }); } - const codeFamilySlugs = CODE_AGENT_TYPES.map(codeSlugOf); - - it('reports each Code-family extra name removed from each Code-family row', () => { - expect(codeFamilySlugs.length, 'the probe loops over the whole family').toBeGreaterThan(0); - for (const slug of codeFamilySlugs) { - for (const extra of CODE_FAMILY_DENY_EXTRA) { - const row = AGENT_CONFIG[slug]; - const fm = renderRow(slug, row, f => { f.disallowedTools = (f.disallowedTools ?? []).filter(tool => tool !== extra); }); - expect(collectRowViolations(slug, fm, row).length, `${slug} without ${extra}`).toBeGreaterThan(0); + it('reports each shared deny name removed from each deny-list row', () => { + expect(DENY_AGENTS.length, 'the probe loops over every deny-list row').toBeGreaterThan(0); + for (const slug of DENY_AGENTS) { + const row = AGENT_CONFIG[slug]; + for (const shared of SHARED_DENYLIST) { + const fm = renderRow(slug, row, f => { f.disallowedTools = (f.disallowedTools ?? []).filter(tool => tool !== shared); }); + expect(collectRowViolations(slug, fm, row).length, `${slug} without ${shared}`).toBeGreaterThan(0); } } }); - it('reports the Code-family extra list on the Research row, which denies the shared list only', () => { - const row = AGENT_CONFIG.research; - const fm = renderRow('research', row, f => { f.disallowedTools = [...(f.disallowedTools ?? []), ...CODE_FAMILY_DENY_EXTRA]; }); - expect(collectRowViolations('research', fm, row).length).toBeGreaterThan(0); + it('reports a name beyond the row added to each deny-list row', () => { + for (const slug of DENY_AGENTS) { + const row = AGENT_CONFIG[slug]; + const fm = renderRow(slug, row, f => { f.disallowedTools = [...(f.disallowedTools ?? []), 'Bash']; }); + expect(collectRowViolations(slug, fm, row).length, `${slug} with Bash added`).toBeGreaterThan(0); + } }); }); @@ -633,23 +645,17 @@ describe('Git and Tracker hold vendor-neutral allowlists (D-GIT-ROW, D-TRACKER-R }); describe('one shared denylist (D-SHARED-DENYLIST)', () => { - it('holds exactly seventeen distinct names, each spelled out', () => { - expect(SHARED_DENYLIST).toHaveLength(17); + it('holds exactly twenty-three distinct names, each spelled out, the last six in the gate order', () => { + expect(SHARED_DENYLIST).toHaveLength(23); expect(duplicates(SHARED_DENYLIST)).toEqual([]); for (const tool of SHARED_DENYLIST) expect(tool, tool).toMatch(/^[A-Z][A-Za-z]+$/); + expect(ADDED_SIX).toEqual(['Monitor', 'TaskStop', 'Workflow', 'Artifact', 'ListAgents', 'ReportFindings']); }); - it('the Code-family extra list holds six distinct names in order, each spelled out, none on the shared list', () => { - expect(CODE_FAMILY_DENY_EXTRA).toEqual(['Monitor', 'TaskStop', 'Workflow', 'Artifact', 'ListAgents', 'ReportFindings']); - expect(duplicates(CODE_FAMILY_DENY_EXTRA)).toEqual([]); - for (const tool of CODE_FAMILY_DENY_EXTRA) expect(tool, tool).toMatch(/^[A-Z][A-Za-z]+$/); - expect(CODE_FAMILY_DENY_EXTRA.filter(tool => SHARED_DENYLIST.includes(tool))).toEqual([]); - }); - - it('Code, Fix and Refactor deny the list plus the Code-family extra and declare no tools, Research denies exactly the list, and Harden and Polish deny it plus Skill and mcp__*', () => { + it('Code, Fix, Refactor and Research deny exactly the list, Code, Fix and Refactor declare no tools, and Harden and Polish deny it plus Skill and mcp__*', () => { expect(CODE_AGENT_TYPES.length, 'the loop covers the whole family').toBeGreaterThan(0); for (const slug of CODE_AGENT_TYPES.map(codeSlugOf)) { - expect(sameSet(agent(slug).fm.disallowedTools ?? [], [...SHARED_DENYLIST, ...CODE_FAMILY_DENY_EXTRA]), slug).toBe(true); + expect(sameSet(agent(slug).fm.disallowedTools ?? [], SHARED_DENYLIST), slug).toBe(true); expect(agent(slug).fm.tools, slug).toBeNull(); expect(agent(slug).fm.keys, slug).not.toContain('tools'); } @@ -659,6 +665,16 @@ describe('one shared denylist (D-SHARED-DENYLIST)', () => { } }); + it('all six deny-list agents carry the six added names, in order, right after DesignSync', () => { + expect([...DENY_AGENTS].sort(), 'the loop covers the whole deny set').toEqual(['code', 'fix', 'harden', 'polish', 'refactor', 'research']); + for (const slug of DENY_AGENTS) { + const denied = agent(slug).fm.disallowedTools ?? []; + const from = denied.indexOf('DesignSync') + 1; + expect(from, `${slug} denies DesignSync`).toBeGreaterThan(0); + expect(denied.slice(from, from + ADDED_SIX.length), slug).toEqual(ADDED_SIX); + } + }); + it('only the agents MCP_DENY_AGENTS names deny MCP, and they are exactly Harden and Polish (D-SCAN-IN-CODE)', () => { expect([...MCP_DENY_AGENTS].sort()).toEqual(['harden', 'polish']); for (const record of agents.values()) { @@ -667,13 +683,34 @@ describe('one shared denylist (D-SHARED-DENYLIST)', () => { } }); - it('the two policies never mix, and no list holds a wildcard, denies web access or denies a named MCP tool', () => { + it('the two policies never mix, and no list holds a wildcard, denies web access, denies a named MCP tool or grants a shared deny name', () => { for (const record of agents.values()) { expect(record.fm.tools !== null && record.fm.disallowedTools !== null, `${record.name} mixes policies`).toBe(false); expect(collectDenylistViolations(record.name, record.fm), record.name).toEqual([]); } }); + const ALLOW_AGENTS = AGENT_NAMES.filter(slug => AGENT_CONFIG[slug].policy.kind === 'allow'); + + it('no allowlist agent grants a name every deny-list agent denies', () => { + expect(ALLOW_AGENTS.length, 'the check reads at least one allowlist row').toBeGreaterThan(0); + for (const slug of ALLOW_AGENTS) { + expect(agent(slug).fm.tools, `${slug} holds a tools list`).not.toBeNull(); + expect(collectDenylistViolations(slug, agent(slug).fm), slug).toEqual([]); + } + }); + + it('known-bad probe: each shared deny name added to each allowlist row is reported, once, by name', () => { + for (const slug of ALLOW_AGENTS) { + for (const shared of SHARED_DENYLIST) { + const fm = renderRow(slug, AGENT_CONFIG[slug], f => { f.tools = [...(f.tools ?? []), shared]; }); + const violations = collectDenylistViolations(slug, fm); + expect(violations, `${slug} granting ${shared}`).toHaveLength(1); + expect(violations[0], `${slug} granting ${shared}`).toContain(`"${shared}"`); + } + } + }); + it('known-bad probes: a wildcard, a denied WebFetch and a denied MCP name are reported', () => { const base = renderRow('code', AGENT_CONFIG.code); expect(collectDenylistViolations('x', { ...base, disallowedTools: ['mcp__*'] })).toHaveLength(2); @@ -888,24 +925,17 @@ describe('tool/body agreement (D-TOOL-BODY-MATCH)', () => { expect(loaded('See src/Agent(1) and MyAgent(x) and foo.Skill(y).', noSkill)).toEqual([]); }); - it('reports each Code-family extra name, as a call and as "the X tool", on each Code-family row', () => { - expect(CODE_AGENT_TYPES.length, 'the probe loops over the whole family').toBeGreaterThan(0); - for (const slug of CODE_AGENT_TYPES.map(codeSlugOf)) { + it('reports each shared deny name, as a call and as "the X tool", on each deny-list row', () => { + expect(DENY_AGENTS.length, 'the probe loops over every deny-list row').toBeGreaterThan(0); + for (const slug of DENY_AGENTS) { const fm = renderRow(slug, AGENT_CONFIG[slug]); - for (const extra of CODE_FAMILY_DENY_EXTRA) { - expect(loaded(`Then run ${extra}(x) to finish.`, fm), `${slug}: ${extra} as a call`).toEqual([extra]); - expect(loaded(`Then use the ${extra} tool to finish.`, fm), `${slug}: ${extra} as a phrase`).toEqual([extra]); - expect(loaded(`Never run ${extra}(x), and do not use the ${extra} tool.`, fm), `${slug}: ${extra} negated`).toEqual([]); + for (const shared of SHARED_DENYLIST) { + expect(loaded(`Then run ${shared}(x) to finish.`, fm), `${slug}: ${shared} as a call`).toEqual([shared]); + expect(loaded(`Then use the ${shared} tool to finish.`, fm), `${slug}: ${shared} as a phrase`).toEqual([shared]); + expect(loaded(`Never run ${shared}(x), and do not use the ${shared} tool.`, fm), `${slug}: ${shared} negated`).toEqual([]); } } }); - - it('leaves the Code-family extra names alone on the Research row, which does not deny them', () => { - const research = renderRow('research', AGENT_CONFIG.research); - for (const extra of CODE_FAMILY_DENY_EXTRA) { - expect(loaded(`Then run ${extra}(x) and use the ${extra} tool.`, research), extra).toEqual([]); - } - }); }); }); diff --git a/tests/guards/other-agents-sizes.test.ts b/tests/guards/other-agents-sizes.test.ts index c5ee64ab..bc7030ff 100644 --- a/tests/guards/other-agents-sizes.test.ts +++ b/tests/guards/other-agents-sizes.test.ts @@ -4,7 +4,9 @@ * spawn reads these bytes again in every turn, so each ceiling holds the measured size: after * the lean cut for the #718 agents, as found for Harden and Polish. Validate and Synthesize keep * their ceilings in validate-lint-pack.test.ts and agent-references.test.ts. Each row is - * registered in `tests/fixtures/numeric-floors.json`; lowered, never raised. + * registered in `tests/fixtures/numeric-floors.json`. A value may move either way; its + * description and the PR give the old value, the new value and the reason. Each ceiling counts + * the whole compiled file, frontmatter included. */ import { describe, it, expect } from 'vitest' @@ -17,17 +19,17 @@ type Build = 'on' | 'off' * itself for a hand-authored agent. Each row's text is the pattern its numeric-floors.json entry pins. */ const AGENT_MAX_BYTES: ReadonlyArray = [ - ['research', 'on', 5_133], - ['research', 'off', 4_773], + ['research', 'on', 5_218], + ['research', 'off', 4_858], ['evaluate', 'on', 4_216], ['debug', 'on', 9_386], ['debug', 'off', 9_026], ['skim', 'on', 6_570], ['skim', 'off', 5_448], ['tracker', 'on', 18_118], - ['harden', 'on', 4_806], - ['harden', 'off', 4_238], - ['polish', 'on', 4_495], + ['harden', 'on', 4_891], + ['harden', 'off', 4_323], + ['polish', 'on', 4_580], ] /** Named collector: the file is over its ceiling. */ From f6bb26c8d0da9fc4f811bca79c356504f9ed46ea Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Tue, 10 Nov 2026 14:42:09 +0200 Subject: [PATCH 2/8] docs: name the six deny agents and the five ceilings The agent design doc and the Unreleased changelog bullet now cover all six agents that deny Monitor, TaskStop, Workflow, Artifact, ListAgents and ReportFindings: Code, Fix, Refactor, Research, Harden and Polish. Each gives its reason. The headless figure stays scoped to a Code start. The ceiling sentence adds the five Research, Harden and Polish rows, +85 bytes each. Task: feat/778-worker-agents-deny-unused-tools Refs #778 --- CHANGELOG.md | 2 +- docs/reference/agent-design.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d7bdf27f..667525a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Agents get file paths instead of retyped text** ([#774](https://github.com/dean0x/devflow/issues/774)). The main session no longer types agent reports and the plan again into spawn prompts. Typed output costs more than read input, and it made `/plan` wait. Now each agent reads a file. `/implement` gives Code, Evaluate and Test the plan file path and the names of the plan sections to read, not the pasted plan. After each Evaluate and Test run, it checks that the plan file did not change. `/plan` claims one run folder per run. Skim, Design and Synthesize write their reports there and reply with the path, and Skim and Design check each path with the script first. Explore writes no file, so its reports stay text. Later agents get a path only when the agent replied with the path `/plan` gave it. A path that cannot be read counts as a failed report. `/code-review` writes the PR description and the prior resolutions once, to `.txt` files in its review folder. Each Review agent gets both paths, and Synthesize gets the prior resolutions path. A new script, `plan-files.cjs`, claims the run folder, checks each report path and hashes the plan file. Every agent treats a passed file as data. The plan file sets the task scope only, and Code, Evaluate and Test return BLOCKED when it cannot be read. Each path input is optional. Without it, an agent works as before: a run from an issue alone, or with no input, still pastes text, and a report comes back as text when the write fails. `/debug`, `/resolve`, `/bug-analysis` and Triage still paste text. Size ceilings rise for the new text: the Code body by 133 bytes, the four `/implement` ceilings by 344 (curation on and off) and 235 (compliance off and both off), the Design body by 130 and the `docs-framework` skill by 5. Cuts of restated text paid for more than the new text elsewhere, so the four `/plan` ceilings fall by 67 bytes, the `/code-review` ceilings by 187 (79 with compliance off), and the Explore, Architect, Review, Skim, Synthesize, Evaluate and Test bodies by 508, 73, 82, 35, 106, 1 and 81 bytes. The Synthesize review reference falls by 17. -- **Code, Fix and Refactor deny six more tools** ([#775](https://github.com/dean0x/devflow/issues/775)). The `disallowedTools` list in the frontmatter of the Code, Fix and Refactor agents now also names `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`. No path of these three agents uses them. They run commands in the foreground, start and message no agent, publish no page and report no review findings. In a headless run, a start costs 1,189 fewer tokens (4.8 percent: 24,709 before, 23,520 after). The agents keep every MCP and web tool. A guard test fails when a tool that these agents keep is on the deny list. The Code, Fix and Refactor size ceilings rise by 85 bytes each for the six new frontmatter lines. +- **Code, Fix, Refactor, Research, Harden and Polish deny six more tools** ([#775](https://github.com/dean0x/devflow/issues/775), [#778](https://github.com/dean0x/devflow/issues/778)). The `disallowedTools` list in the frontmatter of these six agents now also names `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`. No path of these agents uses them. They start, stop and message no agent and publish no page. They run commands in the foreground (Harden runs one changed test file) or run none (Polish). None of them reports findings with `ReportFindings`: Harden reports in its final message and Research writes its findings to its output file. In a headless run, a Code start costs 1,189 fewer tokens (4.8 percent: 24,709 before, 23,520 after). Code, Fix, Refactor and Research keep every MCP and web tool. A guard test fails when a tool that these four agents keep is on the deny list, and when an agent with a `tools:` list grants any name on the shared deny list. The Code, Fix and Refactor size ceilings, and the five Research, Harden and Polish ceilings (curation on and off), rise by 85 bytes each for the six new frontmatter lines. --- diff --git a/docs/reference/agent-design.md b/docs/reference/agent-design.md index 85343e5d..1ceb8c28 100644 --- a/docs/reference/agent-design.md +++ b/docs/reference/agent-design.md @@ -46,7 +46,7 @@ tools: ["Bash", "Read"] When an agent only needs a subset of tools, prefer platform-enforced restriction over prompt instructions. An agent holds one tool policy, never both: - **Allowlist (`tools:`)** — the agent holds exactly the tools named. This is the default for an agent that needs no user-environment MCP or web access. A whole-server entry `mcp__` grants every tool that server exposes, deferred behind `ToolSearch`; an entry for a server that is not connected grants nothing and does not block launch. Git and Tracker list only built-in tools in source, and the installer appends one `mcp__` per configured tracker server. -- **Denylist (`disallowedTools:`)** — the agent keeps every tool except the ones named, MCP and web tools included. Use it where the agent must keep that access (Code, Fix, Refactor, Research). Code, Fix and Refactor also deny `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`, because no path of these agents uses them. They run commands in the foreground, start and message no agent, publish no page and report no review findings. Harden and Polish also deny `mcp__*`, which drops every MCP tool and keeps web access, so code scanning runs in Code alone. Spell every other name out: a wildcard removes every name it matches. +- **Denylist (`disallowedTools:`)** — the agent keeps every tool except the ones named, MCP and web tools included. Use it where the agent must keep that access (Code, Fix, Refactor, Research). Code, Fix, Refactor, Research, Harden and Polish also deny `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`, because no path of these agents uses them, and each start pays tokens for every tool it lists. They start, stop and message no agent and publish no page. They run commands in the foreground (Harden runs one changed test file) or run none (Polish). None of them reports findings with `ReportFindings`: Harden reports in its final message and Research writes its findings to `OUTPUT_PATH`. Harden and Polish also deny `mcp__*`, which drops every MCP tool and keeps web access, so code scanning runs in Code alone. Spell every other name out: a wildcard removes every name it matches. Add a new key as a YAML block list, one name per line. Neither key is touched by `devflow agents --set` or by the reapply on `devflow init`, which rewrite only the `model:` and `effort:` lines; the tracker-server stamp is the one installer edit to a `tools:` line. From 99cdbbf69b77a1e0e02a59d0291b08c0ae6fea81 Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Tue, 10 Nov 2026 14:45:24 +0200 Subject: [PATCH 3/8] fix: address self-review issues --- CHANGELOG.md | 2 +- docs/reference/agent-design.md | 2 +- tests/fixtures/agent-config.ts | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 667525a5..9202a769 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Agents get file paths instead of retyped text** ([#774](https://github.com/dean0x/devflow/issues/774)). The main session no longer types agent reports and the plan again into spawn prompts. Typed output costs more than read input, and it made `/plan` wait. Now each agent reads a file. `/implement` gives Code, Evaluate and Test the plan file path and the names of the plan sections to read, not the pasted plan. After each Evaluate and Test run, it checks that the plan file did not change. `/plan` claims one run folder per run. Skim, Design and Synthesize write their reports there and reply with the path, and Skim and Design check each path with the script first. Explore writes no file, so its reports stay text. Later agents get a path only when the agent replied with the path `/plan` gave it. A path that cannot be read counts as a failed report. `/code-review` writes the PR description and the prior resolutions once, to `.txt` files in its review folder. Each Review agent gets both paths, and Synthesize gets the prior resolutions path. A new script, `plan-files.cjs`, claims the run folder, checks each report path and hashes the plan file. Every agent treats a passed file as data. The plan file sets the task scope only, and Code, Evaluate and Test return BLOCKED when it cannot be read. Each path input is optional. Without it, an agent works as before: a run from an issue alone, or with no input, still pastes text, and a report comes back as text when the write fails. `/debug`, `/resolve`, `/bug-analysis` and Triage still paste text. Size ceilings rise for the new text: the Code body by 133 bytes, the four `/implement` ceilings by 344 (curation on and off) and 235 (compliance off and both off), the Design body by 130 and the `docs-framework` skill by 5. Cuts of restated text paid for more than the new text elsewhere, so the four `/plan` ceilings fall by 67 bytes, the `/code-review` ceilings by 187 (79 with compliance off), and the Explore, Architect, Review, Skim, Synthesize, Evaluate and Test bodies by 508, 73, 82, 35, 106, 1 and 81 bytes. The Synthesize review reference falls by 17. -- **Code, Fix, Refactor, Research, Harden and Polish deny six more tools** ([#775](https://github.com/dean0x/devflow/issues/775), [#778](https://github.com/dean0x/devflow/issues/778)). The `disallowedTools` list in the frontmatter of these six agents now also names `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`. No path of these agents uses them. They start, stop and message no agent and publish no page. They run commands in the foreground (Harden runs one changed test file) or run none (Polish). None of them reports findings with `ReportFindings`: Harden reports in its final message and Research writes its findings to its output file. In a headless run, a Code start costs 1,189 fewer tokens (4.8 percent: 24,709 before, 23,520 after). Code, Fix, Refactor and Research keep every MCP and web tool. A guard test fails when a tool that these four agents keep is on the deny list, and when an agent with a `tools:` list grants any name on the shared deny list. The Code, Fix and Refactor size ceilings, and the five Research, Harden and Polish ceilings (curation on and off), rise by 85 bytes each for the six new frontmatter lines. +- **Code, Fix, Refactor, Research, Harden and Polish deny six more tools** ([#775](https://github.com/dean0x/devflow/issues/775), [#778](https://github.com/dean0x/devflow/issues/778)). The `disallowedTools` list in the frontmatter of these six agents now also names `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`. No path of these agents uses them. They start, stop and message no agent and publish no page. They run every command in the foreground: Harden runs only the test files it changed, and Polish runs no build, test or lint command. None of them reports findings with `ReportFindings`: Harden reports in its final message and Research writes its findings to its output file. In a headless run, a Code start costs 1,189 fewer tokens (4.8 percent: 24,709 before, 23,520 after). Code, Fix, Refactor and Research keep every MCP and web tool. A guard test fails when a tool that these four agents keep is on the deny list, and when an agent with a `tools:` list grants any name on the shared deny list. The Code, Fix and Refactor size ceilings, and the five Research, Harden and Polish ceilings (curation on and off), rise by 85 bytes each for the six new frontmatter lines. --- diff --git a/docs/reference/agent-design.md b/docs/reference/agent-design.md index 1ceb8c28..d2a00b34 100644 --- a/docs/reference/agent-design.md +++ b/docs/reference/agent-design.md @@ -46,7 +46,7 @@ tools: ["Bash", "Read"] When an agent only needs a subset of tools, prefer platform-enforced restriction over prompt instructions. An agent holds one tool policy, never both: - **Allowlist (`tools:`)** — the agent holds exactly the tools named. This is the default for an agent that needs no user-environment MCP or web access. A whole-server entry `mcp__` grants every tool that server exposes, deferred behind `ToolSearch`; an entry for a server that is not connected grants nothing and does not block launch. Git and Tracker list only built-in tools in source, and the installer appends one `mcp__` per configured tracker server. -- **Denylist (`disallowedTools:`)** — the agent keeps every tool except the ones named, MCP and web tools included. Use it where the agent must keep that access (Code, Fix, Refactor, Research). Code, Fix, Refactor, Research, Harden and Polish also deny `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`, because no path of these agents uses them, and each start pays tokens for every tool it lists. They start, stop and message no agent and publish no page. They run commands in the foreground (Harden runs one changed test file) or run none (Polish). None of them reports findings with `ReportFindings`: Harden reports in its final message and Research writes its findings to `OUTPUT_PATH`. Harden and Polish also deny `mcp__*`, which drops every MCP tool and keeps web access, so code scanning runs in Code alone. Spell every other name out: a wildcard removes every name it matches. +- **Denylist (`disallowedTools:`)** — the agent keeps every tool except the ones named, MCP and web tools included. Use it where the agent must keep that access (Code, Fix, Refactor, Research). Code, Fix, Refactor, Research, Harden and Polish also deny `Monitor`, `TaskStop`, `Workflow`, `Artifact`, `ListAgents` and `ReportFindings`, because no path of these agents uses them, and each start pays tokens for every tool it lists. They start, stop and message no agent and publish no page. They run every command in the foreground: Harden runs only the test files it changed, and Polish runs no build, test or lint command. None of them reports findings with `ReportFindings`: Harden reports in its final message and Research writes its findings to `OUTPUT_PATH`. Harden and Polish also deny `mcp__*`, which drops every MCP tool and keeps web access, so code scanning runs in Code alone. Spell every other name out: a wildcard removes every name it matches. Add a new key as a YAML block list, one name per line. Neither key is touched by `devflow agents --set` or by the reapply on `devflow init`, which rewrite only the `model:` and `effort:` lines; the tracker-server stamp is the one installer edit to a `tools:` line. diff --git a/tests/fixtures/agent-config.ts b/tests/fixtures/agent-config.ts index f55309f4..07f4b17a 100644 --- a/tests/fixtures/agent-config.ts +++ b/tests/fixtures/agent-config.ts @@ -95,8 +95,9 @@ export interface AgentConfigRow { * The six names after DesignSync are unused by all six agents, and each start pays tokens for * every tool it lists. Workflow starts agents and ListAgents finds agents to message; none of * these agents starts, stops or messages one. TaskStop stops a background run and Monitor waits - * on one; these agents run commands in the foreground (Harden runs one changed test file) or run - * none (Polish). Artifact publishes a page; none of them does. ReportFindings reports review + * on one; these agents run every command in the foreground (Harden runs only the test files it + * changed, and Polish runs no build, test or lint command). Artifact publishes a page; none of + * them does. ReportFindings reports review * findings; Harden reports in its final message and Research writes its findings to OUTPUT_PATH * with Write. Workflow, TaskStop, ListAgents and Artifact stay members whatever their measured * cost. From b42fd815aba2295e6d8462f27c79d5b9edf5307e Mon Sep 17 00:00:00 2001 From: Dean Sharon Date: Tue, 10 Nov 2026 15:20:29 +0200 Subject: [PATCH 4/8] docs(knowledge): update test-harness feature knowledge base --- .devflow/features/test-harness/KNOWLEDGE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.devflow/features/test-harness/KNOWLEDGE.md b/.devflow/features/test-harness/KNOWLEDGE.md index e0ce86ae..2f71070e 100644 --- a/.devflow/features/test-harness/KNOWLEDGE.md +++ b/.devflow/features/test-harness/KNOWLEDGE.md @@ -5,7 +5,7 @@ description: "Use when adding a guard, seam or golden test, changing the agent-s category: conventions directories: [tests/helpers.ts, tests/git-agent.test.ts, tests/seams, tests/goldens, tests/guards, tests/fixtures, scripts/update-golden.ts, tests/integration, tests/tracker, tests/installer, tests/evidence, tests/provider-literals.test.ts, tests/tracker-agent.test.ts, tests/commands, tests/install-bound-input.test.ts, tests/curation, tests/decisions, tests/bug-analysis] created: 2026-09-06 -updated: 2026-11-09 +updated: 2026-11-10 --- # Test Harness @@ -24,6 +24,7 @@ updated: 2026-11-09 - **KB-INV-10** Every CLI-spawning test file names one `SUBPROCESS_TIMEOUT_MS` and uses it for the `spawnSync` timeout AND every `it()` timeout, directly or through a describe-level `{ timeout }` option. - **KB-INV-11** `/code-review` and `/bug-analysis` check their fresh-base and stored-head text through the shared `collectFreshBaseDefects` / `collectStoredHeadDefects` in `tests/helpers.ts` (shaped by a `DiffRangeShape`); a fact only one command states goes in that guard's wrapper collector or its `FreshBaseParts`, never a copy of the shared checks. - **KB-INV-12** A deny-list agent outside `MCP_DENY_AGENTS` keeps every `DENY_AGENT_KEEP` tool: `collectDenylistViolations` reports a deny of one, over `KEEP_AGENTS` derived from the deny rows. +- **KB-INV-13** An allow-list agent never grants a `SHARED_DENYLIST` name: `collectDenylistViolations` reports it, because every deny-list agent denies that name. - **KB-AP-1** `scanned > 0` over a corpus is necessary, not sufficient: assert completeness against a named set (`getAllAgentNames()`, a manifest) and, for a scan of two sources, by provenance that both contributed. - **KB-AP-2** A probe that reimplements the collector inline, or names one member of a set the gate ranges over, stays green after the guard breaks: call the real collector and loop the probe over the whole set. - **KB-AP-3** Never write into the real `dist/` or `src/` from a test, nor rebuild the repo's own `dist/`: parallel workers read those paths and an unscoped build repairs staleness mid-suite; use `buildCommittedTree()` or a temp root. @@ -155,7 +156,7 @@ Guard 10 reads each operation in `GIT_OPERATIONS` through `opSection = extractOp **`retired-wording.test.ts`** is one shared grep guard with a denylist that grows over time, never a new grep and never emptied. Each `RETIRED_LITERALS` entry carries an optional `scope: readonly string[]` (corpus path-prefixes the literal is retired FROM; absent means the whole corpus). Rows include `gh issue` (scope `dist/commands/`), `sleep 60`, `