Tools Reference

AI Crawler / Raw View: Fetch this page as raw Markdown at /reference/tools.md.

Cloud Harness MCP exposes 52 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

• readOnly: Tool inspects state without mutating workspace filesystem or runtime.
• destructive: Tool modifies files, processes, or git state.
• idempotent: Calling the tool repeatedly with identical inputs yields equivalent state.
• openWorld: Tool may interact with network or long-running execution boundaries.

---

Workspace Lifecycle

Tools for opening, inspecting, listing, 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 · openWorld

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
networkMode	"none" | "bridge"	No	—
environmentId	string	No	pattern: ^env_[A-Za-z0-9_-]{20,80}$
confirmEnvironmentInjection	true	No	—

workspace_list

List workspaces

List owner-visible workspace records with bounded cursor pagination.

Attributes: readOnly · idempotent

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

workspace_status

Workspace status

Read the lifecycle state and metadata for one workspace.

Attributes: readOnly · idempotent

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

workspace_close

Close workspace

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

Attributes: destructive · idempotent

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

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: readOnly · idempotent

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

files_read

Read file

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

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
path	string	Yes	length: 1–1024
offset	integer	Yes	range: 0–9007199254740991, default: 0
limit	integer	Yes	range: 1–262144, default: 65536

files_write

Write file

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

Attributes: destructive · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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_apply_patch

Apply text patch

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

Attributes: destructive · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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: destructive

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
path	string	Yes	length: 1–1024
recursive	boolean	Yes	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: destructive

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

files_mkdir

Create directory

Create one workspace directory, including missing parents by default.

Attributes: idempotent

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

grep_search

Search workspace

Search workspace text with a bounded regular expression and optional path or glob filter.

Attributes: readOnly · idempotent

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

symbols_search

Find symbol definitions

Find bounded indexed symbol definitions by case-insensitive substring.

Attributes: readOnly · idempotent

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

symbols_references

Find lexical symbol references

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

Attributes: readOnly · idempotent

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

Commands and Shells

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

exec_run

Run command

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

Attributes: destructive · openWorld

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

shell_open

Open shell

Open an idempotent ephemeral interactive shell in the workspace.

Attributes: idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
cwd	string	Yes	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: destructive · openWorld

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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	Yes	range: 0–5000, default: 100

shell_close

Close shell

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

Attributes: destructive · idempotent

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

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: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
cursor	string	No	max length: 256
limit	integer	Yes	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	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
name	string	Yes	pattern: ^[A-Za-z0-9._-]{1,80}$
cwd	string	Yes	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: destructive · openWorld

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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	Yes	range: 0–5000, default: 100

sessions_close

Close coding session

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

Attributes: destructive · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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: readOnly · idempotent

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

tasks_run

Run task

Start an idempotent managed command task with optional task dependencies.

Attributes: destructive · idempotent · openWorld

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

tasks_status

Task status

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

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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: destructive · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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: readOnly · idempotent

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

Git and Worktrees

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

git_status

Git status

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

Attributes: readOnly · idempotent

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

git_diff

Git diff

Read a bounded staged or unstaged Git diff, optionally narrowed to one path.

Attributes: readOnly · idempotent

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

git_log

Git log

Read bounded recent commit metadata from the workspace repository.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
limit	integer	Yes	range: 1–100, default: 20

git_branch

Manage Git branches

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

Attributes: destructive

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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	Yes	default: false

git_checkout

Checkout Git ref

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

Attributes: destructive

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
ref	string	Yes	length: 1–255
create	boolean	Yes	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	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
all	boolean	Yes	default: false
paths	string[]	Yes	default: []

git_commit

Create Git commit

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

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
message	string	Yes	length: 1–10000
authorName	string	Yes	length: 1–200
authorEmail	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,}$
all	boolean	Yes	default: false

git_fetch

Fetch Git refs

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

Attributes: openWorld

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
remote	"origin"	Yes	default: "origin"
refspec	string	No	length: 1–255

git_pull

Pull Git changes

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

Attributes: destructive · openWorld

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

git_push

Push Git changes

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

Attributes: destructive · openWorld

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

git_merge

Merge Git ref

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

Attributes: destructive

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
ref	string	Yes	length: 1–255
fastForward	"allow" | "only" | "never"	Yes	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: destructive

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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	Yes	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	Yes	default: false

worktrees_remove

Remove worktree

Remove one named managed worktree, optionally discarding dirty state.

Attributes: destructive

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

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: readOnly · idempotent

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

skills_read

Read skill

Read bounded instructions for one repository-provided agent skill.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
name	string	Yes	pattern: ^[A-Za-z0-9._:-]{1,120}$

skills_run

Run skill script

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

Attributes: destructive · openWorld

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

hooks_list

List hooks

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

Attributes: readOnly · idempotent

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

hooks_run

Run hook

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

Attributes: destructive · openWorld

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

memories_list

List memories

List repository-local Cloud Harness memory note names.

Attributes: readOnly · idempotent

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

memories_read

Read memory

Read one bounded repository-local Cloud Harness memory note.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
name	string	Yes	pattern: ^[A-Za-z0-9._-]{1,120}$

memories_write

Write memory

Create or replace one repository-local Cloud Harness memory note.

Attributes: destructive · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
name	string	Yes	pattern: ^[A-Za-z0-9._-]{1,120}$
content	string	Yes	max length: 262144

deployments_list

List deployment targets

List repository-defined deployment targets without running them.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
workspaceId	string	Yes	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: destructive · openWorld

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