---
id: SMH-ISSUE-GW0YODWB
type: issue
title: "Brush-backed Shell SDK Facility"
specs: [SMH-SPEC-SPEC0001, SMH-SPEC-PLUG0001, SMH-SPEC-WASM0001, SMH-SPEC-ZVMD_XYT]
---

# Brush-backed Shell SDK Facility

## Symptom

Plugin authors lack a defined in-process Bash-compatible shell SDK facility.
Human direction: use `brush-core` as embedded library behind the shell-class Smith plugin API.
This is a reusable SDK mechanism, not a native tool registry or new plugin category.

## Impact

Shell wrappers otherwise require interpreter launches or private evaluator implementations.
Unmediated embedding risks filesystem/process access outside grants, leaked execution state, unbounded native work.

## Evidence

[Brush](https://github.com/reubeno/brush) exposes an embeddable Rust shell engine and custom builtins.
Its [compatibility reference](https://brush.sh/reference/compatibility/) documents Bash compatibility gaps.
[Current WIT](../../../wit/smith-plugin.wit) exports tool declaration/invocation only; no shell facility exists in that surface.
Embedding support is established by upstream documentation; Smith effect mediation, bounds, supported targets remain unproved.

## Requested direction

Ordinary wasm plugins access embedded Brush through a granted typed shell SDK facility.

```mermaid
flowchart TB
  p["Wasm plugin"] --> s["Shell SDK"]
  s --> b["Embedded brush-core"]
  b --> e["Granted effect broker"]
```

- Native backend owned by `smith-harness`; Brush types and async APIs remain private.
- Shell input, cwd, environment, stdin, limits explicit; output preserves bounded stdout/stderr bytes, exit status, typed failures.
- Shell evaluation starts no Bash/helper interpreter process; external commands use supervised process effects and may spawn.
- Builtins, redirection, globbing, source loading, substitutions, jobs, clock, randomness cannot bypass grants or durable recording.
- No startup files, ambient environment, process-global cwd changes, uncontrolled signals, or cross-invocation state leakage.
- Native parsing, allocation, execution, conversion, output require independent bounds and cancellation; wasm fuel does not cover Brush.
- Unsupported semantics fail explicitly; no GNU Bash fallback or exact-compatibility promise.
- Bundled and user plugins share grants, generation pins, replay, secret handling; no default Bash tool implied.
- SDK reference and supported shell semantics belong in bounded offline `smith docs`, backed by tested examples.

## Spec gap

[Smith Specification](../../specs/SMH-SPEC-SPEC0001-smith-specification/index.md) permits reusable native mechanisms but defines no Brush shell contract.
[Embedded Nushell](../../specs/SMH-SPEC-ZVMD_XYT-embedded-nushell/index.md) explicitly excludes a built-in Bash evaluator; distinguish optional Brush-backed SDK evaluation from default tool contributions.
[Plugin System](../../specs/SMH-SPEC-PLUG0001-plugin-system/index.md) and [Wasm Plugin Runtime](../../specs/SMH-SPEC-WASM0001-wasm-plugin-runtime/index.md) retain existing sandbox, world, artifact, and lifecycle laws.
Spec approval precedes implementation; dependency version, feature set, license, platform support, broker hooks, native limits require verification.

## Acceptance

- [ ] Approved spec defines shell SDK scope and resolves evaluator exclusion.
- [ ] Two real plugin consumers earn the interface without privileged paths.
- [ ] Built Smith evaluates supported shell scripts without an installed shell or interpreter spawn.
- [ ] Effect escape attempts fail; external descendants remain supervised; replay repeats no mutations.
- [ ] Native bounds, cancellation, state isolation, supported-platform behavior pass tests.
- [ ] Checked examples and release-matched offline reference expose supported semantics and limitations.