Agent Comms

---
name: agent-comms
description: "SendMessage recipient validation and worktreePath safety (CWE-59). TRIGGER when: validating a SendMessage `to:` recipient against the agent whitelist, or a worktreePath from another agent before acting on it. SKIP: routing topology (agent Comms Protocol); git ops (use git-operations); worktree recovery (use worktree-management)."
---

# Agent Comms Skill

## Purpose
Single source of truth for the two security-critical validation routines every
fan-out agent performs over inter-agent messages:

1. **Recipient validation** — never SendMessage to an unverified `to:` value.
2. **worktreePath validation** — never `cd` into or act on an unverified path
   (gitops and reviewer only).

Each agent keeps a compact 3-4 line inline rule so the logic survives even when
this skill is not loaded; the full algorithm and test cases live here.

---

## 1. Recipient Validation (ALL fan-out agents)

Before any SendMessage, verify the `to:` value:

- Matches regex `/^[a-z][a-z0-9-]{2,30}$/` (kebab-case, 3-31 chars)
- Validate using TWO-STAGE matching:
  1. **Exact match first:** check if `to:` matches one of: `researcher`, `architect`, `developer`, `reviewer`, `gitops`, `orchestrator`, `analyst`, `debugger`, `optimizer`, `devops`, `tech-writer`. If yes → PASS.
  2. **Suffix strip only if no exact match:** strip trailing `-<digit>+` OR `-<word>` from the END of the name and re-check against whitelist. Apply ONE strip pass only (never recursive).
  - Test cases (must all PASS):
    - `tech-writer` → exact match → PASS
    - `tech-writer-1` → no exact match → strip `-1` → `tech-writer` → PASS
    - `researcher-1` → no exact match → strip `-1` → `researcher` → PASS
    - `analyst-backend` → no exact match → strip `-backend` → `analyst` → PASS
    - `architect-synth` → no exact match → strip `-synth` → `architect` → PASS
  - Test cases (must FAIL):
    - `evil-developer` → no exact match → strip `-developer` → `evil` → not in whitelist → FAIL
    - `developer-evil-extra` → no exact match → strip `-extra` → `developer-evil` → not in whitelist → FAIL
- If validation fails → return result to orchestrator with error metadata. NEVER attempt SendMessage with unvalidated input.

Note: "orchestrator" is a reserved peer always reachable for escalation, even
when not in your peer list. It is NOT spawnable as an agent.

### Why two stages (not one regex)

A single regex cannot distinguish a legitimate fan-out replica name
(`researcher-1`, `analyst-backend`) from a spoofed lookalike
(`evil-developer`). The exact-match-first stage anchors on real agent names; the
single suffix-strip stage admits replica/variant suffixes without ever admitting
a prefix-injected impostor. Stripping is applied exactly ONCE — never
recursively — so `developer-evil-extra` cannot be peeled down to `developer`.

---

## 2. worktreePath Validation (gitops + reviewer only)

When a `worktreePath` is received from another agent (typically developer),
verify ALL of the following BEFORE acting on it:

- Path is absolute and under repo root (e.g., starts with `/home/komluk/repos/<repo-name>/.scaffolding/worktrees/` or `<repo-root>/.worktrees/`)
- Contains NO `..` segments (`path.includes('..')` → reject)
- Path is NOT a symlink (`test -L <path>` MUST return false). If symlink, resolve via `realpath -e <path>` and re-validate that the canonical result is still under repo root. Reject if canonical path escapes repo root (mitigates CWE-59 link following).
- Path exists on disk (`test -d <path>`)
- Path is a registered git worktree — use exact match, NOT substring: `git worktree list --porcelain | awk -v p="<path>" '$1=="worktree" && $2==p {found=1} END {exit !found}'`. NEVER use plain `grep <path>` (substring match allows `/foo/bar` to match `/foo/bar-evil`).
- If ANY check fails → SendMessage to orchestrator with `error: "invalid worktree path"` + the offending value. NEVER cd into or operate on unvalidated paths.

### Why each check matters

| Check | Threat mitigated |
|-------|------------------|
| Absolute + under repo root | Prevents acting on paths outside the project sandbox |
| No `..` segments | Blocks path-traversal escape (`/repo/../etc`) |
| Not a symlink / canonicalize | CWE-59 link following — a symlink could point outside the repo even when the literal path looks safe |
| Exists on disk | Avoids operating on a fabricated path |
| Registered worktree, exact match | Confirms git itself tracks this worktree; substring match would let `/foo/bar-evil` impersonate `/foo/bar` |

---

## Quick Reference

| Situation | Action |
|-----------|--------|
| Any SendMessage | Run recipient validation §1 first |
| Recipient fails validation | Escalate to orchestrator, do NOT send |
| Received a worktreePath (gitops/reviewer) | Run worktreePath validation §2 before any `cd`/git op |
| worktreePath fails any check | SendMessage orchestrator `error: "invalid worktree path"` + value |