Tools Reference

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

• 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, 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 · 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
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: readOnly · 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: readOnly · 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: readOnly · 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: readOnly · 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: destructive

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

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: destructive

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: readOnly · 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: readOnly · 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: readOnly · 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: destructive · openWorld

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: destructive · openWorld

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: destructive · 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: readOnly · 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: destructive · 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: readOnly · 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: readOnly · 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: destructive · openWorld

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

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

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: destructive

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

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: openWorld

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: destructive · openWorld

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: destructive · openWorld

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]
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: destructive

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: destructive

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

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: destructive · openWorld

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: readOnly · 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: readOnly · 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: destructive · openWorld

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: readOnly · 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: destructive · openWorld

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: readOnly · 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: readOnly · 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: destructive · 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: readOnly · 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: destructive · openWorld

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

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: destructive

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: openWorld

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: destructive

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: destructive

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

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

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: destructive · idempotent · openWorld

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

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