# Demo CLI 동작 계약

<a id="overview"></a>

`cmd/agentcore`는 SDK demo REPL/one-shot host다. daemon, batch runner, durable worker가 아니다. 기본 Session은 transcript, SessionID persistence, memory, Noa와 output spill을 설정하지 않으므로 process 재시작 뒤 대화를 resume할 durable state가 없다. random in-memory SessionID는 background task directory 식별에만 쓰인다. [CLI 근거](evidence:cli-main)

<a id="inputs"></a>

## 입력과 설정

| input | default/precedence | construction failure |
|---|---|---|
| `-provider` | flag > `AGENT_PROVIDER` > `anthropic` | unknown format: stderr + exit 2 |
| `-model` | flag > `AGENT_MODEL`; required | missing: stderr + exit 2 |
| `-base-url` | flag only; empty면 provider env/public default | provider construction error: stderr + exit 2 |
| `-api-key` | flag only; empty면 provider env | empty 자체는 construction error 아님 |
| `-system` | empty면 built-in coding prompt | file read error: stderr + exit 1 |
| `-dir` | empty면 current working directory | `Getwd` error를 검사하지 않음 |
| `-yes` | false | true면 bypass mode; explicit/tool hard deny는 여전히 가능 |
| `-max-turns` | 50 | turn budget terminal을 process status로 변환하지 않음 |
| `-p` | empty면 interactive | non-empty면 한 turn 후 return |

<a id="stdio"></a>

## stdout/stderr

| channel | output |
|---|---|
| stdout | startup banner/prompt, model text, tool-use summary, tool-result `ok/error`, newline |
| stderr | construction/file errors, permission/tool question이 아닌 `runTurn` iterator errors |
| stdin | REPL lines, permission y/yes prompt, structured question selection |

permission과 AskUser UI 자체는 stdout에 쓰고 stdin을 별도 `bufio.Reader`로 읽는다. REPL은 stdin을 `Scanner`로도 읽으므로 같은 stream의 buffered readers를 섞는 host pattern에 주의해야 한다.

<a id="termination"></a>

## signal, EOF와 exit status

- `signal.NotifyContext`가 `SIGINT`와 `SIGTERM`을 취소 context로 바꾼다. 별도 signal-specific exit code는 설정하지 않는다.
- interactive `Ctrl-D`/EOF는 scanner가 끝나 newline을 stdout에 쓰고 main이 정상 return한다. `/exit`, `/quit`도 정상 return한다. `/reset`은 in-memory conversation/usage만 지운다.
- one-shot도 `runTurn` 뒤 무조건 main return이다.
- `runTurn`은 iterator의 non-nil error를 stderr에 `[error: ...]`로 쓰고 return할 뿐 main에 error를 반환하지 않는다. 따라서 prompt 실행 실패도 process가 **exit 0**일 수 있다.
- `KindResult.Terminal.Reason`과 `Terminal.Err`를 읽거나 exit status로 변환하지 않는다. `max_turns`, `timeout`, `model_error` 같은 terminal도 process 성공처럼 보일 수 있다.
- `Session.Close`를 defer하지 않아 normal exit cleanup은 process teardown에 의존한다. MCP client도 이 CLI는 만들지 않는다.

batch automation은 이 demo exit code를 success oracle로 쓰면 안 된다. `Session.Prompt` result event를 직접 소비하고 업무 성공 조건과 exit mapping을 가진 host를 작성해야 한다. [event 근거](evidence:harness-event) [Prompt 근거](evidence:agentcore-prompt)