Skip to content
Merged
30 changes: 15 additions & 15 deletions .devflow/features/test-harness/KNOWLEDGE.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. None of them starts a background run, and a spawned subagent needs no `Monitor` to read the end of a run that passes its timeout: 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.

---

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/agent-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -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__<server>` 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__<name>` 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. None of them starts a background run: Harden runs only the test files it changed, and Polish runs no build, test or lint command. The end notice re-invokes a spawned subagent whose foreground call passes its timeout, so none needs `Monitor`. 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.

Expand Down
6 changes: 6 additions & 0 deletions src/assets/agents/harden.mds
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,12 @@ disallowedTools:
- RemoteTrigger
- PushNotification
- DesignSync
- Monitor
- TaskStop
- Workflow
- Artifact
- ListAgents
- ReportFindings
- Skill
- mcp__*
---
Expand Down
6 changes: 6 additions & 0 deletions src/assets/agents/polish.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,12 @@ disallowedTools:
- RemoteTrigger
- PushNotification
- DesignSync
- Monitor
- TaskStop
- Workflow
- Artifact
- ListAgents
- ReportFindings
- Skill
- mcp__*
---
Expand Down
6 changes: 6 additions & 0 deletions src/assets/agents/research.mds
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ disallowedTools:
- RemoteTrigger
- PushNotification
- DesignSync
- Monitor
- TaskStop
- Workflow
- Artifact
- ListAgents
- ReportFindings
omitClaudeMd: true
---

Expand Down
45 changes: 21 additions & 24 deletions tests/fixtures/agent-config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,14 +84,24 @@ 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; none of these agents starts a background run (Harden runs only the test files it
* changed, and Polish runs no build, test or lint command), and the end notice re-invokes a
* spawned subagent whose foreground call passes its timeout, so none needs Monitor. 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',
Expand All @@ -111,19 +121,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',
Expand All @@ -137,7 +134,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',
Expand Down Expand Up @@ -248,7 +245,7 @@ export const AGENT_CONFIG: Readonly<Record<string, AgentConfigRow>> = {
code: {
model: 'sonnet',
effort: 'high',
policy: { kind: 'deny', extra: CODE_FAMILY_DENY_EXTRA },
policy: { kind: 'deny', extra: [] },
omitClaudeMd: false,
skills: null,
digest: [],
Expand All @@ -262,15 +259,15 @@ export const AGENT_CONFIG: Readonly<Record<string, AgentConfigRow>> = {
fix: {
model: 'sonnet',
effort: 'high',
policy: { kind: 'deny', extra: CODE_FAMILY_DENY_EXTRA },
policy: { kind: 'deny', extra: [] },
omitClaudeMd: false,
skills: null,
digest: [],
},
refactor: {
model: 'sonnet',
effort: 'high',
policy: { kind: 'deny', extra: CODE_FAMILY_DENY_EXTRA },
policy: { kind: 'deny', extra: [] },
omitClaudeMd: false,
skills: null,
digest: [],
Expand Down
30 changes: 15 additions & 15 deletions tests/fixtures/numeric-floors.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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."
}
]
}
Loading
Loading