# Tools Reference

<!-- DO NOT EDIT MANUALLY. Generated by scripts/build-docs-reference.mjs from packages/contracts/src/tool-schemas.ts -->


Cloud Harness MCP exposes **92 tools** across six operational domains. Every tool executes strictly inside a sandboxed, TTL-limited Docker container with non-root privileges and default network isolation.

## Security & Capability Badges

- <span class="badge-ro">readOnly</span>: Tool inspects state without mutating workspace filesystem or runtime.
- <span class="badge-destructive">destructive</span>: Tool modifies files, processes, or git state.
- `idempotent`: Calling the tool repeatedly with identical inputs yields equivalent state.
- <span class="badge-openworld">openWorld</span>: Tool may interact with network or long-running execution boundaries.

---

## Workspace Lifecycle

Tools for opening, inspecting, listing, secrets discovery, and closing isolated TTL-bound workspaces.

### `workspace_open`

**Open workspace**

Clone an approved HTTPS repository and start an owner-bound, TTL-limited coding workspace.

**Attributes:** `idempotent` · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `repositoryUrl` | `string` | **Yes** | format: `uri` |
| `ref` | `string` | No | length: 1–255 |
| `idempotencyKey` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |
| `fetchDepth` | `integer` | No | Commits of history to clone; 0 clones full history. Omitted keeps the default single-commit clone. (range: 0–100000) |
| `shallowSince` | string \| string | No | Clone history newer than this ISO date or datetime instead of a commit count. |
| `networkProfile` | `"network-none"` \| `"dependency-access"` | No | — |
| `networkMode` | `any` · **Deprecated** | No | Retired and rejected: this field was replaced by networkProfile. |
| `environmentId` | `string` | No | pattern: `^env_[A-Za-z0-9_-]{20,80}$` |
| `confirmEnvironmentInjection` | `true` | No | — |
| `toolkits` | any[] | No | default: `[]` |
| `skillSets` | object[] | No | default: `[]` |
| `skillOverrides` | `object` | No | default: `{}` |
| `allowToolkitWorkspaceChanges` | `true` | No | — |

### `workspace_list`

**List workspaces**

List owner-visible workspace records with bounded cursor pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–500, default: `100` |

### `workspace_status`

**Workspace status**

Read the lifecycle state and metadata for one workspace.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `workspace_capabilities`

**Workspace capabilities**

Inspect workspace and repository authorization capabilities (including issue and pull request operations mapped to github_action) without modifying state or minting tokens.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `workspace_context`

**Workspace context**

Read the active workspace ID, branch, lease time, Git identity, and repository overview.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `clientProfile` | `"all"` \| `"claude"` \| `"codex"` \| `"cursor"` \| `"aider"` | No | default: `"all"` |
| `include` | string[] | No | default: `["instructions","languages","test_commands","skills"]` |
| `contentMode` | `"none"` \| `"excerpt"` | No | default: `"none"` |
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–100, default: `50` |
| `maxBytes` | `integer` | No | range: 4096–131072, default: `32768` |

### `workspace_set_active`

**Set active workspace**

Set the caller preferred active workspace when multiple workspaces exist.

**Attributes:** `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | **Yes** | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `workspace_lease_renew`

**Renew workspace lease**

Explicitly renew the workspace idle lease duration or reactivate a recoverable expired workspace.

**Attributes:** `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `extensionSeconds` | `integer` | No | range: 60–86400 |

### `workspace_recover`

**Recover workspace state**

Recover a recoverable expired workspace to active state, or inspect, patch, or export unpushed work.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `mode` | `"resume"` \| `"status"` \| `"patch"` \| `"export"` | No | default: `"resume"` |
| `targetBranch` | `string` | No | length: 1–255 |

### `workspace_close`

**Close workspace**

Stop a workspace executor and permanently remove all workspace files, including unpushed commits.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `secrets_list`

**List available secrets**

List available global and environment secret names and descriptions without revealing secret values. Reference credentials by name in commands.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `environmentId` | `string` | No | pattern: `^env_[A-Za-z0-9_-]{20,80}$` |
| `query` | `string` | No | max length: 200 |
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–500, default: `100` |

## Files and Code Intelligence

Tools for navigating directory trees, reading/writing files, structural search, and symbol analysis.

### `files_list`

**List files**

List one workspace directory with bounded cursor pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | No | length: 1–1024, default: `"."` |
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–500, default: `100` |

### `files_read`

**Read file**

Read a bounded byte range from a workspace file with its size, SHA-256, and continuation cursor.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | **Yes** | length: 1–1024 |
| `offset` | `integer` | No | range: 0–9007199254740991, default: `0` |
| `limit` | `integer` | No | range: 1–1048576, default: `65536` |
| `cursor` | `string` | No | max length: 256 |
| `readAll` | `boolean` | No | — |

### `files_write`

**Write file**

Atomically create or replace a workspace file, optionally guarded by its current SHA-256.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | **Yes** | length: 1–1024 |
| `content` | `string` | **Yes** | max length: 1048576 |
| `expectedSha256` | `string` | No | length: 64–64 |

### `files_write_batch`

**Write batch files**

Atomically write multiple workspace files in one call, automatically creating missing parent directories.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `files` | object[] | **Yes** | — |
| `createParents` | `boolean` | No | default: `true` |
| `atomic` | `boolean` | No | default: `true` |
| `idempotencyKey` | `string` | No | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |

### `files_apply_patch`

**Apply text patch**

Replace one unique exact text occurrence, optionally guarded by the file SHA-256.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | **Yes** | length: 1–1024 |
| `oldText` | `string` | **Yes** | max length: 262144 |
| `newText` | `string` | **Yes** | max length: 262144 |
| `expectedSha256` | `string` | No | length: 64–64 |

### `files_delete`

**Delete file or directory**

Delete one workspace file or directory, with explicit recursion and optional file hash guard.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | **Yes** | length: 1–1024 |
| `recursive` | `boolean` | No | default: `false` |
| `expectedSha256` | `string` | No | length: 64–64 |

### `files_move`

**Move file or directory**

Move or rename one workspace entry, optionally overwriting an existing file.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `source` | `string` | **Yes** | length: 1–1024 |
| `destination` | `string` | **Yes** | length: 1–1024 |
| `overwrite` | `boolean` | No | default: `false` |

### `files_mkdir`

**Create directory**

Create one workspace directory, including missing parents by default.

**Attributes:** `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | **Yes** | length: 1–1024 |
| `recursive` | `boolean` | No | default: `true` |

### `grep_search`

**Search workspace**

Search workspace text with a bounded regular expression and optional path, glob filter, and continuation cursor.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `pattern` | `string` | **Yes** | length: 1–4096 |
| `path` | `string` | No | length: 1–1024, default: `"."` |
| `glob` | `string` | No | max length: 512 |
| `maxResults` | `integer` | No | range: 1–500, default: `100` |

### `symbols_search`

**Find symbol definitions**

Find bounded indexed symbol definitions by case-insensitive substring.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `query` | `string` | **Yes** | length: 1–256 |
| `path` | `string` | No | length: 1–1024, default: `"."` |
| `language` | `string` | No | pattern: `^[A-Za-z0-9_+#.-]{1,40}$` |
| `maxResults` | `integer` | No | range: 1–500, default: `100` |

### `symbols_references`

**Find lexical symbol references**

Find bounded lexical whole-word occurrences of a symbol in workspace text.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `symbol` | `string` | **Yes** | length: 1–256 |
| `path` | `string` | No | length: 1–1024, default: `"."` |
| `glob` | `string` | No | max length: 512 |
| `maxResults` | `integer` | No | range: 1–500, default: `100` |

## Commands and Shells

Tools for running isolated non-root commands, operations, and persistent interactive PTY shell sessions.

### `exec_run`

**Run command**

Run one bounded shell command in the workspace and return captured output.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `command` | `string` | **Yes** | length: 1–32768 |
| `cwd` | `string` | No | length: 1–1024, default: `"."` |
| `timeoutMs` | `integer` | No | range: 100–300000, default: `60000` |
| `maxOutputBytes` | `integer` | No | range: 1024–1048576, default: `262144` |
| `privileged` | `boolean` | No | default: `false` |
| `approvalGrantToken` | `string` | No | length: 1–128 |
| `async` | `boolean` | No | default: `false` |

### `shell_open`

**Open shell**

Open an idempotent ephemeral interactive shell in the workspace.

**Attributes:** `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `cwd` | `string` | No | length: 1–1024, default: `"."` |
| `idempotencyKey` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |

### `shell_io`

**Use shell**

Send input to or poll bounded output from an open interactive shell.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `shellId` | `string` | **Yes** | pattern: `^sh_[A-Za-z0-9_-]{20,80}$` |
| `input` | `string` | No | max length: 65536 |
| `cursor` | `string` | No | max length: 256 |
| `waitMs` | `integer` | No | range: 0–5000, default: `100` |

### `shell_close`

**Close shell**

Terminate an interactive shell and release its in-memory state.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `shellId` | `string` | **Yes** | pattern: `^sh_[A-Za-z0-9_-]{20,80}$` |

### `operation_status`

**Read operation status**

Query the execution state, progress, and terminal result of a long-running operation.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `operationId` | `string` | **Yes** | pattern: `^op_[A-Za-z0-9_-]{20,80}$` |
| `cursor` | `string` | No | max length: 256 |

### `operation_cancel`

**Cancel operation**

Cancel an in-flight long-running operation.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `operationId` | `string` | **Yes** | pattern: `^op_[A-Za-z0-9_-]{20,80}$` |

### `operation_wait`

**Wait for operation**

Wait for a long-running operation to reach a terminal state with a timeout.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `operationId` | `string` | **Yes** | pattern: `^op_[A-Za-z0-9_-]{20,80}$` |
| `timeoutMs` | `integer` | No | range: 100–300000, default: `60000` |

## Sessions and Tasks

Tools for long-running agent sessions and directed acyclic task graph workflows.

### `sessions_list`

**List coding sessions**

List named coding sessions in a workspace with bounded cursor pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–500, default: `100` |

### `sessions_open`

**Open coding session**

Open an idempotent named coding session in the workspace.

**Attributes:** `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,80}$` |
| `cwd` | `string` | No | length: 1–1024, default: `"."` |
| `idempotencyKey` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |

### `sessions_io`

**Use coding session**

Send input to or poll bounded output from a named coding session.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `sessionId` | `string` | **Yes** | pattern: `^sess_[A-Za-z0-9_-]{20,80}$` |
| `input` | `string` | No | max length: 65536 |
| `cursor` | `string` | No | max length: 256 |
| `waitMs` | `integer` | No | range: 0–5000, default: `100` |

### `sessions_close`

**Close coding session**

Terminate a coding session and release its in-memory state.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `sessionId` | `string` | **Yes** | pattern: `^sess_[A-Za-z0-9_-]{20,80}$` |

### `tasks_list`

**List tasks**

List managed background task records with bounded cursor pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–500, default: `100` |

### `tasks_run`

**Run task**

Start an idempotent managed command task with optional task dependencies.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent` · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `command` | `string` | **Yes** | length: 1–32768 |
| `cwd` | `string` | No | length: 1–1024, default: `"."` |
| `idempotencyKey` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |
| `timeoutMs` | `integer` | No | range: 100–86400000, default: `900000` |
| `dependsOn` | string[] | No | default: `[]` |

### `tasks_status`

**Task status**

Read one managed task state and its next bounded output chunk.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `taskId` | `string` | **Yes** | pattern: `^task_[A-Za-z0-9_-]{20,80}$` |
| `cursor` | `string` | No | max length: 256 |

### `tasks_cancel`

**Cancel task**

Terminate a managed task process group without rolling back completed effects.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `taskId` | `string` | **Yes** | pattern: `^task_[A-Za-z0-9_-]{20,80}$` |

### `tasks_graph`

**Read task dependency graph**

Read the current managed-task dependency graph for a workspace.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

## Git and Worktrees

Local repository version control, branch management, worktree isolation, Git identity, and credential-isolated origin transfer.

### `git_status`

**Git status**

Read branch, index, and working-tree status for the workspace repository.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `git_diff`

**Git diff**

Read a bounded staged or unstaged Git diff with cursor pagination and readAll convenience.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `staged` | `boolean` | No | default: `false` |
| `path` | `string` | No | length: 1–1024 |
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–500000, default: `65536` |
| `readAll` | `boolean` | No | — |

### `git_log`

**Git log**

Read bounded recent commit metadata from the workspace repository with cursor pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `limit` | `integer` | No | range: 1–500, default: `20` |
| `cursor` | `string` | No | max length: 256 |
| `readAll` | `boolean` | No | — |

### `git_branch`

**Manage Git branches**

List, create, or delete a local Git branch with constrained ref arguments.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `action` | `"list"` \| `"create"` \| `"delete"` | **Yes** | — |
| `name` | `string` | No | length: 1–255 |
| `startPoint` | `string` | No | length: 1–255 |
| `force` | `boolean` | No | default: `false` |

### `git_checkout`

**Checkout Git ref**

Check out an existing Git ref or create and check out a local branch.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `ref` | `string` | **Yes** | length: 1–255 |
| `create` | `boolean` | No | default: `false` |

### `git_add`

**Stage Git changes**

Stage either explicit workspace paths or all tracked and untracked changes.

**Attributes:** `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `all` | `boolean` | No | default: `false` |
| `paths` | string[] | No | default: `[]` |

### `git_commit`

**Create Git commit**

Create an unsigned local Git commit with default or explicit author and message.

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `message` | `string` | **Yes** | length: 1–10000 |
| `authorName` | `string` | No | length: 1–200 |
| `authorEmail` | `string` | No | format: `email`, pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$` |
| `all` | `boolean` | No | default: `false` |
| `expectedHeadOid` | `string` | No | pattern: `^(?:[0-9a-f]{40}|[0-9a-f]{64})$` |
| `idempotencyKey` | `string` | No | length: 1–256 |

### `git_identity_status`

**Read Git author identity**

Read the default or configured Git author name and email for the workspace.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `git_identity_set`

**Set Git author identity**

Configure default Git author name and email for workspace commits.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | length: 1–200 |
| `email` | `string` | **Yes** | format: `email`, pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$` |

### `workspace_finalize`

**Finalize workspace commit and push**

Transactionally stage changes, run preflights, commit with default or explicit identity, and push to remote in one call.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent` · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `paths` | string[] | No | — |
| `all` | `boolean` | No | default: `true` |
| `commitMessage` | `string` | **Yes** | length: 1–10000 |
| `branch` | `string` | No | length: 1–255 |
| `push` | `boolean` | No | default: `true` |
| `authorName` | `string` | No | length: 1–200 |
| `authorEmail` | `string` | No | format: `email`, pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$` |
| `preflight` | `object` | No | — |
| `idempotencyKey` | `string` | No | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |

### `git_fetch`

**Fetch Git refs**

Fetch a constrained source ref from origin through the trusted repository broker.

**Attributes:** <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `remote` | `"origin"` | No | default: `"origin"` |
| `refspec` | `string` | No | length: 1–255 |
| `depth` | `integer` | No | Deepen history to this many commits from each fetched tip. (range: 1–100000) |
| `unshallow` | `boolean` | No | Fetch the complete history of a shallow workspace. |
| `shallowSince` | string \| string | No | Deepen history back to this ISO date or datetime. |

### `git_pull`

**Pull Git changes**

Integrate an origin branch using ff-only, merge, or rebase strategy.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `remote` | `"origin"` | No | default: `"origin"` |
| `branch` | `string` | No | length: 1–255 |
| `strategy` | `"ff-only"` \| `"merge"` \| `"rebase"` | No | default: `"ff-only"` |

### `git_push`

**Push Git changes**

Push a constrained branch refspec to origin, with optional explicit force-with-lease.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `remote` | `"origin"` | No | default: `"origin"` |
| `refspec` | `string` | No | length: 1–512 |
| `forceWithLease` | `boolean` | No | default: `false` |
| `expectedRemoteOid` | `string` | No | pattern: `^(?:[0-9a-f]{40}|[0-9a-f]{64})$` |
| `idempotencyKey` | `string` | No | length: 1–256 |

### `git_merge`

**Merge Git ref**

Merge a Git ref with an explicit fast-forward policy and optional message.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `ref` | `string` | **Yes** | length: 1–255 |
| `fastForward` | `"allow"` \| `"only"` \| `"never"` | No | default: `"allow"` |
| `message` | `string` | No | length: 1–10000 |

### `git_rebase`

**Manage Git rebase**

Start, continue, or abort a local Git rebase with constrained ref arguments.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `action` | `"start"` \| `"continue"` \| `"abort"` | **Yes** | — |
| `upstream` | `string` | No | length: 1–255 |

### `worktrees_list`

**List worktrees**

List managed Git worktrees and their current branch or HEAD state.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `worktrees_create`

**Create worktree**

Create a named managed worktree, optionally with a new local branch.

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,80}$` |
| `ref` | `string` | **Yes** | length: 1–255 |
| `createBranch` | `boolean` | No | default: `false` |

### `worktrees_remove`

**Remove worktree**

Remove one named managed worktree, optionally discarding dirty state.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,80}$` |
| `force` | `boolean` | No | default: `false` |

### `github_action`

**Create and manage GitHub issues, pull requests, and labels**

Create GitHub issues (action: "issue_create"), list, view, comment on, update, and publish issues, manage labels, and list, view, create, update, and comment on pull requests in the repository bound to an owner-authorized workspace. Maps to advertised capabilities like operations.issueCreate, issueComment, and pullRequestCreate. Supported actions: issue_create, issue_list, issue_view, issue_comment, issue_comment_update, issue_update, issue_publish, label_create, issue_labels_add, issue_labels_remove, pr_list, pr_view, pr_create, pr_update, pr_comment, commit_list, compare, release_list, tag_list. Prefer github_read for read-only actions: this tool is annotated destructive, so clients may ask for approval on every call. Uses broker-managed GitHub App credentials via an ephemeral helper; GitHub tokens are never exposed to the workspace.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `action` | `"pr_list"` \| `"pr_view"` \| `"issue_list"` \| `"issue_view"` \| `"commit_list"` \| `"compare"` \| `"release_list"` \| `"tag_list"` \| `"pr_create"` \| `"pr_update"` \| `"pr_comment"` \| `"issue_create"` \| `"issue_comment"` \| `"issue_comment_update"` \| `"label_create"` \| `"issue_labels_add"` \| `"issue_labels_remove"` \| `"issue_update"` \| `"issue_publish"` | **Yes** | — |
| `limit` | `integer` | No | range: 1–250 |
| `state` | `"open"` \| `"closed"` \| `"all"` | No | — |
| `prNumber` | `integer` | No | range: 0–9007199254740991 |
| `issueNumber` | `integer` | No | range: 0–9007199254740991 |
| `commentId` | `integer` | No | range: 0–9007199254740991 |
| `title` | `string` | No | length: 1–256 |
| `body` | `string` | No | max length: 65536 |
| `head` | `string` | No | length: 1–256 |
| `base` | `string` | No | length: 1–256 |
| `draft` | `boolean` | No | — |
| `labels` | string[] | No | — |
| `assignees` | string[] | No | — |
| `name` | `string` | No | length: 1–100 |
| `color` | `string` | No | pattern: `^[0-9A-Fa-f]{6}$` |
| `description` | `string` | No | max length: 200 |
| `label` | `string` | No | length: 1–100 |
| `createMissing` | `boolean` | No | — |
| `createMissingLabels` | `boolean` | No | — |
| `stateReason` | `"completed"` \| `"not_planned"` \| `"reopened"` | No | — |
| `comment` | `string` | No | max length: 65536 |
| `addLabels` | string[] | No | — |
| `removeLabels` | string[] | No | — |
| `sha` | `string` | No | length: 1–255 |
| `path` | `string` | No | length: 1–1024 |
| `since` | string \| string | No | — |
| `until` | string \| string | No | — |
| `idempotencyKey` | `string` | No | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |

## Repository Extensions

Skills execution, workspace hooks, persistent memory, and repository-defined deployment operations.

### `skills_list`

**List skills**

List repository-provided agent skills discovered in the workspace.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `limit` | `integer` | No | range: 1–100, default: `50` |
| `cursor` | `string` | No | max length: 256 |
| `includeShadowed` | `boolean` | No | default: `true` |

### `skills_read`

**Read skill**

Read bounded instructions for one repository-provided agent skill.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]{1,120}$` |
| `source` | `"built-in"` \| `"owner"` \| `"workspace"` \| `"repository"` | No | — |
| `expectedSha256` | `string` | No | length: 64–64 |
| `offset` | `integer` | No | range: 0–9007199254740991, default: `0` |
| `limit` | `integer` | No | range: 1–262144, default: `65536` |

### `skills_run`

**Run skill script**

Execute one reviewed script packaged by a repository-provided skill.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]{1,120}$` |
| `source` | `"built-in"` \| `"owner"` \| `"workspace"` \| `"repository"` | No | — |
| `script` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,120}$` |
| `args` | string[] | No | default: `[]` |
| `timeoutMs` | `integer` | No | range: 100–300000, default: `60000` |
| `expectedSha256` | `string` | No | length: 64–64 |
| `expectedContentSha256` | `string` | No | length: 64–64 |
| `approvalGrantToken` | `string` | No | length: 1–128 |

### `hooks_list`

**List hooks**

List repository-defined Cloud Harness automation hooks without running them.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `event` | `"on_workspace_open"` \| `"post_checkout"` \| `"pre_commit"` \| `"post_commit"` \| `"manual"` | No | — |
| `includeInactive` | `boolean` | No | default: `false` |
| `limit` | `integer` | No | range: 1–100, default: `50` |
| `cursor` | `string` | No | max length: 256 |

### `hooks_run`

**Run hook**

Execute one named repository-defined hook as a bounded shell command.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,120}$` |
| `event` | `"on_workspace_open"` \| `"post_checkout"` \| `"pre_commit"` \| `"post_commit"` \| `"manual"` | No | — |
| `expectedSha256` | `string` | No | length: 64–64 |
| `expectedManifestSha256` | `string` | No | length: 64–64 |
| `timeoutMs` | `integer` | No | range: 100–300000, default: `60000` |

### `memories_list`

**List memories**

List Cloud Harness memory note names across owner, repository, and workspace scopes.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `scope` | `"owner"` \| `"repository"` \| `"workspace"` | No | — |
| `tags` | string[] | No | — |
| `limit` | `integer` | No | range: 1–100, default: `50` |
| `cursor` | `string` | No | max length: 256 |

### `memories_read`

**Read memory**

Read one bounded Cloud Harness memory note by name or ID.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `scope` | `"owner"` \| `"repository"` \| `"workspace"` | No | — |
| `name` | `string` | No | pattern: `^[A-Za-z0-9._-]{1,120}$` |
| `memoryId` | `string` | No | pattern: `^mem_[A-Za-z0-9_-]{10,80}$` |

### `memories_write`

**Write memory**

Create or replace one scoped Cloud Harness memory note with optimistic concurrency.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `scope` | `"owner"` \| `"repository"` \| `"workspace"` | No | default: `"workspace"` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,120}$` |
| `content` | `string` | **Yes** | max length: 262144 |
| `tags` | string[] | No | default: `[]` |
| `retentionSeconds` | `integer` | No | range: 60–31536000 |
| `expectedGeneration` | `integer` | No | range: 0–9007199254740991, default: `0` |
| `idempotencyKey` | `string` | No | length: 1–256 |

### `deployments_list`

**List deployment targets**

List repository-defined deployment targets without running them.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `deployments_run`

**Run deployment target**

Execute one named repository-defined deployment target with external-effect risk.

**Attributes:** <span class="badge-destructive">destructive</span> · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `name` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,120}$` |
| `timeoutMs` | `integer` | No | range: 100–300000, default: `60000` |

## Retained Artifacts

Tools for snapshotting workspace files, listing, reading bounded ranges, restoring into workspaces, and deleting retained artifacts.

### `artifacts_snapshot`

**Preserve workspace file snapshot**

Preserve one workspace file as a principal-owned, TTL-retained artifact snapshot.

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | **Yes** | length: 1–1024 |
| `logicalName` | `string` | **Yes** | pattern: `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` |
| `retentionSeconds` | `integer` | No | range: 60–2592000 |

### `artifacts_list`

**List retained artifacts**

List principal-owned retained artifact snapshots with bounded pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `cursor` | `string` | No | max length: 256 |
| `limit` | `integer` | No | range: 1–100, default: `50` |

### `artifacts_read`

**Read retained artifact chunk**

Read a bounded base64 byte chunk from a principal-owned retained artifact with hash and EOF verification.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `artifactId` | `string` | **Yes** | pattern: `^art_[A-Za-z0-9_-]{20,80}$` |
| `offset` | `integer` | No | range: 0–9007199254740991, default: `0` |
| `limit` | `integer` | No | range: 1–1048576, default: `65536` |

### `artifacts_restore`

**Restore artifact to workspace**

Restore an unexpired principal-owned artifact into an active workspace file with overwrite protection.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `artifactId` | `string` | **Yes** | pattern: `^art_[A-Za-z0-9_-]{20,80}$` |
| `path` | `string` | **Yes** | length: 1–1024 |
| `overwrite` | `boolean` | No | default: `false` |
| `expectedSha256` | `string` | No | length: 64–64 |

### `artifacts_delete`

**Delete retained artifact**

Delete a principal-owned retained artifact snapshot before its retention expiry.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `artifactId` | `string` | **Yes** | pattern: `^art_[A-Za-z0-9_-]{20,80}$` |
| `expectedGeneration` | `integer` | No | range: 0–9007199254740991, default: `1` |

## Additional Tools

### `skill_suggest`

**Suggest a skill**

Suggest at most one skill from the workspace roster for a prompt. When an integration key is configured, the redacted prompt is sent to the configured TypeSafe endpoint; the answer is a skill name, never model prose.

**Attributes:** <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `prompt` | `string` | **Yes** | min length: 1 |
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |

### `hooks_activate`

**Activate lifecycle hooks**

Explicitly activate reviewed lifecycle hooks for a workspace by exact manifest digest.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `manifestSha256` | `string` | **Yes** | length: 64–64 |
| `events` | string[] | **Yes** | — |
| `retentionSeconds` | `integer` | No | range: 60–2592000 |

### `hooks_deactivate`

**Deactivate lifecycle hooks**

Deactivate enrolled lifecycle hooks for a workspace.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `events` | string[] | No | — |

### `memories_search`

**Search memories**

Search scoped memory notes by literal text query and tag filters with bounded pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `query` | `string` | **Yes** | length: 1–512 |
| `scope` | `"owner"` \| `"repository"` \| `"workspace"` | No | — |
| `tags` | string[] | No | — |
| `tagMatch` | `"all"` \| `"any"` | No | default: `"all"` |
| `limit` | `integer` | No | range: 1–50, default: `20` |
| `cursor` | `string` | No | max length: 256 |

### `memories_delete`

**Delete memory note**

Delete one scoped memory note with generation guard.

**Attributes:** <span class="badge-destructive">destructive</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `memoryId` | `string` | No | pattern: `^mem_[A-Za-z0-9_-]{10,80}$` |
| `name` | `string` | No | pattern: `^[A-Za-z0-9._-]{1,120}$` |
| `scope` | `"owner"` \| `"repository"` \| `"workspace"` | No | — |
| `expectedGeneration` | `integer` | No | range: 0–9007199254740991, default: `1` |

### `knowledge_create`

**Create knowledge note or journal**

Create a new scoped memory or chronological journal entry in the control plane with CAS generation 0.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `kind` | `"memory"` \| `"journal"` | No | default: `"memory"` |
| `scope` | `"owner"` \| `"project"` \| `"workspace"` | No | default: `"workspace"` |
| `projectId` | `string` | No | pattern: `^prj_[A-Za-z0-9_-]{20,80}$` |
| `title` | `string` | **Yes** | length: 1–120 |
| `content` | `string` | **Yes** | max length: 262144 |
| `journalType` | `"engineering-log"` \| `"decision-record"` \| `"session-reflection"` | No | — |
| `occurredAt` | `integer` | No | range: 0–9007199254740991 |
| `tags` | string[] | No | default: `[]` |
| `retentionSeconds` | `integer` | No | range: 60–31536000 |
| `expectedGeneration` | `integer` | No | range: 0–9007199254740991, default: `0` |
| `idempotencyKey` | `string` | No | length: 1–256 |

### `knowledge_read`

**Read knowledge item**

Read one scoped knowledge item by stable ID with metadata, tags, and link relationships.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `id` | `string` | **Yes** | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |

### `knowledge_update`

**Update knowledge item**

Atomically update title, content, or metadata of one knowledge item with CAS expectedGeneration.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `id` | `string` | **Yes** | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |
| `title` | `string` | No | length: 1–120 |
| `content` | `string` | No | max length: 262144 |
| `journalType` | `"engineering-log"` \| `"decision-record"` \| `"session-reflection"` | No | — |
| `occurredAt` | `integer` | No | range: 0–9007199254740991 |
| `tags` | string[] | No | — |
| `retentionSeconds` | `integer` | No | range: 60–31536000 |
| `expectedGeneration` | `integer` | **Yes** | range: 0–9007199254740991 |

### `knowledge_delete`

**Delete knowledge item**

Soft-delete one knowledge item by ID with generation guard.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `id` | `string` | **Yes** | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |
| `expectedGeneration` | `integer` | **Yes** | range: 0–9007199254740991 |

### `knowledge_list`

**List knowledge items**

List knowledge items across scopes with project, journal-type, tag, and date filters.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `kind` | `"memory"` \| `"journal"` | No | — |
| `scope` | `"owner"` \| `"project"` \| `"workspace"` | No | — |
| `projectId` | `string` | No | pattern: `^prj_[A-Za-z0-9_-]{20,80}$` |
| `journalType` | `"engineering-log"` \| `"decision-record"` \| `"session-reflection"` | No | — |
| `tags` | string[] | No | — |
| `tagMatch` | `"all"` \| `"any"` | No | default: `"all"` |
| `limit` | `integer` | No | range: 1–100, default: `50` |
| `cursor` | `string` | No | max length: 256 |

### `knowledge_search`

**Hybrid search knowledge items**

Perform hybrid search combining FTS5 lexical matching and semantic vector similarity with 0–100 relevance scoring.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `query` | `string` | **Yes** | length: 1–512 |
| `kinds` | string[] | No | — |
| `scope` | `"owner"` \| `"project"` \| `"workspace"` | No | — |
| `projectId` | `string` | No | pattern: `^prj_[A-Za-z0-9_-]{20,80}$` |
| `journalType` | `"engineering-log"` \| `"decision-record"` \| `"session-reflection"` | No | — |
| `tags` | string[] | No | — |
| `tagMatch` | `"all"` \| `"any"` | No | default: `"all"` |
| `limit` | `integer` | No | range: 1–50, default: `20` |
| `cursor` | `string` | No | max length: 256 |

### `knowledge_link`

**Link knowledge items**

Create a typed relationship link between two knowledge items.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `sourceId` | `string` | **Yes** | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |
| `targetId` | `string` | **Yes** | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |
| `relation` | `"relates-to"` \| `"references"` \| `"supports"` \| `"contradicts"` \| `"supersedes"` | No | default: `"relates-to"` |
| `expectedGeneration` | `integer` | No | range: 0–9007199254740991, default: `0` |

### `knowledge_unlink`

**Unlink knowledge items**

Remove a relationship link between two knowledge items.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `linkId` | `string` | No | pattern: `^knl_[A-Za-z0-9_-]{10,80}$` |
| `sourceId` | `string` | No | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |
| `targetId` | `string` | No | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |
| `relation` | `"relates-to"` \| `"references"` \| `"supports"` \| `"contradicts"` \| `"supersedes"` | No | — |
| `expectedGeneration` | `integer` | No | range: 0–9007199254740991 |

### `knowledge_graph`

**Query knowledge neighborhood graph**

Traverse and query the bounded neighborhood knowledge graph for a root node.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `rootId` | `string` | No | pattern: `^kn_[A-Za-z0-9_-]{10,80}$` |
| `depth` | `integer` | No | range: 1–3, default: `1` |
| `maxNodes` | `integer` | No | range: 1–200, default: `50` |
| `kinds` | string[] | No | — |
| `projectId` | `string` | No | pattern: `^prj_[A-Za-z0-9_-]{20,80}$` |

### `github_read`

**Read GitHub pull requests, issues, commits, comparisons, releases, and tags**

Read-only GitHub access for the repository bound to an owner-authorized workspace, without per-call approval prompts. Supported actions: pr_list, pr_view, issue_list, issue_view, commit_list (history with sha, path, since, until filters), compare (base...head commits and changed files), release_list, tag_list. Maps to operations.pullRequestList, pullRequestView, issueList, issueView, commitList, compare, releaseList, and tagList. Uses broker-managed GitHub App credentials via an ephemeral helper; GitHub tokens are never exposed to the workspace.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent` · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `action` | `"pr_list"` \| `"pr_view"` \| `"issue_list"` \| `"issue_view"` \| `"commit_list"` \| `"compare"` \| `"release_list"` \| `"tag_list"` | **Yes** | — |
| `limit` | `integer` | No | range: 1–250 |
| `state` | `"open"` \| `"closed"` \| `"all"` | No | — |
| `prNumber` | `integer` | No | range: 0–9007199254740991 |
| `issueNumber` | `integer` | No | range: 0–9007199254740991 |
| `sha` | `string` | No | length: 1–255 |
| `path` | `string` | No | length: 1–1024 |
| `since` | string \| string | No | — |
| `until` | string \| string | No | — |
| `base` | `string` | No | length: 1–255 |
| `head` | `string` | No | length: 1–255 |

### `agent_spawn`

**Spawn coding agent**

Spawn an owner-bound, budgeted Pi coding-agent subagent in an isolated container.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent` · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `prompt` | `string` | **Yes** | min length: 1 |
| `idempotencyKey` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |
| `profileId` | `string` | **Yes** | pattern: `^[A-Za-z0-9._-]{1,80}$` |
| `parentAgentId` | `string` | No | pattern: `^agent_[A-Za-z0-9_-]{20,80}$` |
| `proxyOperations` | string[] | **Yes** | — |
| `ttlSeconds` | `integer` | No | range: 30–86400, default: `900` |
| `maxOutputBytes` | `integer` | No | range: 1024–10485760, default: `262144` |
| `maxInputTokens` | `integer` | No | range: 1–2000000, default: `200000` |
| `maxOutputTokens` | `integer` | No | range: 1–2000000, default: `32000` |
| `maxCostMicros` | `integer` | No | range: 0–1000000000, default: `10000000` |

### `agent_status`

**Read coding agent status**

Read the execution state, budgets, and terminal summary of one coding agent.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `agentId` | `string` | No | pattern: `^agent_[A-Za-z0-9_-]{20,80}$` |
| `idempotencyKey` | `string` | No | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |

### `agent_logs`

**Read coding agent logs**

Read bounded streaming diagnostic and tool events from one coding agent.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `agentId` | `string` | **Yes** | pattern: `^agent_[A-Za-z0-9_-]{20,80}$` |
| `cursor` | `string` | No | pattern: `^(?:0|[1-9]\d*)$`, default: `"0"` |
| `limitBytes` | `integer` | No | range: 1024–262144, default: `65536` |

### `agent_message`

**Message coding agent**

Send an idempotent steering or follow-up message to a running coding agent.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent` · <span class="badge-openworld">openWorld</span>

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `agentId` | `string` | **Yes** | pattern: `^agent_[A-Za-z0-9_-]{20,80}$` |
| `idempotencyKey` | `string` | **Yes** | pattern: `^[A-Za-z0-9._:-]+$`, length: 8–128 |
| `mode` | `"steer"` \| `"followUp"` | **Yes** | — |
| `message` | `string` | **Yes** | min length: 1 |

### `agent_cancel`

**Cancel coding agent**

Cancel an in-flight coding agent and cascade cancellation to all its child agents.

**Attributes:** <span class="badge-destructive">destructive</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `agentId` | `string` | **Yes** | pattern: `^agent_[A-Za-z0-9_-]{20,80}$` |
| `reason` | `string` | No | max length: 2000 |

### `agent_list`

**List coding agents**

List coding agents in a workspace with bounded pagination.

**Attributes:** <span class="badge-ro">readOnly</span> · `idempotent`

| Parameter | Type | Required | Constraints & Notes |
|---|---|---|---|
| `workspaceId` | `string` | No | pattern: `^ws_[A-Za-z0-9_-]{20,80}$` |
| `parentAgentId` | `string` | No | pattern: `^agent_[A-Za-z0-9_-]{20,80}$` |
| `status` | `"SPAWNING"` \| `"RUNNING"` \| `"CANCELLING"` \| `"SUCCEEDED"` \| `"FAILED"` \| `"CANCELLED"` \| `"TIMED_OUT"` \| `"LIMIT_EXCEEDED"` \| `"INTERRUPTED"` | No | — |
| `cursor` | `string` | No | pattern: `^[1-9]\d*$` |
| `limit` | `integer` | No | range: 1–100, default: `50` |