---
title: Core Tools
description: Reference for system command execution and filesystem tools in Corvus.
owner: team-runtime
status: canonical
lastReviewed: 2026-05-06
appliesTo: main
docType: reference
---

Core tools provide the foundation for agent autonomy, allowing interaction with the host operating system and the local workspace.

## `code_search`

Searches workspace files for literal or regex matches and returns both human-readable output and structured match data.

- **Security Tier:** Read-Only (Safe).
- **Execution:** Native runtime tool with optional literal-query index narrowing and mandatory live verification against current file contents.
- **Current limitation:** Regex correctness is supported, but indexed candidate narrowing does **not** support regex in v1. Regex planning falls back with `query_regex_not_supported` to discovery plus live verification.
- **Rollout evidence:** See the dedicated [`code_search` rollout page](code-search.md) for measured shell-vs-native results, fallback labels, and recommendation guidance.

### Parameters

See the dedicated [`code_search` page](code-search.md) for the full parameter contract, benchmark methodology, and rollout guidance.

---

## Parity naming map

| Canonical tool | Compatibility alias | Backing runtime surface | Notes |
| --- | --- | --- | --- |
| `Glob` | `glob` | workspace discovery helpers | additive parity alias |
| `Grep` | `grep` | `code_search` internals | `code_search` remains the retained native contract |
| `TaskCreate` | `task_create` | persistent task service | only available on SQLite memory backend |
| `TaskGet` | `task_get` | persistent task service | only available on SQLite memory backend |
| `TaskList` | `task_list` | persistent task service | deterministic created_at/id ordering |
| `TaskUpdate` | `task_update` | persistent task service | updates mutable task fields only |
| `TaskStop` | `task_stop` | persistent task service | semantic cancellation path |

---

## `Glob`

Claude-style parity tool for workspace-safe file pattern discovery.

- **Security Tier:** Read-Only (Safe).
- **Execution:** Native runtime tool backed by workspace discovery metadata helpers.
- **Contract:** Requires `pattern`; optionally scopes traversal with a workspace-relative `path`.
- **Compatibility alias:** `glob`
- **Parity note:** `Glob` is the canonical parity-facing name for this slice and is additive alongside existing native tool names.

---

## `Grep`

Claude-style parity content search backed by the same Corvus search internals used by `code_search`.

- **Security Tier:** Read-Only (Safe).
- **Execution:** Native runtime tool with deterministic workspace-relative outputs.
- **Contract:** Supports `pattern`, optional `path`, optional `glob`, and `output_mode` values `content`, `files_with_matches`, or `count`.
- **Compatibility alias:** `grep`
- **Parity note:** `Grep` is canonical for parity-facing documentation, while `code_search` remains available as the retained native contract.

---

## Task management parity

These tools provide a persistent task lifecycle backed by the runtime SQLite memory store (`brain.db`). They are only available when the active memory backend is `sqlite`.

### `TaskCreate`

Create a persistent runtime task with optional session linkage.

- **Security Tier:** Action-Bearing (Risk-bearing).
- **Compatibility alias:** `task_create`

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `title` | `string` | **Required.** Brief summary of the task. |
| `description` | `string` | Optional detailed instructions or context. |
| `priority` | `string` | Task priority: `low`, `medium`, or `high`. |
| `session_id` | `string` | Optional ID to link the task to a specific chat session. |

---

### `TaskGet`

Fetch a persistent runtime task by its unique ID.

- **Security Tier:** Read-Only (Safe).
- **Compatibility alias:** `task_get`

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | **Required.** The UUID of the task to fetch. |

---

### `TaskList`

List persistent runtime tasks with basic filters and pagination.

- **Security Tier:** Read-Only (Safe).
- **Compatibility alias:** `task_list`

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `status` | `string` | Filter by status: `pending`, `in_progress`, `completed`, or `cancelled`. |
| `priority` | `string` | Filter by priority: `low`, `medium`, or `high`. |
| `session_id` | `string` | Filter by chat session ID. |
| `limit` | `integer` | Maximum number of tasks to return (default: 10). |
| `offset` | `integer` | Number of tasks to skip for pagination (default: 0). |

---

### `TaskUpdate`

Update mutable fields on a persistent runtime task.

- **Security Tier:** Action-Bearing (Risk-bearing).
- **Compatibility alias:** `task_update`

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | **Required.** The UUID of the task to update. |
| `title` | `string` | New title for the task. |
| `description` | `string` | New description for the task. |
| `priority` | `string` | New priority: `low`, `medium`, or `high`. |
| `status` | `string` | New status: `pending`, `in_progress`, `completed`, or `cancelled`. |

---

### `TaskStop`

Cancel an active persistent runtime task.

- **Security Tier:** Action-Bearing (Risk-bearing).
- **Compatibility alias:** `task_stop`

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | **Required.** The UUID of the task to cancel. |

---

## `shell`

Executes an arbitrary shell command within the workspace directory.

- **Security Tier:** Action-Bearing (Risk-bearing).
- **Execution:** Runs via the configured [Runtime](../architecture.md#runtime) (Native or Docker).
- **Constraints:**
  - Blocked commands: Defined in `autonomy.forbidden_paths`.
  - Allowed commands: Must be in `autonomy.allowed_commands` if configured.
  - Environment: Only safe functional variables (`PATH`, `HOME`, `USER`, etc.) are passed. API keys and secrets are explicitly redacted/cleared.
  - Timeout: Defaults to 60 seconds.
  - Output limit: Truncated at 1 MB to prevent memory exhaustion.

### Parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `command` | `string` | **Required.** The shell command to execute. |
| `approved` | `boolean` | Set `true` to explicitly approve medium/high-risk commands in supervised mode. |

---

## `file_read`

Reads the contents of a file within the workspace.

- **Security Tier:** Read-Only (Safe).
- **Constraints:**
  - Path traversal (e.g., `../../etc/passwd`) is strictly blocked.
  - Symlinks that resolve outside the workspace boundary are rejected.
  - Maximum file size: 10 MB.

### Parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `path` | `string` | **Required.** Relative path to the file within the workspace. |

---

## `file_write`

Writes or overwrites a file within the workspace.

- **Security Tier:** Action-Bearing (Risk-bearing).
- **Constraints:**
  - Creates parent directories automatically if they don't exist.
  - Refuses to write through symlinks (TOCTOU protection).
  - Subject to the same path-sandboxing rules as `file_read`.

### Parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `path` | `string` | **Required.** Relative path to the file within the workspace. |
| `content` | `string` | **Required.** The content to write to the file. |
