도구, 권한과 외부 효과

상위 경로: Norma 시스템 지도 → 기능 지도 → Tool action

CoreTool은 이름·설명·prompt·input schema, read-only/concurrency 판정, 자체 permission decision과 Call을 제공한다. tool.Build에서 생략한 보안 metadata는 mutating, exclusive, approval-required로 닫힌다. registry의 duplicate name은 교체이고, schema를 provider에 노출하는 목록과 name lookup 실행 경로는 별도다. tool 근거 registry 근거

Direct tool call의 실행 순서

Direct tool call의 실행 순서 · 관계

이 대상이 사용하는 구현·계약·의존 · 4개

구현 담당 · tool, permission, hook · · harness-tools · permission
계약 사용 · Tool interface와 input schema · · tool-contract
계약 사용 · Permission 계약 · · permission
계약 사용 · 정적 catalog 30개 · 실행 전 정적 tool catalog, metadata와 install 조건을 확인 · tool-defaults · tool-optional

전체 관계 4개 · 종류 선택·관계도

그림 크게 보기

Mermaid 원문

flowchart TD
  U[tool_use name + raw input] --> R{registry lookup}
  R -->|missing| ER[error tool_result]
  R -->|found| S{schema validation}
  S -->|fail| ER
  S -->|pass or RawInput| P[permission Evaluate]
  P -->|deny| ER
  P -->|allow + optional input rewrite| H[PreToolUse hooks]
  H -->|block| ER
  H -->|last input rewrite| C[CoreTool.Call]
  C --> O[global output cap/spill]
  O --> PH[PostToolUse hooks]
  PH --> RT[paired tool_result + optional Extra messages]

  click S "#schema-validation" "Schema validation"
  click P "#permission-stages" "Permission stages"
  click H "#hooks" "Hook 경계"
  click O "#output-capture" "Output 제한"

permission callback이 UpdatedInput을 반환하면 그 값을 PreToolUse에 보낸다. PreToolUse가 다시 input을 바꿀 수 있지만 schema와 permission을 재실행하지 않는다. 따라서 hook은 이미 승인된 capability보다 넓은 resource/command로 rewrite하지 않아야 한다. 실행 근거

Schema validation

중앙 validator는 object의 required와 string/number/integer/boolean/array/object 같은 기본 JSON type을 검사한다. enum, numeric bounds, pattern, additionalProperties를 포함한 전체 JSON Schema 구현은 아니다. required를 []any로 작성한 built-in schema와 달리 다른 Go 표현은 검사에서 누락될 수 있다. RawInput tool은 model 안내용 schema를 계속 노출하지만 중앙 validation을 건너뛰고 자체 parser가 책임진다. schema 근거

Permission stages

1. DisallowedTools name rule 또는 tool hard-deny → deny
2. bypass → allow / plan + mutating → deny / plan + read-only → allow
3. AllowedTools, acceptEdits file edit, read-only, tool self-allow → allow
4. dontAsk/auto → deny, 그 밖에는 CanUseTool callback 또는 deny

rule match는 *, exact name, Name(...)의 name 부분만 본다. argument, path, host, URL, tenant를 평가하지 않는다. ModeBypass도 explicit deny rule과 tool hard-deny를 넘지 못한다. ModeAuto는 tool 자체 allow를 인정하지만 approval-required action을 묻지 않고 거부한다. permission 근거

Hook 경계

Hook 경계 · 관계

이 대상이 사용하는 구현·계약·의존 · 1개

구현 담당 · tool, permission, hook · · hooks

전체 관계 1개 · 종류 선택·관계도

hook.Registry는 PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStart를 선언한다. callback은 등록 순서로 실행하며 PreToolUse의 첫 block이 중단하고 마지막 non-empty rewrite가 이긴다. Stop은 hard prevent와 blocking continuation을 구분한다. hook 근거

현재 SessionStart, UserPromptSubmit, tool hooks, Stop, SubagentStart 호출은 확인했지만 SessionEnd의 agentcore 호출처는 확인되지 않았다. callback timeout·panic recovery·thread safety도 제공하지 않는다. hook은 audit trail이나 외부 policy broker를 자동 구성하지 않는다.

기본·선택 도구의 capability 경계

기본·선택 도구의 capability 경계 · 관계

이 대상이 사용하는 구현·계약·의존 · 1개

구현 담당 · tool, permission, hook · · tool-defaults

전체 관계 1개 · 종류 선택·관계도

아래는 도구군 요약이다. 30개 정적 이름의 설치 조건, read-only/concurrency/permission metadata와 effect는 Tool 전수 색인에 있다.

도구군	설치 조건	외부 효과와 핵심 경계
Read/Write/Edit/MultiEdit/LS/Glob/Grep/Bash	`Tools == nil` 기본	WorkingDir 기반 편의 처리이며 path sandbox가 아님
TaskOutput/TaskStop/TaskList/Monitor	background disable이 아니면 자동 추가	session temp file/process와 notification; Prompt 종료 뒤에도 process 가능
PTY shell five tools	host가 `ShellSessionTools()` 추가	persistent process/TTY; Bash deny parser를 공유하지 않음
WebFetch	option	redirect/DNS/IP allowlist 없음; proxy 실패 시 direct-intended fallback, default transport가 환경 proxy를 재상속할 수 있음
WebSearch	option과 backend config	provider endpoint로 outbound; query target scope 없음
Todo/AskUser	store/callback option	in-memory state 또는 host interaction
plan/memory/skill/deferred	해당 option	mode/file/instruction/unlock 상태 변경

Bash는 일부 command deny pattern, foreground timeout과 background 전환을 제공하지만 command sandbox, egress, credential isolation은 아니다. Task manager path에는 SessionID가 들어가므로 host가 trusted identifier를 제공해야 한다. Session.Close는 task manager cleanup을 호출한다. Bash 근거 task 근거 PTY 근거

Tool output 제한

모든 direct tool result의 text block은 execOne의 공통 capOutput을 거친다. 기본 head cap은 30,000 characters다. ToolOutputDir가 있으면 full output을 파일에 쓰고 model에는 head와 pointer를 주며, 없으면 잘린 marker를 준다. 이미 marker가 있는 값은 idempotent하게 다시 처리하지 않는다. capture 근거

spill file은 편의상 원문을 보존하지만 evidence store는 아니다. integrity digest, action provenance, retention, encryption과 atomic coupling이 없고 marker-like 원문은 이미 처리된 값으로 오인될 수 있다.

Deferred tool의 노출과 실행

Deferred tool의 노출과 실행 · 관계

이 대상이 사용하는 구현·계약·의존 · 1개

구현 담당 · tool, permission, hook · · deferred-tools

전체 관계 1개 · 종류 선택·관계도

DeferredTools가 있으면 provider schema에서 이름들을 숨기고 SearchExtraTools, ExecuteExtraTool을 추가한다. UnlockSet은 wrapper가 실제 inner name을 호출할지 결정한다. deferred 근거

숨긴 schema는 original registry에 남아 있어 model/provider가 name을 직접 만들면 direct execOne으로 실행될 수 있다.
ExecuteExtraTool wrapper의 permission/hook는 적용되지만 inner tool의 CheckPermissions와 inner name hook는 다시 호출되지 않는다.
skill invocation이 unlock set을 바꿀 수 있으나 일반 resume은 그 상태를 durable하게 복원하지 않는다.
subagent가 parent registry를 공유하면 parent의 schema filter 설정은 별도로 상속되지 않는다.

따라서 deferred 기능은 context 절약/UX primitive이며 capability admission 경계로 단독 사용하면 안 된다.

Web, search와 MCP outbound

WebFetch는 optional proxy/CA/insecure TLS를 지원하고 response cap과 HTML-to-text 변환을 수행한다. configured proxy request가 실패하면 direct-intended client로 fallback해 recording/scope 경계를 이탈할 수 있다. InsecureTLS=false인 fallback client는 nil Transport라 proxy environment를 다시 상속할 수 있으므로 실제 direct 연결도 보장하지 않는다. redirect마다 scope를 재검사하거나 DNS/IP를 pin하지 않는다. WebFetch 근거

WebSearch는 ddgs, brave-free, tavily, deepseek backend를 조립한다. 잘못된 설정은 NewSession에서 오류나 warning 없이 tool 생략으로 이어진다. WebSearchProbe 같은 host helper는 agent permission pipeline 밖에서 직접 호출할 수 있다. WebSearch 근거

MCP stdio child는 host environment로 실행되고 tool을 Norma registry에 감싼다. MCP와 web 모두 host-owned egress broker, endpoint allowlist, request/response evidence capture가 있어야 승인된 target 범위를 강제할 수 있다. HTTP method/header/result/retry/timeout과 MCP method별 fidelity는 소비 operation 계약에 있다. MCP 상세

이동한 문서 주소

등록된 주소만 자동 이동합니다. 아래에서 새 위치를 선택할 수 있습니다.

상위 영역: 기능 지도

전체로 돌아가기 · Markdown 원본