Keep the signal in command output.

Run a bounded command

When an installed shell hook already routes a command through LeanCTX, run the command normally. Do not wrap it again.

Automatic Bash / zsh shell hooks are a Unix integration. Native Windows users can use the explicit CLI or MCP examples below; installing LeanCTX does not automatically intercept ordinary PowerShell commands. Host-specific agent hooks have their own support and are separate from these shell hooks.

For an explicit CLI invocation:

lean-ctx -c "git status --short"

For an MCP client:

{"name":"ctx_shell","arguments":{"command":"git status --short","cwd":"."}}

Use a real project directory. Command gating and the host’s permissions still apply.

A blocked command is not made permissible by switching to ctx_execute: shell execution there uses the same allowlist. Review the command and its effects before deliberately changing your allowlist through lean-ctx allow <command>.

The command inside a shell tool is parsed by its selected child shell, not necessarily the terminal you are looking at. On Windows the runtime can select PowerShell, cmd or a Git Bash environment; Unix execution uses a compatible POSIX shell. Use that shell’s path, environment-variable and quoting syntax. The single git command above avoids shell-specific operators. See shell and path conventions.

Understand the result

Command-specific patterns retain important summaries, errors and test results while reducing repeated progress output. Unsupported or already compact formats can follow other paths, including passthrough.

A compressed success-looking summary is not a substitute for the command’s exit status. Check both, and recover omitted output when diagnosing a failure.

Handle long-running work

ctx_shell supports background jobs. A started job returns a job_id; subsequent calls use background_action and that exact ID. A job that is still running has not passed its check.

The shell schema lists the supported actions and timeout fields. Avoid launching duplicate jobs just because the first call returned early.

Completed job status can include an archiveId. Use that returned value with ctx_expand; the current expansion contract also accepts a shell_* job ID while the corresponding result remains available.

Recover exact output

Follow a returned archive reference with ctx_expand. A targeted search for the failure is often enough. Use raw delivery when exact formatting or a dataset is the subject of the task.

Raw delivery disables compression for that operation; it is not permission to bypass the command allowlist or other enforced boundaries.

Sources & versions7 references · Reviewed 18 Sept 2026

• ctx_shell.rsrust/src/tools/ctx_shell.rsReviewed checkout
• ctx_shell.rsrust/src/tools/registered/ctx_shell.rsReviewed checkout
• ctx_execute.rsrust/src/tools/ctx_execute.rsReviewed checkout
• mod.rsrust/src/shell/mod.rsReviewed checkout
• platform.rsrust/src/shell/platform.rsReviewed checkout
• shell_hook.rsrust/src/shell_hook.rsReviewed checkout
• 02-daily-use.mddocs/reference/02-daily-use.mdReviewed checkout

Core checkout

5198ea1867

Installed runtime

3.10.2

SDK release

1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility