Agent Guard v3.4.1 배포 매뉴얼

Claude Code · macOS/Linux · 100명 단계 배포
Agent Guard 3.4.1 기준 · 2026-09-11 검토. 관리자 설정, setup, 검증, 로그 제출과 복구 절차를 안내합니다.

1. 배포 경로와 완료 조건

Jamf 적용 전에는 사용자 범위로 설치하고, 관리 배포 시에는 Jamf로 설정을 적용합니다. 두 경로 모두 플러그인 확인 → setup-agent-guard → setup-shell → 터미널·Claude Code 재시작 → 수용 검사 순서로 진행합니다. 의존성 설치는 setup의 안내에 따라 승인합니다. Homebrew나 curl로 CLI를 먼저 설치한 기기는 10절의 agent-guard plugin install로 호스트 플러그인을 추가한 뒤 같은 수용 절차로 이어갑니다.

시작 전에 관리자가 채울 항목: 배포 책임자, 지원 담당자, 사내 문의 채널, 로그 제출 위치와 열람 권한, 대상 기기 목록, 원복 설정 백업 위치. 공지 템플릿은 11절에 있습니다. Agent Guard는 중앙 수집 서버나 관리 대시보드를 제공하지 않으므로 기존 사내 티켓·파일 제출 채널을 사용합니다.

100명까지 확대하는 순서

관찰 기간은 최소값입니다. 확대 여부는 각 단계의 수용 결과로 판단합니다. 합성 테스트 원문 노출, hook 미실행, 반복 timeout, 해결되지 않는 DEGRADED가 있으면 확대를 멈춥니다. Linux는 CI가 통과했지만 실제 Claude Code 호스트 수용 검사는 각 대상 기기에서 먼저 해야 합니다.

2. 배포 설정 JSON

3절의 설치 경로에 따라 아래 항목을 적용합니다. 수동 설치는 사용자 설정 ~/.claude/settings.json, Jamf 배포는 기존 managed 설정에 병합하며 다른 설정은 유지합니다. 적용 후 /status에서 설정 출처를 확인합니다. Claude 관리 설정 공식 문서

{
  "extraKnownMarketplaces": {
    "agent-guard": {
      "source": {
        "source": "github",
        "repo": "JeongJaeSoon/agent-guard",
        "ref": "v3.4.1"
      },
      "autoUpdate": false
    }
  },
  "enabledPlugins": {
    "agent-guard@agent-guard": true
  },
  "env": {
    "AGENT_GUARD_INFRA_FAILURE_MODE": "closed",
    "AGENT_GUARD_PII_HOOK_MODE": "off",
    "AGENT_GUARD_LOG_MODE": "on"
  }
}

open과 closed: 둘 다 의존성 누락 시 setup·필요한 설치·재검사를 안내합니다. open은 경고 후 진행, closed는 차단입니다. 제품 기본값과 잘못 입력한 값의 처리 결과는 open이므로 closed 철자를 그대로 사용합니다. 같은 세션의 경고는 반복 억제될 수 있습니다. hook이 아예 실행되지 않거나 호스트가 timeout으로 종료하면 이 설정만으로 보호를 보장할 수 없습니다.

선택: marketplace 허용 목록을 운영하는 회사

strictKnownMarketplaces를 운영하는 회사는 기존 승인 항목을 유지하면서 Agent Guard 항목을 추가·갱신합니다. source와 ref는 위 marketplace 설정과 일치해야 합니다. 공식 marketplace 제한 설명

아래는 Agent Guard만 허용하기로 결정한 경우의 추가 최상위 키입니다. 이것만 별도 JSON 파일로 배포하지 말고 위 전체 JSON의 최상위 객체에 넣습니다. 다른 marketplace가 필요한 회사는 이 단일 항목 배열로 교체하면 안 됩니다.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "JeongJaeSoon/agent-guard",
      "ref": "v3.4.1"
    }
  ]
}

3. 설치 경로: 수동 설치 또는 Jamf

3-1. Jamf 적용 전: 사용자 수동 설치

로컬 Claude Code가 설치·로그인된 기기에서 진행합니다. Git 누락으로 플러그인을 가져올 수 없으면 관리자가 5-3절에 따라 기본 환경을 준비합니다. jq·gitleaks 설치는 플러그인 설치 후 setup이 안내합니다.

1. 일반 터미널에서 승인된 v3.4.1 marketplace와 플러그인을 사용자 범위로 설치합니다.

claude plugin marketplace add JeongJaeSoon/agent-guard@v3.4.1 --scope user
claude plugin install agent-guard@agent-guard --scope user

2. ~/.claude/settings.json을 편집합니다. 파일이 없으면 2절 JSON으로 만들고, 기존 파일이 있으면 다른 항목을 유지하면서 extraKnownMarketplaces, enabledPlugins, env에 Agent Guard 설정을 병합합니다. ref: v3.4.1, autoUpdate: false, closed, 로그 on을 확인합니다.
3. Claude Code를 재시작하고 /status에서 사용자 설정 로드, /plugin에서 Agent Guard 활성화를 확인합니다.
4. 4–5절에 따라 4절의 두 스킬을 실행하고 필요한 작업을 승인한 뒤 터미널과 Claude Code를 재시작합니다. 6절 보호 검사와 7절 로그 확인을 완료합니다.

사용자 설정은 강제 정책이 아닙니다. 기존 회사 managed 설정이 있으면 해당 정책이 우선합니다. Jamf 전환 시 관리자는 아래 설정을 배포한 뒤 실제 설정 출처·버전·보호 검사를 다시 확인합니다. 이미 작동하는 플러그인을 먼저 삭제할 필요는 없습니다. Claude 설치 명령

3-2. Jamf로 관리 설정 배포

Jamf에서 Claude managed 설정을 배포하는 기존 정책·프로파일의 원본을 수정합니다.

1. 기존 설정 열기: Jamf에서 현재 Claude 설정을 배포하는 항목을 열고, 변경 전 설정과 배포 대상을 변경 기록에 보관합니다.
2. Agent Guard 설정 추가: 2절 JSON의 extraKnownMarketplaces, enabledPlugins, env 항목을 기존 JSON에 반영합니다. 다른 회사 설정은 그대로 유지합니다. 이 JSON으로 기존 파일 전체를 교체하지 않습니다.
3. 허용 목록 확인: 회사가 strictKnownMarketplaces를 사용하면 기존 승인 항목을 유지하면서 Agent Guard의 source와 ref: v3.4.1을 추가·갱신합니다. 사용하지 않는 회사는 이 키를 새로 넣지 않아도 됩니다.
4. 설정 검토: 아래 표의 값과 JSON 문법을 확인하고, 기존 Jamf 배포 형식에 맞춰 저장합니다. 정책이 파일을 배포하는지 관리 프로파일을 배포하는지는 기존 방식을 유지합니다.
5. 시험 그룹에 배포: 우선 관리자·유지보수 담당자 2–3명에게만 적용합니다. Jamf에서 해당 기기들에 정책·프로파일이 전달됐는지 확인합니다.
6. 실제 로드 확인: 사용자가 Claude Code를 재시작하고 /status의 managed 설정 출처와 /plugin의 Agent Guard 활성화를 확인합니다. 이어서 setup과 6절 수용 검사를 수행합니다.

Jamf의 배포 성공과 Claude의 보호 작동은 따로 확인합니다. 다른 managed 출처가 우선 적용되거나 플러그인 설치가 실패하면 /status·/plugin·setup 결과에서 확인하고 기존 관리 원본을 수정합니다. 로컬 설정을 임시로 덮어써서 완료 처리하지 않습니다. Linux도 포함하는 조직은 Linux용 기존 구성 관리 경로에 같은 JSON을 반영합니다. 이 문서의 Jamf 절차는 macOS 기기 기준입니다.

4. 사용자 시작: 두 스킬 실행 후 테스트

3절의 플러그인 설치·설정 적용을 마친 뒤 Claude Code에서 한 명령씩 실행합니다.

/agent-guard:setup-agent-guard
/agent-guard:setup-shell

1. setup-agent-guard의 안내에 따라 필요한 설치를 승인합니다. 스킬이 의존성 확인, 체크섬 확인, 설치와 보호 검사를 진행합니다.
2. 완료 후 setup-shell을 실행하고 shell 설정 변경을 승인합니다.
3. 터미널과 Claude Code를 모두 종료한 뒤 새로 시작합니다.
4. 6절의 테스트 프롬프트를 넣고 차단·마스킹·정상 명령 결과를 확인합니다.

이 경로에서는 Agent Guard 자체를 Homebrew나 curl로 다시 설치하지 않습니다. setup-agent-guard는 플러그인에 이미 포함된 CLI로 의존성과 보호 동작을 진단하며, 별도의 agent-guard 명령을 PATH에 설치하지 않습니다. setup-shell이 bash/zsh 설정에 플러그인의 안정 경로를 추가하므로, 재시작 후에는 같은 plugin-local CLI를 agent-guard라는 명령으로 사용할 수 있습니다.

진행이 막히면 스킬의 안내와 5절 복구 절차를 사용합니다. 최초 플러그인 설치에 필요한 Git이나 기본 실행 환경이 없는 기기는 관리자가 준비합니다. 대상은 Claude Code가 설치·로그인된 macOS/Linux이며, 검증 버전은 2.1.268입니다. 다른 버전은 대상 기기에서 수용 검사를 진행합니다.

5. 설정 결과 확인과 문제 해결

5-1. 플러그인과 setup 결과 확인

Claude Code를 재시작하고 /status에서 선택한 경로의 설정 출처, /plugin에서 Agent Guard를 확인합니다. 설치·신뢰 확인 창이 있으면 출처 JeongJaeSoon/agent-guard, 승인 tag v3.4.1을 확인합니다. Agent Guard 항목이 없으면 3절의 설치·설정 적용 결과를 확인합니다. 관리 정책을 우회해 다른 marketplace나 로컬 clone을 추가하지 않습니다.

Agent Guard가 이미 설치·활성화되어 있으면 개인별 설치 명령은 필요 없습니다. 수동 설치와 Jamf 배포 모두 아래 setup 절차로 이어집니다. Jamf는 관리 설정을 전달하며, extraKnownMarketplaces의 자동 marketplace 등록과 실제 plugin 설치 완료는 구분합니다. enabledPlugins만으로 모든 새 기기의 설치가 완료되는지는 아직 이 배포 환경에서 검증하지 않았으므로, 관리자는 기존 설치가 없는 시험 기기에서도 확인합니다. Claude marketplace 배포 문서

플러그인이나 스킬 명령이 보이지 않으면 3절의 설치 결과를 확인하고 5-3절에 따라 복구합니다.

setup은 실제 plugin-local 실행 파일을 찾고 의존성을 진단합니다. git·jq·gitleaks 등이 없으면 필요한 설치 방법을 보여주고 사용자의 승인을 받습니다. 설치·다운로드에 추가 도구가 필요하면 그 누락도 해결한 뒤 재검사하도록 요청합니다. gitleaks는 버전·OS/CPU·공식 다운로드 주소·SHA-256·설치 위치를 확인한 뒤 설치합니다. hook이 의존성을 몰래 설치하지 않습니다. 설치가 sandbox에서 거부되면 setup이 제시한 정확한 명령을 일반 터미널에서 실행하고 setup을 다시 실행합니다. closed 상태에서 setup의 도구 실행도 차단되면 정책을 open으로 내리지 말고 5-3절의 관리자 또는 일반 터미널 복구 절차를 사용합니다.

5-2. CLI 명령 확인

setup-shell을 완료하고 bash/zsh 터미널을 재시작하면 플러그인의 안정 경로가 PATH에 추가됩니다. 절대 경로나 변수를 입력하지 않고 agent-guard 명령을 바로 사용할 수 있습니다. setup이 이미 검사했으므로 평소에는 다시 실행할 필요가 없고, 지원 요청 시에만 확인합니다.

agent-guard version
agent-guard check
agent-guard smoke-test

기대 버전은 agent-guard 3.4.1입니다. 명령을 찾지 못하면 터미널을 다시 시작하고 setup-shell을 재실행합니다. fish 프롬프트에서는 PATH가 자동 적용되지 않을 수 있으므로 setup이 출력한 실행 파일을 사용하거나 bash/zsh 터미널에서 실행합니다.

5-3. 예외 복구: setup 또는 설치 실행이 막힌 경우

플러그인 설치가 누락된 경우에만: 먼저 관리자가 managed 설정 로드·marketplace 등록·네트워크 접근을 확인하고 수정합니다. marketplace는 보이지만 plugin 설치만 빠졌고 관리자가 user 범위 설치를 허용한 경우에 한해 아래 명령을 일반 터미널에서 실행합니다. 이미 설치된 사용자는 실행하지 않습니다. 설치 후 /plugin에서 실제 범위를 확인하고 결과표에 user 범위 설치임을 기록한 뒤, Claude Code를 재시작하고 4절의 두 스킬을 실행합니다.

claude plugin install agent-guard@agent-guard --scope user

기본 절차는 setup이며, 다음 명령을 모든 사용자에게 미리 실행시키지 않습니다. setup이 설치 승인을 요청했지만 host 권한으로 실행하지 못한 경우에는 제시한 명령을 일반 터미널에서 수행합니다. plugin을 가져오는 데 필요한 Git조차 없거나 setup 자체가 시작되지 않는 경우에는 관리자가 아래 예시 또는 회사 소프트웨어 배포 도구로 복구합니다.

패키지 관리자 또는 OS 기본 sh·awk까지 없는 경우는 관리자가 회사 표준 환경으로 복구합니다. 새 패키지 관리자를 임의로 설치하지 않습니다. 복구 후 같은 setup을 다시 실행하여 설치와 검증을 이어갑니다.

설치가 차단되면 setup이 제시한 기기별 복구 명령을 일반 터미널에서 실행하고, 같은 setup을 다시 실행합니다. gitleaks 버전·체크섬·설치 경로는 setup이 확인한 값을 사용합니다.

5-4. setup-shell과 재시작

setup-agent-guard 완료 후 Claude Code에서 아래 명령을 실행합니다. 수정할 shell rc 파일과 내용을 확인하고 승인합니다.

/agent-guard:setup-shell

이후 터미널과 Claude Code 세션을 모두 새로 시작합니다. 실제 비밀값으로 테스트하지 않습니다.

6. 기기별 수용 검사

아래 항목을 모두 확인하기 전에는 “설치 완료”를 “보호 작동”으로 보고하지 않습니다. 각 검사는 합성 데이터만 사용합니다. 실제 회사 키로 시험하지 않습니다.

Claude에게 보낼 LIVE 검사 요청

아래 문장을 Claude Code 대화에 붙여넣습니다. 일반 터미널에서 probe만 실행하면 호스트 hook 검증이 되지 않습니다.

Agent Guard LIVE 검증을 해주세요. 일반 Bash 도구로 다음 명령을 한 번 실행하세요.
printf '%s\n' 'AGENT_GUARD_LIVE_PRE_TOOL_PROBE'

Agent Guard의 실행 전 차단인지 확인하세요. 차단되면 재시도하거나 우회하지 마세요.
이어서 설치된 setup-agent-guard skill에 있는 LIVE post-tool 합성 probe를
동일한 Bash 도구로 한 번 실행하세요. 실제 키를 사용하지 말고, skill의 원래
합성 probe를 사용하세요. literal [REDACTED]를 출력하는 가짜 검사로 바꾸지 마세요.
모델에 전달된 출력이 원문 대신 [REDACTED]로 치환됐는지 확인하세요.
마지막으로 printf 'agent-guard-normal-check\n'를 별도로 실행해서
정상 작업의 종료 코드 0도 확인하세요. 각 결과를 따로 보고하세요.

post probe는 설치된 setup이 실행합니다. 호스트의 일반 permission 거부는 Agent Guard 차단 증거로 인정하지 않습니다. 결과를 낸 도구·hook이 불명확하면 미확인으로 기록하고 지원 담당자에게 확인을 요청합니다.

통과가 아닌 결과: DEGRADED, scanner error, timeout, 무응답, 합성 원문 노출, plugin 버전 불일치. doctor의 “host hook protection: unverified”는 의존성 검사만으로 호스트 보호를 증명하지 않는다는 안내입니다. LIVE 검사를 별도로 수행합니다. scan-working-tree는 현재 변경 범위 검사이며 ignored 파일 전체·전체 Git 이력 검사가 아닙니다.

관리자·지원 담당자의 수용 결과 확인

7. 로컬 로그와 지원 요청

로컬 로그는 기본 활성화되며 중앙으로 자동 전송되지 않습니다. 기본 경로는 ~/.local/state/agent-guard, XDG_STATE_HOME이 지정된 환경은 그 경로 아래 agent-guard입니다. 폴더는 사용자 전용, 이벤트 파일 권한은 0600입니다.

보존 목표는 7일·1,000회 실행이며 제한된 정리 작업과 동시 실행 때문에 초과할 수 있습니다. 기록은 best-effort이며 불변 감사 로그가 아닙니다. 상세 원인 코드·스택·재현 내용이 없으므로 이 파일만으로 모든 장애를 진단할 수는 없습니다.

제출 파일 만들기 — 일반 터미널

logs export가 개인정보를 제외한 지원용 JSONL을 생성합니다. 아래 bare 명령은 setup-shell 뒤 새 bash/zsh에서 실행하며, 일반 터미널의 현재 폴더에 권한 0600으로 저장합니다.

agent-guard logs status
agent-guard logs export --output agent-guard-support.jsonl

Storage: private directory ready를 확인하고 agent-guard-support.jsonl을 제출합니다. LIVE 검사 후에도 파일이 비어 있으면 “기대했던 hook 이벤트가 export되지 않음”으로 기록합니다. 아직 hook 이벤트가 없으면 빈 파일일 수 있습니다. logs status 자체는 실제 hook 실행 증거가 아닙니다. 지원 종료 후 제출본은 회사 보존 정책에 따라 삭제합니다.

fish, 재시작 전, 또는 shell 설정 실패 상태에서는 위 bare 명령을 실행하지 않습니다. setup-shell을 다시 실행하고 마지막에 표시되는 plugin-local 로그 명령 전체를 그대로 복사합니다. 경로를 모르면 원시 stderr나 대화 transcript를 대신 제출하지 않습니다.

export가 jq 누락을 보고하면 setup-agent-guard가 제시하는 의존성 복구를 승인한 뒤 다시 시도합니다. 로그가 꺼짐, 저장소 사용 불가, 재현 후 빈 export, 시작 기록만 존재하는 경우에는 버전·host·OS/CPU·발생 시각과 시간대·결과 분류· 비밀값을 제거한 오류 요약만 지원 담당자에게 보냅니다. 원시 진단 자료로 대체하지 않습니다.

함께 보낼 수동 요약: 대상 식별번호, OS/CPU, Claude 버전, Agent Guard 버전, 발생 시각·시간대, 정상/차단/마스킹/오류 분류, 재현 순서의 비밀값 없는 설명, 관련 run_id. 프롬프트 원문·대화 transcript·stderr 전문·환경 변수 덤프·키·원본 파일은 보내지 않습니다.

8. 저장소의 GitHub Actions 검사

호스트 hook과 별개로 저장소에도 검사를 유지합니다. 아래 내용을 저장소의 .github/workflows/agent-guard.yml로 저장하고 PR을 통해 반영합니다. 기존 동일 검사가 있다면 중복 추가하지 않습니다.

name: Agent Guard
on:
  pull_request:
  push:
permissions:
  contents: read
jobs:
  secret-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: JeongJaeSoon/agent-guard@f2edc23f2b7d5d772345046f423ae14df759a9ca # v3.4.1
        with:
          paths: "."
          gitleaks-version: "8.30.1"
          gitleaks-checksum: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"

위 체크섬은 gitleaks 8.30.1 / Linux x64용입니다. runner OS/CPU를 바꾸면 그대로 사용하지 않습니다. 회사가 허용한 runner에서 실제 PR을 열어 job 실행과 정상 종료를 확인한 뒤, 저장소 Settings의 branch rules/ruleset에서 대상 브랜치의 해당 실제 check 이름을 merge 필수 검사로 지정합니다. 워크플로 파일만 추가하면 merge가 자동으로 차단되는 것은 아닙니다. 사용자별 로컬 Git hook은 우회 가능하므로 회사 CI의 대체 수단으로 취급하지 않습니다.

9. 장애 대응·버전 변경·원복

증상별 첫 조치

다음 버전으로 변경

1. 관리자가 새 릴리스와 검증 결과를 검토하고 승인 tag를 정합니다.
2. Jamf의 기존 Claude managed 설정에서 Agent Guard marketplace의 ref를 새 tag로 변경합니다. strictKnownMarketplaces에도 Agent Guard 항목이 있으면 그 ref도 함께 변경합니다. 다른 회사 설정은 유지합니다.
3. autoUpdate: false, closed, 로그 on을 유지한 채 시험 그룹부터 배포합니다.
4. 사용자가 Claude Code를 재시작하고 /plugin에서 승인된 marketplace 갱신·plugin 업데이트를 진행합니다. 적용된 plugin-local 버전이 기대 값인지 setup으로 확인합니다. 버전이 바뀌지 않으면 관리자와 함께 실제 설치 범위·marketplace ref를 확인합니다.
5. setup → check/smoke → 실제 LIVE 검사 → 로그 확인을 다시 통과하면 다음 그룹으로 확대합니다. shell 통합이 drift를 알리면 /agent-guard:setup-shell을 다시 실행합니다.

관리 설정의 tag를 바꿨다는 사실만으로 설치된 플러그인까지 업데이트됐다고 판단하지 않습니다. 플러그인 캐시는 Claude의 플러그인 관리자를 통해 갱신하고 plugin-local CLI의 update는 사용하지 않습니다.

원복

1. 신규 확대를 중단하고, 변경 기록에 보관한 이전 승인 설정을 확인합니다.
2. Jamf의 기존 Claude managed 설정에서 Agent Guard source/ref·환경 설정을 이전 값으로 되돌려 같은 대상에 재배포합니다. 그 사이 다른 회사 정책이 바뀌었다면 전체 설정을 과거 상태로 덮어쓰지 않고 Agent Guard 관련 변경만 되돌립니다.
3. 사용자가 Claude Code를 재시작하고 /status·/plugin·setup으로 이전 설정과 실제 플러그인 버전을 확인합니다. 호스트가 이전 버전을 적용하지 않으면 관리자가 승인한 plugin 재설치를 수행합니다.
4. 초기 도입 자체를 철회하는 경우에는 Jamf의 강제 활성화 설정을 제거한 뒤 /plugin에서 Agent Guard를 비활성화·제거합니다. 관리 키 삭제만으로 이미 설치된 사용자 plugin이 자동 삭제된다고 가정하지 않습니다.
5. 선택적으로 사용한 shell wrapping도 꺼야 한다면 plugin-local 실행 파일이 남아 있을 때 아래 명령을 실행하고 터미널과 Claude Code를 재시작합니다.

agent-guard setup-shell --no-command-wrapping

초기 도입 철회는 보호 해제를 뜻하므로 대상 사용자에게 알립니다. v3.3.0으로 원복하면 v3.4.1의 로그·보완을 유지한다고 가정할 수 없습니다. 원복 중에도 저장소 CI는 유지하고, 정상 보호 검사 없이 다음 그룹으로 확대하지 않습니다.

10. 선택: Homebrew·curl CLI 설치

플러그인 설치 후 setup-shell까지 완료한 bash/zsh 사용자는 agent-guard 명령을 이미 사용할 수 있으므로, 명령을 얻기 위해 Homebrew를 추가 설치하지 않습니다. 이 절은 Homebrew나 curl CLI를 먼저 설치하거나 호스트 플러그인 없이 CLI만 운영하는 기기용입니다.

반대로 Homebrew 또는 curl로 v3.4.1 CLI를 먼저 설치한 기기에서는 CLI가 Claude Code와 Codex의 공식 플러그인 관리자를 호출할 수 있습니다. 자체적으로 호스트 설정 파일이나 플러그인 캐시를 수정하지 않습니다. Jamf 관리 대상은 사용자가 이 명령으로 설치·업데이트·삭제하지 않으며, CLI도 managed 설정을 감지하면 변경을 거부합니다. 관리자는 2절의 pinned tag를 변경합니다.

agent-guard plugin status --host all
agent-guard plugin install --host claude
agent-guard plugin install --host codex

설치 명령은 marketplace를 CLI와 같은 v3.4.1 tag로 고정합니다. 이미 같은 이름의 marketplace가 무고정 상태이거나 다른 tag·source를 사용하면 이를 조용히 바꾸지 않고 중단하며, 공식 host manager로 제거한 뒤 재설치할 정확한 명령을 출력합니다. marketplace 제거는 그곳에서 설치한 플러그인도 제거하므로 안내된 순서대로 바로 재설치하고 다시 검사합니다.

Claude만 사용하는 기기는 --host claude 한 줄만 실행합니다. 설치 후 호스트를 재시작하고 4절의 두 스킬과 6절 수용 검사를 진행합니다. 이후 업데이트는 agent-guard plugin update --host claude, 삭제는 agent-guard plugin uninstall --host claude로 명시적으로 실행합니다.

CLI를 새 버전으로 바꿔도 호스트 플러그인의 고정 tag는 자동으로 바뀌지 않습니다. standalone의 agent-guard update 또는 Homebrew의 brew upgrade 후에는 사용 중인 host에 대해 다음을 실행합니다.

agent-guard plugin status --host all
agent-guard plugin update --host all

이전 릴리스 tag가 남아 있으면 update는 변경 전에 중단하고 공식 host manager로 marketplace를 제거한 뒤 새 tag로 다시 설치할 정확한 명령을 출력합니다. 그 순서를 따른 뒤 host를 재시작하고 두 setup 스킬과 6절 수용 검사를 다시 실행합니다. Codex는 변경된 hook을 다시 검토·신뢰합니다. 해당 기기에 설치된 host만 지정하며, Jamf 관리 대상은 이 명령 대신 9절의 관리자 업데이트 절차를 사용합니다.

Homebrew가 이미 있는 기기

brew tap JeongJaeSoon/tap
brew install JeongJaeSoon/tap/agent-guard
agent-guard version
agent-guard check
agent-guard smoke-test
agent-guard plugin install --host claude
brew pin agent-guard

v3.4.1 공개 릴리스와 tap 게시를 확인한 뒤 이 절을 사용합니다. brew는 설치 시점의 tap 버전을 사용하므로 출력이 다르면 3.4.1 배포 성공으로 처리하지 않습니다. brew pin은 향후 일반 upgrade를 막는 용도이며 과거 버전을 선택하는 기능이 아닙니다. 승인된 업데이트 시에만 brew unpin agent-guard → brew upgrade JeongJaeSoon/tap/agent-guard → 버전·check/smoke 확인 → 위의 host plugin 동기화와 재수용 검사 → brew pin agent-guard를 수행합니다. Homebrew 설치에 agent-guard update를 실행하지 않습니다.

curl로 정확한 v3.4.1 설치

일반 터미널에서 실행합니다. installer는 자체 archive SHA-256을 검증합니다. CLI만 추가하려고 shell wrapping까지 바뀌는 일을 피하기 위해 이 선택 경로에서는 wrapping을 off로 둡니다. 플러그인과 standalone CLI가 공존할 때는 이 경로보다 Homebrew 경로를 우선합니다. curl bootstrap은 wrapping을 끄더라도 shell rc의 Agent Guard 관리 블록을 만들거나 갱신할 수 있으므로, 실행 전후 rc 변경을 검토하고 필요한 경우 /agent-guard:setup-shell을 다시 실행해 plugin-local 설정을 복구합니다.

(
  set -eu
  ag_bootstrap=$(mktemp)
  trap 'rm -f "$ag_bootstrap"' EXIT HUP INT TERM
  curl -fsSL 'https://github.com/JeongJaeSoon/agent-guard/releases/download/v3.4.1/bootstrap.sh' -o "$ag_bootstrap"
  sh -n "$ag_bootstrap"
  AGENT_GUARD_VERSION=3.4.1 AGENT_GUARD_COMMAND_WRAPPING=off sh "$ag_bootstrap"
)
export PATH="$HOME/.local/bin:$PATH"
agent-guard version
agent-guard check
agent-guard smoke-test
agent-guard plugin install --host claude

bootstrap은 ~/.agent-guard와 ~/.local/bin/agent-guard를 사용하며 shell 통합 설정도 수행합니다. 플러그인용 관리 env는 일반 터미널의 CLI에 자동 적용되는 설정이 아닙니다. CLI에서도 동일 정책을 원하면 해당 터미널에서 export AGENT_GUARD_INFRA_FAILURE_MODE=closed와 export AGENT_GUARD_LOG_MODE=on을 명시합니다. standalone의 agent-guard update는 최신 공개 버전을 가져오므로 버전 고정 기간에는 실행하지 않습니다. 정확한 tag로 재설치할 때 위 명령의 URL과 AGENT_GUARD_VERSION을 함께 변경한 뒤, 위의 host plugin 동기화와 재수용 검사도 수행합니다.

11. 배포 공지와 수용 결과표

사용자에게 보낼 공지

[Agent Guard v3.4.1 단계 배포]
대상: <그룹과 사용자> / 적용일: <날짜>
지원 담당: <이름> / 문의 채널: <사내 채널>
JSONL 제출 위치: <승인된 위치> / 제출 자료 열람자·보존: <회사 정책>

수동 설치 또는 관리 설정 적용 후 Claude Code를 재시작하세요.
/plugin에서 Agent Guard 활성화를 확인하고
/agent-guard:setup-agent-guard 를 실행하세요.
의존성 설치가 필요하면 제시된 명령·버전·체크섬을 확인하고 승인하세요.
`/agent-guard:setup-shell`을 실행하고 터미널과 Claude Code를 다시 시작하세요.
이 매뉴얼 6절의 의존성·합성·LIVE·정상 작업 검사를 완료해 주세요.
DEGRADED, timeout, 합성 원문 노출은 통과가 아닙니다.

문제 신고에는 7절의 logs export JSONL과 비밀값 없는 수동 요약만 제출하세요.
키, 원본 파일, 대화 transcript, stderr 전문은 보내지 마세요.
버전을 임의로 업데이트하거나 closed를 open으로 변경하지 마세요.

판단 기록에는 검사 시각·검사자·발생 이슈·해결·재검사 여부도 남깁니다. 미확인 항목을 pass로 채우지 않습니다. 운영 담당자는 각 그룹 확대 전에 이 표를 검토합니다.

12. 검증 범위와 근거

v3.4.1 공개 태그 f2edc23f2b7d5d772345046f423ae14df759a9ca에서 로컬 전체 테스트 1,408 통과·실패 0개를 확인했습니다. 격리 환경의 Claude Code 2.1.268와 Codex CLI 0.153.4에서 설치·상태·업데이트·삭제를 확인했고, 공개 archive의 checksum·check·smoke-test, Homebrew formula의 strict online audit·fetch·tap CI를 통과했습니다. 100명 실사용, Linux 실제 Claude 호스트, 회사 기기 전체 수용 검사가 완료됐다는 뜻은 아닙니다.

• Agent Guard v3.4.1 공개 릴리스
• 공개 태그의 설정·설치·검증 소스
• Claude 관리 설정 전달 방법
• Claude 설정 로드·우선순위
• Claude marketplace 제한
• Claude plugin 명령