[tak-bro]

Summary

다른 세션의 에이전트가 사용자가 부르는 Claude Code 세션 이름(ko-qmd-70 같은 cwd 기반 derived 이름, /rename 이름)으로 다른 머신의 세션에 hwip_agent_send 할 수 있게 한다. 지금은 리스너가 derived 이름을 서버에 올리지 않아 UNKNOWN_TARGET 이 난다. 보내기 전에 전 머신 세션을 조회하는 hwip_agent_list {all:true} · hwip agent list --all 도 더한다.

이 변경은 레포 4개에 걸친다 — 배포 순서 server → cli → mcp-server(plugin 은 문서). 새 필드는 양쪽 다 optional 이라 어느 순서로 가도 깨지지 않지만, server 가 먼저여야 handle 이 저장된다.

관련 PR (배포 순서): 1. hwipit/hwip#662 (server) → 2. hwipit/cli#29 → 3. hwipit/mcp-server#7 · 문서 #5

Changes

• skills/hwip/SKILL.md · README.md · CLAUDE.md · docs/ARCHITECTURE.md — handle 로 보내기, hwip_agent_list {all:true} · hwip agent list --all

How to Test

cli node scripts/sync-from-plugin.mjs --check → match.

Evidence

문서 변경 — 해당 없음.

Risks

none.

Merge danger

Door: two-way · Blast radius: docs only
문서만.

Alternatives considered

• providerSessionName 에 derived 이름도 싣기 — 앱 표시 정책(auto-name 숨김)을 깨서 버림. 매칭 전용 필드를 따로 둔다(D1, 사용자 결정).
• 새 CLI hwip sessions 명령·새 MCP 툴 — 기존 agent list 에 all 옵션 하나로 충분(D3, 사용자 결정).
• cwd 를 서버로 올려 후보에 표시 — 올리지 않는다(D2, 사용자 결정).

Auto-decided

• handle 대상 에이전트: Claude 만 — 다른 에이전트는 사용자 이름이 이미 providerSessionName 으로 매칭됨
• --all JSON 모양: {v:1, all:true, sessions} — 로컬 행의 상위 집합(host·online·handle·alias 추가)
• MCP all 경로: MCP 클라이언트가 GET /devices 직접 + 공용 listAgentTargets — send 와 같은 기기 목록·키, 구버전 CLI 에 --all 이 없을 때의 실패 경로가 사라짐
• 배포 순서: server → cli → mcp
• handle 길이 상한: 200자(KNOWN_RUN_TITLE_MAX 관례)

Acceptance

• AC-1 · PASS · 서버 ingest 가 handle 을 한 줄·200자로 정규화해 저장, 비문자열·빈 값은 버림
• AC-2 · PASS · 리스너가 derived Claude 이름을 providerSessionHandle 에 싣고 providerSessionName 은 지금처럼 비움(앱 표시 불변)
• AC-3 · PASS · resolveAgentTarget(cli·mcp 두 사본)이 handle 로 풀고, 여럿이면 AMBIGUOUS_TARGET 후보에 handle·host·state
• AC-4 · PASS · hwip agent list --all --json · hwip_agent_list {all:true} 가 전 머신 세션을 반환
• AC-5 · PASS · 세 레포 기존 suite·typecheck 초록
• verify-check: 8/8 green · audit: ok (5 checked rows at 7a01332)

Checklist

• /review --full(opus fork + sonnet 교차, 형제 레포 별도) — Critical·Important 0
• /security-scan(변경분) — SECURE, Low 2(기존 경로) 중 1건 수정
• 문서(README·SKILL) 갱신

🤖 Generated with Claude Code

[tak-bro]

Review — Approve (docs-only)

Scope: 4 files (+14/-8) · CI: pass · Risk: Low · 반박됨 0
test-check: n/a (docs-only — 변경 파일 전부 *.md)
weaken-check: n/a (docs-only)
routing: none
axis-a: clean
axis-b: as planned

Scope Check: CLEAN

• Intent: handle(에이전트 세션 이름)로 hwip_agent_send, hwip_agent_list {all:true} / hwip agent list --all 로 전 머신 세션 조회 문서화
• Delivered: skills/hwip/SKILL.md · README.md · CLAUDE.md · docs/ARCHITECTURE.md 에 둘 다 반영

Spec coverage (형제 PR 구현과 대조)

• target 매칭 후보(tmux name · alias · label · 앱 표시 이름 · handle) — mcp-server src/agent-target.ts:157 의 [c.name, c.alias, c.providerSessionName, c.providerSessionHandle, c.label] 와 일치
• all 목록 필드(key · host · online · state · alias · handle) — mcp-server src/agent-target.test.ts:188 기대값과 일치
• all 은 서버 조회라 API 키 필요 — mcp-server src/tools/agent-local.ts:13-14 주석과 일치
• cli node scripts/sync-from-plugin.mjs --check (이 브랜치 기준) → match

Findings

없음.