Executes shell commands in a subprocess with optional timeout.

This tool is for terminal operations like git, npm, docker, package managers, build tools, and system commands. 

# Permission System

IMPORTANT: Certain commands require user permission before execution. The user will be prompted to approve or deny:

**Git commands requiring permission:**
- git commit, push, pull, fetch, merge, rebase
- git reset, checkout (when modifying state)
- git stash, cherry-pick, revert, tag
- git branch -d/-D, clean
- Any git command with --force or --hard flags

**GitHub CLI commands requiring permission:**
- gh pr create, gh pr merge
- gh issue create, gh release create

**Other dangerous commands requiring permission:**
- rm -rf, rm -r, sudo, chmod, chown
- Any command that could cause data loss

When permission is denied, you will receive an error message. Do NOT retry the same command without asking the user first.

IMPORTANT: DO NOT use bash for file operations - use the specialized tools instead:
- Reading files → use read tool (NOT cat, head, tail)
- Editing files → use edit tool (NOT sed, awk)
- Writing files → use write tool (NOT echo, cat with heredoc)
- Finding files → use glob tool (NOT find, ls)
- Searching content → use grep tool (NOT grep, rg)

Usage:
- command: The shell command to execute (required)
- cwd: Working directory for the command (optional, defaults to project root)
- timeout: Maximum execution time in seconds (optional, default: 120)

Best practices:
- Always quote file paths that contain spaces: `rm "path with spaces/file.txt"`
- Use cwd parameter instead of `cd dir && command`
- For multiple independent commands, make parallel tool calls
- For dependent commands, chain with && in a single call

<example>
Running tests
[bash command="pytest tests/" cwd="/home/user/project"]
</example>

<example>
Installing dependencies
[bash command="pip install -r requirements.txt" cwd="/home/user/project"]
</example>

<example>
Building a project
[bash command="npm run build" cwd="/home/user/project"]
</example>

# Git Operations

Only create commits when the user explicitly requests it. Follow these guidelines:

1. Before committing, run these commands in parallel:
   - `git status` to see untracked and modified files
   - `git diff` to see staged and unstaged changes
   - `git log --oneline -5` to see recent commit message style

2. Write commit messages that:
   - Are concise (1-2 sentences)
   - Focus on "why" not "what"
   - Follow the repository's existing style

3. Git safety rules:
   - NEVER use --force or --hard unless explicitly requested
   - NEVER skip hooks (--no-verify) unless explicitly requested  
   - NEVER commit files containing secrets (.env, credentials, API keys)
   - NEVER push to remote unless explicitly asked
   - NEVER use interactive flags (-i) as they require user input

<example>
Creating a commit (when asked)
Step 1: Check status and diff in parallel
[bash command="git status"]
[bash command="git diff"]
[bash command="git log --oneline -5"]

Step 2: Stage and commit
[bash command="git add src/feature.py && git commit -m 'Add user validation to signup flow'"]
</example>

# Creating Pull Requests

Use the `gh` CLI for GitHub operations:

<example>
Creating a PR
[bash command="gh pr create --title 'Add user authentication' --body '## Summary
- Implement JWT-based auth
- Add login/logout endpoints
- Include session management'"]
</example>

# Common Command Patterns

Build commands:
- Python: `pip install -e .`, `python setup.py build`
- Node: `npm install`, `npm run build`, `yarn build`
- Rust: `cargo build`, `cargo build --release`
- Go: `go build`, `go mod tidy`

Test commands:
- Python: `pytest`, `python -m pytest tests/`
- Node: `npm test`, `jest`, `vitest`
- Rust: `cargo test`
- Go: `go test ./...`

Lint/format commands:
- Python: `ruff check .`, `black .`, `mypy .`
- Node: `eslint .`, `prettier --check .`
- Rust: `cargo clippy`, `cargo fmt --check`

Common mistakes to avoid:
- DO NOT use cat/head/tail to read files - use read tool
- DO NOT use sed/awk to edit files - use edit tool
- DO NOT use find to locate files - use glob tool
- DO NOT use grep/rg to search - use grep tool
- DO NOT run interactive commands (vim, nano, less, etc.)
- DO NOT use & for background processes - they won't persist
- DO NOT use cd && command - use cwd parameter instead
