From 598df0dc8cb425dc92cbf9197283b5fab85375d0 Mon Sep 17 00:00:00 2001
From: Chaim <chaim@marcus-law.co.il>
Date: Tue, 14 Apr 2026 14:43:54 +0000
Subject: [PATCH] Fix Paperclip API routes and document agent-to-agent wakeup
 pattern
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent JWT cannot wake other agents directly (returns "Agent can only
invoke itself"). The correct pattern: create an issue + assign to the
target agent → Paperclip triggers wakeup automatically.

Also documented all correct API routes in HEARTBEAT.md:
- POST /api/issues/{id}/comments (not /issues/)
- POST /api/companies/{company-id}/issues (not /api/issues)
- PATCH /api/issues/{id}
- POST /api/agents/{id}/wakeup (self only, with payload.issueId)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/agents/HEARTBEAT.md | 16 ++++++++++++++--
 .claude/agents/legal-ceo.md | 24 ++++++++++++++++++++++--
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/.claude/agents/HEARTBEAT.md b/.claude/agents/HEARTBEAT.md
index 588fee8..3137ef4 100644
--- a/.claude/agents/HEARTBEAT.md
+++ b/.claude/agents/HEARTBEAT.md
@@ -107,9 +107,21 @@ curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
 curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
   "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \
-  -d '{"reason": "סוכן [שמך] סיים משימה [issue-id] בסטטוס [done/blocked]. נדרשת בדיקה והחלטה על הצעד הבא."}'
+  -d '{"source":"automation","triggerDetail":"system","reason":"סוכן [שמך] סיים משימה [issue-id] בסטטוס [done/blocked]","payload":{"issueId":"[issue-id]","mutation":"agent_completion"}}'
 ```
-**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.**
+
+**⚠️ כללי ברזל — Paperclip API:**
+1. **אסור** `INSERT INTO agent_wakeup_requests` — לא יוצר heartbeat_run, הסוכן לא יתעורר לעולם
+2. **חובה** `payload.issueId` בכל wakeup — בלי זה הסוכן מתעורר בלי הקשר (בלי תיק, בלי cwd)
+3. **agent JWT לא יכול להעיר סוכנים אחרים** — רק את עצמו. כדי להעיר סוכן אחר → צור issue + הקצה אליו (Paperclip מפעיל wakeup אוטומטי)
+
+**נתיבי API:**
+| פעולה | נתיב |
+|-------|-------|
+| פרסום comment | `POST /api/issues/{issue-id}/comments` |
+| יצירת issue | `POST /api/companies/{company-id}/issues` |
+| עדכון issue | `PATCH /api/issues/{issue-id}` |
+| wakeup עצמי/CEO | `POST /api/agents/{agent-id}/wakeup` (עם payload!) |
 
 ## 5. התראת מייל — כשנדרשת תשובה אנושית
 
diff --git a/.claude/agents/legal-ceo.md b/.claude/agents/legal-ceo.md
index a45cbb5..d3a7633 100644
--- a/.claude/agents/legal-ceo.md
+++ b/.claude/agents/legal-ceo.md
@@ -414,15 +414,35 @@ tools:
 
 5. **דווח** — פרסם comment שמאשר שקיבלת את ההוראה ומה אתה עושה איתה
 
-## איך לקרוא comments של חיים
+## נתיבי API — חובה!
 
 ```bash
 # קרא comments על issue
 curl -s -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" | jq '.[-1].body'
+
+# פרסם comment
+curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" \
+  -d '{"body": "..."}'
+
+# צור issue חדש (עם הקצאה לסוכן → מפעיל wakeup אוטומטי!)
+curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  "$PAPERCLIP_API_URL/api/companies/42a7acd0-30c5-4cbd-ac97-7424f65df294/issues" \
+  -d '{"title":"...","projectId":"25c1b4a1-2c0e-4a2d-9938-8ae56ccda6f1","assigneeAgentId":"{agent-id}","description":"...","status":"todo"}'
+
+# עדכן issue
+curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  "$PAPERCLIP_API_URL/api/issues/{issue-id}" \
+  -d '{"status": "done"}'
 ```
 
-חפש ב-comment:
+**⚠️ agent JWT לא יכול להעיר סוכנים אחרים ישירות.** כדי להעיר סוכן → **צור issue חדש + הקצה אליו** (Paperclip מפעיל wakeup אוטומטי על assignment).
+
+חפש ב-comment של חיים:
 - מספר (1/2/3) → בחירה
 - "כיוון" + מספר → אישור כיוון
 - טבלת טיפול בטענות → סימון claim_handling