| name | add-tool |
| description | Scaffold a new Forge tool end-to-end — implementation, registration, permission/risk metadata, sandbox routing, and a unit test. |
A new tool touches four places. Do all four or the tool is half-registered.
1. src/tools/<name>.ts
zod schemas for input and output.- Declare both
sideEffect (none|read|write|network|exec) and
risk (low|medium|high|critical) on the schema. Be honest —
these drive the permission classifier.
- All filesystem access goes through
src/sandbox/fs.ts helpers.
- All shell commands go through
src/sandbox/shell.ts +
classifyCommandRisk.
- Request permission via
requestPermission
(src/permissions/manager.ts) before the side effect, not
after.
- Return
{ ok: true, data } / { ok: false, error }. Throw only
for programmer errors, and then use ForgeRuntimeError.
2. Registration
Wire it into the registry, following the pattern of an existing tool
like src/tools/read-file.ts.
3. test/unit/<name>.test.ts
Minimum coverage:
- happy path with valid input,
- zod rejection on invalid input,
- permission denied → structured error (not throw),
- sandbox refuses path-escape,
- (if shell)
critical command hard-blocked.
Use vi.mock for the permission manager and sandbox boundaries. No
real filesystem writes outside os.tmpdir().
4. Docs
If user-visible, update the tools table in docs/ARCHITECTURE.md and
the README "At a glance" count.
Finish with the verify skill.
