Fix Agent Teams cross-talk with session-unique team names (#171)

* fix: use session-unique team names to prevent Agent Teams cross-talk

The static team name "PACT" caused message cross-talk when users ran
multiple concurrent Claude Code sessions. Now generates unique names
like PACT-{session_hash} using the first 8 characters of session_id
from the SessionStart hook input.

Includes: generate_team_name() with fallback chain (session_id →
CLAUDE_SESSION_ID env var → random hex), str() coercion for type
safety, 13 unit tests, updated test fixtures. Bumps to v3.0.5.

* docs: align code docstrings and comments with PACT-{session_hash} convention

* docs: update markdown to use {team_name} placeholder convention

- INSTRUCTIONS step 2 defines the format (PACT-{session_hash}) and
  tells the orchestrator to substitute wherever {team_name} appears
- All code templates use {team_name} as the placeholder
- Format description (PACT-{session_hash}) only in INSTRUCTIONS and
  rePACT prose
- Verify session team step retained in protocol files only

* docs: add verify session team step to all command files

Previously only comPACT's protocol sections had the "Verify session
team exists" safety net. Now all 5 command files include it for
consistent three-layer enforcement alongside INSTRUCTIONS step 2
and the session_init hook reminder.

Author: michael-wojcik

.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.0.4",
+      "version": "3.0.5",
       "author": {
         "name": "ProfSynapse"
       },

README.md

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

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

@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "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/CLAUDE.md

@@ -62,9 +62,9 @@ See @~/.claude/protocols/pact-plugin/algedonic.md for full protocol, trigger con
 
 ## INSTRUCTIONS
 1. Read `CLAUDE.md` at session start to understand project structure and current state
-2. Create the session team immediately: `TeamCreate(team_name="PACT")` — this must exist before starting any work
+2. Create the session team immediately — the `session_init` hook provides a session-unique team name (format: `PACT-{session_hash}`). This must exist before starting any work or spawning any agents. Use this name wherever `{team_name}` appears in commands.
 3. Apply the PACT framework methodology with specific principles at each phase, and delegate tasks to specific specialist agents for each phase
-4. **NEVER** add, change, or remove code yourself. **ALWAYS** delegate coding tasks to PACT specialist agents — your teammates on the `PACT` team.
+4. **NEVER** add, change, or remove code yourself. **ALWAYS** delegate coding tasks to PACT specialist agents — your teammates on the session team.
 5. Update `CLAUDE.md` after significant changes or discoveries (Execute `/PACT:pin-memory`)
 6. Follow phase-specific principles and delegate tasks to phase-specific specialist agents, in order to maintain code quality and systematic development
 
@@ -233,7 +233,7 @@ When making decisions, consider which horizon applies. Misalignment indicates mo
 
 **Core Principle**: The orchestrator coordinates; specialists execute. Don't do specialist work—delegate it.
 
-***NEVER add, change, or remove application code yourself***—**ALWAYS** delegate coding tasks to PACT specialist agents — your teammates on the `PACT` team.
+***NEVER add, change, or remove application code yourself***—**ALWAYS** delegate coding tasks to PACT specialist agents — your teammates on the session team.
 
 | Specialist Work | Delegate To |
 |-----------------|-------------|
@@ -358,14 +358,14 @@ When delegating a task, these specialist agents are available to execute PACT ph
 
 ### Agent Teams Dispatch
 
-> ⚠️ **MANDATORY**: Specialists are spawned as teammates via `Task(name=..., team_name="PACT", subagent_type=...)`. The session team (`PACT`) is created at session start per INSTRUCTIONS step 2.
+> ⚠️ **MANDATORY**: Specialists are spawned as teammates via `Task(name=..., team_name="{team_name}", subagent_type=...)`. The session team is created at session start per INSTRUCTIONS step 2. The `session_init` hook provides the specific team name in your session context.
 >
 > ⚠️ **NEVER** use plain `Task(subagent_type=...)` without `name` and `team_name` for specialist agents. This bypasses team coordination, task tracking, and SendMessage communication.
 
 **Dispatch pattern**:
 1. `TaskCreate(subject, description)` — create the tracking task with full mission
 2. `TaskUpdate(taskId, owner="{name}")` — assign ownership
-3. `Task(name="{name}", team_name="PACT", subagent_type="pact-{type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")` — spawn the teammate
+3. `Task(name="{name}", team_name="{team_name}", subagent_type="pact-{type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")` — spawn the teammate
 
 **Exception — `pact-memory-agent`**: This agent is NOT a team member. It still uses the background task model:
 ```python

pact-plugin/README.md

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

pact-plugin/commands/comPACT.md

@@ -140,7 +140,7 @@ Before invoking multiple specialists concurrently, perform this coordination che
 ## Pre-Invocation (Required)
 
 1. **Set up worktree** — If already in a worktree for this feature, reuse it. Otherwise, invoke `/PACT:worktree-setup` with the feature branch name. All subsequent work happens in the worktree.
-2. **Verify session team exists** — The `PACT` team should already exist from session start. If not, create it now: `TeamCreate(team_name="PACT")`.
+2. **Verify session team exists** — The `{team_name}` team should already exist from session start. If not, create it now: `TeamCreate(team_name="{team_name}")`.
 3. **S2 coordination** (if concurrent) — Check for file conflicts, assign boundaries
 
 ---
@@ -154,7 +154,7 @@ When the task contains multiple independent items, invoke multiple specialists t
 For each specialist needed:
 1. `TaskCreate(subject="{specialist}: {sub-task}", description="comPACT mode (concurrent): You are one of [N] specialists working concurrently.\nYou are working in a git worktree at [worktree_path].\n\nYOUR SCOPE: [specific sub-task]\nOTHER AGENTS' SCOPE: [what others handle]\n\nWork directly from this task description.\nCheck docs/plans/, docs/preparation/, docs/architecture/ briefly if they exist.\nDo not create new documentation artifacts in docs/.\nStay within your assigned scope.\n\nTesting: New unit tests for logic changes. Fix broken existing tests. Run test suite before handoff.\n\nIf you hit a blocker, STOP and SendMessage it to the lead.\n\nTask: [this agent's specific sub-task]")`
 2. `TaskUpdate(taskId, owner="{specialist-name}")`
-3. `Task(name="{specialist-name}", team_name="PACT", subagent_type="pact-{specialist-type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="{specialist-name}", team_name="{team_name}", subagent_type="pact-{specialist-type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 Spawn all specialists in parallel (multiple `Task` calls in one response).
 
@@ -171,7 +171,7 @@ Use a single specialist agent only when:
 **Dispatch the specialist**:
 1. `TaskCreate(subject="{specialist}: {task}", description="comPACT mode: Work directly from this task description.\nYou are working in a git worktree at [worktree_path].\nCheck docs/plans/, docs/preparation/, docs/architecture/ briefly if they exist.\nDo not create new documentation artifacts in docs/.\nFocus on the task at hand.\n\nTesting: New unit tests for logic changes (optional for trivial changes). Fix broken existing tests. Run test suite before handoff.\n\n> Smoke vs comprehensive tests: These are verification tests. Comprehensive coverage is TEST phase work.\n\nIf you hit a blocker, STOP and SendMessage it to the lead.\n\nTask: [user's task description]")`
 2. `TaskUpdate(taskId, owner="{specialist-name}")`
-3. `Task(name="{specialist-name}", team_name="PACT", subagent_type="pact-{specialist-type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="{specialist-name}", team_name="{team_name}", subagent_type="pact-{specialist-type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 ---
 

pact-plugin/commands/orchestrate.md

@@ -38,7 +38,7 @@ b. Analyze work needed (QDCL for CODE)
 c. TaskCreate: agent task(s) as children of phase
 d. TaskUpdate: agent tasks owner = "{agent-name}"
 e. TaskUpdate: next phase addBlockedBy = [agent IDs]
-f. Spawn teammates: Task(name="{name}", team_name="PACT", subagent_type="pact-{type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")
+f. Spawn teammates: Task(name="{name}", team_name="{team_name}", subagent_type="pact-{type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")
 g. Monitor via SendMessage (HANDOFFs) and TaskList until agents complete
 h. TaskUpdate: phase status = "completed" (agents self-manage their task status)
 ```
@@ -164,7 +164,7 @@ Sequential execution is the exception requiring explicit justification. When ass
 ---
 
 1. **Set up worktree**: If already in a worktree for this feature, reuse it. Otherwise, invoke `/PACT:worktree-setup` with the feature branch name. This creates both the feature branch and its worktree. All subsequent phases work in the worktree.
-2. **Verify session team exists**: The `PACT` team should already exist from session start. If not, create it now: `TeamCreate(team_name="PACT")`.
+2. **Verify session team exists**: The `{team_name}` team should already exist from session start. If not, create it now: `TeamCreate(team_name="{team_name}")`.
 3. **Check for plan** in `docs/plans/` matching this task
 
 ### Plan Status Handling
@@ -254,7 +254,7 @@ When a phase is skipped but a coder encounters a decision that would have been h
 1. `TaskCreate(subject="preparer: research {feature}", description="CONTEXT: ...\nMISSION: ...\nINSTRUCTIONS: ...\nGUIDELINES: ...")`
    - Include task description, plan sections (if any), and "Reference the approved plan at `docs/plans/{slug}-plan.md` for full context."
 2. `TaskUpdate(taskId, owner="preparer")`
-3. `Task(name="preparer", team_name="PACT", subagent_type="pact-preparer", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="preparer", team_name="{team_name}", subagent_type="pact-preparer", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 Completed-phase teammates remain as consultants. Do not shutdown during this workflow.
 
@@ -324,7 +324,7 @@ When detection fires (score >= threshold), follow the evaluation response protoc
    - Do not read phase output files yourself or paste their content into the task description.
    - If PREPARE was skipped: pass the plan's Preparation Phase section instead.
 2. `TaskUpdate(taskId, owner="architect")`
-3. `Task(name="architect", team_name="PACT", subagent_type="pact-architect", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="architect", team_name="{team_name}", subagent_type="pact-architect", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 Completed-phase teammates remain as consultants. Do not shutdown during this workflow.
 
@@ -412,7 +412,7 @@ For each coder needed:
    - If PREPARE/ARCHITECT were skipped, include: "PREPARE and/or ARCHITECT were skipped based on existing context. Minor decisions (naming, local structure) are yours to make. For moderate decisions (interface shape, error patterns), decide and implement but flag the decision with your rationale in the handoff so it can be validated. Major decisions affecting other components are blockers—don't implement, escalate."
    - Include: "Smoke Testing: Run the test suite before completing. If your changes break existing tests, fix them. Your tests are verification tests—enough to confirm your implementation works. Comprehensive coverage (edge cases, integration, E2E, adversarial) is TEST phase work."
 2. `TaskUpdate(taskId, owner="{coder-name}")`
-3. `Task(name="{coder-name}", team_name="PACT", subagent_type="pact-{coder-type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="{coder-name}", team_name="{team_name}", subagent_type="pact-{coder-type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 Spawn multiple coders in parallel (multiple `Task` calls in one response). Include worktree path and S2 scope boundaries in each task description.
 
@@ -475,7 +475,7 @@ Execute the [CONSOLIDATE Phase protocol](../protocols/pact-scope-phases.md#conso
    - Include task description, CODE phase handoff summaries (from SendMessage, not files), plan sections (if any), plan reference.
    - Include: "You own ALL substantive testing: unit tests, integration, E2E, edge cases."
 2. `TaskUpdate(taskId, owner="test-engineer")`
-3. `Task(name="test-engineer", team_name="PACT", subagent_type="pact-test-engineer", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="test-engineer", team_name="{team_name}", subagent_type="pact-test-engineer", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 **Before completing**:
 - [ ] All tests passing

pact-plugin/commands/peer-review.md

@@ -85,7 +85,7 @@ Review task: in_progress (persists until merge-ready)
 
 **PR Review Workflow**
 
-The `PACT` team should already exist from session start. If not, create it now: `TeamCreate(team_name="PACT")`.
+**Verify session team exists**: The `{team_name}` team should already exist from session start. If not, create it now: `TeamCreate(team_name="{team_name}")`.
 
 Pull request reviews should mirror real-world team practices where multiple reviewers sign off before merging. Dispatch **at least 3 reviewers in parallel** to provide comprehensive review coverage:
 
@@ -105,7 +105,7 @@ Select the domain coder based on PR focus:
 For each reviewer:
 1. `TaskCreate(subject="{reviewer-type}: review {feature}", description="Review this PR. Focus: [domain-specific review criteria]...")`
 2. `TaskUpdate(taskId, owner="{reviewer-name}")`
-3. `Task(name="{reviewer-name}", team_name="PACT", subagent_type="pact-{reviewer-type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="{reviewer-name}", team_name="{team_name}", subagent_type="pact-{reviewer-type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 Spawn all reviewers in parallel (multiple `Task` calls in one response).
 

pact-plugin/commands/plan-mode.md

@@ -97,7 +97,7 @@ Skip specialists clearly not relevant (e.g., skip database engineer for pure UI
 
 ### Phase 1: Parallel Specialist Consultation
 
-The `PACT` team should already exist from session start. If not, create it now: `TeamCreate(team_name="PACT")`.
+**Verify session team exists**: The `{team_name}` team should already exist from session start. If not, create it now: `TeamCreate(team_name="{team_name}")`.
 
 Dispatch relevant specialists **in parallel**, each in **planning-only mode**.
 
@@ -177,7 +177,7 @@ If a specialist fails entirely (timeout, error):
 **Dispatch each consultant**:
 1. `TaskCreate(subject="{specialist}: plan consultation for {feature}", description="PLANNING CONSULTATION ONLY — No implementation.\n\nTask: {task description}\n\n[full template content from above]")`
 2. `TaskUpdate(taskId, owner="{specialist-name}")`
-3. `Task(name="{specialist-name}", team_name="PACT", subagent_type="pact-{specialist-type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="{specialist-name}", team_name="{team_name}", subagent_type="pact-{specialist-type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 Spawn all consultants in parallel.
 

pact-plugin/commands/rePACT.md

@@ -6,7 +6,7 @@ Run a recursive PACT cycle for this sub-task: $ARGUMENTS
 
 This command initiates a **nested P→A→C→T cycle** for a sub-task that is too complex for simple delegation but should remain part of the current feature work.
 
-**Team behavior**: rePACT spawns sub-scope teammates into the existing session team (`PACT`). No new team is created. Use scope-prefixed names (e.g., `backend-coder-auth-scope`) to distinguish sub-scope teammates from parent-scope teammates.
+**Team behavior**: rePACT spawns sub-scope teammates into the existing session team (`PACT-{session_hash}`). No new team is created. Use scope-prefixed names (e.g., `backend-coder-auth-scope`) to distinguish sub-scope teammates from parent-scope teammates.
 
 ---
 
@@ -205,10 +205,12 @@ Design the sub-component:
 
 Implement the sub-component:
 
+**Verify session team exists**: The `{team_name}` team should already exist from session start. If not, create it now: `TeamCreate(team_name="{team_name}")`.
+
 For each specialist needed:
 1. `TaskCreate(subject="{scope-prefixed-name}: implement {sub-task}", description="[full CONTEXT/MISSION/INSTRUCTIONS/GUIDELINES]")`
 2. `TaskUpdate(taskId, owner="{scope-prefixed-name}")`
-3. `Task(name="{scope-prefixed-name}", team_name="PACT", subagent_type="pact-{specialist-type}", prompt="You are joining team PACT. Check TaskList for tasks assigned to you.")`
+3. `Task(name="{scope-prefixed-name}", team_name="{team_name}", subagent_type="pact-{specialist-type}", prompt="You are joining team {team_name}. Check TaskList for tasks assigned to you.")`
 
 For multi-domain: spawn multiple specialists in parallel.
 Apply S2 coordination if parallel work.