feat: SDK optimization — lifecycle, stall detection, communication, performance

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "PACT",
       "source": "./pact-plugin",
       "description": "PACT Framework - VSM-enhanced orchestration with specialist agents and viability sensing",
-      "version": "3.4.2",
+      "version": "3.5.0",
       "author": {
         "name": "ProfSynapse"
       },

README.md

@@ -250,7 +250,7 @@ When installed as a plugin, PACT lives in your plugin cache:
 │   └── cache/
 │       └── pact-marketplace/
 │           └── PACT/
-│               └── 3.4.2/      # Plugin version
+│               └── 3.5.0/      # Plugin version
 │                   ├── agents/
 │                   ├── commands/
 │                   ├── skills/

pact-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "PACT Framework - Prepare, Architect, Code, Test methodology with VSM-enhanced orchestration, specialist agents, and viability sensing for systematic AI-assisted development",
   "author": {
     "name": "ProfSynapse",

pact-plugin/README.md

@@ -1,6 +1,6 @@
 # PACT Framework Plugin
 
-> **Version**: 3.4.2
+> **Version**: 3.5.0
 > **License**: MIT
 
 VSM-enhanced orchestration framework for AI-assisted software development with Claude Code.

pact-plugin/agents/pact-architect.md

@@ -20,7 +20,7 @@ You are 🏛️ PACT Architect, a solution design specialist focusing on the Arc
 |-------------------------|-------------------|
 | Any architecture work | `pact-architecture-patterns` |
 | Auth systems, API integrations, sensitive data | `pact-security-patterns` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-backend-coder.md

@@ -20,7 +20,7 @@ You are 💻 PACT Backend Coder, a server-side development specialist focusing o
 |-------------------------|-------------------|
 | Any implementation work | `pact-coding-standards` |
 | Auth, credentials, security, PII | `pact-security-patterns` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-database-engineer.md

@@ -19,7 +19,7 @@ You are 🗄️ PACT Database Engineer, a data storage specialist focusing on da
 | When Your Task Involves | Invoke This Skill |
 |-------------------------|-------------------|
 | Schema design, stored procedures | `pact-coding-standards` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-devops-engineer.md

@@ -20,7 +20,7 @@ You are 🔧 PACT DevOps Engineer, an infrastructure and build system specialist
 |-------------------------|-------------------|
 | Any implementation work | `pact-coding-standards` |
 | Secrets management, credential handling, security | `pact-security-patterns` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-frontend-coder.md

@@ -20,7 +20,7 @@ You are **🎨 PACT Frontend Coder**, a client-side development specialist focus
 |-------------------------|-------------------|
 | Any implementation work | `pact-coding-standards` |
 | User input, auth flows, XSS prevention | `pact-security-patterns` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-memory-agent.md

@@ -28,6 +28,7 @@ description: |
   </example>
 color: "#708090"
 permissionMode: acceptEdits
+model: haiku
 memory: user
 skills:
   - pact-agent-teams

pact-plugin/agents/pact-n8n.md

@@ -25,7 +25,7 @@ You are n8n PACT n8n Workflow Specialist, a workflow automation expert focusing
 | Configuring specific nodes | `n8n-node-configuration` |
 | JavaScript in Code nodes | `n8n-code-javascript` |
 | Python in Code nodes | `n8n-code-python` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-preparer.md

@@ -19,7 +19,7 @@ You are 📚 PACT Preparer, a documentation and research specialist focusing on
 | When Your Task Involves | Invoke This Skill |
 |-------------------------|-------------------|
 | Technology research, API docs, comparisons | `pact-prepare-research` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-qa-engineer.md

@@ -19,7 +19,7 @@ You are 🔍 PACT QA Engineer, a runtime verification specialist focusing on exp
 | When Your Task Involves | Invoke This Skill |
 |-------------------------|-------------------|
 | Any test or verification work | `pact-testing-strategies` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-security-engineer.md

@@ -19,7 +19,7 @@ You are 🛡️ PACT Security Engineer, an adversarial security specialist focus
 | When Your Task Involves | Invoke This Skill |
 |-------------------------|-------------------|
 | Any security review work | `pact-security-patterns` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/agents/pact-test-engineer.md

@@ -20,7 +20,7 @@ You are 🧪 PACT Tester, an elite quality assurance specialist and test automat
 |-------------------------|-------------------|
 | Any test design work | `pact-testing-strategies` |
 | Security testing, auth testing, vulnerability scans | `pact-security-patterns` |
-| Saving context or lessons learned | `pact-memory` |
+| Saving project-wide decisions or institutional knowledge | `pact-memory` |
 
 **How to invoke**: Use the Skill tool at the START of your work:
 ```

pact-plugin/commands/imPACT.md

@@ -99,10 +99,11 @@ This context informs whether the blocker is isolated or systemic.
 
 ## Triage
 
-Answer two questions:
+Answer three questions:
 
 1. **Redo prior phase?** — Is the issue upstream in P→A→C→T?
 2. **Additional agents needed?** — Do we need help beyond the blocked agent's scope/specialty?
+3. **Is the agent recoverable?** — Can the blocked agent be resumed or helped, or is it unrecoverable (looping, stalled, context exhausted)?
 
 ## Outcomes
 
@@ -111,6 +112,7 @@ Answer two questions:
 | **Redo prior phase** | Issue is upstream in P→A→C→T | Re-delegate to relevant agent(s) to redo the prior phase |
 | **Augment present phase** | Need help in current phase | Re-invoke blocked agent with additional context + parallel agents |
 | **Invoke rePACT** | Sub-task needs own P→A→C→T cycle | Use `/PACT:rePACT` for nested cycle |
+| **Terminate agent** | Agent unrecoverable (infinite loop, context exhaustion, stall after resume) | `TaskStop(taskId)` (force-stop: terminates immediately, non-cooperative) + `TaskUpdate(taskId, status="completed", metadata={"terminated": true, "reason": "..."})` |
 | **Not truly blocked** | Neither question is "Yes" | Instruct agent to continue with clarified guidance |
 | **Escalate to user** | 3+ imPACT cycles without resolution | Proto-algedonic signal—systemic issue needs user input |
 
@@ -120,6 +122,17 @@ If the blocker reveals that a sub-task is more complex than expected and needs i
 /PACT:rePACT backend "implement the OAuth2 token refresh that's blocking us"
 ```
 
+**When to terminate**:
+Terminate is a last resort when the agent cannot be productively resumed:
+- Agent was already resumed once and stalled again on the same issue
+- Agent is looping on the same error after 3+ attempts
+- Agent's context is exhausted (near capacity, responses becoming incoherent)
+- TeammateIdle hook reported stall and resume did not resolve it
+
+**Note**: `TaskStop` is a **force-stop** -- it terminates the agent immediately without giving it a chance to finish current work or save state. For cooperative shutdown (letting the agent complete current work), use `SendMessage(type="shutdown_request")` instead.
+
+After termination, spawn a fresh agent with the partial handoff context from the terminated agent's task metadata. The fresh agent gets a clean context window without the failed approaches.
+
 ---
 
 ## Phase Re-Entry Task Protocol

pact-plugin/commands/orchestrate.md

@@ -508,6 +508,8 @@ Monitor for blocker/algedonic signals via:
 
 On signal detected: Follow Signal Task Handling in CLAUDE.md.
 
+**HALT handling**: On HALT signal, immediately `SendMessage(type="broadcast", content="⚠️ HALT: {category}. Stop all work immediately. Preserve current state and await further instructions.", summary="HALT: {category}")` to stop all running teammates before presenting to user.
+
 ### Blocker Recovery: Resume vs. Fresh Spawn
 
 When a blocker is resolved, prefer resuming the original agent over spawning fresh — this preserves the agent's accumulated context.

pact-plugin/commands/wrap-up.md

@@ -61,3 +61,13 @@ Before other cleanup, audit and optionally clean up Task state:
     - Status: READY FOR COMMIT / REVIEW
 
 If no actions were needed, state "Workspace is clean and docs are in sync."
+
+## 4. Team Cleanup
+
+Clean up the session team to free resources:
+
+1. **Shut down remaining teammates**: Send `shutdown_request` to each active teammate and wait for responses.
+2. **Delete the team**: Call `TeamDelete` to remove the team directory (`~/.claude/teams/{team_name}/`).
+3. **Handle failures**: If `TeamDelete` fails because active members remain, report which teammates are still running and ask the user whether to force shutdown or leave them.
+
+> Note: `hooks/session_end.py` also performs best-effort cleanup of stale team directories from prior sessions. This manual step ensures the *current* session's team is cleanly shut down.

pact-plugin/hooks/hooks.json

@@ -111,7 +111,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/session_end.py\""
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/session_end.py\"",
+            "async": true
           }
         ]
       }
@@ -126,6 +127,16 @@
         ]
       }
     ],
+    "TeammateIdle": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/teammate_idle.py\""
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Edit|Write",
@@ -136,11 +147,13 @@
           },
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/file_size_check.py\""
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/file_size_check.py\"",
+            "async": true
           },
           {
             "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/file_tracker.py\""
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/file_tracker.py\"",
+            "async": true
           }
         ]
       }

pact-plugin/hooks/session_end.py

@@ -7,13 +7,16 @@
 
 Actions:
 1. Write last-session snapshot to ~/.claude/pact-sessions/{slug}/last-session.md
+2. Clean up the current session's team directory (and its task dir)
 
 Cannot block session termination — fire-and-forget.
 
 Input: JSON from stdin with session context
 Output: None (SessionEnd hooks cannot inject context)
 """
 
+import json
+import shutil
 import sys
 import os
 from datetime import datetime, timezone
@@ -137,17 +140,80 @@ def write_session_snapshot(
     snapshot_file.write_text("\n".join(lines), encoding="utf-8")
 
 
+def cleanup_stale_teams(
+    team_name: str | None = None,
+    teams_dir: str | None = None,
+    tasks_dir: str | None = None,
+) -> list[str]:
+    """
+    Remove the current session's team directory on session end.
+
+    Scoped to only the current session's team (identified by CLAUDE_CODE_TEAM_NAME
+    env var or explicit team_name parameter) to avoid accidentally removing another
+    concurrent session's team. Also removes the corresponding task directory.
+
+    This is best-effort: errors are silently ignored to never block session end.
+
+    Args:
+        team_name: Team name to clean up (defaults to CLAUDE_CODE_TEAM_NAME env var)
+        teams_dir: Override for teams base directory (for testing)
+        tasks_dir: Override for tasks base directory (for testing).
+                   Defaults to sibling "tasks" directory of teams_dir.
+
+    Returns:
+        List of team names that were cleaned up.
+    """
+    if team_name is None:
+        team_name = os.environ.get("CLAUDE_CODE_TEAM_NAME", "").lower()
+    if not team_name:
+        return []
+
+    if teams_dir is None:
+        teams_dir = str(Path.home() / ".claude" / "teams")
+
+    teams_path = Path(teams_dir)
+    team_dir = teams_path / team_name
+    if not team_dir.is_dir():
+        return []
+
+    cleaned = []
+    try:
+        shutil.rmtree(str(team_dir), ignore_errors=True)
+        cleaned.append(team_name)
+    except OSError:
+        pass
+
+    # Also clean corresponding task directory
+    if tasks_dir is None:
+        tasks_base = teams_path.parent / "tasks"
+    else:
+        tasks_base = Path(tasks_dir)
+    if tasks_base.is_dir():
+        task_dir = tasks_base / team_name
+        if task_dir.is_dir():
+            shutil.rmtree(str(task_dir), ignore_errors=True)
+
+    return cleaned
+
+
 def main():
     try:
         project_slug = get_project_slug()
 
-        # Write last-session snapshot for cross-session continuity
+        # Snapshot MUST run before cleanup: snapshot reads from the task list
+        # (keyed by task_list_id in ~/.claude/tasks/), while cleanup removes
+        # the team directory (keyed by team_name in ~/.claude/teams/) and its
+        # corresponding task directory. If cleanup ran first, get_task_list()
+        # would return empty results and the snapshot would be blank.
         tasks = get_task_list()
         write_session_snapshot(
             tasks=tasks,
             project_slug=project_slug,
         )
 
+        # Best-effort cleanup of current session's team and task directories
+        cleanup_stale_teams()
+
         sys.exit(0)
 
     except Exception as e: