trustdex 0.7.0 → 0.8.0

package/docs/DEFENSIVE_USE_CASE.ko.md

@@ -54,9 +54,9 @@ ALLOW 결과는 여전히 관찰된 증거에 대한 정책 결과일 뿐입니
 
 `inspect-claude-settings`는 문서화된 `permissions` 객체를 검사하고 셸, 파일 시스템, 네트워크, MCP 및 서브에이전트 기능의 자동 승인을 보고합니다. 또한 훅, 자격 증명 도우미, 환경 설정, 샌드박스 설정 및 플러그인 로딩의 존재를 값은 보관하지 않은 채 드러냅니다.
 
-이는 정적 증거이지 런타임 강제 적용이 아닙니다. 모든 Claude 설정 범위를 병합하거나, 명령줄 플래그를 검사하거나, 관리형 설정이 세션에 실제 적용되었음을 증명하거나, Claude Code 샌드박싱을 대체하지 않습니다. 운영자는 실제 런타임 설정을 별도로 확인해야 합니다.
+`inspect-claude-settings-stack`은 명시적으로 전달된 사용자, 프로젝트, 로컬, 세션 및 관리형 소스에 문서화된 우선순위를 적용합니다. 이는 정적 증거이지 런타임 강제 적용이 아닙니다. 소스를 자동으로 찾거나 관리형 설정이 세션에 실제 적용되었음을 증명하지 않으며 Claude Code 샌드박싱을 대체하지 않습니다. 운영자는 실제 런타임 설정을 별도로 확인해야 합니다.
 
-`inspect-codex-settings`는 Codex 승인 정책, 검토자 선택, 샌드박스 종류, 네트워크 접근, 추가 쓰기 가능 루트 개수, 웹 검색 모드 및 명시적인 서브에이전트 활성화를 평가합니다. 완전히 파싱하지 않는 사용자 정의 권한, 앱 및 플러그인 표면은 값은 보관하지 않고 보고합니다. 마찬가지로 모든 Codex 설정 계층을 병합하거나 활성 Codex 샌드박스를 대체하지 않습니다.
+`inspect-codex-settings`는 Codex 승인 정책, 검토자 선택, 샌드박스 종류, 네트워크 접근, 추가 쓰기 가능 루트 개수, 웹 검색 모드 및 명시적인 서브에이전트 활성화를 평가합니다. 완전히 파싱하지 않는 사용자 정의 권한, 앱 및 플러그인 표면은 값은 보관하지 않고 보고합니다. `inspect-codex-settings-stack`은 전달된 파일에 시스템부터 CLI까지의 문서화된 우선순위와 순서가 있는 프로젝트 계층을 적용합니다. 활성 계층을 자동으로 찾거나 요구사항을 강제하거나 활성 Codex 샌드박스를 대체하지 않습니다.
 
 ## CVP 신청 경계
 

package/docs/DEFENSIVE_USE_CASE.md

@@ -54,13 +54,15 @@ An ALLOW result is still only a policy result over observed evidence. TrustDex i
 
 `inspect-claude-settings` examines the documented `permissions` object and reports automatic approval of shell, filesystem, network, MCP, and subagent capabilities. It also surfaces the presence of hooks, credential helpers, environment settings, sandbox configuration, and plugin loading without retaining their values.
 
-This is static evidence, not runtime enforcement. It does not merge every Claude settings scope, inspect command-line flags, prove that managed settings reached a session, or replace Claude Code sandboxing. The operator must confirm the effective runtime configuration separately.
+`inspect-claude-settings-stack` applies documented precedence to explicitly supplied user, project, local, session, and managed sources. This is static evidence, not runtime enforcement. It does not discover sources or prove that managed settings reached a session, and it does not replace Claude Code sandboxing. The operator must confirm the effective runtime configuration separately.
 
 `inspect-codex-settings` evaluates Codex approval policy, reviewer choice, sandbox
 class, network access, additional writable-root count, web-search mode, and explicit
 subagent enablement. It reports custom permission, app, and plugin surfaces that it
-does not fully parse without retaining their values. It likewise does not merge every
-Codex configuration layer or replace the active Codex sandbox.
+does not fully parse without retaining their values. `inspect-codex-settings-stack`
+applies documented system-through-CLI precedence to supplied files, including ordered
+project layers. It does not discover the active layers, enforce requirements, or replace
+the active Codex sandbox.
 
 ## CVP application boundary
 

package/docs/EVALUATION.ko.md

@@ -77,8 +77,19 @@
 제거된 권한 규칙 안에서 개수는 같고 내용만 바뀌는 경우는 이 구조적 비교의
 범위 밖입니다.
 
+## 병합 설정 스택 사례
+
+`test/settings-stack.test.mjs`는 두 런타임의 명시적 소스 스택을 검사합니다. 다음을 요구합니다.
+
+- Claude 권한 목록을 결합하면서 관리형/세션/로컬/프로젝트/사용자 스칼라 우선순위를 유지
+- 프로젝트 또는 로컬 Claude 소스가 `auto`나 `bypassPermissions` 기본 모드를 활성화하지 않음
+- Codex 시스템/관리형/사용자/프로필/프로젝트/CLI 우선순위와 가장 가까운 프로젝트 순서 적용
+- 높은 소스가 설정을 대체하더라도 잘못된 낮은 우선순위 입력은 실패
+- 스키마 v2 스냅샷은 고정된 범위 개수만 보관하고 소스 구성 변경에 재검토 요구
+- 소스 경로, 규칙, 도메인, 명령, 쓰기 가능 경로, 환경 변수 이름과 값을 계속 제외
+
 ## 이 평가가 측정하지 않는 것
 
-이 벤치마크는 의도적으로 범위가 좁습니다. 런타임 동작, 샌드박스 탈출, 임의의 악성 코드, 모든 형태의 프롬프트 인젝션, 게시자 신원 소유권 또는 전이 의존성의 취약점을 측정하지 않습니다. 모든 Claude 또는 Codex 설정 범위를 병합하거나 세션 명령줄 재정의를 검사하거나 보고된 샌드박스가 실제로 활성화되었음을 증명하지 않습니다. 특히 이미 실행 중인 MCP 서버가 동적으로 반환하는 도구 설명은 현재 정적 설정 경계 밖에 있습니다.
+이 벤치마크는 의도적으로 범위가 좁습니다. 런타임 동작, 샌드박스 탈출, 임의의 악성 코드, 모든 형태의 프롬프트 인젝션, 게시자 신원 소유권 또는 전이 의존성의 취약점을 측정하지 않습니다. 스택 사례는 테스트에 명시적으로 전달된 소스만 병합하며 활성 설정, 요구사항, 환경 변수 재정의 또는 서버 관리 정책을 자동으로 찾지 않고 보고된 샌드박스가 실제로 활성화되었음도 증명하지 않습니다. 특히 이미 실행 중인 MCP 서버가 동적으로 반환하는 도구 설명은 현재 정적 설정 경계 밖에 있습니다.
 
 이 작은 픽스처 집합은 회귀 기준선이지 탐지 정확도에 대한 통계적 주장이 아닙니다. 거짓 양성과 거짓 음성 비율을 측정하려면 민감 정보를 제거한 실제 설정으로 구성되고 독립적으로 검토된 더 큰 코퍼스가 필요합니다.

package/docs/EVALUATION.md

@@ -79,8 +79,19 @@ for both runtimes. `test/posture.test.mjs` requires:
 The digest checks internal consistency, not signer identity. Same-count changes inside
 redacted permission rules remain outside this structural comparison.
 
+## Merged settings stack cases
+
+`test/settings-stack.test.mjs` exercises explicit source stacks for both runtimes. It requires:
+
+- Claude permission lists to combine while managed/session/local/project/user scalar precedence is preserved
+- project or local Claude sources not to activate `auto` or `bypassPermissions` default modes
+- Codex system/managed/user/profile/project/CLI precedence and closest-project ordering
+- invalid lower-precedence input to fail even when a higher source would replace the setting
+- schema-v2 snapshots to retain only fixed scope counts and to require review when source topology changes
+- source paths, rules, domains, commands, writable paths, environment names, and values to remain absent
+
 ## What this does not measure
 
-This benchmark is intentionally narrow. It does not measure runtime behavior, sandbox escape, arbitrary malware, every form of prompt injection, publisher identity ownership, or vulnerabilities in transitive dependencies. It does not merge every Claude or Codex settings scope, inspect session command-line overrides, or prove that the reported sandbox is active. In particular, tool descriptions returned dynamically by an already-running MCP server are outside the current static configuration boundary.
+This benchmark is intentionally narrow. It does not measure runtime behavior, sandbox escape, arbitrary malware, every form of prompt injection, publisher identity ownership, or vulnerabilities in transitive dependencies. The stack cases merge only sources explicitly supplied to the test; they do not discover active settings, requirements, environment overrides, or server-managed policy, and they do not prove that the reported sandbox is active. In particular, tool descriptions returned dynamically by an already-running MCP server are outside the current static configuration boundary.
 
 The small fixture set is a regression baseline, not a statistical claim about detection accuracy. False-positive and false-negative rates require a larger, independently reviewed corpus of redacted real-world configurations.

package/docs/ROADMAP.ko.md

@@ -12,6 +12,8 @@ TrustDex는 초기 단계입니다. 이 로드맵은 방향을 공유하며 릴
 - TrustDex 0.7.0은 값이 제거되고 자체 일관성을 검증하는 권한 상태 스냅샷,
   자율성 확대 검토 게이트, 버전 지정 JSON 스키마 및 공개 적대적 권한 픽스처를
   추가합니다.
+- TrustDex 0.8.0은 문서화된 Claude Code 및 Codex 우선순위를 위한 명시적 병합 소스
+  검사, 스키마 v2 소스 구성 증거 및 안전하게 실패하는 스택 테스트를 추가합니다.
 
 ## 현재: 경계 강화
 
@@ -24,11 +26,10 @@ TrustDex는 초기 단계입니다. 이 로드맵은 방향을 공유하며 릴
 
 ## 다음: 에이전트 행동 경계를 검토 가능하게 만들기
 
-- 명령, 경로, 도메인 또는 자격 증명 값을 보관하지 않고 병합된 설정 소스 검사
-- 초기 단일 파일 권한 상태 비교를 병합 설정 소스로 확장
 - 승인된 도구 출처와 해당 도구에 부여된 행동 권한 연결
 - 버전이 지정된 권한 상태 JSON 스키마를 추가 결정 및 런타임으로 확장
 - 권고형 설정 검사가 런타임 및 운영체제 샌드박스와 결합되는 방식 문서화
+- 비공개 파일을 조용히 찾지 않으면서 런타임이 생성한 실제 설정 증거 추가
 
 ## 그다음: 무결성 증명
 

package/docs/ROADMAP.md

@@ -12,6 +12,8 @@ TrustDex is early-stage. This roadmap communicates direction and is not a releas
 - TrustDex 0.7.0 adds value-free, self-validating permission posture snapshots,
   autonomy-expansion review gates, versioned JSON schemas, and public adversarial
   permission fixtures.
+- TrustDex 0.8.0 adds explicit merged-source inspection for documented Claude Code
+  and Codex precedence, schema-v2 source topology evidence, and fail-closed stack tests.
 
 ## Now: harden the boundary
 
@@ -24,11 +26,10 @@ TrustDex is early-stage. This roadmap communicates direction and is not a releas
 
 ## Next: make agent action boundaries reviewable
 
-- inspect merged settings sources without retaining commands, paths, domains, or credential values
-- extend the initial single-file posture comparison to merged settings sources
 - connect approved tool provenance to the action permissions granted to that tool
 - extend the versioned permission-posture JSON schemas to additional decisions and runtimes
 - document how advisory settings checks compose with runtime and operating-system sandboxes
+- add runtime-produced effective-setting evidence without silently discovering private files
 
 ## Then: prove integrity
 

package/docs/THREAT_MODEL.ko.md

@@ -23,6 +23,7 @@ TrustDex는 하나의 좁은 질문을 다룹니다.
 - 샌드박스를 제거하거나 승인을 생략하거나 네트워크 접근 또는 쓰기 가능 루트를 추가하는 Codex 설정
 - 명시적인 검토 없이 변경되는 행동 권한 설정
 - 값이 제거된 구조적 기준 상태보다 확대되는 Claude 또는 Codex 권한 상태
+- 명시적으로 전달된 Claude 또는 Codex 설정 소스 사이의 우선순위 변경
 
 ## 신뢰 경계
 
@@ -45,7 +46,8 @@ TrustDex는 익숙한 프로젝트 이름, 스타 수, 패키지 이름 또는
 - 로컬 신뢰 저장소 주장만으로 게시자 소유권을 독립적으로 증명
 - 완전히 침해된 호스트 보호
 - 도난당한 서명 비공개 키로부터 보호
-- 모든 사용자, 프로젝트, 프로필, 관리형, 시스템, 환경 및 명령줄 소스를 병합한 실제 설정 계산
+- 모든 활성 설정 소스, 프로필, 환경 변수 재정의, 요구사항 또는 서버 전달 정책의 자동 탐색
+- 명시적으로 병합한 설정 투영이 런타임에서 활성화된 정책임을 증명하는 것
 - Claude Code 또는 Codex 행동 권한의 런타임 강제 적용
 - 서명되지 않은 권한 상태 스냅샷 작성자의 인증
 

package/docs/THREAT_MODEL.md

@@ -23,6 +23,7 @@ TrustDex addresses one narrow question:
 - Codex configurations that remove the sandbox, suppress approvals, enable network access, or add writable roots
 - action-permission settings changing without an explicit review
 - Claude or Codex permission posture expanding relative to a value-free structural baseline
+- precedence changes across explicitly supplied Claude or Codex settings sources
 
 ## Trust boundaries
 
@@ -45,7 +46,8 @@ TrustDex does **not** treat a familiar project name, star count, package name, o
 - independently proving publisher ownership from a local trust-store claim
 - protecting a fully compromised host
 - protecting a stolen signing private key
-- calculating the effective configuration after every user, project, profile, managed, system, environment, and command-line source is merged
+- automatically discovering every active settings source, profile, environment override, requirement, or server-delivered policy
+- proving that the explicitly merged settings projection is the policy active at runtime
 - enforcing Claude Code or Codex action permissions at runtime
 - authenticating the author of an unsigned permission posture snapshot
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustdex",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A local-first trust, provenance, and review gate for AI agent tools, MCP servers, skills, and plugins.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "test:research": "node --test test/research-fixtures.test.mjs test/claude-settings.test.mjs test/codex-settings.test.mjs test/posture.test.mjs",
+    "test:research": "node --test test/research-fixtures.test.mjs test/claude-settings.test.mjs test/codex-settings.test.mjs test/posture.test.mjs test/settings-stack.test.mjs",
     "check": "node --check bin/trustdex.mjs && node --check src/canonical.mjs && node --check src/claude-config.mjs && node --check src/claude-settings.mjs && node --check src/codex-config.mjs && node --check src/codex-settings.mjs && node --check src/extensions.mjs && node --check src/gate.mjs && node --check src/inspect.mjs && node --check src/policy.mjs && node --check src/policy-packs.mjs && node --check src/posture.mjs && node --check src/provenance.mjs && node --check src/provenance-online.mjs && node --check src/review.mjs && node --check src/snapshot.mjs && node --check src/trust-record.mjs",
     "prepublishOnly": "npm test && npm run check"
   },

package/schemas/permission-posture-diff-v2.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/grigent/trustdex/blob/main/schemas/permission-posture-diff-v2.schema.json",
+  "title": "TrustDex merged permission posture diff v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "runtime",
+    "status",
+    "baselineDigest",
+    "currentDigest",
+    "summary",
+    "changes"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "runtime": { "enum": ["claude", "codex"] },
+    "status": { "enum": ["unchanged", "restricted", "needs-review"] },
+    "baselineDigest": { "$ref": "permission-posture-diff-v1.schema.json#/$defs/digest" },
+    "currentDigest": { "$ref": "permission-posture-diff-v1.schema.json#/$defs/digest" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["expansions", "restrictions", "reviews"],
+      "properties": {
+        "expansions": { "$ref": "permission-posture-diff-v1.schema.json#/$defs/count" },
+        "restrictions": { "$ref": "permission-posture-diff-v1.schema.json#/$defs/count" },
+        "reviews": { "$ref": "permission-posture-diff-v1.schema.json#/$defs/count" }
+      }
+    },
+    "changes": {
+      "type": "array",
+      "items": { "$ref": "permission-posture-diff-v1.schema.json#/$defs/change" }
+    }
+  }
+}

package/schemas/permission-posture-v2.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/grigent/trustdex/blob/main/schemas/permission-posture-v2.schema.json",
+  "title": "TrustDex merged permission posture snapshot v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "createdAt",
+    "runtime",
+    "policyDigest",
+    "posture",
+    "sources",
+    "digest"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "kind": { "const": "agent-permission-posture" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "runtime": { "enum": ["claude", "codex"] },
+    "policyDigest": { "$ref": "permission-posture-v1.schema.json#/$defs/digest" },
+    "digest": { "$ref": "permission-posture-v1.schema.json#/$defs/digest" },
+    "posture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "signals", "metadata"],
+      "properties": {
+        "action": { "enum": ["allow", "ask", "block"] },
+        "signals": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string" }
+        },
+        "metadata": { "type": "object" }
+      }
+    },
+    "sources": { "type": "object" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "runtime": { "const": "claude" } } },
+      "then": {
+        "properties": {
+          "posture": {
+            "properties": {
+              "metadata": { "$ref": "permission-posture-v1.schema.json#/$defs/claudeMetadata" }
+            }
+          },
+          "sources": { "$ref": "#/$defs/claudeSources" }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "runtime": { "const": "codex" } } },
+      "then": {
+        "properties": {
+          "posture": {
+            "properties": {
+              "metadata": { "$ref": "permission-posture-v1.schema.json#/$defs/codexMetadata" }
+            }
+          },
+          "sources": { "$ref": "#/$defs/codexSources" }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "claudeSources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceCount", "activeSourceCount", "sourceCounts"],
+      "properties": {
+        "sourceCount": { "$ref": "#/$defs/count" },
+        "activeSourceCount": { "$ref": "#/$defs/count" },
+        "sourceCounts": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["user", "project", "local", "session", "managed"],
+          "properties": {
+            "user": { "$ref": "#/$defs/count" },
+            "project": { "$ref": "#/$defs/count" },
+            "local": { "$ref": "#/$defs/count" },
+            "session": { "$ref": "#/$defs/count" },
+            "managed": { "$ref": "#/$defs/count" }
+          }
+        }
+      }
+    },
+    "codexSources": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sourceCount", "activeSourceCount", "sourceCounts"],
+      "properties": {
+        "sourceCount": { "$ref": "#/$defs/count" },
+        "activeSourceCount": { "$ref": "#/$defs/count" },
+        "sourceCounts": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["system", "managed", "user", "profile", "project", "cli"],
+          "properties": {
+            "system": { "$ref": "#/$defs/count" },
+            "managed": { "$ref": "#/$defs/count" },
+            "user": { "$ref": "#/$defs/count" },
+            "profile": { "$ref": "#/$defs/count" },
+            "project": { "$ref": "#/$defs/count" },
+            "cli": { "$ref": "#/$defs/count" }
+          }
+        }
+      }
+    }
+  }
+}

package/src/claude-settings.mjs

@@ -19,6 +19,14 @@ const MODES = new Set([
   'auto'
 ]);
 const NON_PERMISSION_ROOT_KEYS = new Set(['$schema', 'permissions']);
+const CLAUDE_SCOPE_RANK = Object.freeze({
+  user: 0,
+  project: 1,
+  local: 2,
+  session: 3,
+  managed: 4
+});
+const MERGED_PERMISSION_LISTS = new Set(['allow', 'ask', 'deny', 'additionalDirectories']);
 
 function isObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -171,3 +179,76 @@ export function inspectClaudeSettings(settings, sourceName = 'settings.json') {
     envKeys
   };
 }
+
+function normalizeClaudeLayers(layers) {
+  if (!Array.isArray(layers) || !layers.length) {
+    throw new Error('Claude settings stack requires at least one settings source.');
+  }
+  const seen = new Set();
+  return layers.map((layer, index) => {
+    if (!isObject(layer) || !Object.hasOwn(CLAUDE_SCOPE_RANK, layer.scope)) {
+      throw new Error('Unsupported Claude settings source scope.');
+    }
+    if (seen.has(layer.scope)) {
+      throw new Error(`Claude settings stack accepts only one ${layer.scope} source.`);
+    }
+    seen.add(layer.scope);
+    if (!isObject(layer.settings)) throw new Error('Claude settings source must contain a JSON object.');
+    inspectClaudeSettings(layer.settings, 'Claude settings source');
+    return { ...layer, index };
+  }).sort((left, right) =>
+    CLAUDE_SCOPE_RANK[left.scope] - CLAUDE_SCOPE_RANK[right.scope] || left.index - right.index
+  );
+}
+
+function mergeClaudeSettings(layers) {
+  const merged = {};
+  const permissions = {};
+
+  for (const { scope, settings } of layers) {
+    for (const [key, value] of Object.entries(settings)) {
+      if (key === 'permissions') continue;
+      if (Array.isArray(value) && Array.isArray(merged[key])) merged[key] = [...merged[key], ...value];
+      else merged[key] = value;
+    }
+
+    const current = settings.permissions || {};
+    for (const [key, value] of Object.entries(current)) {
+      if (MERGED_PERMISSION_LISTS.has(key)) {
+        permissions[key] = [...(permissions[key] || []), ...value];
+        continue;
+      }
+      if (key === 'defaultMode' && ['project', 'local'].includes(scope) &&
+          ['auto', 'bypassPermissions'].includes(value)) {
+        continue;
+      }
+      permissions[key] = value;
+    }
+  }
+
+  if (Object.keys(permissions).length) merged.permissions = permissions;
+  return merged;
+}
+
+export function inspectClaudeSettingsStack(layers) {
+  const normalized = normalizeClaudeLayers(layers);
+  const merged = mergeClaudeSettings(normalized);
+  const result = inspectClaudeSettings(merged, 'merged Claude settings');
+  const sourceCounts = Object.fromEntries(Object.keys(CLAUDE_SCOPE_RANK).map((scope) => [scope, 0]));
+  let activeSourceCount = 0;
+  for (const layer of normalized) {
+    sourceCounts[layer.scope] += 1;
+    if (Object.keys(layer.settings).length) activeSourceCount += 1;
+  }
+  return {
+    ...result,
+    name: 'merged Claude settings',
+    kind: 'claude-settings-stack',
+    source: { type: 'local', format: 'claude-settings-stack', scopes: sourceCounts },
+    settingsContext: {
+      sourceCount: normalized.length,
+      activeSourceCount,
+      sourceCounts
+    }
+  };
+}

package/src/codex-settings.mjs

@@ -25,6 +25,14 @@ const INSPECTED_ROOT_KEYS = new Set([
   'default_permissions',
   'web_search'
 ]);
+const CODEX_SCOPE_RANK = Object.freeze({
+  system: 0,
+  managed: 1,
+  user: 2,
+  profile: 3,
+  project: 4,
+  cli: 5
+});
 
 function isObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -154,8 +162,7 @@ function validateSandbox(sandbox) {
   }
 }
 
-export function inspectCodexSettingsText(text, sourceName = 'config.toml') {
-  const { root, sandbox, agents, sections } = parseTomlAssignments(text);
+function inspectParsedCodexSettings({ root, sandbox, agents, sections }, sourceName, kind) {
   validateSandbox(sandbox);
 
   const signals = new Set();
@@ -222,7 +229,7 @@ export function inspectCodexSettingsText(text, sourceName = 'config.toml') {
 
   return {
     name: sourceName,
-    kind: 'codex-settings',
+    kind,
     source: { type: 'local', format: 'codex-settings', path: sourceName },
     metadata: {
       approvalPolicy: approval.mode,
@@ -245,3 +252,74 @@ export function inspectCodexSettingsText(text, sourceName = 'config.toml') {
     envKeys: []
   };
 }
+
+export function inspectCodexSettingsText(text, sourceName = 'config.toml') {
+  return inspectParsedCodexSettings(
+    parseTomlAssignments(text),
+    sourceName,
+    'codex-settings'
+  );
+}
+
+function normalizeCodexLayers(layers) {
+  if (!Array.isArray(layers) || !layers.length) {
+    throw new Error('Codex settings stack requires at least one config source.');
+  }
+  const seen = new Set();
+  return layers.map((layer, index) => {
+    if (!isObject(layer) || !Object.hasOwn(CODEX_SCOPE_RANK, layer.scope)) {
+      throw new Error('Unsupported Codex config source scope.');
+    }
+    if (layer.scope !== 'project' && seen.has(layer.scope)) {
+      throw new Error(`Codex settings stack accepts only one ${layer.scope} source.`);
+    }
+    seen.add(layer.scope);
+    if (typeof layer.text !== 'string') throw new Error('Codex config source must contain TOML text.');
+    const parsed = parseTomlAssignments(layer.text);
+    inspectParsedCodexSettings(parsed, 'Codex settings source', 'codex-settings');
+    return { ...layer, parsed, index };
+  }).sort((left, right) =>
+    CODEX_SCOPE_RANK[left.scope] - CODEX_SCOPE_RANK[right.scope] || left.index - right.index
+  );
+}
+
+export function inspectCodexSettingsStack(layers) {
+  const normalized = normalizeCodexLayers(layers);
+  const merged = {
+    root: Object.create(null),
+    sandbox: Object.create(null),
+    agents: Object.create(null),
+    sections: []
+  };
+  const sections = new Set();
+  const sourceCounts = Object.fromEntries(Object.keys(CODEX_SCOPE_RANK).map((scope) => [scope, 0]));
+  let activeSourceCount = 0;
+
+  for (const layer of normalized) {
+    sourceCounts[layer.scope] += 1;
+    Object.assign(merged.root, layer.parsed.root);
+    Object.assign(merged.sandbox, layer.parsed.sandbox);
+    Object.assign(merged.agents, layer.parsed.agents);
+    for (const section of layer.parsed.sections) sections.add(section);
+    if (Object.keys(layer.parsed.root).length || Object.keys(layer.parsed.sandbox).length ||
+        Object.keys(layer.parsed.agents).length || layer.parsed.sections.length) {
+      activeSourceCount += 1;
+    }
+  }
+  merged.sections = [...sections].sort();
+
+  const result = inspectParsedCodexSettings(
+    merged,
+    'merged Codex settings',
+    'codex-settings-stack'
+  );
+  return {
+    ...result,
+    source: { type: 'local', format: 'codex-settings-stack', scopes: sourceCounts },
+    settingsContext: {
+      sourceCount: normalized.length,
+      activeSourceCount,
+      sourceCounts
+    }
+  };
+}