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 repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • 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 repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • 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, writeDeny and appendOnly decide which paths it may change; workspace.pushAllow decides which refs besides its own branch it may push.
    • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • 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, writeDeny and appendOnly decide which paths it may change; workspace.pushAllow decides which refs besides its own branch it may push.
    • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
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 fails edit_old_string_required; the first create stands.
  • Called by: a run.
  • Needs:
    • The task version's workspace.writeAllow, rewriteAllow, writeDeny and appendOnly decide which paths it may change; workspace.pushAllow decides which refs besides its own branch it may push.
    • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
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'"
}

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 repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • 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 repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • 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 repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • 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 }. part is 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, writeDeny and appendOnly decide which paths it may change; workspace.pushAllow decides which refs besides its own branch it may push.
    • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
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, writeDeny and appendOnly decide which paths it may change; workspace.pushAllow decides which refs besides its own branch it may push.
    • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
    • A code host tool bound in the run's cascade whose git.host custom prop matches the remote: the push authenticates with that binding's credential, and with no other.
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 repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • 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"
}