@clarvis/agent-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `@clarvis/agent-tools` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-01
+
+Initial public release.
+
+### Added
+
+- **Nine coding tools** for driving an LLM agent over a workspace: `read_file`, `list_dir`, `glob`,
+  `grep`, `write_file`, `edit_file`, `multi_edit`, `apply_patch`, and `bash`.
+- **Transport-agnostic library API** — `createAgentTools({ workspaceRoot })` plus the lower-level
+  `dispatch` / `listTools` / `resolveConfig` / `buildConfig` and the raw `ToolDef` registry
+  (`tools`, `readOnlyTools`, `getTool`, `selectSurface`).
+- **Uniform dispatch pipeline** — arguments validated against each tool's JSON Schema (ajv), handler
+  run, output bounded, and errors serialized to a stable `{ error, message, ...fields }` envelope
+  (`ToolError`, `serializeError`, `fsError`, the `ErrorCode` union).
+- **Workspace path confinement** (`confineToWorkspace`, default on) with `realpath` canonicalization
+  and symlink-escape rejection (`path_escape`), plus write-through-symlink refusal.
+- **Read-only mode** (`readOnly`) exposing only `read_file`, `list_dir`, `glob`, and `grep`.
+- **Output bounding & spill** — every result capped to `maxOutputBytes` (UTF-8-safe); `bash` splits
+  the budget across stdout/stderr, enforces a per-stream capture ceiling (`output_limit`), and spills
+  full output to a `.clarvis/` file, swept by `sweepSpillDir`.
+- **Atomic writes** — temp-then-rename with fsync, mode preservation, per-path locking, and
+  multi-file rollback for `apply_patch`.
+- **Text handling** — UTF-8 / UTF-16 (LE/BE) decoding, BOM and per-line EOL preservation on edits,
+  NUL-byte binary rejection, and a `maxFileBytes` input ceiling (`too_large`).
+- **grep** backed by ripgrep when available, with a behaviorally consistent in-process fallback, both
+  honoring `.gitignore`.
+- **VitePress documentation site** ([agent-tools.clarvis.dev](https://agent-tools.clarvis.dev)) and
+  the canonical per-tool [`SPEC.md`](SPEC.md).
+
+[Unreleased]: https://github.com/getclarvis/agent-tools/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/getclarvis/agent-tools/releases/tag/v0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,117 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or
+sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and
+healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the
+  experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their
+  explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior
+and will take appropriate and fair corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits,
+code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and
+will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public spaces. Examples of representing our community
+include using an official email address, posting via an official social media account, or acting as
+an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community
+leaders responsible for enforcement at **conduct@clarvis.dev**. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any
+incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for
+any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or
+unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the
+nature of the violation and an explanation of why the behavior was inappropriate. A public apology
+may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people
+involved, including unsolicited interaction with those enforcing the Code of Conduct, for a
+specified period of time. This includes avoiding interactions in community spaces as well as external
+channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate
+behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the
+community for a specified period of time. No public or private interaction with the people involved,
+including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including
+sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement
+of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to @clarvis/agent-tools
+
+Thanks for your interest in contributing! This document covers how to get set up, the quality gate,
+and the conventions this codebase follows. By participating you agree to abide by our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Getting started
+
+```bash
+git clone https://github.com/getclarvis/agent-tools.git
+cd agent-tools
+npm install
+```
+
+Requires **Node.js >= 20**. [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on `PATH` is
+optional — when present, `grep` uses it; otherwise an equivalent in-process backend runs, and the two
+are kept behaviorally consistent.
+
+## Development workflow
+
+```bash
+npm run build          # emit dist/ (tsc, with .d.ts)
+npm test               # full vitest suite (contract + integration)
+npm run typecheck      # tsc --noEmit (strict)
+npm run lint           # eslint
+npm run format         # prettier --write (src + tests)
+```
+
+Before opening a pull request, make sure the quality gate is green:
+
+```bash
+npm run pre-commit     # typecheck + format:check + test
+```
+
+CI runs `typecheck`, `lint`, `format:check`, `test`, and `build` on pushes and PRs targeting `main`
+and `develop`, across a Node matrix (`20.x`, `lts/*`, `current`). There is no separate coverage gate.
+
+## Project layout
+
+- `src/index.ts` — the public API (`createAgentTools`, `dispatch`, `listTools`, `resolveConfig`,
+  `buildConfig`, the registry, and the error contract).
+- `src/core.ts` — the dispatch pipeline: validate (ajv) → run handler → bound output → serialize error.
+- `src/config.ts` — config resolution, defaults, and the argv/env builder.
+- `src/errors.ts` — `ToolError`, `serializeError`, `fsError`, and the `ErrorCode` union.
+- `src/tools/` — the nine tool handlers plus the registry (`registry.ts`) and `ToolDef` type.
+- `src/lib/` — the shared primitives: path confinement, text decode/encode, the edit match cascade,
+  atomic writes, the two search backends, and output bounding/spill.
+- `tests/` — `contract/` (one file per tool) and `integration/` (cross-cutting) suites, with
+  `helpers/fixtures.ts`.
+
+For the architecture and per-subsystem internals, see [`docs-internal/`](docs-internal/). User-facing
+docs live in [`docs/`](docs/) and the canonical per-tool contract in [`SPEC.md`](SPEC.md).
+
+## Guidelines
+
+- **Match the surrounding style.** The codebase is strict TypeScript with `noUncheckedIndexedAccess`;
+  prefer explicit, narrow types over `any`/casts. **No JSDoc or inline comments** unless a
+  lint/quality rule requires them.
+- **Add tests** for behavior changes. `tests/contract/` guards each tool's input/output/error
+  contract; `tests/integration/` guards cross-cutting behavior (the public API, surface selection,
+  statelessness). Changing a tool contract means updating its contract test, [`SPEC.md`](SPEC.md), and
+  `docs/reference/tools.md` together.
+- **Keep the two grep backends in agreement.** Any change to matching, context, or globbing must land
+  in both the ripgrep and in-process paths and be covered by `tests/integration/grep-parity.test.ts`.
+- **Security-sensitive changes** — anything touching path confinement, `bash` / subprocess spawning,
+  atomic writes, or spill files — deserve extra scrutiny. See [SECURITY.md](SECURITY.md).
+- **Update docs** when you change a tool contract, a config option, or an observable behavior:
+  [`SPEC.md`](SPEC.md), the matching `docs/` reference page, and the matching
+  [`docs-internal/internals/`](docs-internal/internals/) page.
+
+## Reporting bugs and requesting features
+
+Open a [GitHub issue](https://github.com/getclarvis/agent-tools/issues) using the provided templates.
+For security issues, follow the private process in [SECURITY.md](SECURITY.md) instead.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 getclarvis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @clarvis/agent-tools
+
+A minimal, opinionated set of coding tools for driving an LLM agent over a
+workspace, usable as a **plain library**. It gives an agent the primitives it
+needs to read, search, edit, and run code: `read_file`, `list_dir`, `glob`,
+`grep`, `write_file`, `edit_file`, `multi_edit`, `apply_patch`, and `bash`.
+
+This package is **transport-agnostic**: it carries no built-in transport and no
+agent loop — it is the tools, and nothing else. Advertise the surface, dispatch
+the calls, and feed the results back from whatever agent loop or transport you
+build around it.
+
+> [!WARNING]
+> These tools grant **read/write access to the workspace and arbitrary shell
+> execution** with the privileges of the host process. Tool paths are **confined
+> to the workspace root by default**, but `bash` runs arbitrary commands and is
+> not sandboxed. Run it inside an OS-level sandbox. See [Security](#security).
+
+## Requirements
+
+- Node.js >= 20
+- Optional: [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on `PATH`.
+  When present, `grep` uses it; otherwise an equivalent in-process fallback is
+  used. Results are kept consistent between the two backends.
+
+## Install
+
+```sh
+npm install @clarvis/agent-tools
+```
+
+## Library usage
+
+The ergonomic entry point is `createAgentTools`. Give it a workspace root and it
+resolves a config, then lets you list and call tools:
+
+```ts
+import { createAgentTools } from "@clarvis/agent-tools";
+
+const tools = createAgentTools({ workspaceRoot: process.cwd() });
+
+// Advertise the tool surface (name / description / JSON Schema) to your model:
+tools.listTools();
+
+// Call a tool by name with its arguments:
+const res = await tools.callTool("read_file", { path: "package.json" });
+if (res.isError) {
+  const err = JSON.parse(res.text) as { error: string; message: string };
+  console.error(err.error, err.message);
+} else {
+  console.log(res.text);
+}
+```
+
+`callTool` never throws for tool-level problems — it returns
+`{ isError, text }`. On success `text` is the tool output (already bounded to
+`maxOutputBytes`); on failure `text` is a JSON error envelope
+(`{ "error": "<code>", "message": "..." , ... }`). Unknown or read-only-hidden
+tools come back as an `isError` result with code `not_found`.
+
+### Options
+
+`createAgentTools(options)` / `resolveConfig(options)` accept:
+
+| Option               | Default      | Meaning                                                                 |
+| -------------------- | ------------ | ----------------------------------------------------------------------- |
+| `workspaceRoot`      | — (required) | Base directory; relative tool paths resolve against it.                 |
+| `readOnly`           | `false`      | Expose only the non-mutating tools (`read_file`/`list_dir`/`glob`/`grep`). |
+| `confineToWorkspace` | `true`       | Reject paths that escape the workspace root (`path_escape`).             |
+| `maxOutputBytes`     | `131072`     | Per-result output cap (UTF-8 bytes); larger output is bounded.           |
+| `maxFileBytes`       | `20000000`   | Max size of an input file the text tools read; larger is rejected.      |
+| `bashTimeoutMs`      | `120000`     | Default `bash` timeout in milliseconds.                                  |
+| `bashTimeoutMaxMs`   | `600000`     | Hard ceiling a `bash` `timeout_ms` request may reach (≥ the default).    |
+| `probeRipgrep`       | probes `rg`  | Override ripgrep detection (e.g. `() => false` in tests).               |
+
+### Lower-level API
+
+The building blocks are exported too, for custom transports:
+
+```ts
+import { resolveConfig, dispatch, listTools, tools, type ToolDef } from "@clarvis/agent-tools";
+
+const config = resolveConfig({ workspaceRoot: process.cwd() });
+const { isError, text } = await dispatch("grep", { pattern: "TODO" }, config);
+```
+
+- `dispatch(name, args, config)` — validate (ajv, against each tool's JSON
+  Schema), run the handler, bound the output, serialize errors. Returns
+  `{ isError, text }`.
+- `listTools(config)` — the `{ name, description, inputSchema }[]` surface for the
+  active config (respects `readOnly`).
+- `tools` / `readOnlyTools` / `getTool` / `selectSurface` — the raw `ToolDef`
+  registry.
+- `buildConfig(argv, env)` — the argv/env config builder for a CLI or
+  long-running service (delegates to `resolveConfig`).
+- `ToolError` / `serializeError` / `ErrorCode` — the structured error contract.
+
+## Tools
+
+| Tool          | Mutating | Summary                                                            |
+| ------------- | -------- | ----------------------------------------------------------------- |
+| `read_file`   | no       | Read a text file (UTF-8/UTF-16), with line numbers, paging, tail. |
+| `list_dir`    | no       | List the entries of a directory.                                  |
+| `glob`        | no       | Find files by glob, most-recently-modified first.                 |
+| `grep`        | no       | Search file contents by regular expression (optionally multiline).|
+| `write_file`  | yes      | Create or overwrite a file (atomic).                              |
+| `edit_file`   | yes      | Replace one exact occurrence of a string in a file.              |
+| `multi_edit`  | yes      | Apply several `edit_file`-style edits to one file atomically.    |
+| `apply_patch` | yes      | Apply a unified diff (modify/create/delete/rename) atomically.   |
+| `bash`        | yes      | Run a shell command (`sh -c`) and capture stdout/stderr/exit.    |
+
+In read-only mode only `read_file`, `list_dir`, `glob`, and `grep` are exposed.
+
+See [SPEC.md](./SPEC.md) for the full per-tool contract (inputs, behavior, and
+error codes).
+
+### Output bounding
+
+Every tool result is capped to `maxOutputBytes` (truncated on a UTF-8 character
+boundary, with a marker). `bash` additionally enforces a hard per-stream
+in-memory ceiling while a command runs: a command that produces unbounded output
+is killed and the call returns an `output_limit` error rather than exhausting
+memory. When `bash` output overflows the display cap, the full captured output is
+written to a `.clarvis/` spill file and the result points at it.
+
+### Input bounding
+
+The file-reading tools (`read_file`, `edit_file`, `multi_edit`, `apply_patch`,
+and the in-process `grep` backend) refuse to load a file larger than
+`maxFileBytes` (default 20 MB): the read/edit tools fail with `too_large`, and
+`grep` skips the oversized file.
+
+## Security
+
+This is the most important property of these tools, so it is stated plainly:
+
+- **Workspace-confined paths (default).** Every tool resolves paths against the
+  workspace root and, by default, refuses any path that escapes it: `../`
+  traversal, absolute paths outside the root, and symlinks inside the workspace
+  that resolve outside are rejected with `path_escape`. The existing portion of a
+  path is canonicalized with `realpath`, so symlink hops are caught. This guard
+  can be disabled with `confineToWorkspace: false`, which restores unrestricted
+  path resolution.
+- **Arbitrary command execution.** `bash` runs `sh -c <command>` with the full
+  privileges of the host process. Path confinement does **not** constrain a shell
+  command — `bash` can read, modify, and execute anything the process can,
+  regardless of the confinement setting. It is an intentional escape hatch.
+- **The threat model is the host.** Because the agent driving these tools can run
+  arbitrary commands, you must treat the process as having the same trust as the
+  code/agent connected to it. Path confinement is defense-in-depth for the file
+  tools, not a substitute for OS-level isolation.
+
+**Run it inside an OS-level sandbox** — a container, a VM, a dedicated
+low-privilege user, seccomp/AppArmor, or equivalent — scoped to the project you
+intend the agent to work in. See [SECURITY.md](./SECURITY.md) for the full trust
+model.
+
+## Documentation
+
+Full guides and reference live at
+**[agent-tools.clarvis.dev](https://agent-tools.clarvis.dev)** (source in
+[`docs/`](docs/)):
+
+- **Guide** — [getting started](https://agent-tools.clarvis.dev/getting-started),
+  [embed in an agent](https://agent-tools.clarvis.dev/guide/embed-in-an-agent),
+  [the core API](https://agent-tools.clarvis.dev/guide/the-core-api),
+  [read-only mode](https://agent-tools.clarvis.dev/guide/read-only-mode),
+  [limits & spill](https://agent-tools.clarvis.dev/guide/limits-and-spill).
+- **Reference** — [tools](https://agent-tools.clarvis.dev/reference/tools),
+  [configuration](https://agent-tools.clarvis.dev/reference/configuration),
+  [createAgentTools](https://agent-tools.clarvis.dev/reference/create-agent-tools),
+  [core API](https://agent-tools.clarvis.dev/reference/core-api),
+  [error codes](https://agent-tools.clarvis.dev/reference/error-codes).
+- **Concepts & operations** —
+  [how it works](https://agent-tools.clarvis.dev/explanation/how-it-works),
+  [path confinement](https://agent-tools.clarvis.dev/explanation/confinement),
+  [text & encoding](https://agent-tools.clarvis.dev/explanation/text-and-encoding),
+  [deploy securely](https://agent-tools.clarvis.dev/operations/deploy-securely).
+
+The canonical per-tool contract (inputs, behavior, error codes) is
+[SPEC.md](./SPEC.md).
+
+## Development
+
+```sh
+npm run build         # tsc -> dist/ (emits .d.ts)
+npm test              # vitest (contract + integration)
+npm run typecheck
+npm run lint
+npm run format:check
+npm run pre-commit    # typecheck + format:check + test
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup and
+the quality gate, [`docs-internal/`](docs-internal/) for the architecture and
+per-subsystem internals, and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). Report
+security issues privately per [SECURITY.md](./SECURITY.md).
+
+## License
+
+[MIT](./LICENSE) © Clarvis

package/SECURITY.md

@@ -0,0 +1,58 @@
+# Security Policy
+
+## Supported versions
+
+This project is pre-1.0. Security fixes are applied to the latest published `0.x` release.
+
+## Trust model
+
+`@clarvis/agent-tools` is a **library** that gives an agent read/write access to a workspace and
+**arbitrary shell execution** with the privileges of the host process. It carries no transport and no
+sandbox of its own. Two boundaries matter:
+
+- **File tools are workspace-confined by default.** `read_file`, `list_dir`, `glob`, `grep`,
+  `write_file`, `edit_file`, `multi_edit`, and `apply_patch` resolve every path against the workspace
+  root and, with `confineToWorkspace: true` (the default), reject any path that escapes it — `../`
+  traversal, an absolute path outside the root, or a symlink whose real target lies outside — with
+  `path_escape`. The existing prefix of a target path is canonicalized with `realpath`, so symlink
+  hops are caught. Writes additionally refuse to write **through** a symlink at the target itself,
+  regardless of the confinement setting.
+- **`bash` is an intentional escape hatch.** It runs `sh -c <command>` (detached, in its own process
+  group) with the full privileges of the host process. Path confinement does **not** constrain a
+  shell command — `bash` can read, modify, and execute anything the process can, whatever
+  `confineToWorkspace` is set to. Only its working directory is validated.
+
+Because the agent driving these tools can run arbitrary commands, the trust model is the **host**:
+
+> **Run `@clarvis/agent-tools` inside an OS-level sandbox** — a container, a VM, a dedicated
+> low-privilege user, seccomp/AppArmor, or equivalent — scoped to the project you intend the agent to
+> work in. Path confinement is defense-in-depth for the file tools, not a substitute for OS-level
+> isolation.
+
+### Defense-in-depth notes
+
+- **Output is bounded.** Every tool result is capped to `maxOutputBytes` (UTF-8-safe truncation). A
+  `bash` command that produces unbounded output on a single stream is killed at a per-stream capture
+  ceiling and returns `output_limit`, rather than exhausting memory.
+- **Spill files stay in-workspace.** When `bash` output overflows the display cap, the full stream is
+  written to a `.clarvis/` spill file (auto-`.gitignore`d) inside the workspace and the result points
+  at it; nothing is written outside the workspace. `sweepSpillDir()` prunes old spill files.
+- **Writes are atomic.** Mutating tools stage to a temp file, fsync, and rename, so a crash mid-write
+  never truncates the target; `apply_patch` rolls back a failed multi-file change and preserves the
+  original content in an adjacent backup if rollback itself fails.
+- **Confinement is configurable.** `confineToWorkspace: false` (or `ALLOW_OUTSIDE_WORKSPACE=1`)
+  removes the path guard for the file tools. Only disable it when the process is already sandboxed and
+  you intend the tools to reach outside the workspace.
+- **Errors don't leak internals.** A non-`ToolError` throw is logged to stderr and returned to the
+  caller only as an opaque `{ "error": "internal" }` envelope; coded `ToolError`s carry structured
+  fields (paths, sizes, bounded stdout/stderr) but no raw secrets.
+
+## Reporting a vulnerability
+
+Please report security issues **privately**. Do not open a public issue for a vulnerability.
+
+- Use GitHub's [private vulnerability reporting](https://github.com/getclarvis/agent-tools/security/advisories/new), or
+- email the maintainers at **security@clarvis.dev**.
+
+We aim to acknowledge reports within a few business days and will coordinate a fix and disclosure
+timeline with you.