플러그인 권한

플러그인은 이용자의 파일과 네트워크에 접근할 수 있는 일반 프로그램으로 실행됩니다. Agentty는 이를 샌드박스에 가두지 않습니다. 대신 프롬프트 전송, 터미널 입력, 대화 읽기처럼 민감한 기능을 명시적으로 선언하게 하고, 설치 전에 이용자에게 보여줍니다.

네 가지 권한#

권한 없이 호출하면 -32001 오류로 실패합니다. 플러그인 페이지는 설치 전 카드와 설치 후 카드 양쪽에 선언된 권한을 표시합니다.

권한이 없을 때 플러그인이 보는 것#

컨텍스트는 선언한 권한에 따라 걸러집니다. workspace.read가 없으면 폴더와 제목 필드가 제거되고, session.read가 없으면 세션 id가 제거됩니다. 남는 것은 id, kind, tool, status, running, 언어입니다. 어느 페인이 포커스됐고 작업 중인지는 알 수 있지만, 어디서 무엇을 하는지는 알 수 없습니다.

{
  "pane": { "id": 12, "kind": "claude", "tool": "claude", "status": "working", "running": true },
  "language": "ko"
}

다이얼로그가 경계입니다#

target: "ask"로 prompt.inject를 호출하면 **보낼 곳…**이 열립니다. 이용자가 텍스트를 보고 에이전트와 목적지를 고르며, 보내기를 누르기 전에는 아무 일도 일어나지 않습니다. 다른 target은 이 다이얼로그를 건너뛰므로, 외부 입력을 받아 동작하는 플러그인은 항상 ask를 써야 합니다.

injectPrompt는 터미널에서 Enter를 대신 누르지 않습니다. 텍스트를 입력해 두고 이용자에게 맡깁니다.

링크는 신뢰하지 않습니다#

agentty:// 링크는 웹페이지를 포함해 어디서든 올 수 있습니다. 링크가 플러그인에 도달한 뒤 1분 동안 Agentty는

• 그 플러그인의 injectPrompt를 target과 무관하게 **보낼 곳…**으로 돌리고,
• sendToTerminal을 아예 거부합니다.

링크가 연 패널에서 클릭해도 이 제한은 풀리지 않습니다. 링크 한 번이 터미널 입력으로 바뀌는 일은 일어나지 않습니다.

작성 규칙#

• 쓰는 권한만 요청하세요. 모든 권한이 이용자에게 표시되며, 쓰지 않는 권한은 신뢰만 깎아먹습니다.
• 자격 증명을 읽거나 보내지 마세요. 다른 앱의 설정을 읽는다면 필요한 필드만 가져오세요. Cosmica 플러그인은 notes.path와 로컬 포트만 읽습니다.
• 데이터는 AGENTTY_PLUGIN_DATA에 두세요. 다른 앱이 읽는 파일은 조심해서 만들고, 이용자의 파일을 요청 없이 덮어쓰지 마세요.
• 127.0.0.1하고만 통신하세요. 이용자가 직접 다른 엔드포인트를 설정한 경우가 아니라면요.
• 입력 전에 pane.status를 확인하세요. working, permission, question 상태는 방해하면 안 됩니다.
• 외부에서 온 것은 무엇이든 검증하세요. 링크든 파일이든 서버 응답이든 그대로 믿고 동작하지 마세요.

레이트 리밋과 폭주 방지#

Agentty는 실수든 아니든 잘못 동작하는 플러그인으로부터 자신을 보호합니다.

남의 플러그인을 설치하기 전에#

• 카드의 권한을 읽으세요. 노트 플러그인이 terminal.write를 요구한다면 그 이유가 설명돼 있어야 합니다.
• 소스를 읽을 수 있는 플러그인을 선호하세요. 카드의 links가 대개 저장소를 가리킵니다.
• 설치 후 로그를 보면 플러그인이 실제로 무엇을 출력하는지 빠르게 확인할 수 있습니다.
• 비활성화는 즉시 적용되고, 삭제는 플러그인을 제거합니다. 데이터 폴더는 직접 지울 때까지 남습니다.