tool-description-powershell.md

Executes a given PowerShell command with optional timeout. Working directory persists between commands; shell state (variables, functions) does not.

IMPORTANT: This tool is for terminal operations via PowerShell: git, npm, docker, and PS cmdlets. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.

${RENDER_COMMAND_NOTES_FN(COMMAND_NOTES)}

Before executing the command, please follow these steps:

1. Directory Verification:

   • If the command will create new directories or files, first use Get-ChildItem (or ls) to verify the parent directory exists and is the correct location

2. Command Execution:

   • Always quote file paths that contain spaces with double quotes
   • Capture the output of the command.

PowerShell Syntax Notes:

• Variables use $ prefix: $myVar = "value"
• Escape character is backtick (`), not backslash
• Use Verb-Noun cmdlet naming: Get-ChildItem, Set-Location, New-Item, Remove-Item
• Common aliases: ls (Get-ChildItem), cd (Set-Location), cat (Get-Content), rm (Remove-Item)
• Pipe operator | works similarly to bash but passes objects, not text
• Use Select-Object, Where-Object, ForEach-Object for filtering and transformation
• String interpolation: "Hello $name" or "Hello $($obj.Property)"
• Registry access uses PSDrive prefixes: HKLM:\SOFTWARE\..., HKCU:\... — NOT raw HKEY_LOCAL_MACHINE\...
• Environment variables: read with $env:NAME, set with $env:NAME = "value" (NOT Set-Variable or bash export)
• Call native exe with spaces in path via call operator: & "C:\Program Files\App\app.exe" arg1 arg2

Interactive and blocking commands (will hang — this tool runs with -NonInteractive):

• NEVER use Read-Host, Get-Credential, Out-GridView, $Host.UI.PromptForChoice, or pause
• Destructive cmdlets (Remove-Item, Stop-Process, Clear-Content, etc.) may prompt for confirmation. Add -Confirm:$false when you intend the action to proceed. Use -Force for read-only/hidden items.
• Never use git rebase -i, git add -i, or other commands that open an interactive editor

Passing multiline strings (commit messages, file content) to native executables:

• Use a single-quoted here-string so PowerShell does not expand $ or backticks inside. The closing '@ MUST be at column 0 (no leading whitespace) on its own line — indenting it is a parse error:

git commit -m @' Commit message here. Second line with $literal dollar signs. '@ - Use `@'...'@` (single-quoted, literal) not `@"..."@` (double-quoted, interpolated) unless you need variable expansion - For arguments containing `-`, `@`, or other characters PowerShell parses as operators, use the stop-parsing token: `git log --% --format=%H`

Usage notes:

• The command argument is required.
• You can specify an optional timeout in milliseconds (up to ${MAX_TIMEOUT_MS_FN()}ms / ${MAX_TIMEOUT_MS_FN()/60000} minutes). If not specified, commands will timeout after ${DEFAULT_TIMEOUT_MS_FN()}ms (${DEFAULT_TIMEOUT_MS_FN()/60000} minutes).
• It is very helpful if you write a clear, concise description of what this command does.
• If the output exceeds ${MAX_OUTPUT_CHARS_FN()} characters, output will be truncated before being returned to you. ${CUSTOM_USAGE_NOTE?CUSTOM_USAGE_NOTE+ :""} - Avoid using PowerShell to run commands that have dedicated tools, unless explicitly instructed:
  • File search: Use ${GLOB_TOOL_NAME} (NOT Get-ChildItem -Recurse)
  • Content search: Use ${GREP_TOOL_NAME} (NOT Select-String)
  • Read files: Use ${READ_TOOL_NAME} (NOT Get-Content)
  • Edit files: Use ${EDIT_TOOL_NAME}
  • Write files: Use ${WRITE_TOOL_NAME} (NOT Set-Content/Out-File)
  • Communication: Output text directly (NOT Write-Output/Write-Host)
• When issuing multiple commands:
  • If the commands are independent and can run in parallel, make multiple ${POWERSHELL_TOOL_NAME} tool calls in a single message.
  • If the commands depend on each other and must run sequentially, chain them in a single ${POWERSHELL_TOOL_NAME} call (see edition-specific chaining syntax above).
  • Use ; only when you need to run commands sequentially but don't care if earlier commands fail.
  • DO NOT use newlines to separate commands (newlines are ok in quoted strings and here-strings)
• Do NOT prefix commands with cd or Set-Location -- the working directory is already set to the correct project directory automatically. ${CUSTOM_GIT_NOTES?CUSTOM_GIT_NOTES+ :""} - For git commands:
  • Prefer to create a new commit rather than amending an existing commit.
  • Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
  • Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.