From de8460cb99151d774f2179e5e67f77a4e26e4210 Mon Sep 17 00:00:00 2001
From: Dax Raad <d@ironbay.co>
Date: Wed, 10 Dec 2025 08:48:41 -0500
Subject: [PATCH] docs: improve bash and grep tool documentation with clearer
 usage guidelines

---
 packages/opencode/src/tool/bash.txt | 50 ++++++++++++++++++++++++-----
 packages/opencode/src/tool/grep.txt |  2 +-
 2 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/packages/opencode/src/tool/bash.txt b/packages/opencode/src/tool/bash.txt
index b0f68d2b7..2773d3b85 100644
--- a/packages/opencode/src/tool/bash.txt
+++ b/packages/opencode/src/tool/bash.txt
@@ -17,14 +17,48 @@ Before executing the command, please follow these steps:
    - Capture the output of the command.
 
 Usage notes:
-  - The command argument is required.
-  - You can specify an optional timeout in milliseconds. If not specified, commands will timeout after 120000ms (2 minutes). Use the `timeout` parameter to control execution time.
-  - The `workdir` parameter specifies the working directory for the command. Defaults to the current working directory. Prefer setting `workdir` over using `cd` in your commands.
-  - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
-  - If the output exceeds 30000 characters, output will be truncated before being returned to you.
-  - VERY IMPORTANT: You MUST avoid using search commands like `find` and `grep`. Instead use Grep, Glob, or Task to search. You MUST avoid read tools like `cat`, `head`, `tail`, and `ls`, and use Read and List to read files.
-  - If you _still_ need to run `grep`, STOP. ALWAYS USE ripgrep at `rg` (or /usr/bin/rg) first, which all opencode users have pre-installed.
-  - When issuing multiple commands, use the ';' or '&&' operator to separate them. DO NOT use newlines (newlines are ok in quoted strings).
+    - The command argument is required.
+    - You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes).
+  If not specified, commands will timeout after 120000ms (2 minutes).
+    - It is very helpful if you write a clear, concise description of what this command
+  does in 5-10 words.
+    - If the output exceeds 30000 characters, output will be truncated before being
+  returned to you.
+    - You can use the `run_in_background` parameter to run the command in the background,
+  which allows you to continue working while the command runs. You can monitor the output
+  using the Bash tool as it becomes available. You do not need to use '&' at the end of
+  the command when using this parameter.
+
+    - Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or
+  `echo` commands, unless explicitly instructed or when these commands are truly necessary
+   for the task. Instead, always prefer using the dedicated tools for these commands:
+      - File search: Use Glob (NOT find or ls)
+      - Content search: Use Grep (NOT grep or rg)
+      - Read files: Use Read (NOT cat/head/tail)
+      - Edit files: Use Edit (NOT sed/awk)
+      - Write files: Use Write (NOT echo >/cat <<EOF)
+      - Communication: Output text directly (NOT echo/printf)
+    - When issuing multiple commands:
+      - If the commands are independent and can run in parallel, make multiple Bash tool
+  calls in a single message. For example, if you need to run "git status" and "git diff",
+  send a single message with two Bash tool calls in parallel.
+      - If the commands depend on each other and must run sequentially, use a single Bash
+  call with '&&' to chain them together (e.g., `git add . && git commit -m "message" &&
+  git push`). For instance, if one operation must complete before another starts (like
+  mkdir before cp, Write before Bash for git operations, or git add before git commit),
+  run these operations sequentially instead.
+      - 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)
+    - Try to maintain your current working directory throughout the session by using
+  absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly
+  requests it.
+      <good-example>
+      pytest /foo/bar/tests
+      </good-example>
+      <bad-example>
+      cd /foo/bar && pytest tests
+      </bad-example>
 
 # Working Directory
 
diff --git a/packages/opencode/src/tool/grep.txt b/packages/opencode/src/tool/grep.txt
index d964a3d1f..6067ef27b 100644
--- a/packages/opencode/src/tool/grep.txt
+++ b/packages/opencode/src/tool/grep.txt
@@ -2,7 +2,7 @@
 - Searches file contents using regular expressions
 - Supports full regex syntax (eg. "log.*Error", "function\s+\w+", etc.)
 - Filter files by pattern with the include parameter (eg. "*.js", "*.{ts,tsx}")
-- Returns file paths with at least one match sorted by modification time
+- Returns file paths and line numbers with at least one match sorted by modification time
 - Use this tool when you need to find files containing specific patterns
 - If you need to identify/count the number of matches within files, use the Bash tool with `rg` (ripgrep) directly. Do NOT use `grep`.
 - When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Task tool instead