---
description: 'Shell-operation guardrails for shared PowerShell sessions, tool availability checks, and multiline command workarounds'
applyTo: '**'
---

# Shell Operations

Use these rules when running shell commands from this workspace.

## General Rules

- Prefer built-in workspace tools for file search, text search, file reads, and edits before dropping to the terminal.
- Keep terminal commands short and single-line when possible.
- Treat the shared PowerShell session as fragile after any prompt-continuation or escape-sequence artifact appears.

## Tool Availability

- Do not assume `rg` is installed.
- Before using `rg`, check availability with `Get-Command rg -ErrorAction SilentlyContinue`.
- If `rg` is unavailable, use workspace search tools first.
- If shell-side fallback is still needed, use PowerShell-native alternatives:
  - `Get-ChildItem -Recurse -File` for file discovery
  - `Select-String` for text search

## Multiline Command Safety

- Do not paste multiline commands directly into the shared PowerShell terminal when a one-line command or script file will do.
- Do not send multiline PowerShell hash tables, arrays, or loops directly to the shared terminal if the same work can be expressed as:
  - one single-line command, or
  - a temporary `.ps1` script file executed with `pwsh -File`, or
  - a temporary `.py` file executed with Python for Python-side work.
- Always write multiline Python to a temporary `.py` file and execute that file instead of pasting Python into the terminal.

## Recovering From Terminal Weirdness

- If the prompt shows continuation markers, partial prompt redraws, or escape-sequence artifacts, stop issuing more complex commands in that shell.
- Try a single `Esc` first to clear unfinished input.
- If the shell still looks unhealthy, ask the user to reset or fix the terminal with the ask-questions tool before continuing.
- After recovery, resume with single-line commands or temporary script files instead of retrying the same multiline paste.

## Command Style

- Prefer explicit PowerShell cmdlets over aliases in reusable commands.
- Avoid commands that rely on interactive input.
- Prefer one focused command per terminal invocation so failures are easier to attribute.
- When posting HTTP form data from PowerShell, prefer compact one-line request bodies over multiline literal blocks in the shared shell.