agent-relay-plugin 0.4.13 → 0.4.15

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "agent-relay",
   "description": "Client connector for Agent Relay — auto-registers Claude Code sessions as agents and enables inter-agent messaging via a lightweight HTTP message bus",
-  "version": "0.4.11"
+  "version": "0.4.15"
 }

package/hooks/approval-gate.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# Agent Relay plugin — approval gate for PreToolUse and PermissionDenied hooks.
+# Enforces AGENT_RELAY_APPROVAL policy: open (default), guarded, read-only.
+
+MODE="${AGENT_RELAY_APPROVAL:-open}"
+[ "$MODE" = "open" ] && exit 0
+
+input=$(cat)
+event=$(printf '%s' "$input" | jq -r '.hook_event_name')
+
+# --- PermissionDenied: allow retry so the model adapts ---
+if [ "$event" = "PermissionDenied" ]; then
+  jq -n '{hookSpecificOutput:{hookEventName:"PermissionDenied",retry:true}}'
+  exit 0
+fi
+
+tool=$(printf '%s' "$input" | jq -r '.tool_name')
+
+# --- Always allowed: read-only and orchestration tools ---
+case "$tool" in
+  Read|Grep|Glob|WebFetch|WebSearch|Agent|Monitor|ToolSearch|AskUserQuestion|Skill|ScheduleWakeup|CronList|EnterPlanMode|ExitPlanMode)
+    exit 0 ;;
+  Task*|*McpResource*)
+    exit 0 ;;
+  mcp__*)
+    exit 0 ;;
+esac
+
+deny() {
+  jq -n --arg r "$1" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'
+  exit 0
+}
+
+# --- read-only: deny mutation tools ---
+if [ "$MODE" = "read-only" ]; then
+  case "$tool" in
+    Write|Edit|NotebookEdit|CronCreate|CronDelete|PushNotification|RemoteTrigger|EnterWorktree|ExitWorktree)
+      deny "${tool} blocked by read-only policy" ;;
+  esac
+fi
+
+# --- Bash command analysis ---
+if [ "$tool" = "Bash" ]; then
+  cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')
+
+  if [ "$MODE" = "guarded" ]; then
+    # Denylist: block destructive patterns anywhere in the command
+    if printf '%s' "$cmd" | grep -qE '(^|[;&|]\s*)\s*(rm|rmdir)\b'; then
+      deny "rm/rmdir blocked by guarded policy"
+    fi
+    if printf '%s' "$cmd" | grep -qE '(^|[;&|]\s*)\s*mv\b'; then
+      deny "mv blocked by guarded policy (use cp instead)"
+    fi
+    if printf '%s' "$cmd" | grep -qE '(^|[;&|]\s*)\s*(chmod|chown|chattr)\b'; then
+      deny "Permission change blocked by guarded policy"
+    fi
+    if printf '%s' "$cmd" | grep -qE '(^|[;&|]\s*)\s*(kill|pkill|killall)\b'; then
+      deny "Process signal blocked by guarded policy"
+    fi
+    if printf '%s' "$cmd" | grep -qE '(^|[;&|]\s*)\s*(dd|mkfs|truncate|shred)\b'; then
+      deny "Destructive command blocked by guarded policy"
+    fi
+    if printf '%s' "$cmd" | grep -qE '(^|[;&|]\s*)\s*sudo\b'; then
+      deny "sudo blocked by guarded policy"
+    fi
+    if printf '%s' "$cmd" | grep -qE 'git\s+(reset\s+--hard|push\s+.*(-f\b|--force)|clean\s+-[a-z]*f)'; then
+      deny "Destructive git operation blocked by guarded policy"
+    fi
+    exit 0
+  fi
+
+  if [ "$MODE" = "read-only" ]; then
+    # Check for file-writing redirects (allow >/dev/null and fd redirects like 2>&1)
+    redirect_cleaned=$(printf '%s' "$cmd" | sed 's|[0-9]*>[[:space:]]*/dev/null||g; s|[0-9]*>&[0-9]*||g')
+    if printf '%s' "$redirect_cleaned" | grep -qE '>>|[^a-zA-Z0-9_]>|^>'; then
+      deny "Output redirection blocked by read-only policy"
+    fi
+
+    # Allowlist: check first command word
+    first_word=$(printf '%s' "$cmd" | sed 's/^[[:space:]]*//' | awk '{print $1}')
+
+    case "$first_word" in
+      # Filesystem reads
+      ls|cat|head|tail|less|more|file|stat|tree|du|df|readlink|realpath|basename|dirname)
+        exit 0 ;;
+      # Text processing
+      wc|sort|uniq|diff|comm|tr|cut|paste|column|fmt|fold|tac|rev|nl|seq|xargs)
+        exit 0 ;;
+      # Search
+      find|fd|grep|egrep|fgrep|rg|ag|ast-grep)
+        exit 0 ;;
+      # Shell builtins / info
+      echo|printf|pwd|which|whoami|date|env|printenv|uname|id|hostname|type|true|false|test|\[)
+        exit 0 ;;
+      # System info
+      ps|top|htop|uptime|free|lsof|netstat|ss|ip|ifconfig)
+        exit 0 ;;
+      # Data processing
+      jq|yq|bc|expr|base64|xxd|hexdump|od|strings|md5sum|sha256sum|sha1sum|shasum)
+        exit 0 ;;
+      # Network reads
+      curl|wget|dig|nslookup|ping|traceroute|ssh)
+        exit 0 ;;
+      # Git — subcommand check
+      git)
+        git_sub=$(printf '%s' "$cmd" | sed 's/^[[:space:]]*git[[:space:]]*//' | awk '{print $1}')
+        case "$git_sub" in
+          status|log|diff|show|branch|remote|tag|rev-parse|config|shortlog|reflog|blame|describe|ls-files|ls-tree|cat-file|rev-list|for-each-ref|name-rev|merge-base|version)
+            exit 0 ;;
+          stash)
+            stash_action=$(printf '%s' "$cmd" | sed 's/.*stash[[:space:]]*//' | awk '{print $1}')
+            case "$stash_action" in
+              list|show|"") exit 0 ;;
+              *) deny "git stash ${stash_action} blocked by read-only policy" ;;
+            esac ;;
+          *)
+            deny "git ${git_sub} blocked by read-only policy" ;;
+        esac ;;
+      # Everything else denied
+      *)
+        deny "Command '${first_word}' not in read-only allowlist" ;;
+    esac
+  fi
+fi
+
+# Unknown tools: guarded → allow, read-only → deny
+if [ "$MODE" = "read-only" ]; then
+  deny "${tool} not in read-only allowlist"
+fi
+
+exit 0

package/hooks/hooks.json

@@ -1,5 +1,27 @@
 {
   "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/approval-gate.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PermissionDenied": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/approval-gate.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [

package/hooks/poll-inbox.sh

@@ -18,12 +18,64 @@ fi
 
 # PID file so session-start.sh can find and kill us on /clear or /compact.
 pid_file="/tmp/agent-relay-poll-${AGENT_ID}.pid"
+status_file="/tmp/agent-relay-status-${AGENT_ID}.state"
 cleanup() { rm -f "$pid_file"; }
 trap cleanup EXIT
 echo $$ > "$pid_file"
 
+fetch_cursor() {
+  local cursor
+  cursor=$(curl -s --fail "${auth_header_args[@]}" "${RELAY_URL}/api/messages/cursor" 2>/dev/null | jq -r '.latestId // empty' 2>/dev/null) || return 1
+  case "$cursor" in
+    ''|*[!0-9]*) return 1 ;;
+    *) printf '%s\n' "$cursor" ;;
+  esac
+}
+
+current_status() {
+  local status
+  status=$(head -1 "$status_file" 2>/dev/null || true)
+  case "$status" in
+    online|idle|busy|offline) printf '%s\n' "$status" ;;
+    *) printf 'idle\n' ;;
+  esac
+}
+
+re_register() {
+  local machine rig project caps_csv caps_json approval reg_code
+  machine=$(hostname)
+  project=$(basename "${PWD:-unknown}")
+  if [ -n "$CLAUDE_RIG_NAME" ]; then rig="$CLAUDE_RIG_NAME"
+  elif [ -n "$CLAUDE_CONFIG_DIR" ]; then rig=$(basename "$CLAUDE_CONFIG_DIR")
+  else rig="default"; fi
+  caps_csv="${AGENT_RELAY_CAPS:-chat}"
+  caps_json=$(echo "$caps_csv" | jq -R 'split(",") | map(gsub("^\\s+|\\s+$"; ""))')
+  approval="${AGENT_RELAY_APPROVAL:-open}"
+
+  reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agents" "${auth_header_args[@]}" \
+    -H 'Content-Type: application/json' \
+    -d "$(jq -n \
+      --arg id "$AGENT_ID" \
+      --arg name "$project ($rig @ $machine)" \
+      --arg machine "$machine" \
+      --arg rig "$rig" \
+      --argjson tags "$(jq -n --arg r "$rig" --arg p "$project" '[$r, $p]')" \
+      --argjson caps "$caps_json" \
+      --argjson meta "$(jq -n --arg cwd "$PWD" --arg approval "$approval" '{cwd: $cwd, approvalMode: $approval}')" \
+      '{id: $id, name: $name, machine: $machine, rig: $rig, tags: $tags, capabilities: $caps, status: "online", meta: $meta}'
+    )" 2>/dev/null)
+
+  [ "$reg_code" = "200" ] || [ "$reg_code" = "201" ]
+}
+
+set_status() {
+  printf '%s\n' "$1" > "$status_file"
+  curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${AGENT_ID}/status" "${auth_header_args[@]}" \
+    -H 'Content-Type: application/json' -d "{\"status\":\"$1\"}" 2>/dev/null
+}
+
 # Bootstrap cursor at current max so we only see messages arriving after session start.
-since_id=$(curl -s "${auth_header_args[@]}" "${RELAY_URL}/api/messages/cursor" 2>/dev/null | jq -r '.latestId // 0' 2>/dev/null || echo 0)
+since_id=$(fetch_cursor || echo 0)
 
 fail_streak=0
 marked_ready=false
@@ -31,15 +83,24 @@ while true; do
   hb_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${auth_header_args[@]}" \
     "${RELAY_URL}/api/agents/${AGENT_ID}/heartbeat" 2>/dev/null)
 
-  # Agent was deleted or doesn't exist — we're orphaned, exit.
+  # Agent was pruned — re-register instead of exiting.
   if [ "$hb_code" = "404" ]; then
-    exit 0
+    if re_register; then
+      if since_id=$(fetch_cursor); then
+        marked_ready=false
+        hb_code="200"
+      else
+        hb_code="000"
+      fi
+    else
+      hb_code="000"
+    fi
   fi
 
   msgs=$(curl -s --fail "${auth_header_args[@]}" "${RELAY_URL}/api/messages?for=${AGENT_ID}&sinceId=${since_id}&unread=true" 2>/dev/null)
   poll_rc=$?
 
-  if [ "$hb_code" != "200" ] || [ $poll_rc -ne 0 ]; then
+  if [ "$hb_code" != "200" ] && [ "$hb_code" != "404" ] || [ $poll_rc -ne 0 ]; then
     fail_streak=$((fail_streak + 1))
     case "$fail_streak" in
       1) delay=2 ;;
@@ -53,23 +114,43 @@ while true; do
     sleep "$delay"
     continue
   fi
+
+  # Recovery from failure streak — re-assert status so dashboard shows correct state.
+  if [ "$fail_streak" -gt 0 ]; then
+    set_status "$(current_status)"
+  fi
   fail_streak=0
 
   if [ "$marked_ready" = "false" ]; then
     curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${AGENT_ID}/ready" "${auth_header_args[@]}" \
       -H 'Content-Type: application/json' -d '{"ready":true}' 2>/dev/null
+    set_status "idle"
     marked_ready=true
   fi
 
   count=$(echo "$msgs" | jq 'length' 2>/dev/null || echo 0)
   if [ "$count" -gt 0 ] 2>/dev/null && [ "$count" != "0" ]; then
-    echo "$msgs" | jq -r '.[] | if .type == "system" then "⚠ SYSTEM [msg:\(.id)]: \(.body)" else "[msg:\(.id)] \(.from) → \(.to) | \(.subject // "(no subject)"): \(.body)" end'
-    since_id=$(echo "$msgs" | jq '[.[].id] | max')
-    echo "$msgs" | jq -r '.[].id' | while read -r mid; do
+    echo "$msgs" | jq -c '.[]' | while IFS= read -r msg; do
+      mid=$(printf '%s' "$msg" | jq -r '.id')
+      claimable=$(printf '%s' "$msg" | jq -r '.claimable // false')
+
+      if [ "$claimable" = "true" ]; then
+        claim_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST \
+          "${RELAY_URL}/api/messages/${mid}/claim" "${auth_header_args[@]}" \
+          -H 'Content-Type: application/json' \
+          -d "{\"agentId\":\"${AGENT_ID}\"}" 2>/dev/null)
+        if [ "$claim_code" != "200" ]; then
+          continue
+        fi
+      fi
+
+      printf '%s' "$msg" | jq -r 'if .type == "system" then "⚠ SYSTEM [msg:\(.id)]: \(.body)" else "[msg:\(.id)] \(.from) → \(.to) | \(.subject // "(no subject)"): \(.body)" end'
+
       curl -s -X PATCH "${RELAY_URL}/api/messages/${mid}" "${auth_header_args[@]}" \
         -H 'Content-Type: application/json' \
         -d "{\"readBy\":\"${AGENT_ID}\"}" > /dev/null 2>&1 || true
     done
+    since_id=$(echo "$msgs" | jq '[.[].id] | max')
   fi
 
   sleep "$INTERVAL"

package/hooks/relay-monitor.sh

@@ -53,6 +53,7 @@ printf '%s\n' "$agent_id" > "$instance_state"
 # --- Register agent ---
 caps_csv="${AGENT_RELAY_CAPS:-chat}"
 caps_json=$(echo "$caps_csv" | jq -R 'split(",") | map(gsub("^\\s+|\\s+$"; ""))')
+approval="${AGENT_RELAY_APPROVAL:-open}"
 
 reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agents" "${auth_header_args[@]}" \
   -H 'Content-Type: application/json' \
@@ -63,7 +64,7 @@ reg_code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "${RELAY_URL}/api/agen
     --arg rig "$rig" \
     --argjson tags "$(jq -n --arg r "$rig" --arg p "$project" '[$r, $p]')" \
     --argjson caps "$caps_json" \
-    --argjson meta "$(jq -n --arg cwd "$PWD" '{cwd: $cwd}')" \
+    --argjson meta "$(jq -n --arg cwd "$PWD" --arg approval "$approval" '{cwd: $cwd, approvalMode: $approval}')" \
     '{id: $id, name: $name, machine: $machine, rig: $rig, tags: $tags, capabilities: $caps, status: "online", meta: $meta}'
   )" 2>/dev/null)
 
@@ -81,9 +82,16 @@ elif [ "$server_version" != "$PLUGIN_VERSION" ]; then
 fi
 
 # --- Output context (first stdout = notification injected into conversation) ---
+approval_note=""
+case "$approval" in
+  guarded) approval_note=" — destructive ops (rm, mv, chmod, kill, force-push) are blocked" ;;
+  read-only) approval_note=" — observe/analyze/report only, no file writes or mutation commands" ;;
+esac
+
 cat <<CONTEXT
 Agent Relay active. Your agent ID: ${agent_id}
 Relay URL: ${RELAY_URL} | Server: ${server_version:-unknown} | Plugin: ${PLUGIN_VERSION}
+Approval mode: ${approval}${approval_note}
 
 To send a message:
   curl -s -X POST ${RELAY_URL}/api/messages${auth_header_example} -H 'Content-Type: application/json' -d '{"from":"${agent_id}","to":"TARGET","body":"MESSAGE"}'

package/hooks/session-end.sh

@@ -12,6 +12,7 @@ instance_state="/tmp/agent-relay-instance-${PPID}.state"
 if [ -f "$instance_state" ]; then
   agent_id=$(head -1 "$instance_state" 2>/dev/null)
   if [ -n "$agent_id" ]; then
+    printf 'offline\n' > "/tmp/agent-relay-status-${agent_id}.state"
     curl -s -X PATCH "${RELAY_URL}/api/agents/${agent_id}/status" "${auth_header_args[@]}" \
       -H 'Content-Type: application/json' \
       -d '{"status":"offline"}' \

package/hooks/set-status.sh

@@ -24,6 +24,8 @@ if [ -z "$agent_id" ]; then
   exit 0
 fi
 
+printf '%s\n' "$status" > "/tmp/agent-relay-status-${agent_id}.state"
+
 curl -s -o /dev/null -X PATCH "${RELAY_URL}/api/agents/${agent_id}/status" "${auth_header_args[@]}" \
   -H 'Content-Type: application/json' \
   -d "{\"status\":\"${status}\"}" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-plugin",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "Claude Code plugin for Agent Relay — auto-registers sessions as agents and enables inter-agent messaging",
   "type": "module",
   "license": "AGPL-3.0-or-later",