Workspace tools
The workspace.* tools: read, search, change, commit and push a throwaway clone of a repository.
Generated from the built-in tools registry. Do not edit by hand.
A run whose task declares workspace.* tools gets a throwaway clone of the repository named in its repo input. The repository sets the clone up itself (its .os/workspace.yml, or an install the runner detects), and the clone is destroyed when the run ends. A task without workspace.* tools never gets one.
These tools work on that clone only. Issues and pull requests stay with the enterprise's own GitHub tools. What a task may change is its write policy: writeAllow, rewriteAllow, writeDeny and appendOnly on the task version.
| Tool | What it does | Effect |
|---|---|---|
workspace.read_file |
Read a file from the clone, whole or one numbered window of it. | read |
workspace.list_dir |
List a directory in the clone. | read |
workspace.write_file |
Write a whole file in the clone. | write |
workspace.delete_file |
Delete a file from the clone outright. | write |
workspace.edit |
Replace one exact piece of text in a file. | write |
workspace.search |
Search the clone for a string or pattern. | read |
workspace.run_command |
Run one allowlisted binary in the clone, with no shell. | write |
workspace.verified_results |
What the repo's mise run commands already returned on the clone's current commit in this pipeline. |
read |
workspace.git_commit |
Commit the tracked changes and the files this run wrote. | write |
workspace.git_push |
Push the current branch, or one ref the task may push, never the default one unless named. | write |
workspace.share_file |
Share one file from the clone at a public address that stops working after an hour, or up to 72. | write |
workspace.read_file
Read a file from the clone, whole or one numbered window of it.
What the model reads:
Read a file from the run workspace. Pass path for the whole file, or add startLine (1-based) and limit to read one numbered window of a large file. Prefer a window over a scratch script.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | yes | |
startLine |
number | no | First line to read, 1-based. Omit to read the whole file. |
limit |
number | no | How many lines to read from startLine. Default 200. |
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run.
- Needs:
- A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- A
- Returns: The file as UTF-8 text, or the requested window of it with line numbers.
| Error | When | What happens |
|---|---|---|
exploration_budget_exceeded |
Too many reads back over ground already covered with no write, edit or commit in between, or more distinct files, folders and searches than the per-run budget. | Tool error |
Example:
{
"path": "src/index.ts"
}
Example:
{
"path": "src/index.ts",
"startLine": 200,
"limit": 80
}
workspace.list_dir
List a directory in the clone.
What the model reads:
List a directory in the run workspace. Pass path (default .).
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | no |
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run.
- Needs:
- A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- A
- Returns: The directory listing.
| Error | When | What happens |
|---|---|---|
exploration_budget_exceeded |
Too many reads back over ground already covered with no write, edit or commit in between, or more distinct files, folders and searches than the per-run budget. | Tool error |
Example:
{
"path": "src"
}
workspace.write_file
Write a whole file in the clone.
What the model reads:
Write a file in the run workspace. Pass path and content.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | yes | |
content |
string | yes |
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Writing the same content again leaves the same file.
- Called by: a run.
- Needs:
- The task version's
workspace.writeAllow,rewriteAllow,writeDenyandappendOnlydecide which paths it may change;workspace.pushAllowdecides which refs besides its own branch it may push. - A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- The task version's
- Returns:
{ ok: true }.
| Error | When | What happens |
|---|---|---|
workspace_write_not_allowed |
The path is outside the task's write globs, or matches writeDeny. |
Tool error |
workspace_append_only |
The path is add-only for this task, and the call would change or remove a line it had when the run started. A run holding a repairGrant (a recovery-authorised repair handed to the run a suite_repairable edge started) may change or remove exactly the lines it names, while each still reads as the grant recorded it; the refusal then says which lines fell outside the grant, that the grant is stale, or that no grant covers the path. A refusal for a run holding no grant ends by saying why none is in effect: no successor edge started the run, the edge it started from declares no repairGrant carry, the result that started it carried none, or the grant in its input is malformed. A grant never makes a delete, a writeDeny path or a path outside the write globs writable. |
Tool error |
Example:
{
"path": "src/greeting.ts",
"content": "export const greeting = 'hello'\n"
}
workspace.delete_file
Delete a file from the clone outright.
What the model reads:
Delete a file in the run workspace outright, instead of overwriting it empty. Pass path.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | yes |
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A repeat finds nothing to delete and fails
delete_file_missing; the file stays deleted. - Called by: a run.
- Needs:
- The task version's
workspace.writeAllow,rewriteAllow,writeDenyandappendOnlydecide which paths it may change;workspace.pushAllowdecides which refs besides its own branch it may push. - A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- The task version's
| Error | When | What happens |
|---|---|---|
delete_file_missing |
Nothing is at that path. | Tool error |
delete_file_is_directory |
The path is a directory. | Tool error |
workspace_write_not_allowed |
The path is outside the task's write globs, or matches writeDeny. |
Tool error |
workspace_append_only |
The path is add-only for this task, and the call would change or remove a line it had when the run started. A run holding a repairGrant (a recovery-authorised repair handed to the run a suite_repairable edge started) may change or remove exactly the lines it names, while each still reads as the grant recorded it; the refusal then says which lines fell outside the grant, that the grant is stale, or that no grant covers the path. A refusal for a run holding no grant ends by saying why none is in effect: no successor edge started the run, the edge it started from declares no repairGrant carry, the result that started it carried none, or the grant in its input is malformed. A grant never makes a delete, a writeDeny path or a path outside the write globs writable. |
Tool error |
Example:
{
"path": "src/unused.ts"
}
workspace.edit
Replace one exact piece of text in a file.
What the model reads:
Replace one exact piece of text in a workspace file. Pass path, oldString and newString. oldString must appear exactly once unless you pass replaceAll. Use this to change a file, not write_file, which rewrites the whole file. An empty oldString on a path that does not exist creates the file with newString as its content; on a file that exists it is refused.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | yes | |
oldString |
string | yes | Exact text to replace, whitespace included. |
newString |
string | yes | Replacement text. Empty string deletes oldString. |
replaceAll |
boolean | no | Replace every occurrence instead of requiring one. |
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A repeat no longer finds oldString and fails
edit_no_match; the first edit stands. A repeated create (empty oldString) finds the file it made and failsedit_old_string_required; the first create stands. - Called by: a run.
- Needs:
- The task version's
workspace.writeAllow,rewriteAllow,writeDenyandappendOnlydecide which paths it may change;workspace.pushAllowdecides which refs besides its own branch it may push. - A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- The task version's
| Error | When | What happens |
|---|---|---|
edit_old_string_required |
oldString is missing, or it is empty and either newString is missing or the file already exists. Pass both as strings: quote the text to replace, pass an empty oldString with the content as newString to create a missing file, or use workspace.write_file to rewrite the whole file. |
Tool error |
edit_no_match |
The file does not contain oldString exactly. |
Tool error |
edit_not_unique |
oldString appears more than once and replaceAll is not set. |
Tool error |
edit_file_missing |
Nothing is at that path and oldString is not empty. To create the file, use workspace.write_file, or pass an empty oldString. |
Tool error |
workspace_write_not_allowed |
The path is outside the task's write globs, or matches writeDeny. |
Tool error |
workspace_append_only |
The path is add-only for this task, and the call would change or remove a line it had when the run started. A run holding a repairGrant (a recovery-authorised repair handed to the run a suite_repairable edge started) may change or remove exactly the lines it names, while each still reads as the grant recorded it; the refusal then says which lines fell outside the grant, that the grant is stale, or that no grant covers the path. A refusal for a run holding no grant ends by saying why none is in effect: no successor edge started the run, the edge it started from declares no repairGrant carry, the result that started it carried none, or the grant in its input is malformed. A grant never makes a delete, a writeDeny path or a path outside the write globs writable. |
Tool error |
Example:
{
"path": "src/greeting.ts",
"oldString": "'hello'",
"newString": "'hello, world'"
}
workspace.search
Search the clone for a string or pattern.
What the model reads:
Search the run workspace for a string. Pass pattern, optionally globs (e.g. ["apps/api/**/*.ts"]), ignoreCase, regex, maxResults. Returns path, line and text per match. Use this instead of writing a script to grep.
| Field | Type | Required | Description |
|---|---|---|---|
pattern |
string | yes | |
globs |
array of string | no | Limit to these path globs. |
ignoreCase |
boolean | no | |
regex |
boolean | no | Treat pattern as a POSIX extended regexp. |
maxResults |
number | no | Default 100, ceiling 500. |
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run.
- Needs:
- A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- A
- Returns: Path, line and text for each match.
| Error | When | What happens |
|---|---|---|
search_pattern_required |
pattern is missing or empty. |
Tool error |
exploration_budget_exceeded |
Too many reads back over ground already covered with no write, edit or commit in between, or more distinct files, folders and searches than the per-run budget. | Tool error |
Example:
{
"pattern": "TODO",
"globs": [
"src/**/*.ts"
],
"maxResults": 20
}
workspace.run_command
Run one allowlisted binary in the clone, with no shell.
What the model reads:
Run an allowlisted binary in the run workspace. Pass argv as a JSON array of strings. Example: {"argv":["git","status"]}. No shell, no pipes, no cd. Allowed bins: git, pnpm, npm, node, mise. The command's environment carries the values the task version's workspace.credentials name, each a bound tool's secret or custom prop under the variable the version chose; you never read a value, and one a command prints comes back masked.
| Field | Type | Required | Description |
|---|---|---|---|
argv |
array of string | yes | argv[0] is the binary. Example ["pnpm","test"] |
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. The command runs again.
- Called by: a run.
- Needs:
- A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- A
- Returns:
{ code, stdout, stderr }.
| Error | When | What happens |
|---|---|---|
argv_required |
argv is missing or is not an array of strings. |
Tool error |
bin_not_allowlisted |
argv[0] is not one of git, pnpm, npm, node, mise, or is a path. |
Tool error |
git_push_via_run_command |
The command would push. Push with workspace.git_push. |
Tool error |
git_hooks_skip_refused |
The command would skip the repo's git hooks (--no-verify, core.hooksPath). |
Tool error |
direct_typecheck_refused |
The command runs a typechecker (tsc), a task-graph runner (turbo) or a package-manager typecheck script directly, around the repo's verification task. Verify with mise run os:red <issue>, which returns the typecheck's exit code and compiler output; mise run <task> is never refused. |
Tool error |
workspace_credential_missing |
The version asks for a credential (workspace.credentials) no binding on the run’s layers answers: the tool is not bound, or its binding holds no secret or lacks the named custom prop. Checked before the run starts, and again at each command. |
Run fails |
workspace_credential_unavailable |
A credential the version asks for is bound but cannot be read: the secret store is down or the secret no longer decrypts. The command is not run. | Run fails |
scratch_execution_refused |
The command would execute a file this run created outside the task's full-write paths, whether run directly or loaded by an inline script (node -e "require('./tmp.mjs')"), and whether named in full or the way Node resolves it (node tmp, require('./tmp'), a directory's index). Use workspace.read_file, workspace.search or mise run os:red <issue> instead. Files already in the clone, and files in the full-write paths, run as before. |
Tool error |
Example:
{
"argv": [
"git",
"status"
]
}
Example:
{
"argv": [
"npm",
"test"
]
}
workspace.verified_results
What the repo's mise run commands already returned on the clone's current commit in this pipeline.
What the model reads:
Read what the repo's `mise run <task>` commands already returned on the code this clone has now, in this run or an earlier run of the same pipeline (the run before it, or the one it resumes). Answers { commit, clean, results }: commit is the clone's HEAD now, clean is true when its tree has no tracked or untracked change outside ignored files, and results are the commands recorded at exactly that commit, each { task, part, args, exitCode, clean, runId, at }. A result stands for this code only when it and the clone are both clean: then exitCode 0 means that command, or that --part of it, already passed on exactly this code in this pipeline, and you need not run it again. When the clone is not clean, or a result was recorded on a changed tree, it says nothing about the code you have: run the command. A command run in parts whose final verdict part reads files its earlier parts wrote in the same clone cannot be resumed part by part from these records, because those files are not in this clone: reuse it only whole, when its verdict part is recorded as passed, and otherwise run all of its parts. Pass task, and args (the words after the task, flags left out, e.g. the issue number), to narrow the list.
| Field | Type | Required | Description |
|---|---|---|---|
task |
string | no | Only results of this mise task, e.g. "os:check". |
args |
array of string | no | Only results run with exactly these words after the task, flags left out, e.g. ["148"]. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing.
- Called by: a run.
- Needs:
- A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- A
- Returns:
{ commit, clean, results }: the clone's HEAD and whether its tree is clean now, and each result recorded at that commit, oldest first, as{ task, part, args, exitCode, clean, runId, at }.partis the value after--part, or null.
| Error | When | What happens |
|---|---|---|
verified_results_filter_invalid |
task is not a string, or args is not an array of strings. |
Tool error |
Example:
{}
Example:
{
"task": "os:check",
"args": [
"148"
]
}
workspace.git_commit
Commit the tracked changes and the files this run wrote.
What the model reads:
Commit in the run workspace. Pass message. Stages tracked changes and the files you wrote or edited; a new file only a command created may be left out, so `git add` it with workspace.run_command first if it belongs in the commit.
| Field | Type | Required | Description |
|---|---|---|---|
message |
string | yes |
- Effect: write.
- Retry: Not retry-safe: a repeat acts again. A repeat makes another commit, even an empty one.
- Called by: a run.
- Needs:
- The task version's
workspace.writeAllow,rewriteAllow,writeDenyandappendOnlydecide which paths it may change;workspace.pushAllowdecides which refs besides its own branch it may push. - A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- The task version's
| Error | When | What happens |
|---|---|---|
workspace_commit_not_allowed |
The commit would include paths outside the task's write globs, or, in a merge, a path the task may not write in full that is not the version the merge calls for: main's where only main changed it, the branch's where only the branch did, and both sides' changes with no line of the run's own where both did. An add-only path both sides changed may instead keep every line the branch head has, in order, but not while it still holds a conflict-marker line neither side has: that conflict is unresolved. The message names the rule, then each path in full, then the fix. Nothing is committed; a merge stays in progress. | Tool error |
workspace_append_only |
The commit changes or removes a line an add-only path had when the run started, other than a line the run's repairGrant names. In a merge, an add-only path both sides changed drops or edits a line the branch head has: it may add lines and take or leave main's, but keeps every branch-head line in order. Nothing is committed; a merge stays in progress. |
Tool error |
git_commit_failed |
git refused the commit, for example a pre-commit hook failed. | Tool error |
Example:
{
"message": "Add the greeting"
}
workspace.git_push
Push the current branch, or one ref the task may push, never the default one unless named.
What the model reads:
Push HEAD to the current non-default branch. No arguments, usually. With `ref`, a full ref (`refs/heads/production`, `refs/tags/v1.2.3`), HEAD is pushed there instead, only when one of the task version's `workspace.pushAllow` globs matches it; that is the one way a run pushes the default branch, a tag or a branch a host builds from, and never a force push. Answers `{ ok, branch, sha, ref? }`: the branch, the commit that went up and the ref it went to, so a run that verified the tree before pushing can name that commit in the note it leaves on the pull request.
| Field | Type | Required | Description |
|---|---|---|---|
ref |
string | no | A full ref to push HEAD to instead of the current branch (refs/heads/… or refs/tags/…), allowed only when workspace.pushAllow matches it. |
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat with nothing new to push changes nothing.
- Called by: a run.
- Needs:
- The task version's
workspace.writeAllow,rewriteAllow,writeDenyandappendOnlydecide which paths it may change;workspace.pushAllowdecides which refs besides its own branch it may push. - A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone. - A code host tool bound in the run's cascade whose
git.hostcustom prop matches the remote: the push authenticates with that binding's credential, and with no other.
- The task version's
| Error | When | What happens |
|---|---|---|
default_branch_refused |
The current branch is the default branch, and no ref named it under workspace.pushAllow. |
Tool error |
push_ref_not_allowed |
A ref was given that none of the task version's workspace.pushAllow globs matches, or the version names none. |
Tool error |
push_ref_invalid |
A ref was given that is not a full branch or tag ref. |
Tool error |
workspace_append_only |
The path is add-only for this task, and the call would change or remove a line it had when the run started. A run holding a repairGrant (a recovery-authorised repair handed to the run a suite_repairable edge started) may change or remove exactly the lines it names, while each still reads as the grant recorded it; the refusal then says which lines fell outside the grant, that the grant is stale, or that no grant covers the path. A refusal for a run holding no grant ends by saying why none is in effect: no successor edge started the run, the edge it started from declares no repairGrant carry, the result that started it carried none, or the grant in its input is malformed. A grant never makes a delete, a writeDeny path or a path outside the write globs writable. |
Tool error |
git_push_failed |
git refused the push, for example the repo's pre-push hook failed. | Tool error |
workspace.share_file
Share one file from the clone at a public address that stops working after an hour, or up to 72.
What the model reads:
Share one file the run made in its workspace (a rendered video, an image, a PDF) at a public https address, so a bound tool that takes a file by address can fetch it, or a person can open it from a gate. Pass path, and hours (1 to 72, one when left out) when a person must see it later, such as a preview a gate waits on. Answers `{ url, expiresAt, bytes, contentType }`: hand `url` to the tool that needs the file. Anyone holding the address can read the file until it expires, so share only what is meant to leave the run, and only for as long as it is needed.
| Field | Type | Required | Description |
|---|---|---|---|
path |
string | yes | The file to share, relative to the workspace root. |
hours |
integer, 1 to 72 | no | How long the address works, in hours: 1 when left out, at most 72. |
- Effect: write.
- Side effects: Stores a copy of the file with the run's artifacts, counted towards the enterprise's storage, and makes it readable at the address until it expires.
- Retry: Not retry-safe: a repeat acts again. Each call stores another copy and answers a new address; the earlier one keeps working until it expires.
- Called by: a run.
- Needs:
- A
repoinput on the run — a git remote address, or whatever short form the code host binding'sgit.repoTemplatecustom prop expands — which the runner clones. A code host binding may name the repository instead, in itsgit.repoprop. A task withoutworkspace.*tools never gets a clone.
- A
- Returns:
{ url, expiresAt, bytes, contentType }: the public address, when it stops working (ISO 8601), the file's size and the type it is served with.
| Error | When | What happens |
|---|---|---|
share_file_missing |
Nothing is at that path. | Tool error |
share_file_is_directory |
The path is a folder, not a file. | Tool error |
share_file_hours_invalid |
hours is not a whole number from 1 to 72. | Tool error |
share_file_too_large |
The file is larger than 512 MB. | Tool error |
path_escape |
The path leads outside the workspace. | Tool error |
Example, Then pass the answered url to the tool that uploads it.:
{
"path": "out/article-video.mp4"
}