feat: add scanAgents tool for AGENTS.md discovery

[avoidwork]

Summary

A new tool called scanAgents that checks for AGENTS.md in the current working directory and, if found, reads and incorporates its contents into the agent's workflow.

Motivation

Currently, agents don't have a dedicated tool to discover and load AGENTS.md from the current working directory. This tool would enable agents to automatically find and use project-specific guidance files, making the workflow more adaptive to different project contexts.

Proposed Solution

Create a new tool called scanAgents with the following behavior:

1. Accept an optional path parameter (defaults to the agent's current working directory)
2. Check for AGENTS.md at the specified path
3. If found, read the file contents
4. Incorporate the contents into the agent's workflow context

The tool should be simple and direct — no complex configuration, just a straightforward discovery and load mechanism.

Alternatives Considered

• Relying on implicit context loading — rejected because it's not explicit or discoverable
• Adding AGENTS.md loading to an existing tool — rejected because it deserves its own dedicated tool for clarity and composability

OpenSpec Note

This project uses OpenSpec for feature development. If this request is approved, I will:

1. Run /opsx:propose to generate a full proposal with specs and tasks
2. Iterate on the design before any code is written
3. Follow the task-driven implementation workflow

Additional Context

The tool name scanAgents suggests a scanning/discovery pattern — it scans for the presence of AGENTS.md and acts accordingly. If the file is not found, the tool should complete silently (no error). The path parameter allows sub-agents working in other directories to scan for project-specific guidance files in their own context.

---

Audit Findings

• File: src/tools/index.js — Tools are registered in two maps: TOOL_PERMISSIONS (name to required permission scopes) and TOOL_FACTORIES (name to factory function). A new tool would need entries in both.
• File: src/tools/date.js — Example of a minimal tool pattern: implementation function (dateImpl), LangChain tool() definition with schema, and a factory function (createDateTool) that accepts runtime options. The scanAgents tool would follow this same pattern.
• File: src/tools/filesystem.js — Contains createReadFileTool which handles file reading with path validation and size limits. The scanAgents tool would need similar path validation to ensure it only reads from allowed paths.
• Integration point: src/tools/index.js:188-256 — The buildToolConfig function iterates over TOOL_PERMISSIONS, checks permissions, and calls the factory. A new tool with no required permissions (like date) would be registered in the switch statement at line 192-198 or handled by the default case at line 251-254.
• AGENTS.md location: The file exists at the project root (/home/jason/Projects/madz/AGENTS.md, 15KB). The tool should accept an optional path parameter and check for AGENTS.md at that path, reading it if present, silently doing nothing if absent.