@tienne/gestalt 0.120.2 → 0.122.0

package/CLAUDE.md

@@ -7,7 +7,7 @@
 ## 설계 전제
 - Execute Engine은 설계상 **항상 Passthrough 모드**다. Claude Code가 도구(Bash/Edit 등)로 실제 파일 수정과 코드 실행을 하므로 LLM 주체가 되고, API 키 유무와 무관하다. MCP 서버도 API 키가 없으면 Passthrough가 자동으로 켜진다.
 - Local PR은 에이전트끼리 레포 안에서 PR을 만들고 리뷰하고 머지하는 자리라 원격에 안 나간다. 워크트리 여럿이 `.gestalt/reviews.db` 하나를 공유한다.
-- 코드 그래프 훅 자동 주입과 WebFetch 디스크 캐시 훅은 둘 다 기본 꺼짐이다. peer 보는 중 표시 훅은 늘 돌지만 Node를 안 띄운다. 세션에 보는 사람이나 승인 대기가 있거나 팀원의 에이전트가 요약을 가져갔을 때만 데몬이 상태 파일을 써 두고 훅은 그 세션에만 붙인다.
+- 현재 Gestalt 훅 통합은 Claude Code 전용이다. 코드 그래프 훅 자동 주입과 WebFetch 디스크 캐시 훅은 둘 다 기본 꺼짐이다. peer 보는 중 표시 훅은 늘 돌지만 Node를 안 띄운다. 세션에 보는 사람이나 승인 대기가 있거나 팀원의 에이전트가 요약을 가져갔을 때만 데몬이 상태 파일을 써 두고 훅은 그 세션에만 붙인다.
 
 ## Key Commands
 ```bash
@@ -30,6 +30,7 @@ MCP 도구 목록과 액션 스키마는 `src/mcp/`의 툴 정의가 기준이
 세션 공유 → [`docs/peer.md`](./docs/peer.md)
 아키텍처 그림 → [`docs/architecture-view.md`](./docs/architecture-view.md)
 WebFetch 캐시 훅 → [`docs/webfetch-cache.md`](./docs/webfetch-cache.md)
+Codex 훅 지원 범위 → [`docs/codex-hooks.md`](./docs/codex-hooks.md)
 설계 제안 → [docs/proposals/](./docs/proposals/README.md)
 
 ## Role Agent 자동 라우팅
@@ -69,8 +70,8 @@ agents/                           Claude 플러그인 에이전트 (gestalt:<이
 - Codex는 `path`가 가리킨 디렉토리를 통째로 복사한다. 레포 루트를 가리키면 `.git`과 `node_modules`까지 딸려가 1.6GB가 되므로 반드시 `plugin/`으로 좁힌다.
 - Codex는 심링크를 따라가지 않는다. 자산은 실물 파일로 `plugin/` 안에 있어야 한다.
 - `plugin/skills/review/SKILL.md`가 `../../role-agents/`를 참조한다. 스킬과 에이전트를 함께 옮겨야 이 상대 깊이가 유지된다.
-- 훅은 루트 `hooks/hooks.json` 하나만 두고 `plugin.json`에 `hooks` 필드를 넣지 않는다. 문서상 필드와 기본 파일은 merge된다. 같은 파일을 가리키면 실제로는 한 번만 걸리는 걸 확인했지만 그래도 한 곳만 둔다.
-- Codex와 Grok 훅은 지원하지 않는다. 훅 자동 주입은 Claude 전용이다.
+- Claude Code 훅은 루트 `hooks/hooks.json` 하나만 두고 `plugin.json`에 `hooks` 필드를 넣지 않는다. Claude Code 문서상 필드와 기본 파일은 merge된다. 같은 파일을 가리키면 실제로는 한 번만 걸리는 걸 확인했지만 그래도 한 곳만 둔다.
+- Gestalt의 코드 그래프 자동 주입, WebFetch 캐시, peer 보는 중 표시 훅은 현재 Claude Code 전용이며 Codex와 Grok에는 통합하지 않았다. Codex 자체는 수동 설치한 desktop 플러그인의 훅을 지원하지만 명시적 trust가 필요하고 훅 포함 플러그인은 public directory 대상이 아니다. 근거와 호스트별 경계는 [`docs/codex-hooks.md`](./docs/codex-hooks.md)에 있다(공식 문서 확인: 2026-11-05).
 - 루트 `agents/`는 리뷰어 전부와 스킬이 `subagent_type: "gestalt:<이름>"`으로 띄우는 에이전트만 뽑은 생성물이다. 에이전트마다 설명이 모든 세션의 Agent 도구 설명에 붙어서 대상을 좁히고 설명도 빌드 스크립트의 한 줄짜리로 바꿔 싣는다. 고칠 곳은 원본 AGENT.md이고 도구와 `omitClaudeMd`는 `scripts/build-claude-agents.ts`의 표에서 정한다. 타입을 못 찾는 런타임은 Explore와 `ges_agent`로 폴백한다(`plugin/skills/_shared/agent-delegation.md`).
 - `plugin.json`에 `agents` 필드를 넣지 않는다. 배열로 넣으면 기본 `agents/` 디렉토리를 대체한다. 디렉토리 문자열을 넣으면 플러그인 로드가 통째로 깨진다(2.1.302에서 확인). 원리 에이전트가 있는 `plugin/agents/`는 Claude가 직접 읽는 자리가 아니다. 빌드가 continuity-judge만 여기서 읽어 루트 `agents/`로 뽑는다.
 - 생성물 본문의 룰북 경로는 `${CLAUDE_PLUGIN_ROOT}/plugin/...`이다. Claude Code가 에이전트 본문의 이 변수를 설치 경로로 치환해서 서브에이전트가 남의 레포에서 돌아도 풀린다.

package/README.ko.md

@@ -246,6 +246,26 @@ codex plugin add gestalt@gestalt
 
 스킬은 다음 Codex 세션부터 잡혀요. 슬래시 커맨드랑 Claude Code Task 패널은 Claude Code 전용이라, Codex에서는 하려는 일을 말로 설명하면 Codex가 해당 `SKILL.md`를 읽어 진행해요.
 
+설치 후 새 세션에서 “Gestalt 상태 확인해줘” 또는 “이 프로젝트를 Codex용 Gestalt로 초기화해줘”라고 요청하면 돼요.
+MCP 초기화 때 Codex를 인식해서 실행 컨텍스트는 기본으로 `AGENTS.md`에 기록하고 에이전트 모델은 현재
+Codex 세션을 상속해요. 명시한 `client`와 모델 설정은 유지하며 `client: "both"`면 두 호스트 파일에 계속 기록해요.
+프로젝트에 Codex 설정을 남기려면 초기화 스킬에 요청하면 돼요. 스킬이 아래의 버전 고정 런처로
+`setup --client codex`를 실행해요. 코드 그래프와 Git 훅까지 설정하려면 `init --client codex`를
+실행하고 고정된 CLI가 아직 이 옵션을 지원하지 않으면 호환 절차를 적용해요.
+
+스킬은 [호스트 어댑터](./plugin/skills/_shared/host-runtime.md)로 Claude 도구 예시를 현재 Codex 도구에 맞춰 실행해요.
+CLI 검사는 [버전 고정 런처](./plugin/skills/_shared/cli-launcher.md)를 거쳐서 전역 `gestalt` 설치가 필요 없어요.
+첫 CLI 실행은 플러그인과 같은 npm 버전을 내려받을 수 있으니 Node.js >=22와 npm이 PATH에 있어야 해요.
+
+연결이 실패하면 MCP 상태와 Node/npm부터 확인해요. 호스트나 모델이 예상과 다르면 `ges_status`의 `hostClient`,
+`client`, `tierModels`를 먼저 확인해요. Claude Task 패널과 Gestalt의 현재 Claude Code 훅 통합은 Codex 실행을 막지 않아요.
+
+Gestalt는 코드 그래프 자동 주입, WebFetch 캐시, peer 보는 중 표시 훅을 아직 Codex에 통합하지 않았어요.
+Codex desktop 자체는 수동 설치한 플러그인의 훅을 지원하지만 명시적 trust가 필요하고
+훅이 포함된 플러그인은 public directory에 제출할 수 없어요.
+[Codex 훅 지원 범위](./docs/codex-hooks.md)에 2026-11-05 확인한
+[공식 근거](https://developers.openai.com/plugins/build/plugins)와 Orca를 포함한 호스트별 경계를 정리했어요.
+
 ---
 
 ### 옵션 5: OpenAI Codex CLI (MCP만)

package/README.md

@@ -221,6 +221,34 @@ Skills load on the next Codex session. Slash commands and the Claude Code Task
 panel are still Claude Code only — in Codex you invoke a skill by describing the
 task, and Codex reads the matching `SKILL.md`.
 
+Start a new session after installing, then ask “Check Gestalt status” or
+“Set up Gestalt for this Codex project.” The server recognizes Codex during MCP
+initialization: new projects record execution context in `AGENTS.md`, and agent
+models inherit the active Codex session by default. Explicit `client` and model
+settings still take precedence; `client: "both"` continues writing both host files.
+For a persistent Codex-only project, ask the setup skill to save `client: "codex"`.
+The skill runs `setup --client codex` through the versioned launcher below
+(or `init --client codex` for the graph and Git hook), with compatibility handling
+when the pinned CLI predates that option.
+
+Skills use the bundled [host adapter](./plugin/skills/_shared/host-runtime.md) to
+translate Claude tool examples into the available Codex tools. They run CLI
+checks through the [versioned launcher](./plugin/skills/_shared/cli-launcher.md),
+so no global `gestalt` install is needed. The first CLI call may download the
+plugin's exact npm version and needs Node.js >=22 and npm on PATH.
+
+If startup fails, check MCP status and Node/npm availability. If the recorded
+host or model is unexpected, inspect `ges_status` fields `hostClient`, `client`,
+and `tierModels` before changing project settings. Claude Task panels and Gestalt's
+current Claude Code hook integrations are optional; they do not gate Codex execution.
+
+Gestalt has not integrated its code graph injection, WebFetch cache, or peer
+watching hooks with Codex. Codex desktop supports hooks in manually installed
+plugins, subject to explicit trust; plugins containing hooks are ineligible for
+the public directory. See [Codex hook support](./docs/codex-hooks.md) for the
+[official source](https://developers.openai.com/plugins/build/plugins), verified
+2026-11-05, and the boundaries for other hosts, including Orca.
+
 ---
 
 ### Option 5: OpenAI Codex CLI (MCP only)

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tienne/gestalt",
-  "version": "0.120.2",
+  "version": "0.122.0",
   "description": "TypeScript AI Development Harness - Gestalt psychology-driven requirement clarification",
   "repository": {
     "type": "git",
@@ -29,11 +29,12 @@
   "scripts": {
     "dev": "tsx bin/gestalt.ts",
     "build": "tsc -p tsconfig.build.json",
-    "postbuild": "rm -rf dist/plugin && mkdir -p dist/plugin && cp -r plugin/agents plugin/role-agents plugin/review-agents plugin/personas plugin/research-sources plugin/skills dist/plugin/ && cp -r schemas dist/ && cp package.json dist/ && chmod +x dist/bin/gestalt.js dist/bin/gestalt-hook.js && pnpm run verify:plugin && pnpm run verify:rules && pnpm run verify:rule-overlap && pnpm run verify:output-style && pnpm run verify:routing && pnpm run verify:agents",
+    "postbuild": "rm -rf dist/plugin && mkdir -p dist/plugin && cp -r plugin/agents plugin/role-agents plugin/review-agents plugin/personas plugin/research-sources plugin/skills plugin/scripts plugin/.codex-plugin dist/plugin/ && cp -r schemas dist/ && cp package.json dist/ && chmod +x dist/bin/gestalt.js dist/bin/gestalt-hook.js && pnpm run verify:plugin && pnpm run verify:rules && pnpm run verify:rule-overlap && pnpm run verify:output-style && pnpm run verify:routing && pnpm run verify:agents",
     "verify:plugin": "tsx scripts/verify-plugin-assets.ts",
     "prepublishOnly": "pnpm build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:plugin-install": "vitest run --config vitest.plugin-install.config.ts",
     "serve": "tsx bin/gestalt.ts serve",
     "bench": "tsx benchmarks/run.ts",
     "resolution-bench": "tsx benchmarks/run-resolution-benchmark.ts",
@@ -47,7 +48,7 @@
     "postversion": "pnpm run version:sync && pnpm run build:output-style",
     "verify:rules": "tsx scripts/verify-rule-refs.ts",
     "verify:rule-overlap": "tsx scripts/verify-rule-overlap.ts",
-    "gate": "pnpm typecheck && pnpm verify:rules && pnpm verify:rule-overlap && pnpm verify:routing && pnpm verify:agents && pnpm verify:skill-confusion && pnpm lint && pnpm format:check && pnpm build && pnpm test",
+    "gate": "pnpm typecheck && pnpm verify:rules && pnpm verify:rule-overlap && pnpm verify:routing && pnpm verify:agents && pnpm verify:skill-confusion && pnpm lint && pnpm format:check && pnpm build && pnpm test && pnpm test:plugin-install",
     "humanize:baseline": "tsx scripts/humanize-baseline.ts",
     "build:output-style": "tsx scripts/build-output-style.ts",
     "verify:output-style": "tsx scripts/build-output-style.ts --dry-run",
@@ -55,7 +56,8 @@
     "verify:routing": "tsx scripts/build-skill-routing.ts --check",
     "build:agents": "tsx scripts/build-claude-agents.ts",
     "verify:agents": "tsx scripts/build-claude-agents.ts --check",
-    "verify:skill-confusion": "tsx scripts/verify-skill-confusion.ts"
+    "verify:skill-confusion": "tsx scripts/verify-skill-confusion.ts",
+    "test:codex-e2e": "tsx scripts/codex-e2e.ts"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",

package/dist/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "gestalt",
+  "version": "0.122.0",
+  "description": "Gestalt psychology-driven AI development harness. Transforms scattered requirements into structured, validated specifications through interactive interviews.",
+  "author": {
+    "name": "tienne"
+  },
+  "homepage": "https://github.com/tienne/gestalt",
+  "repository": "https://github.com/tienne/gestalt",
+  "license": "MIT",
+  "keywords": [
+    "gestalt",
+    "requirements",
+    "specification",
+    "interview",
+    "mcp",
+    "ai-development",
+    "code-review"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json",
+  "interface": {
+    "displayName": "Gestalt",
+    "shortDescription": "Requirements-to-spec pipeline with review and PR workflows",
+    "longDescription": "Gestalt turns vague ideas into validated specifications through Gestalt-principle interviews, then drives execution, code review, and PR authoring. Bundles workflow skills, specialist agents, and MCP tools.",
+    "developerName": "tienne",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/tienne/gestalt",
+    "defaultPrompt": [
+      "Review this PR with the Gestalt review pipeline.",
+      "Clarify these requirements into a structured spec.",
+      "Write a PR description for the current branch."
+    ]
+  }
+}

package/dist/plugin/review-agents/writing-reviewer/AGENT.md

@@ -53,17 +53,19 @@ git diff --word-diff=porcelain -- <파일>
 
 한 조각이 룰에 걸리는지 보려면 그 조각이 들어간 **문장 전체**를 읽어야 합니다. 조각만 떼어 보면 문장 구조로 걸리는 룰(A-18 좌향 수식, C-11 연결어미 뒤 쉼표, E-2 종결어미 반복)을 판정할 수 없습니다. 판정은 문장으로 하되 이슈로 올릴지는 그 룰에 걸린 부분이 바뀐 조각 안에 있는지로 정합니다.
 
+아래 런처 경로는 이 문서 디렉토리 기준입니다. 실행 전에 절대 경로로 풉니다. 작업 레포의 동명 파일은 사용하지 않습니다.
+
 **정적 탐지를 먼저 돌립니다.** 정규식으로 잡히는 룰은 사람이 눈으로 세는 것보다 정확합니다.
 
 ```bash
-gestalt humanize-check --before <파일> --after <파일> --register doc --json
+node "../../scripts/gestalt-cli.mjs" humanize-check --before <파일> --after <파일> --register doc --json
 ```
 
 같은 파일을 `--before`와 `--after`에 둘 다 넘기면 윤문 전후 비교가 아니라 그 파일에 남아 있는 S1 패턴을 세어 줍니다. 잡히는 룰은 21개뿐이니 나머지는 읽고 판정합니다.
 
 `--register`는 대상 문서의 성격에 맞춰 고릅니다. 문서는 `doc`, 리뷰 코멘트나 대화체는 `chat`, 보고서는 `report`입니다. `chat`에서는 몇몇 S2가 S1으로 올라갑니다. 사람은 대화에서 개념을 명사 덩어리로 뭉치지 않기 때문입니다.
 
-레포에 이 명령이 없으면 그 단계를 건너뛰고 직접 읽어 판정합니다. 없다고 리뷰를 멈추지 않습니다.
+런처를 못 찾거나 버전 해석이 실패하면 그 단계를 건너뛰고 직접 읽어 판정합니다. 건너뛴 사실을 보고합니다.
 
 ## 어휘 선택을 볼 때
 

package/dist/plugin/role-agents/_shared/references/ai-tell-quick-rules.md

@@ -214,9 +214,10 @@
 ## 코드 검사 (자가 채점보다 위)
 
 아래 등급은 모델이 스스로 매기는 참고값이다. 실제 판단은 코드가 한다.
+런처 경로는 이 문서 디렉토리 기준이다. 실행 전에 절대 경로로 풀고 작업 레포의 동명 파일을 사용하지 않는다.
 
 ```bash
-gestalt humanize-check --before before.md --after after.md --register chat
+node "../../../scripts/gestalt-cli.mjs" humanize-check --before before.md --after after.md --register chat
 ```
 
 변경률, S1 잔존, 보호 토큰 생존, 구조 보존 4가지 측면에서 각각 측정하고 exit code로 답한다

package/dist/plugin/role-agents/humanize-monolith/AGENT.md

@@ -74,11 +74,14 @@ S2
 
 ### 0단계 — 스캔 (룰을 좁힌다)
 
+아래 런처 경로는 이 문서 디렉토리 기준이다. 실행 전에 절대 경로로 풀고 작업 레포의 동명 파일을 사용하지 않는다.
+런처를 못 찾거나 버전 해석이 실패하면 스캔과 코드 검사를 건너뛰고 직접 읽어 판정한다. 건너뛴 사실을 보고한다.
+
 원문이 파일로 있으면 먼저 스캔을 돌린다. 말투는 산문이 `doc`, 리뷰 코멘트와 슬랙이 `chat`,
 보고서가 `report`다.
 
 ```bash
-gestalt humanize-scan --file <원문> --register <doc|chat|report>
+node "../../scripts/gestalt-cli.mjs" humanize-scan --file <원문> --register <doc|chat|report>
 ```
 
 종료 코드로도 답한다. 걸린 게 있으면 0, 어투는 깨끗한데 맞춤법만 걸리면 11, 탐지기가 가리는 범위에서 0건이면 10이다. 11이면 어투는 그대로 두고 맞춤법 절만 고쳐서 낸다.
@@ -202,7 +205,7 @@ summary에 적는다. 댈 게 없으면 그건 안 고친 것이라 원문을
 위 3단계 자가검증은 스스로 매기는 참고값이다. 원문과 윤문본이 파일로 있으면 판단은 코드에 맡긴다.
 
 ```bash
-gestalt humanize-check --before <원문> --after <윤문본> --register chat --attempt 1
+node "../../scripts/gestalt-cli.mjs" humanize-check --before <원문> --after <윤문본> --register chat --attempt 1
 ```
 
 변경률, S1 제거율, 보호 토큰 생존, 구조 보존, 신규 유입을 각각 측정하고 exit code로 답한다

package/dist/plugin/scripts/acquisition.mjs

@@ -0,0 +1,96 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { Buffer } from 'node:buffer';
+import { setTimeout, clearTimeout } from 'node:timers';
+
+// One cancellation scope spans npm resolution, version verification and cwd cleanup.
+// A child's own signal/timeout is a failed attempt, never a user's cancellation.
+export function createAcquisition({ cwd, env }) {
+  let current;
+  let signal;
+  const cancel = (received) => {
+    signal = received;
+    current?.cancel(received);
+  };
+  const terminate = () => cancel('SIGTERM');
+  const hangup = () => cancel('SIGHUP');
+  const interrupt = () => cancel('SIGINT');
+  process.on('SIGTERM', terminate);
+  process.on('SIGHUP', hangup);
+  process.on('SIGINT', interrupt);
+
+  return {
+    get signal() {
+      return signal;
+    },
+    run(command, args, timeoutMs) {
+      return new Promise((resolveResult) => {
+        const child = spawn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let bytes = 0;
+        let failed = false;
+        let interruptTimer;
+        let killTimer;
+        let drainTimer;
+        const stop = (received) => {
+          clearTimeout(interruptTimer);
+          child.kill(received);
+          // Give npm a chance to forward cancellation first. KILL targets only this
+          // direct child; descendants can survive if npm cannot relay the signal.
+          killTimer ??= setTimeout(() => child.kill('SIGKILL'), 5000);
+        };
+        const active = {
+          cancel(received) {
+            if (received === 'SIGINT') {
+              // Do not duplicate group INT. Any surviving child gets TERM after grace.
+              interruptTimer ??= setTimeout(() => stop('SIGTERM'), 2000);
+            } else stop(received);
+          },
+        };
+        current = active;
+        const deadline = setTimeout(() => {
+          failed = true;
+          stop('SIGTERM');
+        }, timeoutMs);
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+          bytes += Buffer.byteLength(chunk);
+          if (bytes > 64 * 1024) {
+            failed = true;
+            stop('SIGTERM');
+          } else stdout += chunk;
+        });
+        child.stderr.resume();
+        child.once('error', () => {
+          failed = true;
+        });
+        child.once('exit', () => {
+          clearTimeout(deadline);
+          clearTimeout(interruptTimer);
+          clearTimeout(killTimer);
+          if (current === active) current = undefined;
+          // Descendants can inherit both pipes after npm exits. Drain briefly, then
+          // release both handles so they cannot keep resolution open indefinitely.
+          drainTimer = setTimeout(() => {
+            child.stdout.destroy();
+            child.stderr.destroy();
+          }, 1000);
+        });
+        child.once('close', (status) => {
+          clearTimeout(deadline);
+          clearTimeout(interruptTimer);
+          clearTimeout(killTimer);
+          clearTimeout(drainTimer);
+          if (current === active) current = undefined;
+          resolveResult({ status: failed ? null : status, stdout });
+        });
+        if (signal) active.cancel(signal);
+      });
+    },
+    dispose() {
+      process.off('SIGTERM', terminate);
+      process.off('SIGHUP', hangup);
+      process.off('SIGINT', interrupt);
+    },
+  };
+}

package/dist/plugin/scripts/gestalt-cli.mjs

@@ -0,0 +1,144 @@
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ownsPackage } from './package-owner.mjs';
+import { createAcquisition } from './acquisition.mjs';
+import { npmEnvironment } from './npm-environment.mjs';
+
+const scripts = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(scripts, '..');
+const args = process.argv.slice(2);
+const fail = (message) => {
+  process.stderr.write(`gestalt CLI: ${message}\n`);
+  process.exit(1);
+};
+
+let version;
+try {
+  version = JSON.parse(readFileSync(join(pluginRoot, '.codex-plugin/plugin.json'), 'utf8')).version;
+  if (
+    typeof version !== 'string' ||
+    !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version)
+  ) {
+    throw new Error('invalid version');
+  }
+} catch {
+  fail('cannot read the bundled plugin version; reinstall the plugin.');
+}
+if (Number(process.versions.node.split('.')[0]) < 22) fail('Node.js >=22 is required.');
+
+// A development checkout is identified by the wrapper's own location, never cwd.
+// Without tsx, use a matching compiled entry if available, then the exact npm pin.
+const checkout = resolve(pluginRoot, '..');
+let localArgs;
+let sourceTsconfig;
+try {
+  const pkg = JSON.parse(readFileSync(join(checkout, 'package.json'), 'utf8'));
+  const entry = join(checkout, 'bin/gestalt.ts');
+  if (pkg.name === '@tienne/gestalt' && pkg.version === version && existsSync(entry)) {
+    const tsx = join(checkout, 'node_modules/tsx/dist/loader.mjs');
+    // Keep the target project's tsconfig paths out of the source loader.
+    if (existsSync(tsx)) {
+      localArgs = ['--import', tsx, entry];
+      sourceTsconfig = join(checkout, 'tsconfig.json');
+    }
+  }
+  if (!localArgs && pkg.name === '@tienne/gestalt' && pkg.version === version) {
+    const compiled = [join(checkout, 'bin/gestalt.js'), join(checkout, 'dist/bin/gestalt.js')].find(
+      existsSync,
+    );
+    if (compiled) localArgs = [compiled];
+  }
+} catch {
+  // A copied plugin is deliberately independent of its containing project.
+}
+
+let bin;
+if (!localArgs) {
+  const neutral = mkdtempSync(join(tmpdir(), 'gestalt-cli-'));
+  const acquisition = createAcquisition({ cwd: neutral, env: npmEnvironment(process.env) });
+  try {
+    writeFileSync(join(neutral, 'package.json'), '{"private":true}\n');
+    for (const offline of [true, false]) {
+      if (!offline)
+        process.stderr.write(`gestalt CLI: resolving @tienne/gestalt@${version} from npm.\n`);
+      const result = await acquisition.run(
+        'npm',
+        [
+          'exec',
+          '--yes',
+          `--prefix=${neutral}`,
+          '--no-workspaces',
+          ...(offline ? ['--offline'] : []),
+          `--package=@tienne/gestalt@${version}`,
+          '--',
+          process.execPath,
+          join(scripts, 'resolve-cli.mjs'),
+          version,
+        ],
+        180_000,
+      );
+      if (acquisition.signal) break;
+      if (result.status !== 0) continue;
+      try {
+        const candidate = JSON.parse(result.stdout.trim());
+        if (typeof candidate !== 'string') continue;
+        bin = realpathSync(candidate);
+        if (!ownsPackage(bin, version)) {
+          bin = undefined;
+          continue;
+        }
+        // Do not trust the resolver process or a stale global executable.
+        const check = await acquisition.run(process.execPath, [bin, '--version'], 10_000);
+        if (acquisition.signal) break;
+        if (check.status === 0 && check.stdout.trim() === version) break;
+        bin = undefined;
+      } catch {
+        bin = undefined;
+      }
+    }
+  } finally {
+    try {
+      rmSync(neutral, { recursive: true, force: true });
+    } finally {
+      acquisition.dispose();
+    }
+  }
+  if (acquisition.signal) process.kill(process.pid, acquisition.signal);
+  if (!bin)
+    fail(
+      `could not resolve @tienne/gestalt@${version}; check npm, network access, and its native dependencies. No other version was executed.`,
+    );
+}
+
+const child = spawn(process.execPath, [...(localArgs ?? [bin]), ...args], {
+  cwd: process.cwd(),
+  stdio: 'inherit',
+  ...(sourceTsconfig ? { env: { ...process.env, TSX_TSCONFIG_PATH: sourceTsconfig } } : {}),
+});
+const terminate = () => child.kill('SIGTERM');
+const hangup = () => child.kill('SIGHUP');
+// Group Ctrl-C reaches the child: do not forward it twice. Programmatic callers
+// must use SIGTERM to cancel only this pid. Signal tests cover both delivery modes.
+const interrupt = () => {};
+process.on('SIGTERM', terminate);
+process.on('SIGHUP', hangup);
+process.on('SIGINT', interrupt);
+child.once('error', (error) => fail(error.message));
+child.once('exit', (code, signal) => {
+  process.off('SIGTERM', terminate);
+  process.off('SIGHUP', hangup);
+  process.off('SIGINT', interrupt);
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/dist/plugin/scripts/npm-environment.mjs

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import process from 'node:process';
+import { dirname, join } from 'node:path';
+
+// Registry settings may deliberately use a provider token. Preserve referenced
+// names before filtering known credentials; native-build and network settings pass through.
+export function npmEnvironment(source) {
+  const env = { ...source };
+  const find = (name) => Object.keys(env).find((key) => key.toLowerCase() === name);
+  const get = (name) => {
+    const key = find(name);
+    return key === undefined ? undefined : env[key];
+  };
+  const referenced = new Set();
+  // Match npm's optional references and escaped dollar signs in configuration.
+  const envExpr = /(?<!\\)(\\*)\$\{([^${}?]+)(\?)?\}/g;
+  const collect = (text) => {
+    for (const match of text.matchAll(envExpr)) {
+      if (match[1].length % 2 === 0) referenced.add(match[2].toLowerCase());
+    }
+  };
+  const expand = (path) =>
+    path.replace(envExpr, (whole, escapes, key, optional) => {
+      if (escapes.length % 2) return whole.slice((escapes.length + 1) / 2);
+      const value = env[key] ?? (optional ? '' : '${' + key + '}');
+      return escapes.slice(escapes.length / 2) + value;
+    });
+  const home = get('home') ?? get('userprofile') ?? homedir();
+  const files = [
+    get('npm_config_userconfig') ?? join(home, '.npmrc'),
+    get('npm_config_globalconfig') ??
+      join(get('npm_config_prefix') ?? dirname(dirname(process.execPath)), 'etc/npmrc'),
+  ];
+  for (const file of files) {
+    try {
+      const text = readFileSync(expand(file).replace(/^~(?=[/\\])/, home), 'utf8');
+      collect(
+        text
+          .split('\n')
+          .filter((line) => !/^\s*[#;]/.test(line))
+          .join('\n'),
+      );
+    } catch {
+      // Missing/unreadable npm settings are handled by npm itself.
+    }
+  }
+  for (const [key, value] of Object.entries(env)) {
+    if (/^npm_config_/i.test(key)) collect(value);
+  }
+  for (const key of Object.keys(env)) {
+    if (/^npm_|^node_auth_token$/i.test(key) || referenced.has(key.toLowerCase())) continue;
+    if (
+      /^(ANTHROPIC_|OPENAI_|CLAUDE_CODE_OAUTH_|GEMINI_|CODEX_|XAI_|GROK_|GOOGLE_API_KEY$|AWS_ACCESS_KEY_ID$|AWS_SECRET_ACCESS_KEY$|AWS_SESSION_TOKEN$|GH_TOKEN$|GITHUB_TOKEN$)/i.test(
+        key,
+      ) ||
+      /(_API_KEY|_SECRET|_SECRET_KEY|_CLIENT_SECRET|_PASSWORD|_ACCESS_TOKEN|_AUTH_TOKEN|_BOT_TOKEN)$|^HF_TOKEN$/i.test(
+        key,
+      )
+    )
+      delete env[key];
+  }
+  return env;
+}

package/dist/plugin/scripts/package-owner.mjs

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// The nearest manifest owns the bin; an unrelated parent must not vouch for it.
+export function ownsPackage(bin, version) {
+  try {
+    let directory = dirname(bin);
+    while (directory !== dirname(directory)) {
+      const manifest = join(directory, 'package.json');
+      if (existsSync(manifest)) {
+        const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+        return pkg.name === '@tienne/gestalt' && pkg.version === version;
+      }
+      directory = dirname(directory);
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}

package/dist/plugin/scripts/resolve-cli.mjs

@@ -0,0 +1,22 @@
+import process from 'node:process';
+import { realpathSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { ownsPackage } from './package-owner.mjs';
+
+// npm exec prepends its package bin directory. Verify the owning package instead
+// of accepting a same-named executable inherited from the user's PATH.
+const expected = process.argv[2];
+for (const entry of (process.env.PATH ?? '').split(delimiter)) {
+  if (!entry) continue;
+  const candidate = join(entry, 'gestalt');
+  try {
+    const bin = realpathSync(candidate);
+    if (ownsPackage(bin, expected)) {
+      process.stdout.write(JSON.stringify(bin));
+      process.exit(0);
+    }
+  } catch {
+    // Broken PATH entries and unrelated packages do not resolve this pin.
+  }
+}
+process.exitCode = 1;

package/dist/plugin/skills/_shared/agent-delegation.md

@@ -1,5 +1,7 @@
 # 에이전트를 서브에이전트로 위임하기 (공유 규칙)
 
+> **Codex 등 다른 호스트에서는** [`host-runtime.md`](./host-runtime.md)를 먼저 적용한다. `inherit`는 모델 인자 생략이며 Claude 별칭 폴백을 강제하지 않는다.
+
 > **현재 적용: `review`, `pr`, `brief`, `presentation`, `review-reply`, `slack-send`, `jira-create`, `ship`, `explain`, `research`, `ux-research`, `reverse-plan`.** 에이전트를 불러 쓰는 스킬은 전부 위임한다. 새 스킬이 `ges_agent get`을 메인에서 하면 그건 예외가 아니라 빠뜨린 것이다.
 
 ## 왜 필요한가
@@ -38,6 +40,13 @@
 
 ## 어떻게 위임하나
 
+Codex는 [`codex-delegation-examples.md`](./codex-delegation-examples.md)의 네이티브 호출 예시를 따른다.
+현재 제공된 스키마를 확인하고 `inherit`이면 모델 인자를 생략한다. 아래 `Agent`, `Explore`,
+`subagent_type`과 도구 권한 설명은 Claude Code 기준이며 Codex 호출 인자로 옮기지 않는다.
+페르소나 조회, 룰북 절대 경로와 입력 가드 등 공통 위임 규칙은 그대로 적용한다.
+
+### Claude Code 호출
+
 **`subagent_type`에 `gestalt:<에이전트명>`을 넣는다.** 리뷰어 전부와 스킬이 이렇게 띄우는 에이전트는 플러그인 `agents/`에 Claude Code 에이전트로도 들어 있다. AGENT.md를 `pnpm build:agents`가 옮겨 뽑은 것이라 지침은 `ges_agent`가 주는 것과 같다. 빌드가 스킬 문서의 `subagent_type: "gestalt:<이름>"`을 모아 뽑을 대상을 정하므로 새 스킬이 이 줄을 쓰면 다음 빌드에 함께 생긴다. 이때 `scripts/build-claude-agents.ts`의 한 줄 설명 표에 항목을 넣어야 빌드가 통과한다.
 
 이렇게 띄우면 AGENT.md 본문이 서브에이전트의 시스템 프롬프트로 바로 실린다. 프롬프트에서 페르소나를 가져오게 할 필요가 없다.
@@ -118,7 +127,7 @@ Agent {
 
 ## 실패했을 때
 
-`gestalt:` 타입을 못 찾으면 위의 Explore 폴백으로 간다. 폴백한 서브에이전트가 `ges_agent`에 닿지 못하면 (MCP 미연결 등) 아래를 순서대로 본다.
+`gestalt:` 타입을 못 찾으면 위의 Explore 폴백으로 간다. Codex의 도구 부재와 독립 판정 제한은 [`host-runtime.md`](./host-runtime.md)를 우선한다. 폴백한 서브에이전트가 `ges_agent`에 닿지 못하면 (MCP 미연결 등) 아래를 순서대로 본다.
 
 1. **페르소나 없이 임의로 수행하지 않는다.** 어투와 판정 기준이 에이전트에 있는데 그걸 못 읽었으면 결과가 규칙을 안 지킨다. 이건 어느 경우에도 금지다.
 2. **메인 세션이 대신 `ges_agent get`을 해서 직접 수행하는 폴백은 쓸 수 있다.** 페르소나는 확보되니 결과는 규칙을 지킨다. 다만 컨텍스트 절감이 사라지므로 그 사실을 완료 보고에 밝힌다.

package/dist/plugin/skills/_shared/agent-model.md

@@ -1,5 +1,7 @@
 # 에이전트 tier로 모델 고르기 (공유 규칙)
 
+> **Codex 등 다른 호스트에서는** [`host-runtime.md`](./host-runtime.md)를 먼저 적용한다. `inherit`는 모델 인자 생략이며 Claude 별칭 폴백을 강제하지 않는다.
+
 `ges_agent`의 `get`과 `list`는 둘 다 `tier`와 **해석된 `model`** 을 돌려준다. 에이전트 frontmatter의
 tier가 "이 역할이 어느 정도 모델을 필요로 하나"를 선언하고 서버가 그걸 호스트 Agent 도구가 받는
 별칭으로 옮겨준 값이다. 둘의 차이는 `systemPrompt`가 딸려오느냐뿐이다. `get`은 한 에이전트의