@dsh-cc/settings-cascade 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/settings/settings-cascade/README.md
+README.md: db5b2923ecf21475673eee83e27fc76de1f8caa3
+README.zh.md: e57ba534c84da51f4ec75e398c2ebcc54e4703fe

package/README.md

@@ -0,0 +1,57 @@
+# @dsh-cc/settings-cascade
+
+English | [中文](README.zh.md)
+
+Claude Code-style five-level settings cascade provider for `ctx.settings`. Five sources merge low-to-high — user settings, project settings, local settings, flag settings, policy settings — under a plugin-default base. The merged raw document feeds the user-settings seam, whose namespace resolution layers schema defaults, the registrant `base`, and this user layer in turn.
+
+## Config
+
+| Field | Meaning | Default |
+|---|---|---|
+| `userSettingsPath` | User settings file | `settings.json` under the harness home |
+| `projectSettingsPath` | Project settings file | `<project>/.claude/settings.json` |
+| `localSettingsPath` | Local (gitignored) settings file | git main-checkout root (linked worktree) or git toplevel `.claude/settings.local.json` |
+| `flagSettingsPath` | Command-line `--settings` file | none |
+| `flagSettingsInline` | Inline `--settings` content, merged over the flag file | none |
+| `projectDir` | Seeds the **project** settings path and is the launch directory for the git probe behind the local settings path | current working directory |
+| `dshHome` | Harness home for the default user settings path | `$DSH_HOME` or `~/.dsh` |
+| `policy.remoteSettings` | Hosted policy settings; highest policy priority | none |
+| `policy.systemPath` | System-level managed settings file | none |
+| `policy.userPath` | User-writable managed settings file | none |
+
+Defaulting is one explicit `resolveSpec(config)` step.
+
+## Behavior
+
+- **Priority order from low to high.** user < project < local < flag < policy. Sources deep-merge recursively; a higher source fills keys a lower one omitted and replaces the values it does carry.
+- **Plugin defaults sit at the bottom.** Registration `base` and schema defaults resolve below every file source, so a missing document resolves exactly as a leaf provider would.
+- **Permission arrays union, `deny` wins.** `allow`, `deny`, and `ask` rule arrays concatenate and deduplicate across layers, and the unioned `deny` set is removed from `allow` — a higher-layer deny always beats a lower-layer allow. Empty permission arrays are omitted. Other arrays (for example `additionalDirectories`) let the higher layer override wholesale.
+- **Policy is first-source-wins.** The policy layer takes the first non-empty of its sub-sources in priority order: remote > system file > user file. An empty or absent higher source falls through to the next.
+- **Flag settings merge file-then-inline.** If both a `--settings` file and inline content are present, the inline content merges over the file within the flag layer.
+- **Misconfiguration fails loud.** A present-but-invalid settings document (unparsable JSON, or a non-object root) fails plugin load; an absent source file contributes nothing and is not an error.
+- **The provider is writable through the user layer.** `writable` is `true`, so the seam's in-process `update()`/`replace()`/`mutate()` paths are accepted. A write is applied as a surgical delta onto the user-layer settings file (default `$DSH_HOME/settings.json`): only the keys the caller actually changed land in the user file. Values the write did not touch are not copied in, even if they were inherited from a higher layer. The seam still owns validation, revision, and update events; project/local/flag/policy sources remain read-side-only contributors.
+- **The local settings file path hoists git-style.** When the launch directory is a git worktree or a subdirectory of a git repo, `.claude/settings.local.json` is read from the git **main checkout root** (worktree) or **toplevel** (subdirectory start), matching Claude Code. Project `settings.json` stays at the launch directory, the session cwd and git operations are unaffected, and paths *inside* the file still resolve against the launch directory. Fallbacks that keep the file at the launch directory: not a git repo, Windows (`win32`), the repo root is `$HOME`, a bare-main hoist target without `.git`, a git probe failure, or ownership of the repo root / `.git` / `.claude` not confirmed as the current user (fail-closed). A worktree-local `settings.local.json` is silently not loaded (merging both is unconfirmed in Claude Code). No hot-reload: entering a worktree mid-session does not re-resolve.
+- **CC camelCase keys alias onto kebab namespaces.** After the five-layer merge (and before publish), a fixed whitelist of Claude Code camelCase top-level keys (`statusLine` → `statusline`) is copied onto its dsh-native kebab namespace. The alias is injected only when the CC key's value is a plain object AND the kebab key is absent from the merged document — a dsh-native key already present wins untouched, and non-object CC values are ignored. No fuzzy matching: the whitelist map is the contract; unknown camelCase keys are never aliased.
+- **`env` applies in two stages.** A top-level `env` section is split out of the merged document and exposed through `getEnv()` with every value coerced to a string. `applyEnv()` assigns ordinary variables; `applyTrustedEnv()` additionally assigns environment-altering variables (`LD_PRELOAD`, `PATH`, `DYLD_INSERT_LIBRARIES`, and the other `DANGEROUS_ENV_VARS`) and runs only after the user grants trust.
+
+## Permissions schema
+
+The `permissions` field schema (`allow`, `deny`, `ask`, `defaultMode`, `disableBypassPermissionsMode`, `additionalDirectories`, `protectedFiles`, `dangerousPatterns`), matching Claude Code's settings.json, is exported as `PermissionsSchema` (with `PermissionRuleSchema` and `PERMISSION_MODES`) for the permission-rule engine. The optional LLM risk-classifier section is exported as `AutoModeSchema` (delivered as `permissions.autoMode`, not a root-level `autoMode` key — a documented deviation from Claude Code's settings surface).
+
+## Model Experience
+
+Indirectly, through consumers of `ctx.settings`: composition remains the read model, with writes supported through the user layer, and each consumer's own surface documents any model effect.
+
+#### KV Cache effect
+
+No direct invalidation; the consuming plugin owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **JSON-only sources.** Sources must be `.json` (the settings.json convention); YAML is deferred.
+- **Unsetting an inherited key is not persisted.** Unsetting a key that comes from a lower-priority source (project/local/flag/policy) cannot be persisted to the user file; the unset holds for the running process, but the value reappears on restart. Also, `describe()`'s `user` field reflects the merged section rather than the literal user file, so GUI override markers are approximate (pre-existing behavior).
+- **Concurrent writers can lose updates.** Concurrent writes from multiple dsh processes to the same user settings file can silently lose updates — atomic rename prevents file corruption, not lost writes; the stock provider's cross-process lock was dropped for this port. Single-process profiles (the norm) are unaffected.
+- **Writes go to the user layer, not the hoisted local file.** `persist()` writes to the user settings file (pre-existing); an always-allow granted in a worktree therefore still does not update the main checkout's `settings.local.json`.
+- **No file hot-reload.** External edits to any source file take effect only on restart (pre-existing).
+- **No per-source provenance.** The merged result does not record which source supplied each resolved value, and `describe()` cannot mark a field's origin across the five layers the way a single user layer does.
+- **Dangerous env is a static allowlist.** `DANGEROUS_ENV_VARS` names a fixed set; deployment-specific variables need an explicit extension point before first use.

package/README.zh.md

@@ -0,0 +1,56 @@
+# @dsh-cc/settings-cascade
+
+[English](README.md) | 中文
+
+面向 `ctx.settings` 的 Claude Code 风格五级设置级联提供方。五级来源按优先级从低到高合并——用户设置、项目设置、本地设置、flag 设置、策略设置——其下是插件默认基底。合并后的原始文档进入用户设置 seam，其 namespace 解析按 schema 默认、注册方 `base`、本用户层依次叠放。
+
+## 配置
+
+| 字段 | 含义 | 默认 |
+|---|---|---|
+| `userSettingsPath` | 用户设置文件 | harness home 下的 `settings.json` |
+| `projectSettingsPath` | 项目设置文件 | `<project>/.claude/settings.json` |
+| `localSettingsPath` | 本地（被 git 忽略的）设置文件 | git 主检出根（linked worktree）或 git 顶层目录下的 `.claude/settings.local.json` |
+| `flagSettingsPath` | 命令行 `--settings` 文件 | 无 |
+| `flagSettingsInline` | 内联 `--settings` 内容，在 flag 文件之上合并 | 无 |
+| `projectDir` | 决定**项目**设置路径，并作为本地设置路径 git 探测的启动目录 | 当前工作目录 |
+| `dshHome` | 默认用户设置路径所用的 harness home | `$DSH_HOME` 或 `~/.dsh` |
+| `policy.remoteSettings` | 托管策略设置；策略最高优先级 | 无 |
+| `policy.systemPath` | 系统级托管设置文件 | 无 |
+| `policy.userPath` | 用户可写的托管设置文件 | 无 |
+
+默认值解析是一步显式的 `resolveSpec(config)`。
+
+## 行为
+
+- **优先级从低到高。** user < project < local < flag < policy。各来源递归深合并；高层来源补上低层缺失的键，并替换其携带的值。
+- **插件默认位于最底层。** 注册 `base` 与 schema 默认值解析于每个文件来源之下，因此文档缺失时解析结果与叶子提供方完全一致。
+- **权限数组取并集，`deny` 优先。** `allow`、`deny`、`ask` 规则数组跨层拼接去重，合并后的 `deny` 集合会从 `allow` 中剔除——高层 deny 始终压过低层 allow。空的权限数组被省略。其余数组（例如 `additionalDirectories`）由高层整体覆盖。
+- **策略是首个来源胜出。** 策略层按其子来源优先级取第一个非空者：remote > 系统文件 > 用户文件。较高来源为空或缺失时回退到下一来源。
+- **flag 设置先文件后内联。** 若同时存在 `--settings` 文件与内联内容，内联内容在 flag 层内部覆盖文件。
+- **坏配置加载期明确报错。** 存在但非法的设置文档（不可解析的 JSON，或非对象根）使插件加载失败；来源文件缺失不算错误，不贡献任何内容。
+- **提供方经用户层可写。** `writable` 为 `true`，seam 的进程内 `update()`/`replace()`/`mutate()` 路径被接受。写入以 surgical delta（外科手术式增量）应用到用户层设置文件（默认 `$DSH_HOME/settings.json`）：只有调用方实际改动的键才落入用户文件。写入未触及的值——即使源自更高层——也不会被带进来。校验、修订号与更新事件仍由 seam 负责；project/local/flag/policy 来源仍是只读侧贡献者。
+- **本地设置文件路径按 git 语义上提。** 启动目录位于 git worktree 或 git 仓库子目录时，`.claude/settings.local.json` 改从 git **主检出根**（worktree）或**顶层目录**（子目录启动）读取，与 Claude Code 一致。项目 `settings.json` 仍留在启动目录，会话 cwd 与 git 操作不受影响，文件内部的路径仍相对启动目录解析。以下情形回退到启动目录本身：非 git 仓库、Windows（`win32`）、仓库根为 `$HOME`、上提目标缺少 `.git` 的裸主仓库、git 探测失败，或仓库根 / `.git` / `.claude` 的属主未确认为当前用户（fail-closed）。worktree 本地的 `settings.local.json` 不会被读取（两者合并的行为在 Claude Code 中未确认）。无热重载：会话中途进入 worktree 不会重新解析。
+- **`env` 分两阶段应用。** 顶层 `env` 分节从合并文档中拆出，经 `getEnv()` 暴露，所有值已强制转为字符串。`applyEnv()` 赋值普通变量；`applyTrustedEnv()` 另赋值改变环境的变量（`LD_PRELOAD`、`PATH`、`DYLD_INSERT_LIBRARIES` 及其余 `DANGEROUS_ENV_VARS`），仅在用户授予信任后运行。
+
+## 权限 schema
+
+`permissions` 字段 schema（`allow`、`deny`、`ask`、`defaultMode`、`disableBypassPermissionsMode`、`additionalDirectories`、`protectedFiles`、`dangerousPatterns`）与 Claude Code 的 settings.json 一致，以 `PermissionsSchema` 导出（连同 `PermissionRuleSchema` 与 `PERMISSION_MODES`），供权限规则引擎使用。
+
+## 模型体验
+
+间接生效：组合仍是读模型，写入经用户层得到支持；任何模型效果都经由 `ctx.settings` 的消费方产生，并由各消费方自己的接口文档说明。
+
+#### KV Cache 影响
+
+无直接失效；请求前缀的任何变更均由消费方插件负责。
+
+## 已知限制与暂缓事项
+
+- **仅 JSON 来源。** 来源必须是 `.json`（settings.json 惯例）；YAML 暂缓实现。
+- **取消继承键不落盘。** 取消一个来自更低优先级来源（project/local/flag/policy）的键无法写入用户文件；该取消对运行中的进程生效，但重启后该值重现。此外，`describe()` 的 `user` 字段反映合并段而非用户文件实含量，因此 GUI 的 override 标记为近似（既有行为）。
+- **并发写入可能丢更新。** 多个 dsh 进程并发写同一个用户设置文件可能静默丢失更新——原子 rename 只防文件损坏、不防丢写；原生提供方的跨进程锁已在本移植中移除。单进程配置（通常情况）不受影响。
+- **写入仍走用户层，而非上提后的本地文件。** `persist()` 写入用户设置文件（既有行为）；因此在 worktree 中授予的 always-allow 仍不会更新主检出的 `settings.local.json`。
+- **无文件热重载。** 任何来源文件的外部编辑均在重启后才生效（既有）。
+- **无逐来源出处。** 合并结果不记录每个解析值来自哪个来源，`describe()` 也无法像单一用户层那样标注字段在五层之间的出处。
+- **危险环境变量是静态白名单。** `DANGEROUS_ENV_VARS` 命名固定集合；部署专属变量在首次使用前需要显式的扩展点。

package/lib/auto-mode.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Claude Code-compatible `autoMode` schema — the settings surface for the LLM
+ * risk classifier (design doc §4.5). The delivery route is the `autoMode` key
+ * INSIDE the existing `permissions` namespace (`permissions.autoMode`), not a
+ * root-level key: top-level settings namespaces must be kebab-case upstream,
+ * so Claude Code's root `autoMode` location is a documented deviation (the
+ * cascade registers no root `autoMode` namespace). Exported as a standalone
+ * value so the settings cascade and the permission-rules plugin (which
+ * hand-mirrors the shape) share one definition of the section.
+ * @module @dsh-cc/settings-cascade/auto-mode
+ */
+import z from '@deepseek-ai/schemastery';
+/** `autoMode.classifier` — only defaults apply when the object itself is present. */
+export interface AutoModeClassifier {
+    /** Master switch for the LLM risk classifier stage (default `false`). */
+    enabled?: boolean;
+    /** Model route used for classification (default `'haiku'`). */
+    route?: string;
+    /** Per-call timeout in milliseconds (default `8000`). */
+    timeoutMs?: number;
+    /** Verdict cache size in entries (default `256`). */
+    cacheMaxEntries?: number;
+}
+/** The `autoMode` section (delivered as `permissions.autoMode`). */
+export interface AutoMode {
+    /**
+     * Soft-deny hints evaluated by the classifier, in CC's snake_case spelling.
+     * `$defaults` expansion happens at consumption time in the classifier
+     * module — the schema never expands it, so merging never sees the expansion.
+     */
+    soft_deny?: string[];
+    /** LLM risk classifier configuration; absent when the section omits it. */
+    classifier?: AutoModeClassifier;
+}
+/**
+ * Schemastery schema for `autoMode.classifier`. Defaults apply only when the
+ * object itself is present (the parent uses a union-with-`undefined` so an
+ * absent key stays absent instead of materializing defaults).
+ */
+export declare const AutoModeClassifierSchema: z<AutoModeClassifier>;
+/**
+ * Schemastery schema for the `autoMode` section. The section itself stays
+ * `undefined` when absent from every settings layer — the classifier remains
+ * disarmed.
+ */
+export declare const AutoModeSchema: z<AutoMode | undefined>;
+//# sourceMappingURL=auto-mode.d.ts.map

package/lib/auto-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-mode.d.ts","sourceRoot":"","sources":["../src/auto-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,oEAAoE;AACpE,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAChC;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,kBAAkB,CAKzD,CAAA;AAgBF;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,QAAQ,GAAG,SAAS,CAGtB,CAAA"}

package/lib/auto-mode.js

@@ -0,0 +1,46 @@
+/**
+ * Claude Code-compatible `autoMode` schema — the settings surface for the LLM
+ * risk classifier (design doc §4.5). The delivery route is the `autoMode` key
+ * INSIDE the existing `permissions` namespace (`permissions.autoMode`), not a
+ * root-level key: top-level settings namespaces must be kebab-case upstream,
+ * so Claude Code's root `autoMode` location is a documented deviation (the
+ * cascade registers no root `autoMode` namespace). Exported as a standalone
+ * value so the settings cascade and the permission-rules plugin (which
+ * hand-mirrors the shape) share one definition of the section.
+ * @module @dsh-cc/settings-cascade/auto-mode
+ */
+import z from '@deepseek-ai/schemastery';
+/**
+ * Schemastery schema for `autoMode.classifier`. Defaults apply only when the
+ * object itself is present (the parent uses a union-with-`undefined` so an
+ * absent key stays absent instead of materializing defaults).
+ */
+export const AutoModeClassifierSchema = z.object({
+    enabled: z.boolean().default(false),
+    route: z.string().default('haiku'),
+    timeoutMs: z.number().default(8000),
+    cacheMaxEntries: z.number().default(256),
+});
+/**
+ * Schemastery schema for the `autoMode` section body. Unknown fields pass
+ * through unmodified, matching {@link PermissionsSchema}. Sub-keys stay
+ * absent when absent from every settings layer.
+ */
+const AutoModeSectionSchema = z.object({
+    // Union with `undefined` keeps an absent `soft_deny` key absent — no empty
+    // array is materialized (permissive array, no default).
+    soft_deny: z.union([z.array(z.string()), z.const(undefined)]),
+    // Union with `undefined` keeps an absent `classifier` key absent; a present
+    // object resolves through AutoModeClassifierSchema (defaults apply there).
+    classifier: z.union([AutoModeClassifierSchema, z.const(undefined)]),
+});
+/**
+ * Schemastery schema for the `autoMode` section. The section itself stays
+ * `undefined` when absent from every settings layer — the classifier remains
+ * disarmed.
+ */
+export const AutoModeSchema = z.union([
+    AutoModeSectionSchema,
+    z.const(undefined),
+]);
+//# sourceMappingURL=auto-mode.js.map

package/lib/auto-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-mode.js","sourceRoot":"","sources":["../src/auto-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AA0BxC;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA0B,CAAC,CAAC,MAAM,CAAC;IACtE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACnC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;CACzC,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,2EAA2E;IAC3E,wDAAwD;IACxD,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7D,4EAA4E;IAC5E,2EAA2E;IAC3E,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,wBAAwB,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;CACpE,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAA4B,CAAC,CAAC,KAAK,CAAC;IAC7D,qBAAqB;IACrB,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;CACnB,CAA4B,CAAA"}

package/lib/cc-key-aliases.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CC-key aliasing for the settings cascade: recognized Claude Code camelCase
+ * top-level keys are aliased onto dsh-native kebab-case namespaces so a
+ * `settings.json` shared verbatim with a real CC checkout resolves through
+ * `settingsNamespace`. The whitelist map is the contract — no fuzzy matching.
+ * @module @dsh-cc/settings-cascade/cc-key-aliases
+ */
+/**
+ * Explicit whitelist of CC camelCase top-level keys → dsh-native kebab-case
+ * namespaces. Unknown camelCase keys are never auto-aliased.
+ */
+export declare const CC_KEY_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Inject aliases for recognized CC keys into a merged settings document.
+ * Mutates and returns the document: a whitelisted CC key whose value is a
+ * plain object is copied onto its kebab namespace ONLY when that namespace
+ * key is absent — a dsh-native key already present wins untouched.
+ * @param document - merged settings document (aliased in place).
+ * @returns the same document, with aliases injected.
+ */
+export declare function applyCcKeyAliases(document: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=cc-key-aliases.d.ts.map

package/lib/cc-key-aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cc-key-aliases.d.ts","sourceRoot":"","sources":["../src/cc-key-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE3D,CAAA;AASD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS5F"}

package/lib/cc-key-aliases.js

@@ -0,0 +1,43 @@
+/**
+ * CC-key aliasing for the settings cascade: recognized Claude Code camelCase
+ * top-level keys are aliased onto dsh-native kebab-case namespaces so a
+ * `settings.json` shared verbatim with a real CC checkout resolves through
+ * `settingsNamespace`. The whitelist map is the contract — no fuzzy matching.
+ * @module @dsh-cc/settings-cascade/cc-key-aliases
+ */
+/**
+ * Explicit whitelist of CC camelCase top-level keys → dsh-native kebab-case
+ * namespaces. Unknown camelCase keys are never auto-aliased.
+ */
+export const CC_KEY_ALIASES = {
+    statusLine: 'statusline',
+};
+/** Whether a value is a plain data object (not an array, null, or instance). */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Inject aliases for recognized CC keys into a merged settings document.
+ * Mutates and returns the document: a whitelisted CC key whose value is a
+ * plain object is copied onto its kebab namespace ONLY when that namespace
+ * key is absent — a dsh-native key already present wins untouched.
+ * @param document - merged settings document (aliased in place).
+ * @returns the same document, with aliases injected.
+ */
+export function applyCcKeyAliases(document) {
+    for (const [ccKey, namespace] of Object.entries(CC_KEY_ALIASES)) {
+        if (!(ccKey in document))
+            continue;
+        if (namespace in document)
+            continue;
+        const value = document[ccKey];
+        if (!isPlainObject(value))
+            continue;
+        document[namespace] = structuredClone(value);
+    }
+    return document;
+}
+//# sourceMappingURL=cc-key-aliases.js.map

package/lib/cc-key-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cc-key-aliases.js","sourceRoot":"","sources":["../src/cc-key-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAqC;IAC9D,UAAU,EAAE,YAAY;CACzB,CAAA;AAED,gFAAgF;AAChF,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACrF,MAAM,KAAK,GAAY,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAA;IACnD,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAA;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAiC;IACjE,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC;YAAE,SAAQ;QAClC,IAAI,SAAS,IAAI,QAAQ;YAAE,SAAQ;QACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;QAC7B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;YAAE,SAAQ;QACnC,QAAQ,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/lib/env.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Two-phase application of the cascade's top-level `env` section. Ordinary
+ * variables apply in the first stage; environment-altering variables
+ * (`LD_PRELOAD`, `PATH`, and similar) defer to `applyTrustedEnv`, run only
+ * after the user grants trust for them. Values are coerced to strings.
+ * @module @dsh-cc/settings-cascade/env
+ */
+/** Environment variables that alter process behavior or library loading. */
+export declare const DANGEROUS_ENV_VARS: readonly string[];
+/** One parsed `env` entry: variable name to a value coerced to string on apply. */
+export type EnvSettings = Record<string, unknown>;
+/**
+ * Coerce one configured `env` value into the string a process environment
+ * carries. Numbers and booleans stringify literally; objects and arrays
+ * serialize as JSON; a string passes through unchanged.
+ * @param value - the configured raw value.
+ * @returns the string form to assign to the environment variable.
+ */
+export declare function coerceEnv(value: unknown): string;
+/**
+ * Apply the first (untrusted) stage of an `env` section: every ordinary
+ * variable is assigned, dangerous variables are held back for the trusted
+ * stage. The returned mapping is a new object; neither input is mutated.
+ * @param env - the parsed `env` section.
+ * @param target - optional existing environment mapping to merge over.
+ * @returns the next environment mapping without dangerous variables.
+ */
+export declare function applyEnv(env: EnvSettings, target?: Record<string, string>): Record<string, string>;
+/**
+ * Apply the trusted stage of an `env` section: dangerous variables are
+ * assigned together with ordinary ones. Call only after the user has granted
+ * trust for environment-altering variables.
+ * @param env - the parsed `env` section.
+ * @param target - optional existing environment mapping to merge over.
+ * @returns the complete next environment mapping including dangerous variables.
+ */
+export declare function applyTrustedEnv(env: EnvSettings, target?: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=env.d.ts.map

package/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAWtC,CAAA;AAIV,mFAAmF;AACnF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEjD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMhD;AAYD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAElG;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEzG"}

package/lib/env.js

@@ -0,0 +1,69 @@
+/**
+ * Two-phase application of the cascade's top-level `env` section. Ordinary
+ * variables apply in the first stage; environment-altering variables
+ * (`LD_PRELOAD`, `PATH`, and similar) defer to `applyTrustedEnv`, run only
+ * after the user grants trust for them. Values are coerced to strings.
+ * @module @dsh-cc/settings-cascade/env
+ */
+/** Environment variables that alter process behavior or library loading. */
+export const DANGEROUS_ENV_VARS = [
+    'LD_PRELOAD',
+    'LD_LIBRARY_PATH',
+    'DYLD_INSERT_LIBRARIES',
+    'DYLD_LIBRARY_PATH',
+    'PATH',
+    'PYTHONPATH',
+    'NODE_OPTIONS',
+    'NODE_PATH',
+    'RUBYLIB',
+    'PERL5LIB',
+];
+const DANGEROUS = new Set(DANGEROUS_ENV_VARS);
+/**
+ * Coerce one configured `env` value into the string a process environment
+ * carries. Numbers and booleans stringify literally; objects and arrays
+ * serialize as JSON; a string passes through unchanged.
+ * @param value - the configured raw value.
+ * @returns the string form to assign to the environment variable.
+ */
+export function coerceEnv(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null || value === undefined) {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+/** Write a new environment mapping from an env section merged over a base. */
+function apply(env, target, includeDangerous) {
+    const out = { ...target };
+    for (const [name, raw] of Object.entries(env)) {
+        if (!includeDangerous && DANGEROUS.has(name))
+            continue;
+        out[name] = coerceEnv(raw);
+    }
+    return out;
+}
+/**
+ * Apply the first (untrusted) stage of an `env` section: every ordinary
+ * variable is assigned, dangerous variables are held back for the trusted
+ * stage. The returned mapping is a new object; neither input is mutated.
+ * @param env - the parsed `env` section.
+ * @param target - optional existing environment mapping to merge over.
+ * @returns the next environment mapping without dangerous variables.
+ */
+export function applyEnv(env, target) {
+    return apply(env, target, false);
+}
+/**
+ * Apply the trusted stage of an `env` section: dangerous variables are
+ * assigned together with ordinary ones. Call only after the user has granted
+ * trust for environment-altering variables.
+ * @param env - the parsed `env` section.
+ * @param target - optional existing environment mapping to merge over.
+ * @returns the complete next environment mapping including dangerous variables.
+ */
+export function applyTrustedEnv(env, target) {
+    return apply(env, target, true);
+}
+//# sourceMappingURL=env.js.map

package/lib/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kBAAkB,GAAsB;IACnD,YAAY;IACZ,iBAAiB;IACjB,uBAAuB;IACvB,mBAAmB;IACnB,MAAM;IACN,YAAY;IACZ,cAAc;IACd,WAAW;IACX,SAAS;IACT,UAAU;CACF,CAAA;AAEV,MAAM,SAAS,GAAG,IAAI,GAAG,CAAS,kBAAkB,CAAC,CAAA;AAKrD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACrG,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED,8EAA8E;AAC9E,SAAS,KAAK,CAAC,GAAgB,EAAE,MAA0C,EAAE,gBAAyB;IACpG,MAAM,GAAG,GAA2B,EAAE,GAAG,MAAM,EAAE,CAAA;IACjD,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,IAAI,CAAC,gBAAgB,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAQ;QACtD,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IAC5B,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAgB,EAAE,MAA+B;IACxE,OAAO,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAA;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAgB,EAAE,MAA+B;IAC/E,OAAO,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;AACjC,CAAC"}