agent-relay-runner 0.62.2 → 0.63.0

package/plugins/claude/hooks/read-only-bash-guard.sh

@@ -0,0 +1,689 @@
+#!/usr/bin/env bash
+# BEST-EFFORT GUARDRAIL / defense-in-depth only. This hook denies common
+# mutating Bash patterns for read-only Claude sessions, but it is not a sandbox.
+# Real boundaries are Relay token scope, unavailable write tools, and future
+# OS-level enforcement.
+set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard read-only-bash-guard
+
+payload="$(cat)"
+
+emit_deny() {
+  local reason="${1:-Read-only Claude sessions may only run inspection commands.}"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' \
+    "$(relay_json_escape "$reason")"
+}
+
+case "${AGENT_RELAY_APPROVAL:-}" in
+  open|guarded)
+    exit 0
+    ;;
+  read-only)
+    ;;
+  *)
+    # Unknown approval values fail closed so typos such as "readonly" or
+    # casing drift do not silently disable the read-only boundary.
+    ;;
+esac
+
+if ! command -v jq >/dev/null 2>&1; then
+  emit_deny "Read-only Bash guard could not inspect the command because jq is unavailable."
+  exit 0
+fi
+
+tool_name="$(printf '%s' "$payload" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+if [ "${tool_name,,}" != "bash" ]; then
+  exit 0
+fi
+
+command_text="$(printf '%s' "$payload" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
+if [ -z "$command_text" ]; then
+  emit_deny "Read-only Bash guard denied an empty Bash command."
+  exit 0
+fi
+
+shopt -s extglob
+
+DENY_REASON=""
+SEGMENTS=()
+WORDS=()
+
+deny_segment() {
+  DENY_REASON="$1"
+  return 1
+}
+
+trim_shell_text() {
+  local value="$1"
+  value="${value##+([[:space:]])}"
+  value="${value%%+([[:space:]])}"
+  printf '%s' "$value"
+}
+
+hard_deny_reason() {
+  local text="$1"
+  case "$text" in
+    *'$('*|*'`'*)
+      printf '%s' "Read-only Bash guard denied command substitution."
+      return 0
+      ;;
+    *'<('*|*'>('*)
+      printf '%s' "Read-only Bash guard denied process substitution."
+      return 0
+      ;;
+  esac
+
+  local i len ch next quote="" escaped=0
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      fi
+      continue
+    fi
+
+    case "$ch" in
+      "'"|'"')
+        quote="$ch"
+        ;;
+      "\\")
+        escaped=1
+        ;;
+      ">")
+        printf '%s' "Read-only Bash guard denied shell output redirection."
+        return 0
+        ;;
+      "<")
+        next="${text:i+1:1}"
+        if [ "$next" = ">" ]; then
+          printf '%s' "Read-only Bash guard denied shell output redirection."
+          return 0
+        fi
+        ;;
+    esac
+  done
+
+  return 1
+}
+
+split_segments() {
+  local text="$1"
+  local current="" i len ch next quote="" escaped=0
+  SEGMENTS=()
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      current+="$ch"
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      current+="$ch"
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      fi
+      continue
+    fi
+
+    case "$ch" in
+      "'"|'"')
+        quote="$ch"
+        current+="$ch"
+        ;;
+      "\\")
+        escaped=1
+        current+="$ch"
+        ;;
+      $'\n'|";")
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      "&")
+        next="${text:i+1:1}"
+        if [ "$next" = "&" ]; then
+          ((i += 1))
+        fi
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      "|")
+        next="${text:i+1:1}"
+        if [ "$next" = "|" ]; then
+          ((i += 1))
+        fi
+        SEGMENTS+=("$current")
+        current=""
+        ;;
+      *)
+        current+="$ch"
+        ;;
+    esac
+  done
+
+  if [ -n "$quote" ] || (( escaped )); then
+    return 1
+  fi
+  SEGMENTS+=("$current")
+  return 0
+}
+
+shell_words() {
+  local text="$1"
+  local word="" i len ch quote="" escaped=0 in_word=0
+  WORDS=()
+  len=${#text}
+  for ((i = 0; i < len; i++)); do
+    ch="${text:i:1}"
+    if (( escaped )); then
+      word+="$ch"
+      in_word=1
+      escaped=0
+      continue
+    fi
+    if [ -n "$quote" ]; then
+      if [ "$quote" = '"' ] && [ "$ch" = "\\" ]; then
+        escaped=1
+        continue
+      fi
+      if [ "$ch" = "$quote" ]; then
+        quote=""
+      else
+        word+="$ch"
+      fi
+      in_word=1
+      continue
+    fi
+
+    case "$ch" in
+      [[:space:]])
+        if (( in_word )); then
+          WORDS+=("$word")
+          word=""
+          in_word=0
+        fi
+        ;;
+      "'"|'"')
+        quote="$ch"
+        in_word=1
+        ;;
+      "\\")
+        escaped=1
+        in_word=1
+        ;;
+      *)
+        word+="$ch"
+        in_word=1
+        ;;
+    esac
+  done
+
+  if [ -n "$quote" ] || (( escaped )); then
+    return 1
+  fi
+  if (( in_word )); then
+    WORDS+=("$word")
+  fi
+  return 0
+}
+
+validate_git_branch() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    case "$arg" in
+      --list|--all|--remotes|--show-current|-a|-r|-v|-vv)
+        ;;
+      *)
+        deny_segment "Read-only Bash guard denied a git branch mutation or unsupported branch option."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_git_read_args() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      --output|--output=*)
+        deny_segment "Read-only Bash guard denied git output-to-file options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_git() {
+  local i="$1" arg sub
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    case "$arg" in
+      -C)
+        ((i += 1))
+        if (( i >= ${#WORDS[@]} )); then
+          deny_segment "Read-only Bash guard denied git -C without a path."
+          return 1
+        fi
+        ((i += 1))
+        ;;
+      --no-pager)
+        ((i += 1))
+        ;;
+      -c|--config-env|--config-env=*)
+        deny_segment "Read-only Bash guard denied git configuration or alias injection."
+        return 1
+        ;;
+      --)
+        ((i += 1))
+        break
+        ;;
+      -*)
+        deny_segment "Read-only Bash guard denied an unsupported git global option."
+        return 1
+        ;;
+      *)
+        break
+        ;;
+    esac
+  done
+
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied git without an explicit read-only subcommand."
+    return 1
+  fi
+
+  sub="${WORDS[i],,}"
+  ((i += 1))
+  case "$sub" in
+    diff|log|status|show|blame|grep|rev-parse|describe)
+      validate_git_read_args "$i"
+      return $?
+      ;;
+    branch)
+      validate_git_branch "$i"
+      return $?
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied a git subcommand that is not in the read-only allow-list."
+      return 1
+      ;;
+  esac
+}
+
+find_arg_takes_operand() {
+  local arg="$1"
+  case "$arg" in
+    -name|-iname|-path|-ipath|-wholename|-iwholename|-regex|-iregex|-type|-xtype|-user|-group|-newer|-samefile|-size|-perm|-mtime|-mmin|-atime|-amin|-ctime|-cmin|-maxdepth|-mindepth|-printf|-printf0)
+      return 0
+      ;;
+    -newer??)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+validate_find() {
+  local i="$1" arg skip_next=0
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if (( skip_next )); then
+      skip_next=0
+      ((i += 1))
+      continue
+    fi
+    case "$arg" in
+      -exec|-execdir|-ok|-okdir|-delete|-fls|-fprint|-fprintf|-fprint0)
+        deny_segment "Read-only Bash guard denied find mutating action predicates."
+        return 1
+        ;;
+    esac
+    if find_arg_takes_operand "$arg"; then
+      skip_next=1
+    fi
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_fd() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      -x|-X|--exec|--exec-batch)
+        deny_segment "Read-only Bash guard denied fd exec action options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_rg() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      --pre|--pre=*)
+        deny_segment "Read-only Bash guard denied rg preprocessor execution options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_sort() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      -o|-o?*|--output|--output=*)
+        deny_segment "Read-only Bash guard denied sort output-to-file options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+uniq_arg_takes_operand() {
+  local arg="$1"
+  case "$arg" in
+    -f|-s|-w|--skip-fields|--skip-chars|--check-chars)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+validate_uniq() {
+  local i="$1" arg operands=0 after_options=0 skip_next=0
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if (( skip_next )); then
+      skip_next=0
+      ((i += 1))
+      continue
+    fi
+    if (( ! after_options )) && [ "$arg" = "--" ]; then
+      after_options=1
+      ((i += 1))
+      continue
+    fi
+    if (( ! after_options )) && [ "$arg" != "-" ] && [[ "$arg" == -* ]]; then
+      if uniq_arg_takes_operand "$arg"; then
+        skip_next=1
+      fi
+      ((i += 1))
+      continue
+    fi
+
+    ((operands += 1))
+    if (( operands > 1 )); then
+      deny_segment "Read-only Bash guard denied uniq output-file operands."
+      return 1
+    fi
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_yq() {
+  local i="$1" arg
+  while (( i < ${#WORDS[@]} )); do
+    arg="${WORDS[i]}"
+    if [ "$arg" = "--" ]; then
+      return 0
+    fi
+    case "$arg" in
+      -i|-i?*|--inplace|--inplace=*)
+        deny_segment "Read-only Bash guard denied yq in-place edit options."
+        return 1
+        ;;
+    esac
+    ((i += 1))
+  done
+  return 0
+}
+
+validate_bun() {
+  local i="$1" sub next
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied bun without an explicit test/typecheck command."
+    return 1
+  fi
+  sub="${WORDS[i],,}"
+  case "$sub" in
+    test)
+      return 0
+      ;;
+    run)
+      next="${WORDS[i+1]:-}"
+      if [ "$next" = "typecheck" ]; then
+        return 0
+      fi
+      deny_segment "Read-only Bash guard only allows bun run typecheck in read-only sessions."
+      return 1
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied a bun command outside the test/typecheck allow-list."
+      return 1
+      ;;
+  esac
+}
+
+validate_agent_relay() {
+  local i="$1" sub next
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied agent-relay without an allowed read/message subcommand."
+    return 1
+  fi
+  sub="${WORDS[i]}"
+  next="${WORDS[i+1]:-}"
+  case "$sub" in
+    /reply|/react|/message|/status|/read-message|/tags|/whoami|/guide)
+      return 0
+      ;;
+    get-message|status|whoami|guide|tags)
+      return 0
+      ;;
+    workspace)
+      if [ "$next" = "status" ]; then
+        return 0
+      fi
+      deny_segment "Read-only Bash guard denied a mutating agent-relay workspace command."
+      return 1
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied an agent-relay command outside the read/message allow-list."
+      return 1
+      ;;
+  esac
+}
+
+validate_leading_assignment() {
+  local assignment="$1" name value
+  name="${assignment%%=*}"
+  value="${assignment#*=}"
+
+  case "$name" in
+    LANG|LANGUAGE|LC_*)
+      if [[ "$value" =~ ^[A-Za-z0-9_.:@+-]+$ ]]; then
+        return 0
+      fi
+      ;;
+    TZ)
+      if [[ "$value" =~ ^[A-Za-z0-9_+:-]+(/[A-Za-z0-9_+:-]+)*$ ]]; then
+        return 0
+      fi
+      ;;
+    PAGER|GIT_PAGER)
+      if [ "$value" = "cat" ]; then
+        return 0
+      fi
+      ;;
+  esac
+
+  deny_segment "Read-only Bash guard denied unsafe leading environment assignment."
+  return 1
+}
+
+validate_segment() {
+  local raw="$1" segment i=0 saw_assignment=0 command_name base
+  segment="$(trim_shell_text "$raw")"
+  if [ -z "$segment" ]; then
+    return 0
+  fi
+  if ! shell_words "$segment"; then
+    deny_segment "Read-only Bash guard denied shell syntax it could not parse."
+    return 1
+  fi
+  if (( ${#WORDS[@]} == 0 )); then
+    return 0
+  fi
+
+  while (( i < ${#WORDS[@]} )) && [[ "${WORDS[i]}" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; do
+    if ! validate_leading_assignment "${WORDS[i]}"; then
+      return 1
+    fi
+    saw_assignment=1
+    ((i += 1))
+  done
+
+  if (( i >= ${#WORDS[@]} )); then
+    deny_segment "Read-only Bash guard denied an assignment-only shell segment."
+    return 1
+  fi
+
+  command_name="${WORDS[i]}"
+  if [[ "$command_name" == \$* ]]; then
+    deny_segment "Read-only Bash guard denied an indirect command name."
+    return 1
+  fi
+
+  base="${command_name##*/}"
+  base="${base,,}"
+  if [ -z "$base" ]; then
+    deny_segment "Read-only Bash guard denied an empty command name."
+    return 1
+  fi
+
+  case "$base" in
+    bash|sh|zsh|dash|env|python*|node|ruby|perl|php|awk|eval|exec|source|.)
+      deny_segment "Read-only Bash guard denied a nested shell, interpreter, or shell re-entry command."
+      return 1
+      ;;
+  esac
+
+  if (( saw_assignment )) && [[ "$command_name" == *'$'* ]]; then
+    deny_segment "Read-only Bash guard denied assignment-based command indirection."
+    return 1
+  fi
+
+  case "$base" in
+    git)
+      validate_git "$((i + 1))"
+      return $?
+      ;;
+    find)
+      validate_find "$((i + 1))"
+      return $?
+      ;;
+    fd)
+      validate_fd "$((i + 1))"
+      return $?
+      ;;
+    rg)
+      validate_rg "$((i + 1))"
+      return $?
+      ;;
+    sort)
+      validate_sort "$((i + 1))"
+      return $?
+      ;;
+    uniq)
+      validate_uniq "$((i + 1))"
+      return $?
+      ;;
+    yq)
+      validate_yq "$((i + 1))"
+      return $?
+      ;;
+    grep|cat|ls|head|tail|wc|pwd|jq|nl|cut)
+      return 0
+      ;;
+    bun)
+      validate_bun "$((i + 1))"
+      return $?
+      ;;
+    agent-relay)
+      validate_agent_relay "$((i + 1))"
+      return $?
+      ;;
+    *)
+      deny_segment "Read-only Bash guard denied a command outside the read-only allow-list."
+      return 1
+      ;;
+  esac
+}
+
+if reason="$(hard_deny_reason "$command_text")"; then
+  emit_deny "$reason"
+  exit 0
+fi
+
+if ! split_segments "$command_text"; then
+  emit_deny "Read-only Bash guard denied shell syntax it could not parse."
+  exit 0
+fi
+
+for segment in "${SEGMENTS[@]}"; do
+  if ! validate_segment "$segment"; then
+    emit_deny "${DENY_REASON:-Read-only Claude sessions may only run explicit inspection commands.}"
+    exit 0
+  fi
+done
+
+exit 0