crew-agent-runner

crew-agent-runner

crew 업무 스킬은 에이전트 provider별 호출 세부사항을 직접 구현하지 않고 이 중앙 규약을 따른다. 본 스킬은 prepare, resolve, dispatch, resume, followup 주입, retry/fallback/escalate 판단의 공통 표면을 정의한다.

설치 후 drift 차단용 pre-commit hook은 node "$CREW_ROOT/scripts/crew-agent-runner.mjs" install-hooks로 설치한다. (plugin 개발자 전용 — 사용자는 호출하지 않습니다. build/validate는 plugin source repo의 drift 차단 도구입니다.)

Dispatch 절차

업무 스킬(crew-plan/crew-interview/crew-dev)이 role을 실행해야 할 때 본 절차를 따른다.

Step 0. Runner 경로 결정

오케스트레이터는 runner 호출 전에 plugin root를 결정하고, 결정된 경로를 CREW_ROOT로 사용한다.

Fallback 체인 (순서 중요):

1. $CLAUDE_PLUGIN_ROOT가 있으면 사용한다. 정상 Claude Code plugin 환경이므로 추가 검증하지 않는다.
2. ~/.claude/crew/plugin-root.json의 pluginRoot를 읽는다. 해당 경로에 scripts/crew-agent-runner.mjs가 존재하면 사용하고, 없으면 다음 fallback으로 진행한다.
3. git rev-parse --show-toplevel 결과를 dev 환경 전용 후보로 사용한다. 해당 경로의 package.json에서 name이 @jjlabsio/claude-crew인지 검증하고, 맞으면 사용한다. 아니면 다음 fallback으로 진행한다.
4. 모든 fallback이 실패하면 '/crew-setup을 먼저 실행하세요' 에러 메시지로 중단한다.

이후 모든 runner 호출은 node "$CREW_ROOT/scripts/crew-agent-runner.mjs" 형식을 사용한다.

1. request 객체 작성

{ role, inputs (path+content), instruction, successGate, failureHandling, taskId } 형태의 임시 JSON 파일을 작성한다.

2. prepare

오케스트레이터는 node "$CREW_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json을 실행한다. prepare는 provider/model/contract를 해석하고 다음 action 중 하나를 반환한다.

3a. dispatch action

action == dispatch이면 prepare가 반환한 command를 실행한다. 이 경로는 Codex provider role에만 사용하며 AgentResult JSON을 즉시 반환한다.

3b. agent action

action == agent이면 prepare가 반환한 subagent_type, model, prompt로 메인 오케스트레이터가 Claude provider 역할을 실행하고, sub-agent 결과를 AgentResult JSON 형식으로 정규화한다.

주의: 업무 스킬은 직접 provider를 분기하거나 직접 하위 에이전트를 호출하지 않는다. 항상 prepare 결과의 action만 수행한다.

AgentResult 상태 처리

AgentResult 5상태:

complete

artifact를 outputs.target에 저장한다. 이후 다음 phase로 진행한다.

blocked_on_user

questions를 메인 오케스트레이터의 사용자 질문 도구로 사용자에게 전달한다. 답변 수신 후 followup을 주입한다. 절차는 아래 Resume 섹션을 따른다.

needs_agent

requests의 role을 새 dispatch 사이클로 실행한다. 결과를 followup으로 원래 에이전트에 주입한다.

needs_tool

capability를 넘어선 도구 요청이다. 오케스트레이터가 contract.policy에 따라 직접 도구 실행 후 결과를 주입하거나, 실행할 수 없으면 failed로 escalate한다.

failed

contract.policy의 maxAttempts, fallbackProvider, escalateAfterAttempts, consecutiveSameFailureLimit에 따라 처리한다.

• retry: maxAttempts 미만이면 재시도한다.
• fallbackProvider 전환: fallback provider가 있으면 provider를 전환한다.
• 사용자 escalate: 한도에 도달했거나 같은 사유가 반복되면 사용자에게 에스컬레이션한다.

Resume

needs_agent / blocked_on_user 상태에서 같은 sub-agent context를 이어가는 표준 절차.

Codex 경로

1. node "$CREW_ROOT/scripts/crew-agent-runner.mjs" render-followup --previous-result <file> --new-input <file> 실행 → followup prompt 문자열 → 임시 파일에 저장.
2. node "$CREW_ROOT/scripts/crew-agent-runner.mjs" dispatch --role <role> --request-file <new-request-with-followup-prompt> --resume-handle <agent_handle> --json 실행.
   • 내부적으로 runner가 crew-codex-companion.mjs task-resume-candidate로 thread 일치 검증 후 task --resume-last를 호출하고 AgentResult를 정규화한다.
3. AgentResult JSON을 받아 다음 상태 처리.

주의: 직접 crew-codex-companion.mjs task --resume-last를 호출하지 말 것. runner의 candidate guard와 AgentResult 정규화를 건너뛴다.

Claude 경로

1. Agent spawn으로 받은 sub-agent handle을 보존한다.
2. render-followup을 사용하여 followup prompt를 생성한다.
3. 메인 conversation에서 SendMessage(to: <agent-handle>, message: <followup-prompt>)로 같은 sub-agent에 후속 turn을 전달한다.

Followup 주입

Followup prompt 형식은 양 provider에서 동일하다.

## 이전 결과
status: <status>
summary: <summary>
artifact:
---
<artifact>
---

## 추가 입력
<new-input>

## 지시
계속 진행해라.

이 형식은 runner.mjs render-followup이 결정론적으로 생성한다. artifact가 객체/배열인 경우 runner가 JSON으로 직렬화하여 fence 블록 안에 삽입한다 (정보 손실 방지).

Retry / Fallback / Escalate

contract.policy:

• maxAttempts: retry 횟수 한도
• fallbackProvider: claude/codex 전환
• escalateAfterAttempts: 한도 도달 시 사용자 escalate
• consecutiveSameFailureLimit: 같은 사유 연속 fail 한도