# Host shell discovery

> The process host capability owns shell discovery and shell-mode invocation. This keeps IDEs, TUIs, headless CLI runs, and cloud workers on the same contract instead of...

Website: https://harnlang.com/spec/language/28-host-shell-discovery.html

This page documents Harn, which is pre-1.0. Language, standard library, and CLI APIs may change. If the intended version is unclear, clarify before using this page.

---

<!-- Generated from spec/chapters/*.md by scripts/sync_language_spec.harn -->

## Host shell discovery

The `process` host capability owns shell discovery and shell-mode invocation.
This keeps IDEs, TUIs, headless CLI runs, and cloud workers on the same
contract instead of hardcoding `/bin/sh`, `cmd`, or host-specific settings in
each integration.

- `process.list_shells` returns `{shells, default_shell_id}`. Each shell entry
  has `id`, `label`, `path`, `platform`, `available`, `supports_login`,
  `supports_interactive`, `default_args`, `login_args`, and `source`.
- `process.get_default_shell` returns the selected shell object for the
  current host/session. Harn only chooses a shell whose command syntax its
  safety analyzer supports. An unrecognized login shell remains listed but
  can't become the implicit default.
- `process.set_default_shell` may be implemented by stateful hosts. Harn's
  standalone fallback stores a supported selection for the current
  thread/session and rejects an unsupported shell.
- `process.shell_invocation` resolves `{shell_id?, shell?, command?, login?,
  interactive?}` into `{program, args, command_arg_index, shell}`. When neither
  `shell_id` nor `shell` is supplied, it uses the selected default shell.

Shell-mode command runners may pass a shell object or shell ID resolved through
this capability, and otherwise use the selected default shell. `argv` mode
remains preferred for programmatic execution; shell mode is for user-authored
commands and interactive shell semantics. The normative schema is
`spec/schemas/host-shell-discovery.schema.json`.

Command-risk scans include `execution_semantics` with the request mode,
resolved dialect, resolution source, shell ID, and unresolved reason. An
explicit unsupported shell adds both `shell_dialect_unknown` and
`execution_semantics_unresolved`, so command policy still fails closed.

---

## Read next

- [Agent lifecycle (suspend/resume)](https://harnlang.com/spec/language/27-agent-lifecycle-suspend-resume.md)
- [Workspace manifest (`harn.toml`)](https://harnlang.com/spec/language/29-workspace-manifest-harn-toml.md)