Workspace Tool Nodes
Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: crates/cheng-nodes/src/nodes/builtin/tools, crates/cheng-workspace-tools/src
The non-file half of the workspace toolset, and it is deliberately lopsided: tools/workspace_git,
tools/workspace_markdown, and tools/workspace_preview expose read-only operations, while anything
that can change the machine — an arbitrary shell command, or actually running a test suite — is
approval-gated. That asymmetry is the design: inspection should be free, mutation should be a
decision. tools/workspace_tests splits along the same line, with a read-only detect operation and a
gated run.
Workspace Shell — tools/workspace_shell
Run workspace commands (build/test/lint/diagnostics) with policy checks, bounded output, timeout, and cancellation. Structured command form preferred; shell strings are opt-in and high risk.
Inputs
| Field | Type | Required | Default | Description |
|---|
command | string | — | "" | Executable program to run, e.g. "ls", "cargo", "pnpm", "pytest". This is NOT the tool name. |
args | array<string> | — | [] | Literal arguments for command, e.g. command="ls", args=["-la"]. No shell syntax. |
shell_string | string | — | null | Compatibility input for simple commands. Shell syntax disabled by default. |
cwd | string | — | null | Working directory relative to the workspace root. Omit for the root itself. |
env | object | — | {} | Extra environment variables (subject to allowlist). |
timeout_ms | integer | — | null | Wall-clock budget in ms (default 60000, max 600000). |
purpose | string | — | null | One sentence explaining why this command is needed; shown on the approval card. |
sandbox_root | string | — | null | Server-local sandbox root directory (engine-injected; not for LLM) |
allow_shell_string | boolean | — | false | Static opt-in for raw shell strings (author-only; default off). Raw shell syntax (pipes, redirection, variables) is disabled unless this is on. Control: switch |
command_whitelist | string | — | "" | User-configured command whitelist. One program name per line. When non-empty, only listed programs are allowed and shell strings are denied. Control: textarea |
Outputs
| Field | Type | Description |
|---|
success | boolean | Whether the command succeeded (exit code 0) |
summary | string | Human-readable summary of the command result |
command_display | string | Display form of the executed command |
cwd | string | Working directory used for the command |
exit_code | integer | Process exit code (None when the process did not exit normally) |
termination | string | Termination reason: exited, timed_out, cancelled, signalled, or spawn_failed |
duration_ms | integer | Wall-clock duration of the command in milliseconds |
stdout | string | Capped stdout text (head+tail truncated when over the cap) |
stdout_truncated | boolean | True when stdout was head+tail truncated due to byte cap |
stderr | string | Capped stderr text (head+tail truncated when over the cap) |
stderr_truncated | boolean | True when stderr was head+tail truncated due to byte cap |
error_kind | string | Stable machine code on failure (LOCAL_EXECUTOR_* vocabulary) |
terminal | boolean | True when the error is terminal and must not be retried |
error | string | Error message when the command failed |
Workspace Git — tools/workspace_git
Read-only git inspection (status/diff/log/show/branch) with structured, bounded output. Destructive git operations are not available.
Inputs
| Field | Type | Required | Default | Description |
|---|
operation | string | — | "" | Read-only git operation: status, diff, log, show, or branch |
cwd | string | — | null | Repository directory relative to the workspace root. Omit for the root. |
pathspecs | array<string> | — | [] | Relative pathspecs to narrow diff/log/status. No absolute paths, no '..' |
revision | string | — | null | For show: local revision (HEAD, branch name, commit hash). |
max_bytes | integer | — | null | Output byte cap (default 262144). |
max_count | integer | — | null | For log: number of commits (default 20, max 100) |
sandbox_root | string | — | null | Server-local sandbox root directory (engine-injected; not for LLM) |
Outputs
| Field | Type | Description |
|---|
operation | string | Git operation that was executed |
success | boolean | Whether the operation succeeded |
summary | string | Human-readable summary of the operation result |
files | any | Structured status entries (changed/staged/untracked files) |
commits | any | Structured log entries (hash/author/date/subject) |
branches | any | Local branch names |
current_branch | string | Current branch name (marked in branch list) |
stdout | string | Raw capped stdout text (diff/show output) |
stdout_truncated | boolean | True when stdout was head+tail truncated due to byte cap |
stderr | string | Raw capped stderr text |
error_kind | string | Stable machine code on failure (LOCAL_EXECUTOR_* vocabulary) |
terminal | boolean | True when the error is terminal and must not be retried |
error | string | Error message when the operation failed |
Workspace Tests — tools/workspace_tests
Detect the project's toolchain and test commands (read-only) and run explicit test commands with structured pass/fail summaries, timeout, and cancellation.
Inputs
| Field | Type | Required | Default | Description |
|---|
operation | string | — | "" | detect = read-only project inspection; run = execute an explicit test command (approval-gated) |
command | string | — | null | Test program for run operation (e.g. "cargo", "pnpm"). |
args | array<string> | — | [] | For run: literal command arguments, e.g. ["test", "--no-fail-fast"] |
cwd | string | — | null | Directory relative to the workspace root (project subdirectory in a monorepo) |
timeout_ms | integer | — | null | For run: wall-clock budget in ms (default 300000, max 600000) |
sandbox_root | string | — | null | Server-local sandbox root directory (engine-injected; not for LLM) |
Outputs
| Field | Type | Description |
|---|
operation | string | Test operation that was executed (detect or run) |
success | boolean | Whether the operation succeeded |
summary | string | Human-readable summary of the test result |
detected_project | any | Detected project types, package manager, suggested commands, confidence, and evidence (detect only) |
command_display | string | Display form of the executed test command (run only) |
passed | integer | Number of passed tests (run only) |
failed | integer | Number of failed tests (run only) |
duration_ms | integer | Wall-clock duration of the test run in milliseconds (run only) |
failure_summary | any | Failure hints (name/file/line/message), best effort (run only) |
termination | string | Termination reason: exited, timed_out, cancelled, signalled, or spawn_failed (run only) |
stdout | string | Capped stdout text (head+tail truncated when over the cap) |
stdout_truncated | boolean | True when stdout was head+tail truncated due to byte cap |
stderr | string | Capped stderr text (head+tail truncated when over the cap) |
stderr_truncated | boolean | True when stderr was head+tail truncated due to byte cap |
error_kind | string | Stable machine code on failure (LOCAL_EXECUTOR_* vocabulary) |
terminal | boolean | True when the error is terminal and must not be retried |
error | string | Error message when the operation failed |
Workspace Markdown — tools/workspace_markdown
Read-only Markdown analysis: heading outlines, structured diagnostics, format suggestions (as edit_file-ready replacements), and local link checks.
Inputs
| Field | Type | Required | Default | Description |
|---|
operation | string | — | "" | Read-only markdown analysis: outline, diagnostics, format_suggestions, or link_check_local |
path | string | — | "" | Markdown file path relative to the workspace root |
sandbox_root | string | — | null | Server-local sandbox root directory (engine-injected; not for LLM) |
Outputs
| Field | Type | Description |
|---|
operation | string | Markdown analysis operation that was executed |
path | string | Markdown file path that was analyzed |
success | boolean | Whether the analysis succeeded |
summary | string | Human-readable summary of the analysis result |
outline | any | Heading tree entries with levels, 1-indexed lines, and GitHub-style anchors |
diagnostics | any | Structured diagnostics: duplicate-heading, heading-hierarchy-jump, empty-link-target, etc. |
suggested_edits | any | Mechanical fixes as edit_file-ready replacements; this tool never writes files itself |
error_kind | string | Stable machine code on failure (LOCAL_EXECUTOR_* vocabulary) |
terminal | boolean | True when the error is terminal and must not be retried |
error | string | Error message when the operation failed |
Workspace Preview — tools/workspace_preview
Render bounded, sanitized previews: Markdown to safe HTML, HTML to a text summary, or artifact metadata. Read-only; persisting output goes through file operations.
Inputs
| Field | Type | Required | Default | Description |
|---|
operation | string | — | "" | Preview operation: markdown, html, or artifact_summary |
path | string | — | null | Source file relative to the workspace root. Takes precedence over content. |
content | string | — | null | Inline source text when no workspace file is involved |
max_bytes | integer | — | null | Preview byte cap (default and max 524288) |
sandbox_root | string | — | null | Server-local sandbox root directory (engine-injected; not for LLM) |
Outputs
| Field | Type | Description |
|---|
operation | string | Preview operation that was executed |
success | boolean | Whether the preview succeeded |
summary | string | Human-readable summary of the preview result |
format | string | Output format: html, text, or metadata |
preview | string | Rendered or derived preview text (bounded) |
preview_truncated | boolean | True when the preview was head+tail truncated due to byte cap |
source_bytes | integer | Size of the source content in bytes |
source_path | string | Source file path when the preview was from a workspace file |
error_kind | string | Stable machine code on failure (LOCAL_EXECUTOR_* vocabulary) |
terminal | boolean | True when the error is terminal and must not be retried |
error | string | Error message when the operation failed |
Next steps