shell-manual

# Shell manual — router Use the schema for a short, deterministic command. Read one focused route before long-lived/coding-CLI work, scheduling, an unfamiliar workflow, or recovery. The selected dialect, policy, and working-directory sandbox remain boundaries. ## Route by task | Task | Read one direct reference | |---|---| | Long command/CLI; `job_id`, `poll`, `cancel`, reminder, completion, relaunch, or async recovery | [async jobs](reference/async-jobs/SKILL.md) | | Recurring or time-triggered work | [scheduled work](reference/scheduled-work/SKILL.md) | | One future self-wakeup | [notification reminders](reference/notification-reminders/SKILL.md) | | Silent, duplicated, failed, or retired scheduler | [debugging and cleanup](reference/debugging-cleanup/SKILL.md) | | Unfamiliar dialect, working directory, timeout, or policy boundary | First success and Settings inventory below | | Backend-specific CLI flags, environment, or parser behavior | `daemon-manual` → `reference/cli-backends/SKILL.md` | ## First success 1. For a bounded command, call `shell(action="run", input={"command": "..."}, reasoning="...")` synchronously. Keep `working_dir` inside the sandbox; for an external checkout, leave it at the granted root and use `cd /absolute/path && ...` in the command. Dialect is fixed and policy still applies. 2. For work that may take minutes, set `input.async=true` and keep the returned `job_id`. On completion or a genuine health-check trigger, poll once for exact output; do not poll to stay active. Follow up with `shell(action="poll", input={"job_id": "..."}, reasoning="...")`; cancel only within authority with `shell(action="cancel", input={"job_id": "..."}, reasoning="...")`. A reminder means “may still be running,” not completion; cancellation is not cleanup. 3. Judge `exit_code`, `ok`, `command_status`, and `warning`; top-level `status` only records spawn/terminal handling, not inner command success. `status: "error"` means Shell could not run it. Prefer bounded `rg --files` and parse JSONL line by line. Unknown or late async state stays unknown: never invent an exit code, completion, or cancellation before durable terminal truth. Keep the job ID pollable after lease/return failure. Completion is authoritative; a reminder is fallback. Retain artifacts unless the human authorizes cleanup. Optional progress is channel-neutral; use `task_card(action="manual", input={})`. Shell creates no watcher. ## Settings inventory Call `shell(action="settings", input={}, reasoning="inspect applied Shell settings")` for read-only rows. The live schema/settings response owns values and configurability; this section owns only procedures. SHOW has no set/reset authority and an unavailable value fails the whole action without partial rows. | Row | Meaning, source and authorized change | |---|---| | `shell_kind` | Setup-selected `posix`, `powershell`, `cmd`, `gitbash` or `wsl`; valid capability value wins, then case-insensitive `LINGTAI_SHELL`, then platform discovery. Invalid values fall through; default is null because discovery has no universal shell. Change the capability/launcher or `setup(shell_kind=...)`, rebuild/relaunch the owning Agent, recheck SHOW. | | `sync_timeout_default_seconds` | Built-in 30, immutable; nullable call timeout uses it. A finite non-negative per-call timeout does not reconfigure it. | | `sync_timeout_max_seconds` | `LINGTAI_TOOL_TIMEOUT_MAX_SECONDS` read each call/SHOW: positive finite values win over 120, invalid/missing values use 120, and values below 30 are floored at 30. Change only the authorized process/launcher environment; relaunch if snapshotted. Work above the ceiling uses async. | | `result_max_chars` | Per-stream stdout/stderr capture limit, default 50000. Only an authorized embedding owner can pass positive `ShellManager(max_output=...)` before rebuilding the manager. Normal capability setup exposes no key or environment override. | | `async_default` | Built-in false, immutable; `input.async` selects one call. | | `async_reminder_default_seconds` | Built-in 1800, immutable. For one async run, `input.reminder` must be finite/non-negative within the platform timer bound; it is fallback, not completion. | | `command_policy` | Both values stay redacted. Default (omitted config or `shell: {}`) is yolo. Authorized setup selects explicit `yolo=true`, then `policy_file`, then packaged policy for explicit `yolo=false`; rebuild/relaunch and verify SHOW. No rules/paths are disclosed. | SHOW is strict-empty and read-only; there is no Shell settings file or mutation verb. Verify an authorized change through its owning construction procedure and SHOW. Result limits affect disclosure, not authority; no setting permits a working-directory escape.