# 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

- [Workspace Nodes](/docs/nodes-workspace)
- [File Operation Nodes](/docs/nodes-file-ops)
- [Code Index Nodes](/docs/nodes-code-index)