@chorus-aidlc/chorus 0.14.0 → 0.14.2

package/.next/standalone/public/kiro-plugin/bin/chorus-api.sh

@@ -0,0 +1,392 @@
+#!/usr/bin/env bash
+# chorus-api.sh — Lightweight REST API wrapper for Chorus session management
+# Used by hook scripts to communicate with Chorus backend.
+#
+# Environment variables:
+#   CHORUS_URL       — Chorus base URL (e.g., http://localhost:8637)
+#   CHORUS_API_KEY   — Agent API key (cho_xxx)
+#   CHORUS_STATE_DIR — optional override for the session-state directory
+#
+# State file: $CHORUS_STATE_DIR/state.json (gitignored). Runtime-agnostic:
+# under Kiro CLI (which does not set CLAUDE_PROJECT_DIR) state defaults to a
+# stable per-user location (~/.kiro/.chorus) instead of the launch cwd, so a
+# hook-triggered MCP call never litters a stray .chorus/ dir into whatever
+# directory `kiro` happened to be started from.
+
+set -euo pipefail
+
+# ===== Configuration =====
+
+CHORUS_URL="${CHORUS_URL:-}"
+CHORUS_API_KEY="${CHORUS_API_KEY:-}"
+STATE_DIR="${CHORUS_STATE_DIR:-${CLAUDE_PROJECT_DIR:-$HOME/.kiro}/.chorus}"
+STATE_FILE="${STATE_DIR}/state.json"
+
+# ===== Helpers =====
+
+die() {
+  echo "ERROR: $*" >&2
+  exit 1
+}
+
+require_env() {
+  [ -n "$CHORUS_URL" ]    || die "CHORUS_URL is not set"
+  [ -n "$CHORUS_API_KEY" ] || die "CHORUS_API_KEY is not set"
+}
+
+# Make an authenticated API request to Chorus
+# Usage: api_call METHOD PATH [DATA]
+api_call() {
+  local method="$1"
+  local path="$2"
+  local data="${3:-}"
+
+  local args=(
+    -s -S
+    -X "$method"
+    -H "Authorization: Bearer ${CHORUS_API_KEY}"
+    -H "Content-Type: application/json"
+  )
+
+  if [ -n "$data" ]; then
+    args+=(-d "$data")
+  fi
+
+  local response
+  response=$(curl "${args[@]}" "${CHORUS_URL}${path}" 2>&1) || {
+    echo "CURL_ERROR: Failed to reach ${CHORUS_URL}${path}" >&2
+    return 1
+  }
+
+  echo "$response"
+}
+
+# Ensure state directory and file exist
+ensure_state() {
+  mkdir -p "$STATE_DIR"
+  if [ ! -f "$STATE_FILE" ]; then
+    echo '{}' > "$STATE_FILE"
+  fi
+}
+
+# ===== State Management =====
+
+state_get() {
+  local key="$1"
+  ensure_state
+  if command -v jq &>/dev/null; then
+    jq -r --arg k "$key" '.[$k] // empty' "$STATE_FILE"
+  else
+    # Fallback: simple grep-based extraction
+    grep -o "\"${key}\":\"[^\"]*\"" "$STATE_FILE" 2>/dev/null | cut -d'"' -f4
+  fi
+}
+
+state_set() {
+  local key="$1"
+  local value="$2"
+  ensure_state
+  # Use flock to serialize concurrent state writes (multiple SubagentStart hooks
+  # may run in parallel, each calling state-set multiple times).
+  (
+    flock -w 5 200 || { echo "WARN: state_set flock timeout for key=$key" >&2; return 0; }
+    if command -v jq &>/dev/null; then
+      local tmp
+      tmp=$(mktemp)
+      jq --arg k "$key" --arg v "$value" '.[$k] = $v' "$STATE_FILE" > "$tmp" && mv "$tmp" "$STATE_FILE"
+    else
+      if grep -q "\"${key}\":" "$STATE_FILE" 2>/dev/null; then
+        sed -i "s|\"${key}\":\"[^\"]*\"|\"${key}\":\"${value}\"|" "$STATE_FILE"
+      else
+        local tmp
+        tmp=$(mktemp)
+        sed "s|}$|,\"${key}\":\"${value}\"}|" "$STATE_FILE" > "$tmp" && mv "$tmp" "$STATE_FILE"
+      fi
+    fi
+  ) 200>"${STATE_FILE}.lock"
+}
+
+state_delete() {
+  local key="$1"
+  ensure_state
+  (
+    flock -w 5 200 || { echo "WARN: state_delete flock timeout for key=$key" >&2; return 0; }
+    if command -v jq &>/dev/null; then
+      local tmp
+      tmp=$(mktemp)
+      jq --arg k "$key" 'del(.[$k])' "$STATE_FILE" > "$tmp" && mv "$tmp" "$STATE_FILE"
+    fi
+  ) 200>"${STATE_FILE}.lock"
+}
+
+# ===== Hook Output =====
+# Produces JSON that Claude Code parses:
+#   systemMessage                          → shown to user as notification
+#   hookSpecificOutput.additionalContext   → injected into Claude's context (LLM sees this)
+#   hookSpecificOutput.hookEventName       → identifies which hook event produced this context
+#
+# Usage: hook_output "User-visible message" "Context for Claude LLM" ["HookEventName"]
+hook_output() {
+  local system_message="$1"
+  local additional_context="${2:-}"
+  local hook_event_name="${3:-}"
+  local updated_input_json="${4:-}"  # Optional: raw JSON object for updatedInput
+  if command -v jq &>/dev/null; then
+    if [ -n "$updated_input_json" ]; then
+      # Build output with updatedInput (for PreToolUse parameter modification)
+      jq -n \
+        --arg sm "$system_message" \
+        --arg ac "$additional_context" \
+        --arg hen "$hook_event_name" \
+        --argjson ui "$updated_input_json" \
+        '{systemMessage: $sm, hookSpecificOutput: {hookEventName: $hen, additionalContext: $ac, updatedInput: $ui}}'
+    elif [ -n "$additional_context" ]; then
+      jq -n \
+        --arg sm "$system_message" \
+        --arg ac "$additional_context" \
+        --arg hen "$hook_event_name" \
+        '{systemMessage: $sm, hookSpecificOutput: {hookEventName: $hen, additionalContext: $ac}}'
+    else
+      jq -n \
+        --arg sm "$system_message" \
+        '{systemMessage: $sm}'
+    fi
+  else
+    # Fallback: manual JSON — escape newlines and quotes
+    local sm_escaped="${system_message//\\/\\\\}"
+    sm_escaped="${sm_escaped//\"/\\\"}"
+    sm_escaped="${sm_escaped//$'\n'/\\n}"
+    if [ -n "$additional_context" ]; then
+      local ac_escaped="${additional_context//\\/\\\\}"
+      ac_escaped="${ac_escaped//\"/\\\"}"
+      ac_escaped="${ac_escaped//$'\n'/\\n}"
+      printf '{"systemMessage":"%s","hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}\n' "$sm_escaped" "$hook_event_name" "$ac_escaped"
+    else
+      printf '{"systemMessage":"%s"}\n' "$sm_escaped"
+    fi
+  fi
+}
+
+# ===== Session File Management (Plan A) =====
+
+SESSIONS_DIR="${STATE_DIR}/sessions"
+
+# Read a session file by agent name
+# Usage: session_file_read <agent_name>
+session_file_read() {
+  local name="$1"
+  local file="${SESSIONS_DIR}/${name}.json"
+  if [ -f "$file" ]; then
+    cat "$file"
+  else
+    echo "" >&2
+    return 1
+  fi
+}
+
+# List all session files
+session_file_list() {
+  if [ ! -d "$SESSIONS_DIR" ]; then
+    echo "[]"
+    return
+  fi
+  if command -v jq &>/dev/null; then
+    local result="["
+    local first=true
+    for f in "$SESSIONS_DIR"/*.json; do
+      [ -f "$f" ] || continue
+      if [ "$first" = true ]; then
+        first=false
+      else
+        result="${result},"
+      fi
+      result="${result}$(cat "$f")"
+    done
+    result="${result}]"
+    echo "$result" | jq '.'
+  else
+    ls "$SESSIONS_DIR"/*.json 2>/dev/null | while read -r f; do
+      basename "$f" .json
+    done
+  fi
+}
+
+# ===== Subcommands =====
+
+cmd_checkin() {
+  require_env
+  api_call GET "/api/health"
+}
+
+# Call an MCP tool via JSON-RPC over HTTP Streamable Transport
+# Usage: cmd_mcp_tool <tool_name> [arguments_json]
+# Returns the text content from the tool result
+cmd_mcp_tool() {
+  local tool_name="${1:-}"
+  local arguments="${2:-{\}}"
+  [ -n "$tool_name" ] || die "Usage: chorus-api.sh mcp-tool <tool_name> [arguments_json]"
+  require_env
+  ensure_state
+
+  local mcp_url="${CHORUS_URL}/api/mcp"
+  local auth_header="Authorization: Bearer ${CHORUS_API_KEY}"
+  local max_retries=3
+  local retry_count=0
+  local session_id=""
+  local tool_response=""
+
+  # Retry loop for auto-reconnection on 404 (session expired)
+  while [ $retry_count -le $max_retries ]; do
+    # Step 1: Initialize MCP session
+    local init_payload
+    init_payload=$(cat <<JSONEOF
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-hook","version":"0.14.2"}}}
+JSONEOF
+)
+
+    # Use a unique temp file for headers to avoid concurrent hooks overwriting each other
+    local headers_file
+    headers_file=$(mktemp "${STATE_DIR}/.mcp_headers.XXXXXX")
+
+    local init_response
+    init_response=$(curl -s -S -X POST \
+      -H "$auth_header" \
+      -H "Content-Type: application/json" \
+      -H "Accept: application/json, text/event-stream" \
+      -D "$headers_file" \
+      -d "$init_payload" \
+      "$mcp_url" 2>/dev/null) || { rm -f "$headers_file"; die "MCP initialize failed"; }
+
+    # Extract session ID from response headers (optional — stateless servers don't return one)
+    session_id=$(grep -i "^mcp-session-id:" "$headers_file" 2>/dev/null | tr -d '\r' | awk '{print $2}') || true
+    rm -f "$headers_file"
+
+    # Build session header (empty string if stateless server returned no session ID)
+    local session_header=""
+    if [ -n "$session_id" ]; then
+      session_header="mcp-session-id: $session_id"
+    fi
+
+    # Step 2: Send initialized notification
+    local notif_payload='{"jsonrpc":"2.0","method":"notifications/initialized"}'
+    if [ -n "$session_header" ]; then
+      curl -s -S -X POST \
+        -H "$auth_header" \
+        -H "Content-Type: application/json" \
+        -H "Accept: application/json, text/event-stream" \
+        -H "$session_header" \
+        -d "$notif_payload" \
+        "$mcp_url" >/dev/null 2>&1 || true
+    else
+      curl -s -S -X POST \
+        -H "$auth_header" \
+        -H "Content-Type: application/json" \
+        -H "Accept: application/json, text/event-stream" \
+        -d "$notif_payload" \
+        "$mcp_url" >/dev/null 2>&1 || true
+    fi
+
+    # Step 3: Call the tool
+    local call_payload
+    call_payload=$(printf '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"%s","arguments":%s}}' "$tool_name" "$arguments")
+
+    # Capture HTTP status code and response separately
+    local http_code
+    local response_file
+    response_file=$(mktemp "${STATE_DIR}/.mcp_response.XXXXXX")
+
+    if [ -n "$session_header" ]; then
+      http_code=$(curl -s -S -X POST \
+        -H "$auth_header" \
+        -H "Content-Type: application/json" \
+        -H "Accept: application/json, text/event-stream" \
+        -H "$session_header" \
+        -d "$call_payload" \
+        -w "%{http_code}" \
+        -o "$response_file" \
+        "$mcp_url" 2>/dev/null) || http_code="000"
+    else
+      http_code=$(curl -s -S -X POST \
+        -H "$auth_header" \
+        -H "Content-Type: application/json" \
+        -H "Accept: application/json, text/event-stream" \
+        -d "$call_payload" \
+        -w "%{http_code}" \
+        -o "$response_file" \
+        "$mcp_url" 2>/dev/null) || http_code="000"
+    fi
+
+    # Check if session expired (404)
+    if [ "$http_code" = "404" ]; then
+      retry_count=$((retry_count + 1))
+      rm -f "$response_file"
+
+      if [ $retry_count -le $max_retries ]; then
+        # Session expired - retry with new session
+        continue
+      else
+        die "MCP session expired after retry. Please reinitialize."
+      fi
+    fi
+
+    # Read the response
+    tool_response=$(cat "$response_file")
+    rm -f "$response_file"
+
+    # Break the retry loop - request succeeded
+    break
+  done
+
+  # Step 4: Close session (best effort, only for stateful servers)
+  if [ -n "$session_id" ]; then
+    curl -s -S -X DELETE \
+      -H "$auth_header" \
+      -H "mcp-session-id: $session_id" \
+      "$mcp_url" >/dev/null 2>&1 || true
+  fi
+
+  # Response may be SSE format (event: message\ndata: {...}) or plain JSON
+  # Strip SSE framing to get the JSON payload
+  local json_response
+  if echo "$tool_response" | grep -q "^data: "; then
+    json_response=$(echo "$tool_response" | grep "^data: " | head -1 | sed 's/^data: //')
+  else
+    json_response="$tool_response"
+  fi
+
+  # Extract text content from result
+  if command -v jq &>/dev/null; then
+    echo "$json_response" | jq -r '.result.content[]? | select(.type=="text") | .text // empty' 2>/dev/null || echo "$json_response"
+  else
+    echo "$json_response"
+  fi
+}
+
+# ===== Main Dispatch =====
+
+cmd="${1:-}"
+shift || true
+
+case "$cmd" in
+  checkin)          cmd_checkin "$@" ;;
+  mcp-tool)         cmd_mcp_tool "$@" ;;
+  state-get)        state_get "${1:-}" ;;
+  state-set)        state_set "${1:-}" "${2:-}" ;;
+  state-delete)     state_delete "${1:-}" ;;
+  session-read)     session_file_read "${1:-}" ;;
+  session-list)     session_file_list ;;
+  hook-output)      hook_output "${1:-}" "${2:-}" "${3:-}" "${4:-}" ;;
+  *)
+    echo "Usage: chorus-api.sh <command> [args...]"
+    echo ""
+    echo "Commands:"
+    echo "  checkin                                Check connectivity with Chorus"
+    echo "  mcp-tool <name> [args_json]            Call an MCP tool via JSON-RPC"
+    echo "  state-get <key>                        Read from state.json"
+    echo "  state-set <key> <value>                Write to state.json"
+    echo "  state-delete <key>                     Delete key from state.json"
+    echo "  session-read <name>                    Read session file for an agent"
+    echo "  session-list                           List all pre-created session files"
+    exit 1
+    ;;
+esac

package/.next/standalone/public/kiro-plugin/bin/on-agent-spawn.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# on-agent-spawn.sh — Kiro `agentSpawn` hook for the `chorus` main agent.
+#
+# Kiro contract (kiro.dev/docs/cli/hooks): the agentSpawn event delivers
+# {hook_event_name, cwd, session_id} on STDIN, and on exit 0 the hook's
+# STDOUT is added to the agent's context as PLAIN TEXT (there is no
+# hookSpecificOutput/additionalContext JSON envelope the way Claude Code
+# uses — that is the load-bearing difference from the CC on-session-start
+# hook this is ported from).
+#
+# Behavior (parity with CC public/chorus-plugin/bin/on-session-start.sh):
+#   * If CHORUS_URL / CHORUS_API_KEY are unset -> print a "not configured"
+#     notice to STDOUT and exit 0. NEVER abort the spawn.
+#   * Otherwise call chorus_checkin over MCP and print the result (agent
+#     owner / permissions / idea tracker) as the startup context.
+#   * If Chorus is unreachable, print a warning and exit 0 (degrade
+#     gracefully — the spawn must not fail).
+#
+# Bash 3.2 compatible (CLAUDE.md pitfall #10): no ${VAR,,}/${VAR^^},
+# no `declare -A`, no `readarray`/`mapfile`, no `&>>`, no `|&`.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+API="${SCRIPT_DIR}/chorus-api.sh"
+
+# Drain the event JSON from STDIN if present (base fields only for
+# agentSpawn; not needed for logic, but consume it so the pipe closes).
+EVENT=""
+if [ ! -t 0 ]; then
+  EVENT=$(cat)
+fi
+
+# Not configured -> plain-text notice, exit 0 (never abort spawn).
+if [ -z "${CHORUS_URL:-}" ] || [ -z "${CHORUS_API_KEY:-}" ]; then
+  printf '%s\n' "Chorus plugin: not configured. Set CHORUS_URL and CHORUS_API_KEY to enable Chorus session automation (checkin, reviewer nudges, checkout)."
+  exit 0
+fi
+
+# Call chorus_checkin via MCP. On any failure, warn and exit 0.
+CHECKIN_RESULT=$("$API" mcp-tool "chorus_checkin" '{}' 2>/dev/null) || {
+  printf '%s\n' "Chorus plugin: unable to reach Chorus at ${CHORUS_URL}. Session lifecycle hooks are inactive for this session."
+  exit 0
+}
+
+if [ -z "$CHECKIN_RESULT" ]; then
+  printf '%s\n' "Chorus plugin: checkin returned no data from ${CHORUS_URL}. Session lifecycle hooks may be degraded."
+  exit 0
+fi
+
+# Emit the startup context as plain text (Kiro adds STDOUT to context).
+# The checkin payload carries agent owner, effective permissions, and the
+# recent-idea tracker — surfaced verbatim, same as the CC hook.
+CONTEXT="# Chorus Plugin — Active
+
+Chorus is connected at ${CHORUS_URL}. Session lifecycle hooks are enabled (checkin on spawn, best-effort heartbeat/checkout on stop, reviewer nudges after workflow MCP calls).
+
+## Checkin
+
+${CHECKIN_RESULT}
+
+## Quick Reference
+
+- **Idea Tracker**: the checkin above lists up to 10 most recently updated ideas. Use chorus_get_ideas() for the full list.
+- **Reviewers**: after chorus_pm_submit_proposal / chorus_submit_for_verify / chorus_admin_verify_task, a postToolUse hook will nudge you to spawn the matching read-only reviewer subagent (chorus-proposal-reviewer / chorus-task-reviewer / chorus-code-reviewer). See /chorus-review.
+- **Notifications**: chorus_get_notifications() fetches and auto-marks read. See /chorus-develop.
+- **Project Groups**: chorus_get_project_groups() before creating projects."
+
+# Resume: if a Chorus session was cached by a prior swarm-mode flow,
+# send a best-effort heartbeat and note it in context. No session cached
+# in the common single-agent case -> nothing to resume (silent).
+MAIN_SESSION=$("$API" state-get "main_session_uuid" 2>/dev/null) || true
+if [ -n "$MAIN_SESSION" ]; then
+  CONTEXT="${CONTEXT}
+
+Resuming with existing Chorus session: ${MAIN_SESSION}"
+  "$API" mcp-tool "chorus_session_heartbeat" "$(printf '{"sessionUuid":"%s"}' "$MAIN_SESSION")" >/dev/null 2>&1 || true
+fi
+
+printf '%s\n' "$CONTEXT"
+exit 0

package/.next/standalone/public/kiro-plugin/bin/on-post-submit-for-verify.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# on-post-submit-for-verify.sh — Kiro `postToolUse` hook matched to
+# @chorus/chorus_submit_for_verify.
+#
+# Kiro contract: postToolUse delivers {tool_name, tool_input,
+# tool_response, ...} on STDIN; on exit 0 the hook's STDOUT is added to
+# the agent's context as PLAIN TEXT (no additionalContext JSON envelope).
+#
+# Behavior: emit a nudge to spawn the read-only `chorus-task-reviewer`
+# subagent before admin verification. If the event carries no parseable
+# taskUuid -> exit 0 with NO output (no broken nudge).
+#
+# Bash 3.2 compatible (CLAUDE.md pitfall #10).
+
+set -euo pipefail
+
+# Config toggle — default enabled (Kiro analog of CC's ENABLETASKREVIEWER).
+if [ "${CHORUS_ENABLE_TASK_REVIEWER:-true}" != "true" ]; then
+  exit 0
+fi
+
+EVENT=""
+if [ ! -t 0 ]; then
+  EVENT=$(cat)
+fi
+if [ -z "$EVENT" ]; then
+  exit 0
+fi
+
+# Extract taskUuid from tool_input; silent exit if missing/unparseable.
+TASK_UUID=""
+if command -v jq >/dev/null 2>&1; then
+  TASK_UUID=$(printf '%s' "$EVENT" | jq -r '.tool_input.taskUuid // empty' 2>/dev/null) || true
+fi
+if [ -z "$TASK_UUID" ]; then
+  exit 0
+fi
+
+# Optional task title from tool_response.
+TITLE_DISPLAY=""
+if command -v jq >/dev/null 2>&1; then
+  TASK_TITLE=$(printf '%s' "$EVENT" | jq -r '.tool_response.title // empty' 2>/dev/null) || true
+  if [ -n "${TASK_TITLE:-}" ]; then
+    TITLE_DISPLAY=" '${TASK_TITLE}'"
+  fi
+fi
+
+# Max review rounds (0 = unlimited). Kiro analog of CC's
+# CLAUDE_PLUGIN_OPTION_MAXTASKREVIEWROUNDS.
+MAX_ROUNDS="${CHORUS_MAX_TASK_REVIEW_ROUNDS:-3}"
+
+printf '%s\n' "[Chorus Plugin — Task Submitted for Verification]
+Task${TITLE_DISPLAY} (UUID: ${TASK_UUID}) has been submitted for verification.
+
+Max review rounds: ${MAX_ROUNDS} (0 = unlimited).
+
+ACTION REQUIRED: spawn the read-only \`chorus-task-reviewer\` subagent to perform an independent review before admin verification.
+
+In Kiro, hand the reviewer this task (auto-selected by its description; also invokable as /chorus-task-reviewer): \"Review task ${TASK_UUID}. Max review rounds: ${MAX_ROUNDS}. First, read existing comments to count previous VERDICTs and determine your round number. If max > 0 and your round exceeds max, skip the review and post a comment saying the limit was reached — human decision needed. Otherwise, proceed with the review and post your VERDICT as a comment on the task.\"
+
+The reviewer is read-only (tools: read + @chorus) and posts its VERDICT as a comment on the task. After it completes, read comments and act on the most recent \`VERDICT:\` line:
+- VERDICT: PASS — all AC verified, no issues. Proceed to mark AC and call chorus_admin_verify_task.
+- VERDICT: PASS WITH NOTES — all AC verified, minor non-blocking notes. Still proceed to verify.
+- VERDICT: FAIL — BLOCKERs found. Do NOT verify. Reopen the task (chorus_admin_reopen_task) and fix the BLOCKERs.
+
+IMPORTANT: run the reviewer synchronously and wait for its VERDICT before proceeding."
+
+exit 0

package/.next/standalone/public/kiro-plugin/bin/on-post-submit-proposal.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# on-post-submit-proposal.sh — Kiro `postToolUse` hook matched to
+# @chorus/chorus_pm_submit_proposal.
+#
+# Kiro contract (kiro.dev/docs/cli/hooks): postToolUse delivers
+# {hook_event_name, tool_name, tool_input, tool_response, cwd, session_id}
+# on STDIN, and on exit 0 the hook's STDOUT is added to the agent's
+# context as PLAIN TEXT. (No hookSpecificOutput/additionalContext JSON
+# envelope — that is the difference from the CC on-post-submit-proposal
+# hook this is ported from.)
+#
+# Behavior: emit a nudge to spawn the read-only `chorus-proposal-reviewer`
+# subagent before admin approval. If the event carries no parseable
+# proposalUuid -> exit 0 with NO output (no broken nudge).
+#
+# Bash 3.2 compatible (CLAUDE.md pitfall #10).
+
+set -euo pipefail
+
+# Config toggle — default enabled. CHORUS_ENABLE_PROPOSAL_REVIEWER is the
+# Kiro analog of CC's CLAUDE_PLUGIN_OPTION_ENABLEPROPOSALREVIEWER (Kiro has
+# no userConfig plumbing, so we read a plain env var).
+if [ "${CHORUS_ENABLE_PROPOSAL_REVIEWER:-true}" != "true" ]; then
+  exit 0
+fi
+
+# Read the event JSON from STDIN.
+EVENT=""
+if [ ! -t 0 ]; then
+  EVENT=$(cat)
+fi
+if [ -z "$EVENT" ]; then
+  exit 0
+fi
+
+# Extract proposalUuid from tool_input. printf (not echo) preserves
+# multi-line JSON. If jq is unavailable or the field is empty -> silent
+# exit 0 (no broken nudge).
+PROPOSAL_UUID=""
+if command -v jq >/dev/null 2>&1; then
+  PROPOSAL_UUID=$(printf '%s' "$EVENT" | jq -r '.tool_input.proposalUuid // empty' 2>/dev/null) || true
+fi
+if [ -z "$PROPOSAL_UUID" ]; then
+  exit 0
+fi
+
+# Optional proposal title from tool_response for a friendlier nudge.
+TITLE_DISPLAY=""
+if command -v jq >/dev/null 2>&1; then
+  PROPOSAL_TITLE=$(printf '%s' "$EVENT" | jq -r '.tool_response.title // empty' 2>/dev/null) || true
+  if [ -n "${PROPOSAL_TITLE:-}" ]; then
+    TITLE_DISPLAY=" '${PROPOSAL_TITLE}'"
+  fi
+fi
+
+# Max review rounds (0 = unlimited). Kiro analog of CC's
+# CLAUDE_PLUGIN_OPTION_MAXPROPOSALREVIEWROUNDS.
+MAX_ROUNDS="${CHORUS_MAX_PROPOSAL_REVIEW_ROUNDS:-3}"
+
+printf '%s\n' "[Chorus Plugin — Proposal Submitted for Review]
+Proposal${TITLE_DISPLAY} (UUID: ${PROPOSAL_UUID}) has been submitted.
+
+Max review rounds: ${MAX_ROUNDS} (0 = unlimited).
+
+ACTION REQUIRED: spawn the read-only \`chorus-proposal-reviewer\` subagent to perform an independent quality review before admin approval.
+
+In Kiro, hand the reviewer this task (it is auto-selected by its description; you can also invoke it as /chorus-proposal-reviewer): \"Review proposal ${PROPOSAL_UUID}. Max review rounds: ${MAX_ROUNDS}. First, read existing comments to count previous VERDICTs and determine your round number. If max > 0 and your round exceeds max, skip the review and post a comment saying the limit was reached — human decision needed. Otherwise, proceed with the review and post your VERDICT as a comment on the proposal.\"
+
+The reviewer is read-only (tools: read + @chorus) and posts its VERDICT as a comment on the proposal. After it completes, read comments and act on the most recent \`VERDICT:\` line:
+- VERDICT: PASS — no issues. Proceed to approve (chorus_admin_approve_proposal).
+- VERDICT: PASS WITH NOTES — minor non-blocking notes. Still proceed to approve.
+- VERDICT: FAIL — BLOCKERs found. Do NOT approve. Reject (chorus_pm_reject_proposal), fix the BLOCKERs, and resubmit.
+
+IMPORTANT: run the reviewer synchronously and wait for its VERDICT before proceeding."
+
+exit 0