Tools Reference

Cloud Harness MCP exposes 107 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. The result hardExpiresAt is a fixed deadline set by the instance maximum workspace lifetime that no renewal or activity extends.

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. Renewal never passes hardExpiresAt; when the requested extension would pass it, the result sets leaseCapped: true with requestedExpiresAt and a leaseWarnings entry.

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 pipe 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

bash

Run bash command

Run one bounded bash command. target "workspace" (default) uses the exec_run path in the workspace executor. target "toolbox" runs in a disposable no-network container with no workspace checkout, no secrets, and no workspaceId; it is available only when the operator enables packages. Both targets accept async: true for an operation handle. bash has no privileged mode: use exec_run with its approval flow for privileged commands.

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
target	"workspace" | "toolbox"	No	workspace runs in the workspace executor like exec_run; toolbox runs in a disposable no-network container with no checkout. (default: "workspace")
cwd	string	No	Workspace-relative directory; workspace target only. (length: 1–1024, default: ".")
timeoutMs	integer	No	range: 100–300000, default: 60000
maxOutputBytes	integer	No	range: 1024–1048576, default: 262144
async	boolean	No	Return an operation handle for operation_status, operation_wait, and operation_cancel instead of waiting. (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

Managed Packages

Plan, approve, apply, inspect, roll back, and uninstall pinned CLI packages kept across workspaces and redeploys (off unless the operator enables managed packages).

packages_plan

Plan managed package change

Resolve one managed toolbox package change into an immutable plan without installing anything and without running package code (uv accepts wheels only; npm lifecycle scripts stay off unless allowed). ecosystem "npm" or "uv" (uv tools get their own managed Python); "apt" is not supported and returns NOT_SUPPORTED because system packages need a reviewed executor image variant. scope "owner" (default) makes the tool available to all your new workspaces and the bash toolbox target; scope "workspace" needs workspaceId and overrides the owner binding there. "instance" scope does not exist. If resolution is still running after about 20 seconds, the result is { resolutionId, state: "RESOLVING" } instead: poll packages_status with that resolutionId (and waitMs) until it is READY with the plan or FAILED. The plan lists the exact version, source, integrity, dependency count, size, binaries, conflicts, affected workspaces, and planDigest. approval "required" means an operator approves the plan in the Dashboard first; "unavailable" means this instance cannot approve plans. Use for durable CLI tools; use npm install or uv in a workspace for project dependencies. Off unless the operator sets PACKAGES_ENABLED=true.

Attributes: openWorld

Parameter	Type	Required	Constraints & Notes
ecosystem	"npm" | "uv" | "apt"	Yes	—
name	string	Yes	length: 1–214
version	string	No	length: 1–128
scope	"owner" | "workspace"	No	default: "owner"
workspaceId	string	No	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
python	string	No	pattern: ^3\.\d{1,2}(\.\d{1,2})?$
lifecycleScripts	boolean	No	—

packages_apply

Apply managed package plan

Build an approved plan (planId with the exact planDigest from packages_plan) into an immutable release in an isolated builder, verify its file tree, and launch-check every binary without network. Returns an applyId immediately; poll packages_status with applyId. Replaying the same plan returns the same apply. A release is installed only when the apply reaches SUCCEEDED. Existing workspaces keep their mounted releases until they are recreated; new workspaces and the bash toolbox target use the new release.

Attributes: idempotent · openWorld

Parameter	Type	Required	Constraints & Notes
planId	string	Yes	pattern: ^pkp_[A-Za-z0-9_-]{20,80}$
planDigest	string	Yes	pattern: ^[a-f0-9]{64}$

packages_list

List managed packages

List managed package bindings (what each scope uses now) and verified releases, with versions, digests, sizes, binaries, and whether a release was built for an older executor image (stale). Set includeHistory to see earlier releases you can roll back to.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
scope	"owner" | "workspace"	No	—
workspaceId	string	No	pattern: ^ws_[A-Za-z0-9_-]{20,80}$
includeHistory	boolean	No	default: false

packages_status

Managed package status

Read a managed package apply by applyId (state, error code, bounded output tail, release id) or a plan resolution by resolutionId (RESOLVING, READY with the plan, or FAILED with its error), optionally waiting up to waitMs for it to change. Without either, summarize in-flight applies, plans waiting for approval, missing releases, and workspaces that need recreation to pick up a change.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
applyId	string	No	pattern: ^pka_[A-Za-z0-9_-]{20,80}$
resolutionId	string	No	pattern: ^pkq_[A-Za-z0-9_-]{20,80}$
waitMs	integer	No	range: 0–30000, default: 0

packages_rollback

Roll back managed package

Point a managed package binding back to an earlier verified release from its history. Needs bindingId, releaseId, and the binding generation you last read (expectedGeneration); a moved generation returns STALE_GENERATION. Needs no new approval. Workspaces pick up the change when recreated.

Attributes: destructive · idempotent

Parameter	Type	Required	Constraints & Notes
bindingId	string	Yes	pattern: ^pkb_[A-Za-z0-9_-]{20,80}$
releaseId	string	Yes	pattern: ^pkr_[A-Za-z0-9_-]{20,80}$
expectedGeneration	integer	Yes	range: 0–9007199254740991

packages_remove

Uninstall managed package

Uninstall a managed package from one scope: deletes the binding (bindingId from packages_list, with its current generation as expectedGeneration) and its rollback history, and collects releases no retained workspace still mounts. A moved generation returns STALE_GENERATION; a running apply returns CONFLICT. Needs no approval. New workspaces and the bash toolbox stop seeing the tool at once; existing workspaces keep it until recreated. Reinstalling needs a new plan.

Attributes: destructive

Parameter	Type	Required	Constraints & Notes
bindingId	string	Yes	pattern: ^pkb_[A-Za-z0-9_-]{20,80}$
expectedGeneration	integer	Yes	range: 0–9007199254740991

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 an optional atomic lease: forceWithLease with expectedRemoteOid (compare-and-swap), expectedAbsent (create only if the branch does not exist), or delete with expectedRemoteOid (delete only if the branch still points at it).

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]
expectedAbsent	boolean	No	With forceWithLease, create the destination branch only if it does not exist yet. (default: false)
delete	boolean	No	With forceWithLease and expectedRemoteOid, delete the refspec branch only if it still points at expectedRemoteOid. (default: false)
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, native PR reviews, review threads, reviewers, merges, commit statuses, and Actions workflow runs

Create GitHub issues (action: "issue_create"), list, view, comment on, update, and publish issues, manage labels, and list, view, create, update, comment on, review (native COMMENT/APPROVE/REQUEST_CHANGES reviews, inline file/line comments, review-thread reply/resolve/unresolve), assign reviewers, toggle draft/ready, merge, and auto-merge pull requests; create commit statuses on a SHA (commit_status_create: state, context, description, targetUrl); dispatch a workflow on a ref with inputs (workflow_dispatch) and re-run only the failed jobs of a run (workflow_run_rerun_failed), in the repository bound to an owner-authorized workspace. Maps to advertised capabilities like operations.issueCreate, issueComment, pullRequestCreate, pullRequestReview, pullRequestMerge, commitStatusCreate, workflowDispatch, and workflowRunRerun; workspace_capabilities.githubActions is the authoritative action list. 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_reviews, pr_review_threads, pr_create, pr_update, pr_comment, pr_review, pr_review_comment, pr_review_reply, pr_review_thread_resolve, pr_review_thread_unresolve, pr_reviewers_request, pr_reviewers_remove, pr_ready, pr_convert_to_draft, pr_merge, pr_auto_merge_enable, pr_auto_merge_disable, commit_status_create, workflow_dispatch, workflow_run_rerun_failed, commit_list, compare, release_list, tag_list, ref_get, commit_status_get, check_runs_list, workflow_runs_list, workflow_run_view. Writes that can duplicate a side effect accept an idempotencyKey. Prefer github_read for read-only actions: this tool is annotated destructive, so clients may ask for approval on every call. Atomic ref creation, compare-and-swap, and delete-if-match go through git_push leases, not this tool. 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" | "pr_review_threads" | "pr_reviews" | "issue_list" | "issue_view" | "commit_list" | "compare" | "release_list" | "tag_list" | "ref_get" | "commit_status_get" | "check_runs_list" | "workflow_runs_list" | "workflow_run_view" | "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" | "pr_review" | "pr_review_comment" | "pr_review_reply" | "pr_review_thread_resolve" | "pr_review_thread_unresolve" | "pr_reviewers_request" | "pr_reviewers_remove" | "pr_ready" | "pr_convert_to_draft" | "pr_merge" | "pr_auto_merge_enable" | "pr_auto_merge_disable" | "commit_status_create" | "workflow_dispatch" | "workflow_run_rerun_failed"	Yes	—
limit	integer	No	range: 1–250
state	string | string	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	—
event	string | string	No	—
line	integer	No	range: 0–9007199254740991
startLine	integer	No	range: 0–9007199254740991
side	"LEFT" | "RIGHT"	No	—
startSide	"LEFT" | "RIGHT"	No	—
commitId	string	No	pattern: `^(?:[0-9a-f]
threadId	string	No	pattern: ^PRRT_[A-Za-z0-9_-]{4,200}$
reviewers	string[]	No	—
teamReviewers	string[]	No	—
method	"merge" | "squash" | "rebase"	No	—
commitTitle	string	No	length: 1–256
commitBody	string	No	max length: 65536
matchHeadCommit	string	No	pattern: `^(?:[0-9a-f]
ref	string	No	length: 1–255
checkName	string	No	length: 1–255
workflow	integer | string	No	—
headSha	string	No	pattern: `^(?:[0-9a-f]
branch	string	No	length: 1–255
status	"queued" | "in_progress" | "completed" | "requested" | "waiting" | "pending" | "success" | "failure" | "cancelled" | "skipped" | "timed_out" | "action_required" | "neutral" | "stale"	No	—
runId	integer	No	range: 0–9007199254740991
context	string	No	length: 1–255
targetUrl	string	No	format: uri, max length: 2048
inputs	object	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

Models and Spend

Choose a provider and model, check a connection, save agent model profiles (created disabled; the owner activates them on the Dashboard), and read estimated model spend. Keys, activation, deletion, and spend policies stay on the Dashboard.

model_provider_list

List model providers

List the supported model providers (auth header modes, API modes and endpoints, catalog source) and your connected provider credentials as metadata (id, provider, status, key version, last check). Keys are never returned, and no tool creates, rotates, or reads one: the owner adds keys on the Dashboard. Optional provider narrows both lists.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
provider	"openai" | "anthropic" | "openrouter" | "google" | "deepseek" | "opencode-go" | "custom"	No	—

model_catalog_search

Search model catalog

Search the cached model catalog for one provider, optionally through your credential's models listing (credentialId). Prices are integer micro-USD per million tokens and are estimates; null means unknown, not free. A cold or stale cache may be filled from the provider, so the call can be slow. When saving a profile, use an entry's providerModelId as model and its pricing.provenance.sourceModelId as catalogPriceRef.sourceModelId to pin catalog-verified prices.

Attributes: readOnly · idempotent · openWorld

Parameter	Type	Required	Constraints & Notes
provider	"openai" | "anthropic" | "openrouter" | "google" | "deepseek" | "opencode-go" | "custom"	Yes	—
credentialId	string	No	pattern: ^cred_[A-Za-z0-9_-]{20,80}$
query	string	No	max length: 200
cursor	string	No	length: 1–256
limit	integer	No	range: 1–100, default: 25
capability	"tools" | "reasoning" | "vision"	No	—

model_connection_verify

Check model connection

Check a saved profile (profileId) or a draft route on a stored credential (credentialId with model, apiMode, and customUpstreamUrl for a Custom credential) with bounded probes: authentication, model access, streaming inference, and an opt-in tool call. It spends a few tokens, shares the per-principal rate limit with the Dashboard, and is audited. A draft that names a model returns verificationRef; pass it to model_profile_validate and model_profile_create or model_profile_update with the same route to keep the result. Over MCP, a custom upstream URL must already be used by one of your profiles on that credential, else OWNER_APPROVAL_REQUIRED.

Attributes: openWorld

Parameter	Type	Required	Constraints & Notes
credentialId	string	No	pattern: ^cred_[A-Za-z0-9_-]{20,80}$
model	string	No	length: 1–100
apiMode	"chat-completions" | "responses"	No	—
customUpstreamUrl	string	No	format: uri, max length: 1024
checks	object	No	—
profileId	string	No	pattern: ^[A-Za-z0-9._-]+$, length: 1–80

model_profile_list

List agent model profiles

List your agent model profiles with status, generation (pass it as expectedGeneration to model_profile_update), active revision, pinned prices, limits, last connection check, and a repricing review against the cached catalog. Optional profileId narrows the list to one profile.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
profileId	string	No	pattern: ^[A-Za-z0-9._-]+$, length: 1–80

model_profile_validate

Dry-run agent model profile change

Dry-run a profile create (action "create" with the model_profile_create fields) or update (action "update" with profileId, expectedGeneration, and the changed fields). It returns the revision a save would write, issues, a pricing review, whether verificationRef would attach, and escalations: changes that need owner approval on the Dashboard and that model_profile_create or model_profile_update would refuse with OWNER_APPROVAL_REQUIRED. It writes nothing.

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
profileId	string	No	pattern: ^[A-Za-z0-9._-]+$, length: 1–80
displayName	string	No	length: 1–100
credentialId	string	No	pattern: ^cred_[A-Za-z0-9_-]{20,80}$
model	string	No	length: 1–100
apiMode	"chat-completions" | "responses"	No	—
customUpstreamUrl	string	No	format: uri, max length: 1024
pricing	object	No	—
limits	object	No	—
maxProxyOperations	string[]	No	—
verificationRef	string	No	pattern: ^vref_[A-Za-z0-9_-]{20,80}$
catalogPriceRef	object	No	—
action	"create" | "update"	Yes	—
expectedGeneration	integer	No	range: 0–9007199254740991

model_profile_create

Create agent model profile

Create an agent model profile on one of your stored credentials. Profiles created over MCP start DISABLED: the owner activates them on the Dashboard before agent_spawn can use them. Needs an idempotencyKey; replaying the same key and input returns the first result with replayed true, and the same key with other input returns CONFLICT. A custom upstream URL that none of your profiles on that credential uses returns OWNER_APPROVAL_REQUIRED and creates nothing.

Attributes: idempotent

Parameter	Type	Required	Constraints & Notes
profileId	string	Yes	pattern: ^[A-Za-z0-9._-]+$, length: 1–80
displayName	string	Yes	length: 1–100
credentialId	string	Yes	pattern: ^cred_[A-Za-z0-9_-]{20,80}$
model	string	Yes	length: 1–100
apiMode	"chat-completions" | "responses"	Yes	—
customUpstreamUrl	string	No	format: uri, max length: 1024
pricing	object	Yes	—
limits	object	Yes	—
maxProxyOperations	string[]	Yes	—
verificationRef	string	No	pattern: ^vref_[A-Za-z0-9_-]{20,80}$
catalogPriceRef	object	No	—
idempotencyKey	string	Yes	pattern: ^[A-Za-z0-9._:-]+$, length: 8–128

model_profile_update

Update agent model profile

Create a new revision of one of your profiles, guarded by expectedGeneration (a moved generation returns CONFLICT: re-read it with model_profile_list) and an idempotencyKey. Omitted fields keep their current values. Moving to another credentialId, raising a limit, lowering a price that is not catalog-verified, carrying override prices to another model or credential, widening proxy operations, or using an unbound custom upstream returns OWNER_APPROVAL_REQUIRED and changes nothing, whatever the profile status; the owner makes those changes on the Dashboard. Status is never changed here.

Attributes: destructive · idempotent

Parameter	Type	Required	Constraints & Notes
displayName	string	No	length: 1–100
credentialId	string	No	pattern: ^cred_[A-Za-z0-9_-]{20,80}$
model	string	No	length: 1–100
apiMode	"chat-completions" | "responses"	No	—
customUpstreamUrl	string	No	format: uri, max length: 1024
pricing	object	No	—
limits	object	No	—
maxProxyOperations	string[]	No	—
expectedGeneration	integer	Yes	range: 0–9007199254740991
verificationRef	string	No	pattern: ^vref_[A-Za-z0-9_-]{20,80}$
catalogPriceRef	object	No	—
profileId	string	Yes	pattern: ^[A-Za-z0-9._-]+$, length: 1–80
idempotencyKey	string	Yes	pattern: ^[A-Za-z0-9._:-]+$, length: 8–128

model_spend_summary

Read estimated model spend

Read your estimated model spend for the current UTC day and month windows (settled, reserved by open runs, and unreconciled), and the owner-set spend policies that bound it. Read-only. Figures are gateway-side estimates from pinned profile prices, not provider invoices. Spend policies are changed only on the Dashboard. Optional period narrows windows and policies to "day" or "month".

Attributes: readOnly · idempotent

Parameter	Type	Required	Constraints & Notes
period	"day" | "month"	No	—

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, reviews, review threads, issues, commits, comparisons, releases, tags, refs, commit statuses, check runs, and Actions workflow runs

Read-only GitHub access for the repository bound to an owner-authorized workspace, without per-call approval prompts. Supported actions: pr_list, pr_view, pr_reviews (every review with its state and the latest state per reviewer, including CHANGES_REQUESTED), pr_review_threads (review threads with stable thread IDs), issue_list, issue_view, commit_list (history with sha, path, since, until filters), compare (base...head commits and changed files), release_list, tag_list, ref_get (current OID of refs/heads/... or refs/tags/..., or exists: false), commit_status_get (combined status and every status context for a SHA or ref), check_runs_list (check runs for a SHA or ref), workflow_runs_list (Actions runs filtered by workflow, headSha, branch, event, status), and workflow_run_view (one run with its jobs and conclusions). Maps to operations.pullRequestList, pullRequestView, pullRequestReviewList, issueList, issueView, commitList, compare, releaseList, tagList, refGet, commitStatusRead, checkRunList, and workflowRunRead. 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" | "pr_review_threads" | "pr_reviews" | "issue_list" | "issue_view" | "commit_list" | "compare" | "release_list" | "tag_list" | "ref_get" | "commit_status_get" | "check_runs_list" | "workflow_runs_list" | "workflow_run_view"	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
ref	string	No	length: 1–255
checkName	string	No	length: 1–255
workflow	integer | string	No	—
headSha	string	No	pattern: `^(?:[0-9a-f]
branch	string	No	length: 1–255
event	string	No	pattern: ^[a-z_]{1,64}$
status	"queued" | "in_progress" | "completed" | "requested" | "waiting" | "pending" | "success" | "failure" | "cancelled" | "skipped" | "timed_out" | "action_required" | "neutral" | "stale"	No	—
runId	integer	No	range: 0–9007199254740991

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
repositoryContext	"codex" | "claude" | "cursor" | "aider" | "all" | "none"	No	Repository guidance profile placed before the task; omitted uses codex, none sends the task alone.

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