# `MingaAgent.Tools`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_agent/tools.ex#L1)

Tool definitions for the native agent provider.

Each tool is a `ReqLLM.Tool` struct with a name, description, JSON Schema
parameters, and a callback that executes the operation. Tools are scoped
to the project root directory for safety: file operations refuse to escape
the project boundary.

## Available tools

| Tool              | Description                                          |
|-------------------|------------------------------------------------------|
| `read_file`       | Read file contents (supports offset/limit for slices)|
| `write_file`      | Write content to a file (creates or overwrites)      |
| `edit_file`       | Replace exact text in a file                         |
| `multi_edit_file` | Apply multiple edits to one file in a single call    |
| `list_directory`  | List files and directories at a path                 |
| `find`            | Find files by name/glob pattern                      |
| `grep`            | Search file contents for a pattern                   |
| `shell`           | Run a shell command in the project root              |
| `git_status`      | Show changed files with structured status (read-only)|
| `git_diff`        | Show unified diff for files or all changes (read-only)|
| `git_log`         | Show recent commits with structured output (read-only)|
| `git_stage`       | Stage files for commit (destructive)                 |
| `git_commit`      | Create a commit with a message (destructive)         |
| `memory_write`    | Save a learning or preference to persistent memory   |
| `diagnostics`     | Get current LSP diagnostics for a file (read-only)   |
| `definition`      | Find where a symbol is defined via LSP (read-only)   |
| `references`      | Find all usages of a symbol via LSP (read-only)      |
| `hover`           | Get type info and docs for a symbol via LSP (read-only)|
| `document_symbols`| List all symbols in a file via LSP (read-only)       |
| `workspace_symbols`| Search for symbols project-wide via LSP (read-only) |
| `rename`          | Semantic rename across the project via LSP (destructive)|
| `code_actions`    | List/apply LSP code actions (apply is destructive)   |
| `describe_runtime`| Describe the runtime's capabilities and features     |
| `describe_tools`  | List all available tools with descriptions            |

# `tools_opts`

```elixir
@type tools_opts() :: [
  project_root: String.t(),
  changeset: pid() | nil,
  fork_store: pid() | nil
]
```

Options passed to `all/1`.

# `all`

```elixir
@spec all(tools_opts()) :: [ReqLLM.Tool.t()]
```

Returns all available tools scoped to the given project root.

The `project_root` is baked into each tool's callback closure so that every
file operation is sandboxed to that directory tree.

# `destructive?`

```elixir
@spec destructive?(String.t()) :: boolean()
```

Returns true if the named tool is classified as destructive.

Reads the configured list from `:agent_destructive_tools` (defaults to
`["write_file", "edit_file", "shell"]`). Accepts an optional list override
for testing without starting the Options agent.

Some tools have conditional destructiveness based on their arguments.
Pass the tool arguments map to check parameter-dependent cases like
`code_actions` with `apply` set.

# `destructive?`

```elixir
@spec destructive?(String.t(), map()) :: boolean()
```

# `destructive?`

```elixir
@spec destructive?(String.t(), map(), [String.t()]) :: boolean()
```

# `resolve_and_validate_path!`

```elixir
@spec resolve_and_validate_path!(String.t(), String.t()) :: String.t()
```

Resolves a relative path against the project root and validates that the
resolved path does not escape the root directory.

Raises `ArgumentError` if the path escapes the project root.

---

*Consult [api-reference.md](api-reference.md) for complete listing*