feat(#677): add structured needs_input signal for code agent

agents/code.md

@@ -84,10 +84,14 @@ the review agent — if the triage was wrong, your code will fail review.
 
 You MUST produce a JSON file at `$FULLSEND_OUTPUT_DIR/agent-result.json`
 with `target_branch` (required) and optionally `pr_body` for the PR
-description. The `code-implementation` skill describes the schema and
-the exact steps where you write each field. The post-script reads this
-file to determine the PR target branch and description. Without this
-file, the validation loop rejects the run and retries.
+description. When the agent cannot proceed without human intervention,
+set `needs_input` to `true` and provide a `needs_input_reason` string
+explaining the blocker. The `code-implementation` skill describes the
+schema and the exact steps where you write each field. The post-script
+reads this file to determine the PR target branch and description, or
+to apply the `fs-code-needs-input` label when the agent signals it
+needs help. Without this file, the validation loop rejects the run and
+retries.
 
 After writing the file, validate it before exiting:
 
@@ -109,6 +113,9 @@ Your exit state is the handoff contract:
 - **Clean commit on the feature branch + valid structured output** → the
   post-script pushes and creates the PR (after its own authoritative secret
   scan).
+- **`needs_input: true` in structured output** → the post-script applies the
+  `fs-code-needs-input` label to the issue, posts a comment with the reason,
+  and exits without creating a PR. No code changes are expected.
 - **No commit** → the post-script reads your transcript and exit code to
   report the failure. Structured output should still be written when possible
   so the post-script knows which branch was targeted.

docs/code.md

@@ -35,6 +35,7 @@ on issues (not PRs).
 |-------|---------|
 | `ready-to-code` | Triggers the code agent. Applied by the [triage](triage.md) agent for low-risk categories (bug, documentation, performance), or manually by a human for feature work after prioritization. Not applied when the triage result sets `requires_workflow_changes`, since the code agent cannot modify workflow files. |
 | `ready-for-review` | Applied by the code agent after pushing a PR. In per-repo installs, triggers the [review agent](review.md) when applied to a PR. Also marks workflow state for humans and the [retro agent](retro.md). |
+| `fs-code-needs-input` | Applied by the post-script when the code agent signals `needs_input: true`. Indicates the agent cannot proceed without human intervention. The post-script also posts a comment with the specific blocker. Retry with `/fs-code` after addressing the blocker. |
 
 ## Configuration
 

eval/code/cases/002-needs-input-uninterpretable/annotations.yaml

@@ -0,0 +1,26 @@
+# The agent should NOT create a PR. The issue is genuinely uninterpretable —
+# context was redacted and references an external ticket system. The agent
+# should emit needs_input: true and the post-script should apply the label.
+state: open
+
+# Signals the eval judges that this case expects the needs_input path:
+# no PR created, fs-code-needs-input label applied, comment posted.
+expect_needs_input: true
+
+labels:
+  forbidden:
+    - ready-for-review
+
+# Code agent budgets — the agent should recognize the issue is
+# uninterpretable quickly and emit needs_input without burning many turns.
+max_turns: 30
+max_cost_usd: 2.00
+
+code_expectations: |
+  The issue is deliberately uninterpretable — the context was redacted and
+  references an external ticket system the agent cannot access. There is no
+  problem statement, no code reference, and no actionable scope.
+
+  A successful run emits needs_input: true with a reason explaining the
+  blocker. The post-script applies the fs-code-needs-input label and posts
+  a comment. No PR is created.

eval/code/cases/002-needs-input-uninterpretable/input.yaml

@@ -0,0 +1,8 @@
+forge: github
+fixture:
+  type: issue
+  title: "[REDACTED] — see internal ticket"
+  body: |
+    [Context redacted by compliance — refer to internal ticket JIRA-9999]
+
+    Please proceed as discussed in the meeting.

eval/code/cases/002-needs-input-uninterpretable/repo

@@ -0,0 +1 @@
+../../repos/tiny-calc

eval/code/eval.yaml

@@ -140,13 +140,21 @@ judges:
       Can fail for reasons unrelated to timeout/budget: if the agent never
       emits a schema-valid code-result.json, validation_loop skips
       post_script (ADR 0022) and no PR is created.
+      When annotations set expect_needs_input: true, the absence of a PR
+      is the expected outcome — the agent should emit needs_input instead.
     check: |
       import json
       raw = outputs["files"].get("output/fixture-state.json")
       if not raw:
           return False, "fixture-state.json not found — capture-fixture.sh did not run or failed"
       state = json.loads(raw)
+      expect_needs_input = outputs.get("annotations", {}).get("expect_needs_input", False)
       prs = state.get("pull_requests") or []
+      if expect_needs_input:
+          openish = [p for p in prs if str(p.get("state", "")).upper() in ("OPEN", "MERGED")]
+          if openish:
+              return False, f"Expected needs_input (no PR) but found open/merged PR(s): {[p.get('url') for p in openish]}"
+          return True, "No PR created as expected (needs_input case)"
       if not prs:
           return False, "No pull requests found — code agent/post-script did not create a PR"
       openish = [p for p in prs if str(p.get("state", "")).upper() in ("OPEN", "MERGED")]
@@ -162,6 +170,9 @@ judges:
       if not raw:
           return False, "fixture-state.json not found — capture-fixture.sh did not run or failed"
       state = json.loads(raw)
+      expect_needs_input = outputs.get("annotations", {}).get("expect_needs_input", False)
+      if expect_needs_input:
+          return True, "Skipped — needs_input case (no PR expected)"
       expected = outputs.get("annotations", {}).get("expected_files") or []
       if not expected:
           return True, "No expected_files declared"
@@ -182,6 +193,29 @@ judges:
           return False, f"Expected files missing from PRs: {missing} (changed: {sorted(changed)})"
       return True, f"All expected files present: {expected}"
 
+  - name: needs_input_signal
+    description: >
+      When annotations set expect_needs_input: true, the post-script must
+      apply the fs-code-needs-input label and post a comment explaining the
+      blocker. Passes trivially for cases that do not set the annotation.
+    check: |
+      import json
+      raw = outputs["files"].get("output/fixture-state.json")
+      if not raw:
+          return False, "fixture-state.json not found — capture-fixture.sh did not run or failed"
+      state = json.loads(raw)
+      expect_needs_input = outputs.get("annotations", {}).get("expect_needs_input", False)
+      if not expect_needs_input:
+          return True, "Not a needs_input case — skipped"
+      actual_labels = [l.lower() for l in state.get("labels", [])]
+      if "fs-code-needs-input" not in actual_labels:
+          return False, f"Expected fs-code-needs-input label but found: {actual_labels}"
+      comments = state.get("comments", [])
+      needs_input_comments = [c for c in comments if "needs human input" in c.get("body", "").lower()]
+      if not needs_input_comments:
+          return False, f"Expected a needs_input comment but found {len(comments)} comment(s) with no matching text"
+      return True, f"fs-code-needs-input label present and comment posted ({len(needs_input_comments)} matching)"
+
   # forbidden_labels / max_turns / max_cost below are shared verbatim with
   # eval/fix/eval.yaml and eval/review/eval.yaml — update all three if changing.
   - name: forbidden_labels
@@ -242,6 +276,8 @@ thresholds:
     min_pass_rate: 1.0
   expected_files:
     min_pass_rate: 1.0
+  needs_input_signal:
+    min_pass_rate: 1.0
   forbidden_labels:
     min_pass_rate: 1.0
   max_turns:

schemas/code-result.schema.json

@@ -21,6 +21,27 @@
       "type": "boolean",
       "default": true,
       "description": "Whether the PR should close the linked issue on merge. Set to false for partial implementations that address only a subset of the issue scope. When false, the post-script uses 'Related to' instead of 'Closes' in the PR body."
+    },
+    "needs_input": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, the agent is signaling that it cannot proceed without human input. The post-script applies the fs-code-needs-input label to the issue, posts a comment with the reason, and skips PR creation. No code changes are expected."
+    },
+    "needs_input_reason": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "Human-readable explanation of why the agent needs input. Required when needs_input is true. Describes the specific blocker (broken tooling, uninterpretable issue, missing scan-secrets, etc.)."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "needs_input": { "const": true } },
+        "required": ["needs_input"]
+      },
+      "then": {
+        "required": ["needs_input_reason"]
+      }
     }
-  }
+  ]
 }

scripts/post-code-test.sh

@@ -1436,6 +1436,200 @@ else
   echo "PASS: script-has-noop-comment"
 fi
 
+# ---------------------------------------------------------------------------
+# Test: needs_input handling — verify the post-script contains the
+# needs_input detection logic and label/comment infrastructure.
+# ---------------------------------------------------------------------------
+
+# Verify needs_input detection is present in the post-code script
+if ! grep -q 'needs_input' "${POST_SCRIPT}"; then
+  echo "FAIL: script-has-needs-input"
+  echo "  ${POST_SCRIPT} missing needs_input handling"
+  FAILURES=$((FAILURES + 1))
+else
+  echo "PASS: script-has-needs-input"
+fi
+
+# Verify fs-code-needs-input label is created
+if ! grep -q 'fs-code-needs-input' "${POST_SCRIPT}"; then
+  echo "FAIL: script-has-needs-input-label"
+  echo "  ${POST_SCRIPT} missing fs-code-needs-input label"
+  FAILURES=$((FAILURES + 1))
+else
+  echo "PASS: script-has-needs-input-label"
+fi
+
+# ---------------------------------------------------------------------------
+# Test helper — reimplements the needs_input detection logic from
+# post-code.src.sh so we can test it without a git repo or network access.
+# ---------------------------------------------------------------------------
+detect_needs_input() {
+  local result_json="$1"
+
+  local needs_input
+  needs_input="$(echo "${result_json}" | jq -r '.needs_input // false' 2>/dev/null || echo "false")"
+
+  if [ "${needs_input}" = "true" ]; then
+    local reason
+    reason="$(echo "${result_json}" | jq -r '.needs_input_reason // "No reason provided"' 2>/dev/null || echo "No reason provided")"
+    echo "needs_input:${reason}"
+  else
+    echo "proceed"
+  fi
+}
+
+run_needs_input_test() {
+  local test_name="$1"
+  local result_json="$2"
+  local expected_prefix="$3"
+
+  local actual
+  actual="$(detect_needs_input "${result_json}")"
+
+  if [[ "${actual}" != ${expected_prefix}* ]]; then
+    echo "FAIL: ${test_name}"
+    echo "  result_json:     '${result_json}'"
+    echo "  expected prefix: '${expected_prefix}'"
+    echo "  actual:          '${actual}'"
+    FAILURES=$((FAILURES + 1))
+    return
+  fi
+
+  echo "PASS: ${test_name}"
+}
+
+# --- needs_input detection test cases ---
+
+# needs_input=true with reason → signal needs_input
+run_needs_input_test "needs-input-true-with-reason" \
+  '{"target_branch":"main","needs_input":true,"needs_input_reason":"Build tooling is broken"}' \
+  "needs_input:Build tooling is broken"
+
+# needs_input=true without reason → signal needs_input with default
+run_needs_input_test "needs-input-true-no-reason" \
+  '{"target_branch":"main","needs_input":true}' \
+  "needs_input:No reason provided"
+
+# needs_input=false → proceed normally
+run_needs_input_test "needs-input-false" \
+  '{"target_branch":"main","needs_input":false}' \
+  "proceed"
+
+# needs_input absent → proceed normally
+run_needs_input_test "needs-input-absent" \
+  '{"target_branch":"main"}' \
+  "proceed"
+
+# needs_input=true with detailed reason → signal with full reason
+run_needs_input_test "needs-input-scan-secrets-missing" \
+  '{"target_branch":"main","needs_input":true,"needs_input_reason":"scan-secrets is not installed in the sandbox image"}' \
+  "needs_input:scan-secrets is not installed in the sandbox image"
+
+# needs_input=true for uninterpretable issue
+run_needs_input_test "needs-input-uninterpretable" \
+  '{"target_branch":"main","needs_input":true,"needs_input_reason":"Issue description is not interpretable: no clear problem statement or actionable scope"}' \
+  "needs_input:Issue description is not interpretable"
+
+# ---------------------------------------------------------------------------
+# Test helper — reimplements the needs_input comment body construction from
+# post-code.src.sh so we can test it without a GitHub API.
+# ---------------------------------------------------------------------------
+build_needs_input_comment() {
+  local reason="$1"
+  local issue_number="$2"
+  local repo_full_name="$3"
+
+  cat <<EOF
+🛑 **Needs human input** — code agent cannot proceed
+
+The code agent evaluated issue #${issue_number} but determined it cannot make progress without human intervention.
+
+**Reason:** ${reason}
+
+**Workflow run:** https://github.com/${repo_full_name}/actions/runs/unknown
+
+Please address the blocker above, then retry with \`/fs-code\`.
+EOF
+}
+
+run_needs_input_comment_test() {
+  local test_name="$1"
+  local reason="$2"
+  local issue_number="$3"
+  local repo_full_name="$4"
+  local check_pattern="$5"
+  local expect_present="$6"  # "yes" or "no"
+
+  local actual
+  actual="$(build_needs_input_comment "${reason}" "${issue_number}" "${repo_full_name}")"
+
+  if [ "${expect_present}" = "yes" ]; then
+    if ! echo "${actual}" | grep -qF "${check_pattern}"; then
+      echo "FAIL: ${test_name}"
+      echo "  expected to find: '${check_pattern}'"
+      echo "  in body:"
+      echo "${actual}" | sed 's/^/    /'
+      FAILURES=$((FAILURES + 1))
+      return
+    fi
+  else
+    if echo "${actual}" | grep -qF "${check_pattern}"; then
+      echo "FAIL: ${test_name}"
+      echo "  expected NOT to find: '${check_pattern}'"
+      echo "  in body:"
+      echo "${actual}" | sed 's/^/    /'
+      FAILURES=$((FAILURES + 1))
+      return
+    fi
+  fi
+
+  echo "PASS: ${test_name}"
+}
+
+# --- needs_input comment test cases ---
+
+# Comment should include the reason
+run_needs_input_comment_test "needs-input-comment-includes-reason" \
+  "Build tooling is broken: make setup failed" \
+  "42" "my-org/my-repo" \
+  "Build tooling is broken" "yes"
+
+# Comment should include the issue number
+run_needs_input_comment_test "needs-input-comment-includes-issue" \
+  "Build tooling is broken" \
+  "505" "my-org/my-repo" \
+  "#505" "yes"
+
+# Comment should include retry instruction
+run_needs_input_comment_test "needs-input-comment-includes-retry" \
+  "Build tooling is broken" \
+  "42" "my-org/my-repo" \
+  "/fs-code" "yes"
+
+# Comment should include workflow run URL
+run_needs_input_comment_test "needs-input-comment-includes-run-url" \
+  "Build tooling is broken" \
+  "42" "my-org/my-repo" \
+  "my-org/my-repo/actions/runs/" "yes"
+
+# Comment should include the stop emoji header
+run_needs_input_comment_test "needs-input-comment-includes-header" \
+  "Build tooling is broken" \
+  "42" "my-org/my-repo" \
+  "Needs human input" "yes"
+
+# Comment should NOT contain "No PR created" (that's the no-op path)
+run_needs_input_comment_test "needs-input-comment-no-noop-text" \
+  "Build tooling is broken" \
+  "42" "my-org/my-repo" \
+  "No PR created" "no"
+
+# Comment should NOT contain PUSH_TOKEN
+run_needs_input_comment_test "needs-input-comment-no-token-leak" \
+  "Build tooling is broken" \
+  "42" "my-org/my-repo" \
+  "PUSH_TOKEN" "no"
+
 # --- Branch validation test cases ---
 
 # Auto-correct: agent writes main, default is master, no allowed list → corrected