실행 도구 (Exec)

개요

exec 도구는 에이전트가 셸 명령어를 실행할 수 있게 한다. 포그라운드 실행과 process를 통한 백그라운드 실행을 지원하며, 승인 모드와 허용 목록으로 보안을 관리한다.

실행 방식

포그라운드 실행

명령어를 실행하고 완료될 때까지 대기한다. 기본 타임아웃은 **1800초(30분)**이다.

exec("ls -la /tmp")

백그라운드 실행

process 도구를 통해 장시간 실행되는 명령어를 백그라운드에서 처리한다.

process.start("npm run build")
process.status("pid-123")
process.kill("pid-123")

실행 호스트

명령어가 실행되는 환경을 지정한다.

{
  "tools": {
    "exec": {
      "host": "sandbox",
      "timeout": 1800
    }
  }
}

승인 모드

명령어 실행 전 승인을 요구하는 수준을 설정한다.

on-miss (기본값)

허용 목록(allowlist)에 등록된 명령어는 승인 없이 실행되고, 등록되지 않은 명령어는 사용자에게 승인을 요청한다.

{
  "tools": {
    "exec": {
      "approvalMode": "on-miss",
      "allowlist": [
        "ls", "cat", "head", "tail", "grep",
        "git status", "git log", "git diff",
        "node", "npm", "npx",
        "python", "pip"
      ]
    }
  }
}

허용 목록 (Allowlist)

허용 목록은 해석된 바이너리 경로를 기준으로 검증한다. 심볼릭 링크나 별칭(alias)이 아닌 실제 바이너리 경로로 확인한다.

"ls" → /bin/ls (허용)
"my-alias" → /usr/local/bin/dangerous-tool (차단)

보안

환경 변수 차단

다음 환경 변수의 오버라이드가 차단된다.

PATH 확장

차단 대신 pathPrepend를 사용하여 안전하게 PATH를 확장할 수 있다.

{
  "tools": {
    "exec": {
      "pathPrepend": ["/usr/local/custom/bin"]
    }
  }
}

추가 설정

strictInlineEval

인라인 코드 실행(eval, backtick 등)을 엄격하게 제한한다.

{
  "tools": {
    "exec": {
      "strictInlineEval": true
    }
  }
}

활성화하면 $(...), `...`, eval 등의 인라인 실행을 차단하여 명령어 인젝션을 방지한다.

실행 흐름

[에이전트가 exec 요청]
        │
        ▼
  승인 모드 확인
        │
   ┌────┴────┐
   │         │
  off      on-miss / always
   │         │
   │    허용목록 확인
   │    ┌────┴────┐
   │    │         │
   │   허용      미등록
   │    │         │
   │    │    사용자 승인 요청
   │    │    ┌────┴────┐
   │    │    │         │
   │    │   승인       거부
   │    │    │         │
   ▼    ▼    ▼         ▼
  실행  실행  실행     중단