send() 전에는 아무것도 실행되지 않는다

이것이 ActiveRecord에서 빌려온 구조이며, 나머지 API가 이토록 평범할 수 있는 이유입니다.

const command = Command.open(Claude, { workingDir: '/proj' });

command.setModel('opus').setPermissions('plan').setMessage('Plan the migration');

command.toArgv();
// ['-p', '--output-format', 'stream-json', '--input-format', 'stream-json',
//  '--verbose', '--include-partial-messages', '--permission-prompt-tool', 'stdio',
//  '--session-id', '…', '--permission-mode', 'plan', '--model', 'opus']

command.toPayload();
// { type: 'user', message: { role: 'user', content: 'Plan the migration' } }

console.log(command.inspect());
// provider:    claude
// command:     claude -p --output-format stream-json …
// stdin:       {"type":"user","message":{"role":"user","content":"Plan the migration"}}
// model:       opus
// permissions: plan
// attachments: 0
// workingDir:  /proj
// session:     3f2a… (not started)

세터가 두 가지인 것은 의도입니다

모든 속성은 대입과 set 접두 메서드를 둘 다 갖습니다. 세터는 this를 반환하므로 의도를 체이닝할 수 있고, 대입은 체이닝이 소음만 더할 때를 위해 있습니다.

command.model = 'opus';
command.setModel('opus').setPermissions('ask-before-edit').setMessage('…');

속성	세터	비고
`message`	`setMessage(text)`	다음에 보내질 턴.
`model`	`setModel(name \| null)`	`null`이면 CLI 자신의 선택을 건드리지 않습니다.
`permissions`	`setPermissions(mode \| name \| null)`	모르는 이름은 무시되지 않고 throw합니다.
`provider`	`setProvider(provider)`	다음 `send()`에서 적용됩니다.
`attachments`	`setAttachment(one)` / `setAttachments(many)`	단수형은 대체하며, `send()` 후 비워집니다.

대화 도중 provider 바꾸기

command.provider = Codex;  // 다음 send()에서 적용됨

CLI 프로세스는 다른 프로세스가 될 수 없으므로, 교체란 곧 프로세스를 갈아 끼우는 일입니다. 실행할 것이 생기기 전까지 그 비용을 치를 이유가 없고 — 바로 그래서 말만 하는 데에는 비용이 들지 않습니다.

`send()`가 다시 spawn하는 조건

send()는 가능한 한 실행 중인 프로세스를 재사용합니다. 새로 spawn되는 경우는 실행 중인 CLI를 설득해서는 바꿀 수 없는 무언가가 바뀌었을 때뿐입니다.

provider가 달라졌을 때 — 프로세스는 다른 프로그램이 될 수 없습니다.
permission mode가 달라졌을 때 — --permission-mode는 spawn 시점 플래그이고, 실행 중에 바꾸는 방법은 문서화되어 있지 않습니다.

그 밖의 것 — 새 모델, 새 메시지, 새 첨부 — 은 모두 기존 프로세스를 통해 전달됩니다.

다음으로 볼 것

권한 모드 — 모드 변경이 재spawn인 이유.
첨부 — send()가 무엇을 비우고, 왜 그러는지.
레퍼런스: Command — 모든 속성과 메서드를 한자리에.