🤖 docs: add reusable run_and_report helper for mux bash tools

Add a project-level .mux/tool_env that defines run_and_report so bash
invocations can reuse consistent step logging and fail-fast behavior.
Document the helper in AGENTS.md with usage examples.

---

_Generated with [`mux`](https://github.com/coder/mux) • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.20`_

<!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh costs=0.20 -->

Author: ThomasK33

.mux/tool_env

@@ -0,0 +1,33 @@
+# .mux/tool_env
+# Sourced by Mux before every bash tool invocation.
+# Docs: https://mux.coder.com/hooks/tools
+
+run_and_report() {
+  local step_name="${1:-}"
+  if [[ -z "${step_name}" ]]; then
+    echo "assertion failed: run_and_report requires a non-empty step name" >&2
+    return 97
+  fi
+  shift
+
+  if [[ "$#" -eq 0 ]]; then
+    echo "assertion failed: run_and_report requires a command after the step name" >&2
+    return 97
+  fi
+
+  local safe_name
+  safe_name="$(printf '%s' "${step_name}" | tr -cs 'A-Za-z0-9._-' '_')"
+  local workspace_tag="${MUX_WORKSPACE_ID:-local}"
+  local log_file="/tmp/mux-${workspace_tag}-${safe_name}.log"
+
+  echo "==> Running ${step_name}"
+  if "$@" >"${log_file}" 2>&1; then
+    echo "==> ${step_name} passed"
+    return 0
+  else
+    local exit_code=$?
+    echo "==> ${step_name} failed (showing tail from ${log_file})" >&2
+    tail -n 120 "${log_file}" >&2 || true
+    return "${exit_code}"
+  fi
+}

AGENTS.md

@@ -69,6 +69,15 @@ Run from repository root.
 - **Clean:** `go clean -cache -testcache && rm -f ./coder-k8s && rm -rf ./dist`
 - **Shell scripts:** `find . -type f -name '*.sh' -not -path './vendor/*'`
 
+## Mux Tooling Helpers
+
+- `.mux/tool_env` is sourced before every `bash` tool call (Mux docs: `/hooks/tools`).
+- Use `run_and_report <step_name> <command...>` for multi-step validation in one bash invocation.
+- The helper writes full logs to `/tmp/mux-<workspace>-<step>.log`, prints pass/fail markers, and tails failures.
+- Example:
+  - `run_and_report verify-vendor make verify-vendor`
+  - `run_and_report test make test`
+
 ## Patterns
 
 - **Do** preserve fail-fast assertions for impossible states (nil manager/client/scheme, mismatched fetched objects).