openaca 0.1.0b1__tar.gz

openaca-0.1.0b1/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/INDEX.md ]; then printf '=== ARCHITECTURE DECISIONS (docs/adrs/) ===\\n\\nRead a full ADR before changing logic in the area it covers.\\n\\n'; cat docs/adrs/INDEX.md; fi"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE COMPACTION ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE SESSION END ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

openaca-0.1.0b1/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "Bash(git -C /Users/vinodkone/workspace/aivex remote -v)",
+      "Bash(git -C /Users/vinodkone/workspace/aivex config --get remote.origin.url)"
+    ]
+  }
+}

openaca-0.1.0b1/.github/ISSUE_TEMPLATE/beta-feedback.md

@@ -0,0 +1,68 @@
+---
+name: Beta feedback
+about: Report scanner ergonomics, coverage gaps, or workflow fit during the 0.1.0bN beta.
+title: '[beta] '
+labels: ['beta']
+---
+
+<!-- Thanks for testing OpenACA. Fields marked (required) are the ones I look at first. -->
+
+### Feedback type (required)
+
+<!-- Pick the closest fit — helps me triage. -->
+
+- [ ] Scanner ergonomics — install / first scan / output legibility / CLI friction
+- [ ] Coverage gap — something the scanner inventoried or missed that surprised me
+- [ ] Workflow fit — where OpenACA does or doesn't fit in my security tooling
+
+### Command run (required)
+
+```bash
+# Paste the full command you ran, e.g.:
+# openaca scan repo --target ./my-mcp-server --include-posture
+```
+
+### OpenACA version (required)
+
+```
+# Output of `openaca --version`
+```
+
+### Expected vs actual (required)
+
+**Expected:**
+
+**Actual:**
+
+### Output (redacted as needed)
+
+<!--
+Paste scanner output. If it contains internal names, paths, or component IDs
+you don't want public, redact freely — replace with <redacted> or generic
+placeholders. The shape of the output is more useful than the literal
+contents. SARIF is sometimes easier to redact than text.
+-->
+
+```
+```
+
+### Missing or incorrect inventory
+
+<!--
+If the scanner missed something it should have inventoried, or inventoried
+something incorrectly, describe what + where. Format hint:
+- Manifest: path/to/file
+- Should have shown: <name@version>
+- Actually showed: <empty | wrong name | wrong version>
+Leave blank if this isn't an inventory issue.
+-->
+
+### Environment
+
+- OS:
+- Python version (`python --version`):
+- Install path (`pip install ...` / `uv sync` / other):
+
+### Anything else?
+
+<!-- Workflow context, what you wish it did, why you tried it, etc. -->

openaca-0.1.0b1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security disclosure
+    url: https://github.com/open-agent-security/openaca/security/advisories/new
+    about: Private security advisories for OpenACA-the-scanner bugs. See SECURITY.md.
+  - name: Beta tester guide
+    url: https://github.com/open-agent-security/openaca-demo/blob/main/BETA-TESTER-GUIDE.md
+    about: Beta-tester guide (hosted in the public openaca-demo repo since openaca is private during the closed beta).

openaca-0.1.0b1/.github/workflows/autofix.yml

@@ -0,0 +1,309 @@
+name: Autofix
+
+# Two-direction comment-bounce that closes the Codex/Claude review loop
+# without human intervention:
+#
+#   1. Codex bot reviews a PR  ->  this workflow posts `@claude please
+#      address...`  ->  claude.yml fires, claude reads the review, fixes
+#      it, pushes commits, posts a "Claude finished" summary comment.
+#
+#   2. Claude bot's "finished" summary is itself the trigger for the second
+#      bounce: this workflow posts `@codex review`  ->  Codex re-reviews
+#      HEAD on the same PR. (Codex auto-reviews on PR open, draft->ready,
+#      and explicit @codex review comments — but NOT on subsequent pushes.
+#      Without this bounce, claude's fixes land unreviewed.)
+#
+# The two bounces together produce: codex-flag -> claude-fix ->
+# codex-rereview -> ... bounded by the claude-side iteration cap below.
+# Codex is silent when clean (thumbs reaction), so an unnecessary @codex
+# review on a no-op SHA costs one cheap call with no PR noise.
+#
+# Authentication: comments are posted (and PR branches are rebased)
+# using AUTOFIX_TRIGGER_PAT, NOT secrets.GITHUB_TOKEN. GitHub explicitly
+# suppresses workflow runs triggered by events created with
+# GITHUB_TOKEN (recursion guard) — so a comment posted under
+# github-actions[bot] would be silently dropped before claude.yml ever
+# fired, and a rebase pushed under GITHUB_TOKEN would not re-trigger
+# CI / Codex on the rebased branch. The PAT is fine-grained, owned by
+# a repo OWNER/MEMBER, with BOTH:
+#   - `Pull requests: Read and write` — for `gh pr comment` (bounces 1
+#     and 2) and `gh pr list` (bounce 0).
+#   - `Contents: Read and write` — for `actions/checkout` to fetch and
+#     `git push` from the rebase-stale-prs job. WITHOUT this, the job
+#     fails at the `Checkout` step with `403: Write access to
+#     repository not granted` — actions/checkout asks GitHub to verify
+#     write permission upfront because the same token will push later.
+# The resulting comments/pushes are authored by that user, which DOES
+# trigger downstream workflows AND naturally passes claude.yml's
+# OWNER/MEMBER/COLLABORATOR trust gate. The same PAT serves all three
+# bounces — Codex's webhook listener watches @-mentions in PR comments
+# regardless of author.
+#
+# If AUTOFIX_TRIGGER_PAT is unset, both `gh pr comment` paths fail
+# with an auth error and the chain breaks; rebase-stale-prs detects
+# the missing secret and skips with a workflow warning. Manual
+# @claude triggers are unaffected.
+#
+# Workflow-injection safety: every user/bot-controlled input (PR number,
+# comment body, review id) is read via env: and referenced as a shell
+# variable. Comment bodies posted to the PR are hardcoded literals — no
+# interpolation of untrusted input into shell.
+
+on:
+  pull_request_review:
+    types: [submitted]
+  issue_comment:
+    # claude-code-action posts ONE progress comment when it starts and
+    # updates the SAME comment in place when it finishes — that fires
+    # `issue_comment.edited`, not `created`. Listen to both so the
+    # "Claude finished" marker is visible to bounce 2 regardless of
+    # whether the action posts fresh or updates in place. The body
+    # marker check in the `if:` gate keeps non-claude edits out.
+    types: [created, edited]
+  push:
+    # Bounce 0: main moved -> rebase open PRs that are now stale. Catches
+    # both PR merges AND direct pushes to main (manual hotfixes, manual
+    # main pushes). pull_request:closed+merged would miss the latter.
+    branches: [main]
+
+jobs:
+  trigger-claude-via-comment:
+    # Bounce 1: Codex review submitted -> @claude addresses it.
+    if: github.event_name == 'pull_request_review' && github.event.review.user.login == 'chatgpt-codex-connector[bot]' && github.event.review.state == 'commented'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    env:
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      PR_NUM: ${{ github.event.pull_request.number }}
+      REVIEW_ID: ${{ github.event.review.id }}
+      RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+    steps:
+      # Cap the auto-address loop at 7 claude runs per PR. If claude has
+      # already run 7+ times and Codex is still finding issues, the loop
+      # isn't converging — force human attention rather than burn cycles.
+      #
+      # Cap was 3 originally; bumped to 7 because legitimate Codex
+      # reviews on substantive PRs routinely surface 5-6 rounds of real
+      # findings (defensive type guards across sibling parsers, CLI-flag
+      # table extensions one per round, OSV event-window edge cases).
+      # 3 was capping real review work, not just runaway loops; 7 keeps
+      # the safety net while accommodating multi-round legitimate review.
+      #
+      # Count claude-code-action runs by counting top-level PR comments
+      # authored by the bot (the action posts ONE in-progress comment
+      # per run and edits it in place to the "Claude finished..." summary
+      # — 1 comment == 1 run). More accurate than counting bot commits:
+      # a run that lands 0 commits (no-op fix or pre-push failure) and a
+      # run that lands N commits both equal one iteration of the loop.
+      #
+      # Login string is "claude" — NOT "claude[bot]" — because
+      # `gh pr view --json comments` uses GraphQL, and GraphQL's
+      # `author.login` returns the bare bot name without the `[bot]`
+      # suffix. The `[bot]` suffix only appears in REST surfaces (e.g.
+      # `github.event.comment.user.login` at bounce-2 below). Same bot,
+      # two string representations depending on which API you read.
+      - name: Cap auto-address iterations (max 7)
+        run: |
+          MAX=7
+          CLAUDE_RUNS=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+            --jq '[.comments[] | select(.author.login == "claude")] | length')
+          if [ "$CLAUDE_RUNS" -ge "$MAX" ]; then
+            gh pr comment "$PR_NUM" -R "$REPO" --body "🛑 Auto-address loop limit hit — claude has already run $CLAUDE_RUNS times on this PR (max $MAX). Codex review id $REVIEW_ID was NOT auto-addressed. Manual review needed; re-tag claude explicitly after addressing the underlying issue if you want to continue. ([workflow run]($RUN_URL))"
+            echo "::error::Auto-address loop limit hit ($CLAUDE_RUNS/$MAX) — see PR comment."
+            exit 1
+          fi
+          echo "Auto-address iteration $((CLAUDE_RUNS + 1)) of $MAX"
+
+      # Post the @claude trigger. The body intentionally references "the
+      # Codex review above" — claude-code-action's default prompt
+      # construction will include the full review thread so the bot has
+      # the actual findings + line context to act on.
+      - name: Post @claude trigger comment
+        run: |
+          gh pr comment "$PR_NUM" -R "$REPO" --body "@claude please address the Codex review feedback above. CRITICAL: before applying any fix that depends on infrastructure or invariants you have not verified (DLQ, schema, contracts, ADRs in docs/adrs/), grep the repo for the prerequisite. If it is not present, push back via a PR comment explaining the missing context rather than implementing on a false premise."
+
+  trigger-codex-rereview-via-comment:
+    # Bounce 2: claude finished addressing -> @codex re-reviews HEAD.
+    # The "Claude finished" marker is the standard heading
+    # claude-code-action posts when it completes a task. Filtering on
+    # both bot login AND body marker prevents accidental firing from any
+    # other claude[bot] activity (e.g., scheduled tasks). The
+    # pull_request guard is required because issue_comment also fires
+    # on real Issues, where there is no PR head to review.
+    if: |
+      github.event_name == 'issue_comment'
+      && github.event.issue.pull_request != null
+      && github.event.comment.user.login == 'claude[bot]'
+      && contains(github.event.comment.body, 'Claude finished')
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    env:
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      PR_NUM: ${{ github.event.issue.number }}
+      RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+    steps:
+      # Skip if HEAD hasn't changed since our last @codex review request.
+      # Claude can post "Claude finished" without pushing any commits
+      # (e.g., it pushed back via comment instead of implementing).
+      # Without this check, a no-op finished-comment would trigger
+      # another @codex review on the same SHA, codex would re-flag the
+      # same issue, autofix would post @claude again, and the cycle
+      # could repeat indefinitely — the claude-side commit cap doesn't
+      # advance because claude isn't committing.
+      #
+      # Strategy: embed the HEAD SHA in our trigger-comment body via an
+      # HTML comment marker, then check on each run whether we've
+      # already requested review for the current SHA.
+      - name: Post @codex re-review trigger (idempotent per SHA)
+        run: |
+          HEAD_SHA=$(gh pr view "$PR_NUM" -R "$REPO" --json headRefOid --jq '.headRefOid')
+          MARKER="<!-- autofix-rereview-sha:$HEAD_SHA -->"
+          ALREADY=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+            --jq "[.comments[] | select(.body | contains(\"$MARKER\"))] | length")
+          if [ "$ALREADY" -gt 0 ]; then
+            echo "Already requested @codex review for $HEAD_SHA — skipping (claude finished without pushing new commits)."
+            exit 0
+          fi
+          gh pr comment "$PR_NUM" -R "$REPO" --body "$MARKER
+          @codex review the latest commits — claude bot just pushed fixes that haven't been reviewed yet."
+
+  rebase-stale-prs:
+    # Bounce 0: main moved -> for each open PR (same-repo only, fork PRs
+    # excluded), check mergeStateStatus and either rebase cleanly or ask
+    # @claude to resolve conflicts. Catches both PR-merge pushes and
+    # direct pushes to main.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    concurrency:
+      # Coalesce: if main moves twice while we're still working on the
+      # first push, cancel and re-run with the latest SHA. Avoids racing
+      # two rebase runs against the same PR.
+      group: rebase-stale-prs
+      cancel-in-progress: true
+    env:
+      # Use the PAT for both gh API calls AND the git push. Pushing to a
+      # PR branch under GITHUB_TOKEN works but invalidates downstream
+      # workflow triggers (recursion guard) — the PAT keeps the @claude
+      # comment path working if this rebase later races with a Codex
+      # review on the same PR.
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      MAIN_SHA: ${{ github.sha }}
+    steps:
+      # Graceful skip when the PAT secret isn't configured yet (initial
+      # repo setup). Without this guard, actions/checkout fails with
+      # "Input required and not supplied: token" on every push to main,
+      # turning every merge into a red workflow run.
+      - id: have_pat
+        name: Check AUTOFIX_TRIGGER_PAT presence
+        env:
+          PAT: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+        run: |
+          if [ -z "$PAT" ]; then
+            echo "::warning::AUTOFIX_TRIGGER_PAT not set; skipping rebase. Add the secret per setup-autofix instructions to enable."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout (full history for rebase)
+        if: steps.have_pat.outputs.skip != 'true'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+
+      - name: Configure git author
+        if: steps.have_pat.outputs.skip != 'true'
+        run: |
+          git config user.email "actions@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+      - name: Rebase BEHIND PRs / flag DIRTY ones
+        if: steps.have_pat.outputs.skip != 'true'
+        run: |
+          set -euo pipefail
+
+          # mergeStateStatus values that matter:
+          #   CLEAN     - up to date with main (or ahead). skip.
+          #   BEHIND    - mergeable, base moved. clean rebase needed.
+          #   DIRTY     - conflicts. ask @claude.
+          #   BLOCKED   - branch protection or required checks failing. skip.
+          #   UNSTABLE  - mergeable but failing checks. skip — pre-existing.
+          #   UNKNOWN   - GitHub still computing. skip; next push retries.
+          #
+          # We exclude fork PRs: pushing to a fork branch from this workflow
+          # 403s, and posting @claude on a fork is blocked downstream by
+          # claude.yml's fork-refusal step anyway.
+          PRS_JSON=$(gh pr list --state open -R "$REPO" \
+            --json number,headRefName,mergeStateStatus,baseRefName,headRepository \
+            --jq "[.[] | select(.baseRefName == \"main\") | select(.headRepository.nameWithOwner == \"$REPO\")]")
+
+          echo "Open same-repo PRs targeting main:"
+          echo "$PRS_JSON" | jq -r '.[] | "  #\(.number) [\(.mergeStateStatus)] \(.headRefName)"'
+
+          # Process each PR. Loop over JSON array via index so we can read
+          # only env-style fields and never interpolate untrusted data.
+          COUNT=$(echo "$PRS_JSON" | jq 'length')
+          for i in $(seq 0 $((COUNT - 1))); do
+            PR_NUM=$(echo "$PRS_JSON" | jq -r ".[$i].number")
+            BRANCH=$(echo "$PRS_JSON" | jq -r ".[$i].headRefName")
+            STATUS=$(echo "$PRS_JSON" | jq -r ".[$i].mergeStateStatus")
+
+            # Defensive: branch names are user-controlled. Refuse anything
+            # that isn't a sane ref. (`refs/heads/<name>` syntax: letters,
+            # digits, slashes, dashes, underscores, dots.)
+            if ! printf '%s' "$BRANCH" | grep -qE '^[A-Za-z0-9._/-]+$'; then
+              echo "::warning::PR #$PR_NUM has unsafe branch name; skipping"
+              continue
+            fi
+
+            case "$STATUS" in
+              BEHIND)
+                echo "PR #$PR_NUM ($BRANCH): clean rebase needed"
+                git fetch origin "$BRANCH":"refs/remotes/origin/$BRANCH" --force
+                git checkout -B "$BRANCH" "origin/$BRANCH"
+                if git rebase origin/main; then
+                  if git push --force-with-lease origin "$BRANCH"; then
+                    gh pr comment "$PR_NUM" -R "$REPO" \
+                      --body "🔁 Auto-rebased on \`main\` (no conflicts) after $MAIN_SHA."
+                  else
+                    echo "::warning::Force-push of #$PR_NUM failed (lease lost?). Will retry on next push."
+                  fi
+                else
+                  # Race: GitHub said BEHIND but the rebase produced
+                  # conflicts. The next push will see DIRTY and route to
+                  # the @claude path.
+                  git rebase --abort
+                  echo "::warning::Rebase of #$PR_NUM failed despite BEHIND status (likely race with another push)"
+                fi
+                git checkout main
+                ;;
+              DIRTY)
+                echo "PR #$PR_NUM ($BRANCH): conflicts — asking @claude to rebase"
+                # Idempotency: don't re-ask claude for the same main SHA.
+                MARKER="<!-- autofix-rebase-claude:$MAIN_SHA -->"
+                ALREADY=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+                  --jq "[.comments[] | select(.body | contains(\"$MARKER\"))] | length")
+                if [ "$ALREADY" -gt 0 ]; then
+                  echo "  already asked @claude for $MAIN_SHA — skipping"
+                  continue
+                fi
+                gh pr comment "$PR_NUM" -R "$REPO" --body "$MARKER
+                @claude main has moved and this PR has merge conflicts. Please rebase \`$BRANCH\` on \`origin/main\` and resolve any conflicts. Run the local pre-push gate before force-pushing. If the conflicts indicate the underlying approach is invalidated by the new main, push back via a comment instead of force-fitting a resolution."
+                ;;
+              CLEAN)
+                echo "PR #$PR_NUM ($BRANCH): already current — skipping"
+                ;;
+              *)
+                echo "PR #$PR_NUM ($BRANCH): status $STATUS — leaving alone"
+                ;;
+            esac
+          done

openaca-0.1.0b1/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Skip the gates on chore/setup PRs that don't have Python sources yet.
+      # Without this, `uv sync --frozen` fails on a clean repo because there's
+      # no pyproject.toml/uv.lock to install from. Once the first pyproject.toml
+      # lands, the rest of the workflow runs.
+      - id: project_check
+        name: Detect Python project files
+        run: |
+          if [ -f pyproject.toml ] && [ -f uv.lock ]; then
+            echo "have_project=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "have_project=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No pyproject.toml + uv.lock yet — skipping lint/test gates."
+          fi
+
+      - name: Install uv
+        if: steps.project_check.outputs.have_project == 'true'
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          # Match pyproject.toml `requires-python`. Pinning here in CI catches
+          # any newer-syntax regressions that would break the lower bound.
+          # `python-version` here both installs that interpreter AND sets
+          # UV_PYTHON so every subsequent `uv sync`/`uv run` uses it.
+          python-version: "3.11"
+
+      - name: Sync deps
+        if: steps.project_check.outputs.have_project == 'true'
+        # `--frozen` forbids re-resolution: CI installs exactly what's in the
+        # committed uv.lock instead of silently picking up newer transitive
+        # versions. If uv.lock is missing or stale vs. pyproject.toml, this
+        # fails fast — exactly what we want in CI.
+        run: uv sync --frozen
+
+      - name: Ruff check
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run ruff format --check .
+
+      - name: Pyright
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run pyright
+
+      - name: Pytest
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run pytest --cov=tools --cov-report=term-missing
+
+      - name: Lint overlay corpus
+        if: steps.project_check.outputs.have_project == 'true'
+        run: |
+          if [ -d overlays ] && [ "$(find overlays -name '*.yaml' -print -quit)" ]; then
+            uv run openaca lint overlays/
+          else
+            echo "::notice::no overlays present yet; skipping openaca lint"
+          fi

openaca-0.1.0b1/.github/workflows/claude.yml

@@ -0,0 +1,142 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  # 'assigned' is intentionally NOT included: the assigned event fires under
+  # the assigner's identity but `github.event.issue.author_association` stays
+  # the OPENER, so we can't reliably gate it. The practical 'invoke @claude
+  # on an existing issue' path is to comment '@claude ...' on the issue —
+  # that goes through issue_comment, where comment.author_association is the
+  # commenter and the gate works correctly.
+  issues:
+    types: [opened]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    # Only TRUSTED actors (repo OWNER/MEMBER/COLLABORATOR) can invoke @claude.
+    # The job has write perms on contents/pull-requests/issues, so any
+    # non-collaborator who could comment '@claude do X' on an issue/PR would
+    # otherwise be able to trigger arbitrary commits/comments under our token.
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && (github.event.comment.author_association == 'OWNER' || github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'COLLABORATOR')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && (github.event.comment.author_association == 'OWNER' || github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'COLLABORATOR')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && (github.event.review.author_association == 'OWNER' || github.event.review.author_association == 'MEMBER' || github.event.review.author_association == 'COLLABORATOR')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')) && (github.event.issue.author_association == 'OWNER' || github.event.issue.author_association == 'MEMBER' || github.event.issue.author_association == 'COLLABORATOR'))
+    runs-on: ubuntu-latest
+    permissions:
+      # Write across contents/pull-requests/issues so @claude can do the work
+      # people @-mention it for: post comments, create branches, push commits.
+      # The default read-only token would silently 403 on any of those API
+      # calls, breaking the entire mention-driven flow.
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      # Refuse to operate on fork PRs. The if: gate above only checks the
+      # COMMENTER's association — but the next step checks out the PR head
+      # and the action then runs with write tokens. Fork PR + write secrets
+      # against untrusted code is a write-token-exposure risk. Native
+      # filtering in `if:` only works for pull_request_review* events (the
+      # payload has head.repo); for issue_comment events the PR head repo
+      # isn't in the payload, so we resolve it at runtime via the API.
+      - name: Refuse fork PRs (write-token exposure)
+        if: github.event.issue.pull_request != null || github.event.pull_request != null
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUM: ${{ github.event.issue.number || github.event.pull_request.number }}
+        run: |
+          HEAD_REPO=$(gh pr view "$PR_NUM" -R "$REPO" --json headRepository --jq '.headRepository.nameWithOwner')
+          if [ "$HEAD_REPO" != "$REPO" ]; then
+            echo "::error::Refusing to run @claude on PR from fork ($HEAD_REPO) — workflow grants write tokens and would expose secrets to untrusted code."
+            exit 1
+          fi
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # Full history. `fetch-depth: 1` (default) breaks rebase tasks:
+          # `git merge-base origin/main HEAD` returns empty on a shallow
+          # clone whose ancestor commit isn't in the local object store,
+          # and the action then mis-reports the branch as having "no
+          # common ancestor" / "unrelated histories" — see PR #38 where
+          # this caused a clean rebase to be replaced with a merge commit
+          # on a falsely-claimed unrelated-histories premise. Cost is
+          # one slower checkout; correctness is not optional.
+          fetch-depth: 0
+          # For `issue_comment` on a PR, GitHub sets `github.sha` to the
+          # default branch's HEAD — NOT the PR head. Checking out that SHA
+          # means PR-only files don't exist on disk and the action crashes
+          # on `git hash-object`. Resolve to the PR head explicitly:
+          #   - pull_request_review / _review_comment expose pull_request.head.sha
+          #   - issue_comment on a PR has issue.pull_request set; build the
+          #     head ref from the PR number
+          #   - issues:opened (not on a PR) -> fall through to github.ref
+          # The fork-refusal step above guarantees same-repo head when we reach this.
+          ref: ${{ github.event.pull_request.head.sha || (github.event.issue.pull_request && format('refs/pull/{0}/head', github.event.issue.number)) || github.ref }}
+
+      # Install uv + sync deps so @claude can run the same lint/test gates
+      # the pre-push hook + ci.yml run, before pushing commits to a PR.
+      # Without this, @claude's pushes skip the gate entirely and PR-breaking
+      # lint/format/type/test errors land on the PR before anyone notices.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          # Match pyproject.toml `requires-python` and ci.yml. `python-version`
+          # here installs that interpreter AND sets UV_PYTHON, so every
+          # `uv sync`/`uv run` in this job uses it.
+          python-version: "3.11"
+
+      - name: Sync deps
+        # `--frozen` forbids re-resolution: install exactly what's in the
+        # committed uv.lock. Same behavior as ci.yml so claude bot's pushes
+        # hit the same dep set the rest of CI uses.
+        run: uv sync --frozen
+
+      - name: Install pre-push hook
+        run: bash scripts/install-hooks.sh
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Lets Claude read CI results on PRs.
+          additional_permissions: |
+            actions: read
+
+          # Extend the action's default allowed tools with the dev-loop
+          # commands the pre-push hook gates on. Without these, Claude can
+          # commit format-broken code but the wrapped `git push` script's
+          # hook fails on `ruff format --check` and the bot has no way to
+          # run the formatter to recover. PR #8 hit this exact loop — bot
+          # wedged trying to hand-reformat to match ruff's output.
+          #
+          # Each `Bash(<cmd>:*)` entry is a glob over arg lists for that
+          # exact prefix. Keep prefixes specific so we don't open a wide
+          # `Bash(*)` hole on a write-token job.
+          claude_args: |
+            --allowed-tools "Bash(uv run ruff format:*),Bash(uv run ruff check:*),Bash(uv run pyright:*),Bash(uv run pytest:*)"
+
+          # Surface Claude's full SDK conversation in the workflow log.
+          # Default is `false` (per claude-code-action upstream) which hides
+          # everything as "Running Claude Code via SDK (full output hidden
+          # for security)..." and makes silent stalls impossible to diagnose
+          # — runs reporting "success" while making zero commits, with no
+          # way to tell if Claude hit a token cap, got stuck on a tool call,
+          # or decided to bail mid-task.
+          #
+          # Privacy / security tradeoff: workflow logs are visible to anyone
+          # with read access to Actions on this repo. The action's default
+          # prompt construction includes PR title, body, comments, and
+          # review threads — all of which are already public on the PR. We
+          # don't pass secrets through the prompt. Acceptable.
+          show_full_output: true