feat: enforce cwd and track PIDs in subAgent process delegation by avoidwork · Pull Request #456 · avoidwork/madz

avoidwork · 2026-06-26T22:42:58Z

Description

This branch introduces comprehensive subAgent process management: enforcing explicit cwd for delegation, tracking OS-level PIDs in process results, and adding the loadAgents workspace function for AGENTS.md discovery. It also creates and refines the SUB_AGENT.md prompt for one-shot skill execution, adds the --sub-agent CLI flag, and excludes subAgent tools from sub-agent processes to prevent recursion.

Type of Change

New feature (non-breaking change which adds functionality)

Testing

Unit tests for scanAgents tool, subAgent cwd handling, skills module cwd override, sandbox runner, discoverer, and tool registration. Full test suite runs with no failures.

Coverage

100% line coverage maintained

Checklist

npm run lint passes
Tests pass with 100% line coverage
No forbidden patterns used
Conventional Commit style applied

- Add src/tools/scanAgents.js with implementation, tool definition, and factory - Register tool in src/tools/index.js (TOOL_PERMISSIONS, TOOL_FACTORIES, switch case) - Add unit tests in tests/unit/tools_scanAgents.test.js - Update tool_index.test.js to account for new tool registration - Archive OpenSpec change as 2026-06-26-scan-agents-tool - Create spec in openspec/specs/scan-agents/spec.md

avoidwork · 2026-06-26T22:58:49Z

Audit Results — scanAgents Tool (Implementation)

Audit 1: Implementation Against Specs & Goals

Goal Fulfillment

Goal 1 (Add scanAgents tool): Fully implemented.
Key Req 1 (optional path parameter): Implemented — input.path || process.cwd() (line 18).
Key Req 2 (checks for AGENTS.md): Implemented — join(resolved.path, "AGENTS.md") (line 24).
Key Req 3 (returns file contents): Implemented — readFile(agentsPath, "utf-8") returns content (lines 39-40).
Key Req 4 (silent on not found): Implemented — returns "" on ENOENT (lines 28-30).
Key Req 5 (validatePath/checkFileLimit): Implemented — both used for safety (lines 19, 33).
Key Req 6 (minimal tool pattern): Implemented — follows date.js pattern exactly.
Key Req 7-9 (registration): Implemented — TOOL_PERMISSIONS, TOOL_FACTORIES, switch case all updated.

Spec Compliance

Requirement 1 (discovers AGENTS.md): ✓ Lines 18, 24
Requirement 2 (returns file contents): ✓ Lines 39-40
Requirement 3 (silent on not found): ✓ Lines 28-30
Requirement 4 (validates paths): ✓ Lines 19-22
Requirement 5 (enforces size limits): ✓ Lines 33-36

Task Completion

Task 1.1-1.4: Created src/tools/scanAgents.js with implementation, tool definition, factory, and common.js integration. ✓
Task 2.1-2.3: Registered in index.js (import, TOOL_PERMISSIONS, TOOL_FACTORIES, switch case). ✓
Task 3.1-3.6: Created tests/unit/tools_scanAgents.test.js with 6 test cases covering all scenarios. ✓
Task 4.1-4.3: Tests pass (1193/1193), lint passes, application starts. ✓

Quality Check

No obvious issues or inconsistencies.
All edge cases covered by tests.
Code follows existing patterns (date.js, filesystem.js).
JSDoc comments present on public APIs.

Result

No errors found. Implementation is complete and correct.

…rride

- Create src/workspace/loadAgents.js to read AGENTS.md from any directory - Update scanAgents tool to delegate to loadAgents with validated path - Wire loadAgents into index.js session init to append AGENTS.md to system prompt - Remove scanAgents reference from SYSTEM_PROMPT.md

…irements

- Add cwd: '' to config.yaml and schema - Set config.cwd = process.cwd() in loader before any chdir - Import config loader first in index.js, before all other ./src imports - Replace all process.cwd() calls in ./src with config.cwd - Document CLI arguments in README

…ox runner

- Add subAgent option to buildToolConfig to exclude subAgent tools - Skip subAgent, subAgentLog, and subAgentMessage when subAgent=true - Fix pre-existing bug: subAgentMessage missing from TOOL_PERMISSIONS - Pass config.subAgent from index.js to buildToolConfig - Add tests for subAgent tool exclusion behavior

…tradictions, and unnecessary sections

…to SUB_AGENT.md

Sub-agents running in target project directories (e.g., ../tiny-lru) were trying to navigate back to madz. Added explicit WORKING DIRECTORY section to prevent this behavior.

Sub-agents running in target directories (e.g., ../tiny-lru) were denied file access because the cwd wasn't in the sandbox scope. Now config.cwd is pushed into sandbox.paths at load time.

Only push config.cwd into sandbox.paths when running as a sub-agent, preventing unnecessary path pollution for normal app runs.

…l change - Add 'What Actually Happened' sections to design.md and proposal.md - Document the expanded scope beyond original scanAgents tool proposal - Add scope delta table comparing original vs actual implementation - Update .openspec.yaml with name, archived, and archivedDate fields - Fill in Purpose sections for scan-agents and subagent specs - Capture lessons learned about scope creep and architectural evolution

…rompt format

feat: add OpenSpec proposal for scanAgents tool

b1e82ee

avoidwork self-assigned this Jun 26, 2026

avoidwork changed the title ~~feat: add OpenSpec proposal for scanAgents tool~~ feat: add scanAgents tool for AGENTS.md discovery Jun 26, 2026

avoidwork added 3 commits June 26, 2026 19:05

fix: mark all scanAgents tasks as complete

4d05d32

feat: instruct agent to scanAgents on init and filesystem work

14c4616

fix: use config values for sandbox allowedPaths to enable env var ove…

87ed201

…rride

avoidwork force-pushed the feat/scan-agents-tool branch from 33da5c6 to 87ed201 Compare June 26, 2026 23:31

avoidwork added 21 commits June 26, 2026 19:49

fix: add horizontal rule separator in loadAgents output

d07d60c

fix: remove extra blank line from SYSTEM_PROMPT.md

e94dd71

feat: enforce explicit cwd for subAgent delegation and loadAgents

bdf617c

fix: update scanAgents test to match loadAgents wrapper format

7d15d55

docs: update subagent spec with cwd enforcement and CLI argument requ…

299e235

…irements

chore: move agentsText to end of callPrompt concatenation

bb9c372

feat: add scanAgents tool for AGENTS.md discovery

b926663

feat: add scan-agents-tool for AGENTS.md discovery

4ec8443

fix: pass cwd parameter to spawnSubAgentProcess in tests

5cb5c47

refactor: remove meaningless sessionsDir from subAgent execution

b632cdd

feat: use yargs for --cwd CLI argument

e27804a

fix: resolve lint errors from duplicate content and unused variables

bbab43a

fix: declare cwd in context.js to prevent ReferenceError

cb76f83

WIP

656a41b

fix: resolve cwd ReferenceError in files missing loadConfig import

3f976d1

fix: remove unused variable and fix self-referential default in sandb…

6e6593e

…ox runner

fix: export cwd from files using loadConfig().cwd for test override

426f9e4

fix: add setCwd helper to override cwd for tests

357b9e7

fix: remove export from cwd declarations

c38cc56

avoidwork added 20 commits June 27, 2026 12:23

docs: add process identification statements to system prompt

2dd8d55

docs: consolidate Process lines into [PROCESS_IDENTITY] placeholder

0ca1092

feat: replace [PROCESS_IDENTITY] with dynamic process identity text

1006809

fix: remove [PROCESS_IDENTITY] replacement from loadSystemPrompt

ef1113c

docs: remove sub-agent executor and process identity from system prompt

2aef6d4

docs: add explicit subAgent delegation directive to system prompt

0608270

docs: add SUB_AGENT.md prompt for one-shot skill execution

ae731ae

docs: streamline skills protocol with heavy subAgent delegation emphasis

f0655ba

docs: add # SubAgent output marker requirement to SUB_AGENT.md

47003bc

refactor: audit and streamline SUB_AGENT.md — remove duplication, con…

47dd039

…tradictions, and unnecessary sections

refactor: remove execution details from SYSTEM_PROMPT.md — delegated …

2744a0f

…to SUB_AGENT.md

feat: load SUB_AGENT.md when subAgent is true

d625c0d

fix: add working directory directive to SUB_AGENT.md

10b3a38

Sub-agents running in target project directories (e.g., ../tiny-lru) were trying to navigate back to madz. Added explicit WORKING DIRECTORY section to prevent this behavior.

fix: add cwd to sandbox allowed paths for sub-agents

50e4d0d

Sub-agents running in target directories (e.g., ../tiny-lru) were denied file access because the cwd wasn't in the sandbox scope. Now config.cwd is pushed into sandbox.paths at load time.

fix: conditionally add cwd to sandbox paths only for sub-agents

0c2f1bd

Only push config.cwd into sandbox.paths when running as a sub-agent, preventing unnecessary path pollution for normal app runs.

fix: use config.cwd for memory file path resolution in writer.js

0616a33

docs: make audit-code skill state file path configurable

f7f208c

feat: track OS-level PID in subAgent process results

7d71a3f

chore: remove unused msToSeconds function and fix lint errors

67a305d

avoidwork changed the title ~~feat: add scanAgents tool for AGENTS.md discovery with cwd enforcement~~ feat: enforce cwd and track PIDs in subAgent process delegation Jun 27, 2026

avoidwork added 6 commits June 27, 2026 14:51

refactor: use process.cwd() directly in loadAgents

f377d29

docs: update documentation for scan-agents-tool PR

626ec39

fix: correct table delimiters in docs/OVERVIEW.md

215a66e

chore: remove audit-code skill from PR (ignored by .gitignore)

b9956ec

fix: update subAgent descriptions to match actual newline-separated p…

5d6edb0

…rompt format

avoidwork enabled auto-merge (squash) June 27, 2026 19:33

avoidwork merged commit c8d900e into main Jun 27, 2026
2 checks passed

avoidwork deleted the feat/scan-agents-tool branch June 27, 2026 19:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: enforce cwd and track PIDs in subAgent process delegation#456

feat: enforce cwd and track PIDs in subAgent process delegation#456
avoidwork merged 72 commits into
mainfrom
feat/scan-agents-tool

avoidwork commented Jun 26, 2026 •

edited

Loading

Uh oh!

avoidwork commented Jun 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

avoidwork commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of Change

Testing

Coverage

Checklist

Uh oh!

avoidwork commented Jun 26, 2026

Audit Results — scanAgents Tool (Implementation)

Audit 1: Implementation Against Specs & Goals

Goal Fulfillment

Spec Compliance

Task Completion

Quality Check

Result

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

avoidwork commented Jun 26, 2026 •

edited

Loading