From 20a1da0a0e8e7866d79f27c1aad9de3d91af968b Mon Sep 17 00:00:00 2001 From: Chaim Date: Tue, 4 Aug 2026 09:05:35 +0000 Subject: [PATCH] =?UTF-8?q?fix(agents):=20INV-AG3=20=E2=80=94=20=D7=9B?= =?UTF-8?q?=D7=9C=D7=99=20=D7=A9=D7=9E=D7=95=D7=A8=D7=99=D7=9D=20=D7=9C?= =?UTF-8?q?=D7=A1=D7=95=D7=9B=D7=9F=20=D7=9C=D7=94=D7=A8=D7=99=D7=A5=20?= =?UTF-8?q?=D7=97=D7=99=D7=99=D7=91=20=D7=9C=D7=94=D7=99=D7=95=D7=AA=20?= =?UTF-8?q?=D7=9E=D7=95=D7=A2=D7=A0=D7=A7=20=D7=9C=D7=95,=20=D7=95=D7=A9?= =?UTF-8?q?=D7=A2=D7=A8-CI=20=D7=A9=D7=99=D7=90=D7=9B=D7=95=D7=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ה-frontmatter `tools:` של סוכן claude_local הוא allow-list סגורה: כלי הרשום בשרת-ה-MCP אך חסר ממנה אינו ניתן לקריאה, גם כשהשרת מחובר לחלוטין. `analyze_protocol` נרשם בשרת ב-24e3e2f (2026-06-30) בקומיט שנגע ב-9 קבצים, אף אחד מהם ב-.claude/agents/. אחר כך #226 הוסיף את wake_analyst_for_protocol_analysis, שכותב לתוך ה-issue "הרץ mcp__legal-ai__analyze_protocol(...)" — כלומר המערכת הורתה למנתח להריץ כלי שמעולם לא הוענק לו. ב-CMP-229 (2026-08-04) המנתח דיווח נכונה ש"הכלים קיימים בשרת אך אינם נחשפים לסשן", ועקף דרך psql ידני וסקריפט מקומי: ההרצה הראשונה שיגרה אותו לרקע וסיימה את התור, קבוצת-התהליכים נהרגה, והניתוח אבד. רק ההרצה השנייה (recovery) הצליחה. INV-AG3 כיסה את זה בספ מ-2026-06-06, אבל האכיפה נדחתה ("אכיפה אוטומטית עתידית — תת-פרויקט 5"), ולכן הדריפט חי חמישה שבועות. הענקות שנוספו (כל אחת עם ההוראה המתאימה — לא הענקה עודפת): - legal-analyst: analyze_protocol + get_protocol_analysis (+ סעיף "משימה על-פי-דרישה: ניתוח פרוטוקול-הדיון" — אף סוכן לא ידע שהיכולת קיימת), get_legal_arguments ו-get_appraiser_facts (קריאה-בחזרה אחרי כתיבה) - legal-ceo: get_appraiser_facts (אימות שהחילוץ נחת) - legal-qa: precedent_library_list — הוראותיו כבר אמרו "הרץ" אותו. אותו באג בדיוק, שהתגלה אגב הסריקה שער-CI חדש `scripts/agent_tool_grants_guard.py` בדפוס leak_guard.py של G12, ארבעה כללים קשיחים: (1) כל mcp__legal-ai__X ב-web/ מוענק לסוכן כלשהו · (2) כל mcp__legal-ai__X בגוף קובץ-סוכן מוענק באותו קובץ · (3) אין הענקה לכלי לא-רשום · (4) שם-כלי בגרשיים ללא תחילית — מוענק, או מסווג ב-CONTRASTIVE_OK עם נימוק (9 סווגו: אזכור ניגודי, מטלת-סוכן-אחר, שם-עמודה מתנגש), עם בדיקת-התיישנות. מוחרגים קבצים שאינם סוכני-claude_local (hermes-curator, legal-analyst-gemini-critique — בלי frontmatter בכוונה; HEARTBEAT). השער אומת שלילית: לפני התיקון החזיר בדיוק 3 הפרות (analyze_protocol, precedent_library_list, get_legal_arguments) ואפס רעש; אחריו OK. invariants: INV-AG3 (docs/spec/X4-agents.md §2א) — מקיים; האכיפה עברה מידנית ל-CI. G2 — סוכן שאינו יכול לקרוא לכלי בונה מסלול מקביל (SQL ישיר/סקריפט), וזה מה שנחסם כאן. G12 — leak-guard רץ נקי (רגרסיה). Co-Authored-By: Claude Opus 5 --- .claude/agents/legal-analyst.md | 31 +++- .claude/agents/legal-ceo.md | 3 + .claude/agents/legal-qa.md | 1 + .gitea/workflows/agent-tool-grants.yaml | 25 +++ docs/spec/X4-agents.md | 26 ++- scripts/SCRIPTS.md | 1 + scripts/agent_tool_grants_guard.py | 206 ++++++++++++++++++++++++ 7 files changed, 288 insertions(+), 5 deletions(-) create mode 100644 .gitea/workflows/agent-tool-grants.yaml create mode 100755 scripts/agent_tool_grants_guard.py diff --git a/.claude/agents/legal-analyst.md b/.claude/agents/legal-analyst.md index 90f277d..76d714e 100644 --- a/.claude/agents/legal-analyst.md +++ b/.claude/agents/legal-analyst.md @@ -15,8 +15,12 @@ tools: - mcp__legal-ai__document_get_text - mcp__legal-ai__extract_claims - mcp__legal-ai__extract_appraiser_facts + - mcp__legal-ai__get_appraiser_facts - mcp__legal-ai__get_claims - mcp__legal-ai__aggregate_claims_to_arguments + - mcp__legal-ai__get_legal_arguments + - mcp__legal-ai__analyze_protocol + - mcp__legal-ai__get_protocol_analysis - mcp__legal-ai__search_case_documents - mcp__legal-ai__search_decisions - mcp__legal-ai__search_precedent_library @@ -123,9 +127,9 @@ tools: 4. חלץ טענות/תשובות/תגובות (`extract_claims` עם doc_type ו-party_hint מתאימים) - **מסמך גדול (>15,000 תווים):** מאז phase 1 של מערכת הניתוח, ה-chunking הסמנטי + מקבילות + retry מטופל אוטומטית. גם מסמך של 100K+ תווים ירוץ עד הסוף. אם בכל זאת נכשל — דווח ב-issue. - **טיפול בכשל:** אם `extract_claims` החזיר `partial=true` או 0 טענות ממסמך לא ריק — נסה שוב פעם אחת. אם עדיין נכשל — סטטוס issue = `blocked`, פרסם comment עם הפירוט. -5. **חלץ עובדות שמאי** — לכל מסמך `doc_type='appraisal'` בתיק, הרץ `extract_appraiser_facts(case_number)` (פעם אחת לתיק, מטפל בכל השומות). **חובה בכל ערר השבחה (8xxx) ופיצויים (9xxx) — בלי זה ה-writer לא יוכל לכתוב את בלוק ז עם מספרים מדויקים.** +5. **חלץ עובדות שמאי** — לכל מסמך `doc_type='appraisal'` בתיק, הרץ `extract_appraiser_facts(case_number)` (פעם אחת לתיק, מטפל בכל השומות). **חובה בכל ערר השבחה (8xxx) ופיצויים (9xxx) — בלי זה ה-writer לא יוכל לכתוב את בלוק ז עם מספרים מדויקים.** מיד אחריו הרץ `mcp__legal-ai__get_appraiser_facts(case_number)` כדי **לקרוא בחזרה** את מה שנשמר ולוודא שהחילוץ אכן נחת — אל תדווח על חילוץ שלא אימתת בקריאה. 6. וודא שכל פריט מסווג ל-claim_type הנכון -7. **קבץ טענות לטיעונים משפטיים** — לאחר שכל הטענות חולצו וסוּוגו, הרץ `aggregate_claims_to_arguments(case_number)` שמקבץ את הפרופוזיציות הגולמיות לטיעונים משפטיים מובחנים (~6-12 לכל צד). זהו קלט מובנה לבלוק ז (טענות הצדדים) ולבלוק י (דיון) — הכותב נשען עליו. אם 0 טענות חולצו — דלג. הפלט עובר שער-אישור (ראה `get_legal_arguments`). +7. **קבץ טענות לטיעונים משפטיים** — לאחר שכל הטענות חולצו וסוּוגו, הרץ `aggregate_claims_to_arguments(case_number)` שמקבץ את הפרופוזיציות הגולמיות לטיעונים משפטיים מובחנים (~6-12 לכל צד). זהו קלט מובנה לבלוק ז (טענות הצדדים) ולבלוק י (דיון) — הכותב נשען עליו. אם 0 טענות חולצו — דלג. הפלט עובר שער-אישור — קרא אותו בחזרה עם `mcp__legal-ai__get_legal_arguments(case_number)` ואמת שמספר הטיעונים לכל צד סביר לפני שאתה ממשיך. ### שלב 2: ניתוח מעמיק הצג במבנה הבא: @@ -270,6 +274,29 @@ search_precedent_library( **מינימום:** מספר queries ב-Q1+Q2+Q3 לקורפוס הסמכותי = מספר טענות סף + מספר סוגיות מרכזיות. אם זיהית 5 סוגיות + 2 טענות סף → לפחות 7 queries. +## משימה על-פי-דרישה: ניתוח פרוטוקול-הדיון + +**זו אינה חלק מהזרימה הרגילה** — היא מגיעה כ-issue ייעודי כשחיים לוחץ "נתח את פרוטוקול הדיון" בפאנל **"מה קרה בדיון"** (טאב טיעונים-ועמדות). ה-issue יאמר במפורש להריץ `analyze_protocol`. + +``` +mcp__legal-ai__analyze_protocol(case_number="<מספר-התיק>") +mcp__legal-ai__analyze_protocol(case_number="<מספר-התיק>", document_id="") # כשיש כמה פרוטוקולים +``` + +הכלי משווה את **פרוטוקול דיון ועדת-הערר** מול **הטיעונים המאוגדים**, ומסווג כל שינוי ל-`strengthened` / `newly_raised` / `dropped`, עם `evidence_quote` מהפרוטוקול לכל שורה (INV-AH — אין שורה בלי ציטוט). + +**שני תנאים מוקדמים — בדוק אותם לפני שאתה מריץ:** +1. **פרוטוקול של ועדת-הערר.** הכלי בוחר אוטומטית פרוטוקול שה-`protocol_scope` שלו אינו `lower`; פרוטוקול של הוועדה **המקומית** מזין רקע (בלוק ו) בלבד ולא מוביל את ההשוואה. אם כל הפרוטוקולים בתיק הם `lower` — אין דיון-ערר להשוות אליו. +2. **טיעונים מאוגדים.** הרץ `get_legal_arguments(case_number)`. אם ריק — הרץ קודם `aggregate_claims_to_arguments`. + +אם תנאי חסר — **אל תעקוף**: כתוב comment בעברית שמפרט מה חסר, וסגור `blocked`. + +`re-run` מחליף את הניתוח הקודם (idempotent). לקריאה בלבד, בלי ניתוח מחדש: `mcp__legal-ai__get_protocol_analysis(case_number, change_type="")`. + +**דווח ב-comment בעברית**: כמה טענות התחזקו, כמה נטענו לראשונה, כמה ירדו — ומה החידוד המרכזי שעלה בדיון. + +> ⚠️ **הרץ את הכלי בקדמה — לעולם לא ברקע.** שיגור ל-background וסיום התור מסיים את ה-run, וקבוצת-התהליכים נהרגת יחד איתו: הניתוח נקטע ולא נשמר דבר (נצפה ב-CMP-229, 2026-08-04). הכלי לוקח כמה דקות; זה תקין. חכה לו. + ## שלב 6: בדיקת שלמות — לפני שמסיימים! **לפני סיום, בצע את הבדיקות הבאות. אם בדיקה נכשלת — אל תסיים כ-"done".** diff --git a/.claude/agents/legal-ceo.md b/.claude/agents/legal-ceo.md index 620b6da..8520a8a 100644 --- a/.claude/agents/legal-ceo.md +++ b/.claude/agents/legal-ceo.md @@ -41,6 +41,7 @@ tools: - mcp__legal-ai__halacha_corroboration - mcp__legal-ai__corroboration_rebuild - mcp__legal-ai__extract_appraiser_facts + - mcp__legal-ai__get_appraiser_facts - mcp__legal-ai__extract_plans - mcp__legal-ai__plan_get - mcp__legal-ai__plan_search @@ -704,6 +705,8 @@ ls data/cases/$CASE_NUMBER/documents/research/analysis-and-research.md ``` ⚠️ אם מחזיר `status="sides_missing"` → דווח לחיים שאין תיוג `appraiser_side` במסמכי השומה (`document_update` עם `appraiser_side` בערכים `committee`/`appellant`/`deciding`). עצור עד שיתוקן. + אחרי החילוץ — הרץ `mcp__legal-ai__get_appraiser_facts(case_number="...")` כדי **לקרוא בחזרה** ולוודא שהעובדות אכן נשמרו. חילוץ שדיווח הצלחה אך לא נקרא בחזרה אינו ראיה שהנתונים שם. + אם הטבלה כבר מלאה — `write_interim_draft` ידלג על ההרצה אוטומטית, אז גם בלי הצעד הזה זה יעבוד. 3. **כתיבת 5 הבלוקים:** diff --git a/.claude/agents/legal-qa.md b/.claude/agents/legal-qa.md index 77ccaa1..e53eba4 100644 --- a/.claude/agents/legal-qa.md +++ b/.claude/agents/legal-qa.md @@ -17,6 +17,7 @@ tools: - mcp__legal-ai__search_precedent_library - mcp__legal-ai__search_internal_decisions - mcp__legal-ai__precedent_library_get + - mcp__legal-ai__precedent_library_list - mcp__legal-ai__precedent_list - mcp__legal-ai__halacha_review --- diff --git a/.gitea/workflows/agent-tool-grants.yaml b/.gitea/workflows/agent-tool-grants.yaml new file mode 100644 index 0000000..c991b7a --- /dev/null +++ b/.gitea/workflows/agent-tool-grants.yaml @@ -0,0 +1,25 @@ +name: INV-AG3 Agent Tool Grants + +# Hard gate for INV-AG3 (docs/spec/X4-agents.md §2א): a subagent's `tools:` +# frontmatter is a CLOSED allow-list, so any MCP tool an agent is TOLD to run — +# by the backend delegation in web/, or by its own instructions — must appear +# there. Built after analyze_protocol shipped without a grant (2026-06-30) and +# the analyst was handed an issue instructing it to run a tool it could not +# call (CMP-229, 2026-08-04). Pure-stdlib check (no venv) — fast, runs on every +# PR and on push to main. + +on: + pull_request: + branches: [main] + push: + branches: [main] + +jobs: + agent-tool-grants: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: INV-AG3 — agent tool-grant guard + run: python3 scripts/agent_tool_grants_guard.py diff --git a/docs/spec/X4-agents.md b/docs/spec/X4-agents.md index fce20ec..24dda2d 100644 --- a/docs/spec/X4-agents.md +++ b/docs/spec/X4-agents.md @@ -146,9 +146,29 @@ another company`, [X2 §2](X2-multi-company.md)). **כלל:** ה-frontmatter `tools:` של כל סוכן מעניק **בדיוק** את הכלים שהוראותיו דורשות — כל כלי שההוראות מצריכות מוענק, וכלי שמוענק-ולא-בשימוש נבחן. מופע של [G10](00-constitution.md#inv-g10-המערכת-מסייעת--שערים-אנושיים-הם-invariant) (שערים מוגדרים) ו-[G2](00-constitution.md#inv-g2-מקור-אמת-יחיד--אין-מסלולים-מקבילים-מתפצלים); מקביל ל-[X9 INV-TOOL6](X9-mcp-tool-contract.md). -**מקור-סמכות:** frontmatter `tools:` מול ה-instructions בקבצי-[.claude/agents/](../../.claude/agents/). (פרויקטלי-תפעולי.) -**אכיפה:** בדיקת-עקביות tools↔instructions (FU-13 ✅ 2026-06-06). אכיפה אוטומטית עתידית — בתת-פרויקט 5 (spec-guardian). -**הפרה ידועה:** — (טופל ב-FU-13: legal-analyst קיבל `aggregate_claims_to_arguments`; researcher כבר היה תקין; `extract_references`/`extract_internal_citations` הם מטלת-researcher, לא analyst — ראה §2א). + +> **ה-frontmatter הוא allow-list סגורה.** כלי הרשום בשרת-ה-MCP אך חסר מהרשימה **אינו ניתן לקריאה** +> ע"י הסוכן — גם כשהשרת מחובר לחלוטין. הסוכן חווה זאת כ"הכלים לא נחשפים לסשן", ובלי הבנת המנגנון +> הוא נוטה **לעקוף** (SQL ישיר, סקריפט מקומי) במקום לדווח — וזה מסלול מקביל, כלומר הפרת G2. +> **"מורים להריץ" כולל את ה-backend:** טקסט של issue שנוצר ב-`web/` ומכיל `mcp__legal-ai__X` הוא +> הוראה לכל דבר, ולכן מחייב הענקה. + +**מקור-סמכות:** frontmatter `tools:` מול ה-instructions בקבצי-[.claude/agents/](../../.claude/agents/) +**ומול הוראות-ה-backend** ב-`web/`. (פרויקטלי-תפעולי.) +**אכיפה:** ✅ **אוטומטית מ-2026-08-04** — [`scripts/agent_tool_grants_guard.py`](../../scripts/agent_tool_grants_guard.py), +שער-CI קשיח ([`.gitea/workflows/agent-tool-grants.yaml`](../../.gitea/workflows/agent-tool-grants.yaml)), +בדפוס [`leak_guard.py`](../../scripts/leak_guard.py) של G12. ארבעה כללים: (1) כל `mcp__legal-ai__X` +ב-`web/` מוענק לסוכן כלשהו · (2) כל `mcp__legal-ai__X` בגוף קובץ-סוכן מוענק **באותו** קובץ · +(3) אין הענקה לכלי שאינו רשום בשרת · (4) שם-כלי בגרשיים-הפוכים ללא תחילית — מוענק, או מסווג +מפורשות ב-`CONTRASTIVE_OK` (אזכור ניגודי / מטלת-סוכן-אחר / שם-עמודה מתנגש). לא-סוכנים ולכן +מוחרגים: `hermes-curator.md` ו-`legal-analyst-gemini-critique.md` (בלי frontmatter בכוונה — +האדפטר שולח פרומפט גולמי) ו-`HEARTBEAT.md` (checklist משותף). +**הפרה ידועה:** — (היסטוריה: FU-13 ✅ 2026-06-06 — `aggregate_claims_to_arguments` ל-analyst; +`extract_references`/`extract_internal_citations` הם מטלת-researcher, ראה §2א. **הישנות 2026-08-04** +— האכיפה הידנית לא החזיקה: `analyze_protocol` (‏24e3e2f, 2026-06-30) נרשם בשרת בלי הענקה, ו-#226 +הוסיף delegation שמורה למנתח להריץ אותו → CMP-229 נשרף בשתי הרצות ועקף ל-SQL ידני. נסגר יחד עם +`get_protocol_analysis`/`get_legal_arguments`/`get_appraiser_facts` ו-`precedent_library_list` ל-QA, +והאכיפה הועברה ל-CI כדי שלא תישען שוב על משמעת ידנית.) ### INV-AG4: שער שטן-מליץ — red-team לידים לא-סמכותיים תחת אישור-יו"ר **כלל:** אחרי שלב-הניתוח (`analysis-and-research.md` תקין) וב**לפני** הפעלת הכותב, ה-CEO מפעיל diff --git a/scripts/SCRIPTS.md b/scripts/SCRIPTS.md index 8cce214..2e8f6eb 100644 --- a/scripts/SCRIPTS.md +++ b/scripts/SCRIPTS.md @@ -98,6 +98,7 @@ |--------|------|---------|-----------| | `spec-guard.sh` | bash | **PreToolUse hook לאכיפת "פרוטוקול כתיבת-קוד"** (CLAUDE.md §פרוטוקול כתיבת-קוד) — בכל Edit/Write/MultiEdit על נתיב-קוד (`web/`, `mcp-server/`, `web-ui/src/`, `scripts/`, `adapters/`) מזריק תזכורת ל-Claude לקרוא את `docs/spec/00-constitution.md`+ספ-התחום ולוודא קיום G1–G12 — לפני שכותבים. **+ leak-guard בזמן-אמת (G12):** על כתיבה ל-`mcp-server/src/*` בודק את התוכן-הנכתב (`new_string`/`content`) ומזהיר אם מוזרק מונח-Paperclip לשכבת-האינטליגנציה (לא-deduped). המקבילה האינטראקטיבית ל-INV-AG1. קלט JSON ב-stdin, פלט `hookSpecificOutput.additionalContext` (non-blocking, exit 0). Dedup פעם-בסשן לתזכורת-הספ. רשום ב-`.claude/settings.json`. | נקרא אוטומטית ע"י Claude Code (hook) | | `leak_guard.py` | python | **המאכף הקנוני של INV-G12 (שער-הפלטפורמה / docs/spec/X15 §4 / R4).** שני כללים קשיחים: (1) `mcp-server/src` ללא סמלי-Paperclip (allowlist מנומק לפי substring); (2) רק `web/agent_platform_port.py` (+ קבצי-המעטפת) מייבאים את לקוח-Paperclip. stdlib-בלבד (אין venv). `leak_guard.py` = סריקת-repo (exit 1 על הפרה); `leak_guard.py ...` = קבצים נתונים (ל-hook). משותף ל-spec-guard.sh (hook), ל-CI (`.gitea/workflows/leak-guard.yaml`) ול-`mcp-server/tests/test_platform_port_leak_guard.py`. | CI + hook + pytest | +| `agent_tool_grants_guard.py` | python | **המאכף הקנוני של INV-AG3 (מפת-הרשאות הסוכנים / docs/spec/X4-agents.md §2א).** ה-frontmatter `tools:` של סוכן הוא **allow-list סגורה** — כלי הרשום בשרת-ה-MCP אך חסר ממנה אינו ניתן לקריאה, גם כשהשרת מחובר. ארבעה כללים קשיחים: (1) כל `mcp__legal-ai__X` המופיע ב-`web/` (delegation שיוצר issue לסוכן) מוענק לסוכן כלשהו; (2) כל `mcp__legal-ai__X` בגוף קובץ-סוכן מוענק ב-frontmatter של **אותו** קובץ; (3) אין הענקה לכלי שאינו רשום ב-`@mcp.tool`; (4) שם-כלי בגרשיים-הפוכים ללא תחילית — מוענק, או מסווג ב-`CONTRASTIVE_OK` עם נימוק (כולל בדיקת-התיישנות לסיווגים). מחריג קבצים שאינם סוכני-claude_local: `hermes-curator.md`, `legal-analyst-gemini-critique.md`, `HEARTBEAT.md`. stdlib-בלבד. נבנה אחרי CMP-229 (2026-08-04) — `analyze_protocol` נרשם בשרת ב-2026-06-30 בלי הענקה, ו-#226 הורה למנתח להריץ אותו. CI: `.gitea/workflows/agent-tool-grants.yaml`. | CI | | `check_undefined_names.py` | python | **CI gate ל-undefined names (מחלקת ה-NameError).** מריץ pyflakes על `web`, `mcp-server/src`, `scripts` ומפיל build (exit 1) רק על "undefined name"/"may be undefined" — לא על imports-לא-בשימוש/f-strings (רעש). זו בדיוק מחלקת-הבאג של PR #249 (שינוי-שם תיק → 500): שם שמופנה אך לא מיובא/מוגדר, חבוי בתוך `background_tasks` עד זמן-ריצה. דורש pyflakes (ה-workflow מתקין ל-venv זמני). משותף ל-CI (`.gitea/workflows/lint.yaml`). | CI | | `auto-sync-cases.sh` | bash | סנכרון תיקי ערר ל-Gitea — רץ כל דקה | `* * * * *` (cron) | | `host_sync.sh` | bash | מסנכרן את עץ-המארח `~/legal-ai` ל-origin/main (ff-only) כדי שקוד-המארח (כותב/פאנלים/MCP שרצים מהעץ, לא בקונטיינר) יתעדכן אחרי merge; restart מדויק ל-chat/court-fetch/reaper רק כשקבציהם משתנים. בטוח: אף-פעם לא force; tasks.json הדירטי נשמר. סוגר את פער-פריסת-המארח (TaskMaster #160) | `* * * * *` (cron, flock) | diff --git a/scripts/agent_tool_grants_guard.py b/scripts/agent_tool_grants_guard.py new file mode 100755 index 0000000..6e918c6 --- /dev/null +++ b/scripts/agent_tool_grants_guard.py @@ -0,0 +1,206 @@ +#!/usr/bin/env python3 +"""INV-AG3 guard — every MCP tool an agent is TOLD to run must be GRANTED to it. + +The canonical checker for INV-AG3 (docs/spec/X4-agents.md §2א): a Claude-Code +subagent's ``tools:`` frontmatter is a CLOSED allow-list. A tool that is +registered on the MCP server but absent from that list is *not callable* by the +agent, however well the server is connected. + +Why this exists — the failure it is built to catch (2026-08-04): +``analyze_protocol`` shipped on 2026-06-30 (24e3e2f) touching 9 files, none of +them ``.claude/agents/*``. Later ``wake_analyst_for_protocol_analysis`` +(web/paperclip_client.py, #226) started writing "הרץ +``mcp__legal-ai__analyze_protocol(...)``" straight into the analyst's issue. +The analyst therefore received an explicit instruction to run a tool it was +never granted, reported "tools exist on the connected server but aren't exposed +as callable in this session", and burned two runs working around it via raw +psql + a hand-written script. INV-AG3 already covered this on paper; its +enforcement was deferred ("אכיפה אוטומטית עתידית"), so the drift went unnoticed +for five weeks. This script is that deferred enforcement. + +Three HARD rules: + + 1. **Backend delegation.** Every ``mcp__legal-ai__X`` named inside ``web/`` + (the backend telling an agent what to run) must be granted to at least one + agent. This is the rule that catches the 2026-08-04 failure. + + 2. **Per-agent instructions.** Every ``mcp__legal-ai__X`` in an agent file's + BODY must be granted in that same file's frontmatter. Prefixed mentions are + imperative by convention ("הרץ `mcp__legal-ai__…`"). + + 3. **No phantom grants.** Every granted tool must actually be registered on + the MCP server — catches typos and tools deleted out from under an agent. + +Plus one reviewed-exception rule: + + 4. **Bare tool names.** An agent body may name a tool in backticks without the + ``mcp__legal-ai__`` prefix (```get_legal_arguments```). Those are + ambiguous: some are real requirements, others are deliberately contrastive + ("**לא** דרך `precedent_library_upload`"), a pointer at *another* agent's + job, or a DB column that merely shares a tool's name. Each is classified + once in ``CONTRASTIVE_OK`` below; anything new fails until reviewed. + +NOT AGENTS (no frontmatter by design — the adapter sends the file as a raw +prompt, so YAML would leak into it): ``hermes-curator.md`` (deepseek_local), +``legal-analyst-gemini-critique.md`` (gemini_local). ``HEARTBEAT.md`` is a +shared checklist, not an agent. All three are skipped. + +Usage: + agent_tool_grants_guard.py # exit 1 on any violation +""" +from __future__ import annotations + +import re +import sys +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent + +AGENTS_DIR = REPO / ".claude" / "agents" +MCP_SRC = REPO / "mcp-server" / "src" +BACKEND_DIR = REPO / "web" + +# Files under .claude/agents/ that are not claude_local subagent definitions. +NOT_AGENTS = { + "HEARTBEAT.md", + "hermes-curator.md", + "legal-analyst-gemini-critique.md", +} + +# Bare (unprefixed) tool names in an agent body that are NOT requirements. +# Each entry is (agent file, tool, why) — reviewed 2026-08-04. Adding to this +# map is a deliberate act: it asserts "the agent is not being told to call this". +CONTRASTIVE_OK = { + ("legal-analyst.md", "case_create"): "prose about the cases.practice_area CHECK constraint, not a call", + ("legal-analyst.md", "search_internal_decisions"): "names the filter surface when contrasting Axis A/B", + ("legal-ceo.md", "search_decisions"): "contrast — 'search_decisions = only Dafna' vs the granted search_internal_decisions", + ("legal-ceo.md", "precedent_library_upload"): "explicitly the forbidden path ('לא דרך …', citation guard rejects)", + ("legal-ceo.md", "document_update"): "describes the tagging chaim must fix, not a CEO call", + ("legal-proofreader.md", "extraction_status"): "the documents.extraction_status DB column — name collides with a tool", + ("legal-qa.md", "precedent_attach"): "explicitly the researcher's job ('דרך precedent_attach של ה-researcher')", + ("legal-writer.md", "revise_draft"): "the CEO calls it ('CEO יקרא ל-revise_draft'), not the writer", + ("legal-writer.md", "search_case_precedents"): "a do-not-confuse disambiguation note ('שונה! … לא לבלבל')", +} + +TOOL_RE = re.compile(r"mcp__legal-ai__(\w+)") +REGISTER_RE = re.compile(r"@mcp\.tool\([^)]*\)\s*(?:async\s+)?def\s+(\w+)") +# `tool_name(` or `tool_name` inside backticks. +BARE_RE = re.compile(r"`(\w+)[(`]") + + +def server_tools() -> set[str]: + """Tool names registered on the MCP server.""" + out: set[str] = set() + for path in MCP_SRC.rglob("*.py"): + out |= set(REGISTER_RE.findall(path.read_text(encoding="utf-8", errors="ignore"))) + return out + + +def split_frontmatter(text: str) -> tuple[str, str]: + """Return (frontmatter, body). Empty frontmatter when the file has none.""" + if not text.startswith("---"): + return "", text + parts = text.split("---") + if len(parts) < 3: + return "", text + return parts[1], "---".join(parts[2:]) + + +def agent_files() -> list[Path]: + return sorted(p for p in AGENTS_DIR.glob("*.md") if p.name not in NOT_AGENTS) + + +def main() -> int: + registered = server_tools() + if not registered: + print("agent-tool-grants: FAIL — no @mcp.tool registrations found; is the tree complete?") + return 1 + + grants: dict[str, set[str]] = {} + bodies: dict[str, str] = {} + for path in agent_files(): + fm, body = split_frontmatter(path.read_text(encoding="utf-8", errors="ignore")) + grants[path.name] = set(TOOL_RE.findall(fm)) + bodies[path.name] = body + + all_granted: set[str] = set().union(*grants.values()) if grants else set() + violations: list[str] = [] + + # Rule 1 — backend delegation must land on a granted tool. + for path in sorted(BACKEND_DIR.rglob("*.py")): + text = path.read_text(encoding="utf-8", errors="ignore") + for tool in sorted(set(TOOL_RE.findall(text))): + if tool not in all_granted: + rel = path.relative_to(REPO) + violations.append( + f"[1 backend] {rel} instructs an agent to run " + f"mcp__legal-ai__{tool}, but NO agent grants it.\n" + f" fix: add `- mcp__legal-ai__{tool}` to the tools: " + f"frontmatter of the agent that receives that issue." + ) + + # Rule 2 — a prefixed mention in an agent body is an instruction to that agent. + for name, body in bodies.items(): + for tool in sorted(set(TOOL_RE.findall(body))): + if tool not in grants[name]: + violations.append( + f"[2 instructions] .claude/agents/{name} tells the agent to run " + f"mcp__legal-ai__{tool}, which its own tools: list omits.\n" + f" fix: add `- mcp__legal-ai__{tool}` to that frontmatter." + ) + + # Rule 3 — no grant may point at a tool the server does not register. + for name, granted in grants.items(): + for tool in sorted(granted - registered): + violations.append( + f"[3 phantom] .claude/agents/{name} grants mcp__legal-ai__{tool}, " + f"which is not registered on the MCP server.\n" + f" fix: correct the name, or drop the grant if the tool was removed." + ) + + # Rule 4 — every bare tool name is either granted or classified as contrastive. + for name, body in bodies.items(): + bare = {m for m in BARE_RE.findall(body) if m in registered} + for tool in sorted(bare - grants[name]): + if (name, tool) in CONTRASTIVE_OK: + continue + violations.append( + f"[4 bare name] .claude/agents/{name} mentions `{tool}` — a real MCP " + f"tool it is not granted.\n" + f" fix: grant it if the agent must call it, otherwise add " + f"(\"{name}\", \"{tool}\") to CONTRASTIVE_OK with the reason." + ) + + # Stale exceptions: a classification that no longer matches the text is noise. + for (name, tool), _why in sorted(CONTRASTIVE_OK.items()): + if name not in bodies: + violations.append( + f"[4 stale] CONTRASTIVE_OK names {name}, which is not an agent file." + ) + elif tool not in {m for m in BARE_RE.findall(bodies[name])}: + violations.append( + f"[4 stale] CONTRASTIVE_OK ({name}, {tool}) no longer appears in that " + f"file — drop the exception." + ) + + if violations: + print(f"INV-AG3 agent-tool-grants guard: {len(violations)} violation(s)\n") + for v in violations: + print(f" ✗ {v}") + print( + "\ndocs/spec/X4-agents.md §2א INV-AG3 — the frontmatter tools: list is a " + "CLOSED allow-list.\nA tool missing from it is not callable, no matter that " + "the MCP server is connected." + ) + return 1 + + print( + f"INV-AG3 agent-tool-grants guard: OK " + f"({len(agent_files())} agents, {len(all_granted)} distinct grants, " + f"{len(registered)} tools registered)" + ) + return 0 + + +if __name__ == "__main__": + sys.exit(main())