# Tool 이름·설치·효과 참조

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

이 표는 production source가 정적으로 제공하는 **30개 runtime tool 이름**을 constructor/registry 경로에서 전부 열거한다. `RO`와 `C`는 각각 `IsReadOnly({})`, `IsConcurrencySafe({})`, `self`는 `CheckPermissions({})`의 자체 판정이다. 실제 허용 여부는 deny rule·permission mode·allow rule을 앞뒤로 적용한 [permission pipeline](../runtime/tools-and-permissions.md#permission-stages)이 결정한다. 인자에 따라 hard deny하는 Bash 계열 같은 예외는 “효과/실패”에 적었다.

<a id="static-tools"></a>

## 정적 catalog 30개

| # | tool name | 설치 조건 | RO | C | self | 효과와 실패 경계 | source |
|---:|---|---|:---:|:---:|---|---|---|
| 1 | `Read` | `Options.Tools == nil` 기본 | Y | Y | allow | 파일 일부/전체 읽기; WorkingDir는 sandbox가 아니며 output cap 적용 | [근거](evidence:api-tool-files) |
| 2 | `Write` | 기본 | N | N | ask | 파일 생성/덮어쓰기; parent dir 생성, path 격리 없음 | [근거](evidence:api-tool-files) |
| 3 | `Edit` | 기본 | N | N | ask | exact old-text 교체; 불일치/복수 match는 error result | [근거](evidence:api-tool-files) |
| 4 | `MultiEdit` | 기본 | N | N | ask | 한 파일에 순차 edit; 중간 오류의 transaction rollback 없음 | [근거](evidence:api-tool-multiedit) |
| 5 | `LS` | 기본 | Y | Y | allow | 디렉터리 목록; host filesystem을 그대로 봄 | [근거](evidence:api-tool-ls) |
| 6 | `Glob` | 기본 | Y | Y | allow | path pattern 열거; symlink/absolute 경계가 sandbox는 아님 | [근거](evidence:api-tool-search) |
| 7 | `Grep` | 기본 | Y | Y | allow | metadata상 읽기 전용이지만 첫 `RipgrepPath`가 `rg` 부재 시 exact `npm install -g @vscode/ripgrep`을 실행할 수 있음; 실패하면 pure-Go 검색 | [근거](evidence:ripgrep-bootstrap) |
| 8 | `Bash` | 기본 | N | N | ask | shell command/선택적 background process; catastrophic pattern은 hard deny하지만 sandbox/egress는 없음 | [근거](evidence:api-tool-bash) |
| 9 | `sleep` | 기본, 이름은 소문자 | Y | Y | allow | context-aware 대기; duration parse/상한 규칙 위반은 error result | [근거](evidence:api-tool-sleep) |
| 10 | `TaskOutput` | background가 global/per-session disable이 아니고 manager 생성 성공 | Y | Y | allow | task output tail 읽기, 선택적 block | [근거](evidence:api-tool-taskoutput) |
| 11 | `TaskStop` | 같은 조건 | N | N | allow | 한 task 또는 전부의 process tree 중단 | [근거](evidence:api-tool-taskstop) |
| 12 | `TaskList` | 같은 조건 | Y | Y | allow | current session task 상태 열거 | [근거](evidence:api-tool-tasklist) |
| 13 | `Monitor` | 같은 조건 | N | N | ask | long-running command spawn·notification; Bash hard-deny self-check 재사용 | [근거](evidence:api-tool-monitor) |
| 14 | `shell_open` | host가 `ShellSessionTools()` 추가 + background manager 사용 가능 + global PTY 미차단 | N | N | allow | persistent PTY process 시작; Bash deny parser는 거치지 않음 | [근거](evidence:api-tool-shell-tools) |
| 15 | `shell_send` | 같은 조건 | N | N | allow | PTY byte/key/paste 입력, 선택적 wait | [근거](evidence:api-tool-shell-tools) |
| 16 | `shell_read` | 같은 조건 | Y | N | allow | stream cursor 또는 VT screen 읽기; cursor state를 변경해 concurrency false | [근거](evidence:api-tool-shell-tools) |
| 17 | `shell_close` | 같은 조건 | N | N | allow | PTY kill·registry 제거 | [근거](evidence:api-tool-shell-tools) |
| 18 | `shell_list` | 같은 조건 | Y | N | allow | PTY session 목록; manager lock 사용 | [근거](evidence:api-tool-shell-tools) |
| 19 | `WebFetch` | `EnableWebFetch` 또는 host 직접 추가 | N | N | ask | GET/redirect/HTML 변환; 30s, 2 MiB read cap, 50k output cap, proxy 오류 direct-intended fallback(환경 proxy 재상속 가능) | [근거](evidence:webfetch-runner) |
| 20 | `web_search` | `EnableWebSearch`+유효 backend 또는 host 직접 추가 | Y | Y | ask | provider outbound search; 기본 5/최대 20 results, 30s(DeepSeek 120s) | [근거](evidence:websearch-operations) |
| 21 | `TodoWrite` | `Options.Todos != nil` | N | N | allow | in-memory todo 전체 교체 | [근거](evidence:api-tool-todo) |
| 22 | `AskUserQuestion` | `Options.AskUser != nil` | N | N | allow | 동기 host callback; blocking이어서 exclusive | [근거](evidence:api-tool-ask) |
| 23 | `SearchExtraTools` | `DeferredTools` non-empty | Y | N | allow | 숨긴 registry metadata 검색/선택; capability gate가 아님 | [근거](evidence:deferred-tools) |
| 24 | `ExecuteExtraTool` | `DeferredTools` non-empty | N | N | allow | unlock 확인 뒤 inner `Call` 직접 수행; inner permission/hook 재실행 없음 | [근거](evidence:deferred-tools) |
| 25 | `EnterPlanMode` | `Options.Plan != nil` | Y | N | allow | controller mode를 plan으로 변경; state mutation이지만 plan에서 호출하도록 RO=true | [근거](evidence:plan) |
| 26 | `ExitPlanMode` | `Options.Plan != nil` | Y | N | allow | approver 호출·승인 시 target mode 변경 | [근거](evidence:plan) |
| 27 | `RecallMemory` | `Memory.Store != nil` | Y | Y | allow | 관련 memory 최대 5개 읽기 | [근거](evidence:api-memory-tools) |
| 28 | `RecordMemory` | `Memory.Store != nil` | N | N | allow | markdown memory 저장·index rebuild | [근거](evidence:api-memory-tools) |
| 29 | `Skill` | `Options.Skills != nil` | Y | N | allow | skill instructions를 별도 user guidance로 주입하고 optional `OnInvoke` 실행 | [근거](evidence:skills) |
| 30 | `Agent` | host가 `subagent.NewTool` 또는 coordinator tool 추가 | N | N | allow | child harness를 동기 실행; 자체 call은 allow지만 child tool permission은 별도 | [근거](evidence:subagent) |

[기본 9개 근거](evidence:tool-defaults) [선택 도구 근거](evidence:tool-optional) [background 근거](evidence:background-tasks) [PTY 근거](evidence:shell-tools)

`Grep`의 `RO=Y`, `C=Y`, `self=allow`는 등록 metadata 값일 뿐 첫 실행의 숨은 설치 효과를 나타내지 않는다. `rg`가 `PATH`에 없고 `NORMA_DISABLE_RIPGREP`와 `NORMA_RIPGREP_NO_INSTALL`도 비어 있으면 process-wide `sync.Once` 안에서 npm의 global prefix와 network를 사용할 수 있다. 자세한 trigger와 fallback은 [Grep bootstrap operation](external-operations.md#grep-bootstrap)을 확인한다. [구현 근거](evidence:ripgrep-bootstrap)

<a id="noa-compress"></a>

## Adapter가 추가하는 내부 runtime tool

`noaadapter.Enable*`은 위 30개 catalog와 별도로 `Compress`를 registry에 설치한다. private constructor라 host-facing 정적 constructor catalog에는 포함하지 않았지만 model-visible tool이다. `RO=N`, `C=N`, `self=allow`, `RawInput=true`이며 Noa state를 바꾸고 archive를 쓴다. malformed JSON을 자체 복구하려고 중앙 schema validation을 건너뛴다. [Noa 설치](evidence:noa-enable) [Compress tool](evidence:noa-tool)

<a id="dynamic-tools"></a>

## 동적 MCP와 host tool

정적 30개는 runtime 전체 개수의 상한이 아니다.

| 공급자 | 이름/수 | metadata 기본 | 효과 경계 |
|---|---|---|---|
| remote stdio MCP | `mcp__<server>__<remote-name>`, `tools/list` 결과만큼 | fail-closed `RO=N`, `C=N`, self ask | `tools/call`; text만 보존, resource/image/structured content 손실 |
| in-process MCP | `mcp__<server>__<name>`, host slice만큼 | `RO=N`, `C=N`, self ask | 임의 host handler |
| host `tool.Build` / `CoreTool` | 임의 이름·수 | 생략하면 `RO=N`, `C=N`, self ask | host 구현이 선언과 실제 effect를 일치시켜야 함 |
| registry duplicate | 새 개수가 아니라 같은 이름 교체 | 마지막 등록 객체 | constructor catalog와 실제 session object가 달라질 수 있음 |

MCP/host tool은 이름이 동적으로 결정되므로 정적 30개 분모와 섞지 않는다. 정책은 이름 catalog가 아니라 실행 직전 resource/argument를 평가해야 한다. [MCP 근거](evidence:mcp-tools) [CoreTool 근거](evidence:tool-contract)

<a id="methodology"></a>

## inventory 산출 방식

고정 revision의 production(non-test) Go에서 `DefaultTools`, exported optional constructors, agentcore 자동 주입, plan/memory/skill/subagent constructors를 추적했다. 30개 객체를 실제 구성해 빈 object 입력에 대한 세 metadata method를 호출했고, input-dependent deny/effect는 runner source로 보완했다. `Compress`는 private adapter constructor, MCP/host는 runtime-derived이므로 별도 구획으로 유지했다.