AGENTS.md@packages/agents git:20261013.93eeaecA

Immutable. This exact content never changes and is served at /api/v1/blob/1e593f84eb85368b.

# @shadowclone/agents

Runs the installed `claude`, `codex`, `cursor-agent`, and `pi` programs without a terminal. Learning, review, and evaluation use it for every model call.

<!-- package-facts:start -->

(generated by `bun run guides`; do not edit by hand)

- Package name: `@shadowclone/agents`
- Workspace dependencies: `@shadowclone/core`, `@shadowclone/redact`
- External dependencies: `zod`
- Export subpaths: `.`

<!-- package-facts:end -->

## Owns

- `src/engine/`: one runner for each engine (`runClaudeCode`, `runCodex`, `runCursorAgent`, `runPi`), output parsers, and `detectEngine`.
- `src/engine/learning.ts`: `createLearningExecution` and the call, time, and cost limits.
- `src/engine/execution.ts`: the checks for each run purpose (`learning`, `review`, `evaluation`).
- `src/engine/fastTier.ts`: `fastTier`, the small model setting for short generations.
- `src/engine/native/` and `evaluationIsolation/`: native runs and the file system limits for evaluation.
- `src/provider/`: the capability registry (`getProviderByEngine`). Antigravity and OpenCode have no runner, so learning for their sessions uses another engine.

## Rules

- A learning run allows no provider tools and no system prompt file. The runner forces the `dontAsk` mode.
- A review run allows only `Read`, `Grep`, `Glob`, and `Agent`. Web tools need `network: true`.
- `createLearningExecution` owns the call, time, and dollar limits. The defaults are 20 calls, 5 minutes, and $2.
- An engine that cannot meet the learning contract is an error.
- The dollar limit applies only to an engine that supports it. The runner sends no unsupported budget flag.

## Tests

Run `bun test` in this folder, or `bun test packages/agents` from the root. The tests use synthetic provider streams and mock programs. Some Claude tests check for `bubblewrap` and `socat` on Linux.

Update this file in the same commit when you change the package purpose, public exports, dependencies, or a rule above.