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. A-priori root summarize defaults to true. Use it for anticipated long, bulky output; set summarize=false for expected short results or required exact text (for example a mandatory gate, path, field, source or diff). Give CLEAR retention targets in reasoning: status, key fields, counts and evidence, not extra interpretation. Narrow the read. Summaries are lossy; the raw original remains preserved for targeted recovery.

Route by task

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.

Durable filesystem changes

Shell is the one filesystem tool: there is no separate file family. The same sandbox, policy, and authority boundaries apply to every read and write.

1. Anchor the target. Work under the authorized working directory, or cd /absolute/path && ... inside the command for an approved external checkout. Never let a relative path or .. decide where a write lands.
2. Bound every read. Inspect metadata first (wc -lc, file, ls -l), then read a window: sed -n '120,200p' path, head -c 20000 path, rg -n 'pattern' path. A capped window is not the whole file; page by line range until you reach the end you measured.
3. Precondition an exact replacement. Before editing, prove the old text exists exactly once: rg -c -F 'old text' path must print 1. Then replace with a tool that does not reinterpret the text (for example a short python - <<'PY' block using str.replace(old, new, 1) on the UTF-8 content), never an unescaped sed -i over user data.
4. Create or overwrite deliberately. Read the target before a full rewrite; write with a heredoc (cat > path <<'EOF' ... EOF) or a Python block, and create parent directories explicitly (mkdir -p).
5. Verify the mutation. Re-read the changed lines (sed -n/rg -n) or compare (diff) before reporting success; the write receipt is the re-read, not the exit code alone.
6. Handle binary and non-UTF-8 honestly. Check file path first. Convert known encodings explicitly (iconv -f gbk -t utf-8) and treat lossy errors='replace' output as review material, not as the durable copy. Do not describe binary, image, or audio content you did not decode.
7. Rebuild when the owner requires it. Editing a durable prompt source (system/pad.md, system/lingtai.md, pinned references, knowledge, skills) changes disk only; it takes effect after context(action="rebuild", input={}) or a passive refresh/molt. The owning psyche domain manual and context(action="manual", input={}) own that procedure.

Keep private local paths out of human-facing results, and retain artifacts unless the human authorizes cleanup.

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.

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.