aptly 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aptly contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,45 @@
+# Aptly
+
+[한국어](README.md) · **English** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
+
+**A local MCP server that selects Claude Code and Codex subagent models and reasoning effort to suit the task.**
+
+Aptly classifies a minimal task summary with the OpenAI Decisions API and recommends an allowlisted execution profile. Its installed Hook can automatically select defaults for fresh, general-purpose subagents without explicit choices. The host retains control of execution and permissions.
+
+## Quick start
+
+Use Node.js **24 or later** and Claude Code or Codex. This is an **MIT-licensed local 0.1.0 package draft**, not a release published to the npm registry. Replace the archive path below with the actual reviewed archive.
+
+```sh
+npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
+./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+```
+
+During installation, `postinstall` registers the MCP server and a `PreToolUse` Hook in existing host configuration directories. Run `setup` explicitly if automatic registration was skipped or a host has no configuration directory yet. Other settings and Hooks, and any existing Aptly launch command and environment, are preserved.
+
+Pass the classification key, `OPENAI_API_KEY`, to the MCP process through a secure execution environment. Do not put it in command arguments, requests, configuration JSON, or the repository. Restart the host or MCP server, then **review and trust the new Hook through `/hooks` in Codex**. See [installation, keys, and registration](docs/guide/en.md#installation).
+
+## Usage modes
+
+| Mode | Behavior |
+|---|---|
+| Automatic Hook | Selects defaults for fresh, general-purpose calls without an explicit model, effort, fixed role, inherited history, or resume target |
+| Direct recommendation | Returns a profile through `recommend_agent` or `aptly recommend`; review it and decide separately whether to run it in the host |
+| fixture | Tests recommendations generated by local rules without a key or network access; these are not actual Decisions results |
+
+Automatic selection targets Codex calls with `fork_turns: "none"` and Claude Code calls with `subagent_type: "general-purpose"`. Explicit choices, insufficient context, and authentication or connection errors leave the original call unchanged. A recommendation does not verify model access or the host's complete configuration.
+
+## Documentation
+
+- [User guide](docs/guide/en.md): installation and removal, keys, Hooks, direct recommendations, and error recovery
+- [Installation and removal](docs/guide/en.md#installation): local archives, host registration, restarting, and trust review
+- [Models and environment variables](docs/guide/en.md#models-and-environment-variables): six default profiles and candidate configuration
+- [Providing context](docs/guide/en.md#providing-context): encrypted messages and repository URL limitations
+- [Cost benchmark](docs/guide/en.md#cost-benchmark): tokens, converted costs, and measurement scope for a README translation review
+- [Diagnostics and development](docs/guide/en.md#diagnostics-and-development): local reports and checks without paid API calls
+
+Korean is the canonical documentation. The English, Simplified Chinese, and Japanese documents cover the same usage scope. Choosing a documentation language does not change the language of CLI or MCP output.
+
+## License
+
+[MIT](LICENSE).

package/README.ja.md

@@ -0,0 +1,45 @@
+# Aptly
+
+[한국어](README.md) · [English](README.en.md) · [简体中文](README.zh-CN.md) · **日本語**
+
+**タスクに適した Claude Code・Codex のサブエージェント用モデルと effort を選ぶローカル MCP です。**
+
+Aptly は必要最小限のタスク要約を OpenAI Decisions API で分類し、あらかじめ許可された実行プロファイルを推薦します。インストールした Hook は、明示的な指定のない新しい汎用サブエージェントのデフォルト値を自動で選択できます。サブエージェントの実行と権限に関する判断は、既存のホストが行います。
+
+## クイックスタート
+
+Node.js **24 以上**と Claude Code または Codex が必要です。現在は **MIT ライセンスの 0.1.0 ローカルパッケージ案**で、npm registry にはまだ公開していません。確認済みのアーカイブの実際のパスに置き換えてインストールしてください。
+
+```sh
+npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
+./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+```
+
+インストール時の `postinstall` は、既存のホスト設定ディレクトリに MCP と `PreToolUse` Hook を登録します。自動登録をスキップした場合や、ホストに設定ディレクトリがまだない場合も、`setup` を明示的に実行して登録できます。他の既存設定・Hook と、既存の Aptly の実行コマンド・環境は保持します。
+
+分類用の `OPENAI_API_KEY` は、安全な実行環境から MCP プロセスに渡してください。キーをコマンドライン・リクエスト・設定 JSON・リポジトリに記載しないでください。ホストまたは MCP を再起動した後、**Codex では `/hooks` で新しい Hook を確認し、信頼を承認**してください。[インストール・キー・登録の詳細](docs/guide/ja.md#インストール)を確認してください。
+
+## 使用方法
+
+| 方法 | 動作 |
+|---|---|
+| 自動 Hook | モデル・effort・固定ロール・履歴継承・resume の指定がない、新しい汎用呼び出しのデフォルト値を選びます |
+| 直接推薦 | `recommend_agent` または `aptly recommend` でプロファイルを受け取り、実行するかどうかをホストで明示的に判断します |
+| fixture | キーやネットワークを使わず、ローカルで生成した試験用の推薦を確認できます。実際の Decisions の結果ではありません |
+
+自動選択の対象は、Codex の `fork_turns: "none"`、Claude Code の `subagent_type: "general-purpose"` の呼び出しです。明示的な指定や、コンテキスト不足・認証・接続エラーがある場合は、元の呼び出しの引数を変更しません。推薦されたというだけでは、モデルへのアクセス権限やホストの設定全体が確認されたことにはなりません。
+
+## ドキュメント
+
+- [使用ガイド](docs/guide/ja.md): インストール・削除、キー、Hook、直接推薦、エラー復旧
+- [インストール・削除](docs/guide/ja.md#インストール): ローカルアーカイブ、ホスト登録、再起動と信頼の承認
+- [モデルと環境変数](docs/guide/ja.md#モデルと環境変数): 6 つのデフォルトプロファイルと候補の設定
+- [コンテキストの提供](docs/guide/ja.md#コンテキストの提供): 暗号化されたメッセージとリポジトリ URL の制約
+- [費用実測](docs/guide/ja.md#費用実測): README 翻訳レビューのトークン・換算費用と測定範囲
+- [診断・開発](docs/guide/ja.md#診断と開発): ローカル report と無料の検証コマンド
+
+韓国語版が正本です。英語・簡体字中国語・日本語のドキュメントは同じ使用範囲を説明しており、ドキュメントの言語を選んでも CLI・MCP の出力言語は変わりません。
+
+## ライセンス
+
+[MIT](LICENSE)。

package/README.md

@@ -0,0 +1,45 @@
+# Aptly
+
+**한국어** · [English](README.en.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
+
+**작업에 맞는 Claude Code·Codex 서브에이전트 모델과 effort를 선택하는 로컬 MCP입니다.**
+
+Aptly는 최소한의 작업 요약을 OpenAI Decisions API로 분류하고 허용된 실행 프로필을 추천합니다. 설치한 Hook은 명시 선택이 없는 새 일반 서브에이전트의 기본값을 자동으로 선택할 수 있습니다. 실제 실행과 권한 결정은 기존 호스트가 담당합니다.
+
+## 빠른 시작
+
+Node.js **24 이상**과 Claude Code 또는 Codex가 필요합니다. 현재는 **MIT 라이선스의 0.1.0 로컬 패키지 초안**이며 npm 레지스트리에 게시하지 않았습니다. 검토한 아카이브의 실제 경로로 바꿔 설치하십시오.
+
+```sh
+npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
+./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+```
+
+설치 시 `postinstall`은 기존 호스트 설정 디렉터리에 MCP와 `PreToolUse` Hook을 등록합니다. 명시적인 `setup`은 자동 등록을 건너뛰었거나 아직 설정 디렉터리가 없는 호스트에도 사용할 수 있습니다. 기존 다른 설정·Hook과 기존 Aptly 실행 명령·환경은 보존합니다.
+
+분류용 `OPENAI_API_KEY`는 안전한 실행 환경에서 MCP 프로세스에 전달하십시오. 키를 명령행·요청·설정 JSON·저장소에 기록하지 마십시오. 호스트 또는 MCP를 재시작한 뒤, **Codex에서는 `/hooks`에서 새 Hook을 검토하고 신뢰를 승인하십시오.** [설치·키·등록 상세](docs/guide/ko.md#설치)를 참고하십시오.
+
+## 사용 방식
+
+| 방식 | 동작 |
+|---|---|
+| 자동 Hook | 모델·effort·고정 역할·이력 상속·resume을 지정하지 않은 새 일반 호출의 기본값을 선택합니다 |
+| 직접 추천 | `recommend_agent` 또는 `aptly recommend`로 프로필을 받고 호스트에서 명시적으로 실행합니다 |
+| fixture | 키·네트워크 없이 시험용 추천을 확인합니다. 실제 Decisions 결과가 아닙니다 |
+
+자동 선택 대상은 Codex의 `fork_turns: "none"`, Claude Code의 `subagent_type: "general-purpose"` 호출입니다. 명시 선택이나 맥락 부족·인증·연결 오류가 있으면 원래 호출을 유지합니다. 추천은 모델 접근 권한이나 호스트 전체 설정의 확인을 뜻하지 않습니다.
+
+## 문서
+
+- [사용 가이드](docs/guide/ko.md): 설치·제거, 키, Hook, 직접 추천, 오류 복구
+- [설치·제거](docs/guide/ko.md#설치): 로컬 아카이브, 호스트 등록, 재시작과 신뢰 승인
+- [모델과 환경변수](docs/guide/ko.md#모델과-환경변수): 여섯 기본 프로필과 후보 설정
+- [맥락 전달](docs/guide/ko.md#맥락-전달): 암호화된 메시지와 저장소 URL의 한계
+- [비용 실측](docs/guide/ko.md#비용-실측): README 번역 검토의 토큰·환산 비용과 측정 범위
+- [진단·개발](docs/guide/ko.md#진단과-개발): 로컬 진단 보고서와 무료 검증 명령
+
+한국어가 정본입니다. 영어·중국어 간체·일본어 문서는 같은 사용 범위를 설명하며, 문서 언어가 CLI·MCP 출력 언어를 바꾸지는 않습니다.
+
+## 라이선스
+
+[MIT](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,45 @@
+# Aptly
+
+[한국어](README.md) · [English](README.en.md) · **简体中文** · [日本語](README.ja.md)
+
+**用于为 Claude Code 和 Codex 子代理选择合适模型与推理强度（effort）的本地 MCP 服务器。**
+
+Aptly 使用 OpenAI Decisions API 对简要任务摘要进行分类，并推荐允许使用的执行配置。安装 Hook 后，可为未明确指定配置的新建通用子代理自动选择默认值。实际执行与权限决策仍由宿主（Claude Code 或 Codex）负责。
+
+## 快速开始
+
+需要 Node.js **24 或更高版本**，以及 Claude Code 或 Codex。目前是**采用 MIT 许可证的 0.1.0 本地软件包草案**，尚未发布到 npm registry。请将示例路径替换为已审核归档文件的实际路径。
+
+```sh
+npm install --prefix ./aptly-local /absolute/path/aptly-0.1.0.tgz
+./aptly-local/node_modules/.bin/aptly setup --client all --mode defaults
+```
+
+安装时的 `postinstall` 会在现有宿主配置目录中注册 MCP 和 `PreToolUse` Hook。如果跳过了自动注册，或宿主尚无配置目录，也可以显式运行 `setup`。其他现有配置与 Hook，以及 Aptly 原有的启动命令和环境均会保留。
+
+请通过安全的运行环境，将分类用的 `OPENAI_API_KEY` 传递给 MCP 进程。不要将密钥写入命令行、请求、配置 JSON 或代码仓库。重启宿主或 MCP 后，**请在 Codex 的 `/hooks` 中审核新 Hook 并批准信任**。详见[安装、密钥与注册](docs/guide/zh-CN.md#安装)。
+
+## 使用方式
+
+| 方式 | 行为 |
+|---|---|
+| 自动 Hook | 为未指定模型、effort、固定角色、历史继承或 resume 的新建通用调用选择默认值 |
+| 直接推荐 | 通过 `recommend_agent` 或 `aptly recommend` 获取执行配置，再在宿主中明确选择并执行 |
+| fixture | 无需密钥或网络即可测试本地模拟推荐；结果并非实际 Decisions 判断 |
+
+自动选择适用于 Codex 的 `fork_turns: "none"` 调用和 Claude Code 的 `subagent_type: "general-purpose"` 调用。如果已有明确选择，或发生上下文不足、认证或连接错误，则保留原始调用。推荐结果并不表示已确认账户的模型访问权限，也不表示已核实宿主的全部配置。
+
+## 文档
+
+- [使用指南](docs/guide/zh-CN.md)：安装与移除、密钥、Hook、直接推荐、错误恢复
+- [安装与移除](docs/guide/zh-CN.md#安装)：本地归档、宿主注册、重启与信任批准
+- [模型与环境变量](docs/guide/zh-CN.md#模型与环境变量)：六个默认配置与候选设置
+- [提供上下文](docs/guide/zh-CN.md#提供上下文)：加密消息与仓库 URL 的限制
+- [成本实测](docs/guide/zh-CN.md#成本实测)：README 翻译审阅的 token、换算成本与测量范围
+- [诊断与开发](docs/guide/zh-CN.md#诊断与开发)：本地诊断报告与免费验证命令
+
+韩语文档为正本，英语、简体中文和日语文档与其保持相同的使用范围。选择文档语言不会改变 CLI 或 MCP 的输出语言。
+
+## 许可证
+
+[MIT](LICENSE)。

package/dist/bin/aptly.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/aptly.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { serve } from '../src/server.js';
+import { runtime } from '../src/runtime.js';
+import { explainSettings } from '../src/inspect.js';
+import { VERSION } from '../src/version.js';
+import { collectDiagnostics } from '../src/diagnostics.js';
+import { exportDiagnosticReport } from '../src/report.js';
+import { fetchModelInfo, saveModelInfo } from '../src/model-info.js';
+import { errorCode } from '../src/types.js';
+import { setupHosts, removeSetup } from '../src/setup.js';
+const [command = 'serve', ...args] = process.argv.slice(2);
+const output = (value) => process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+try {
+    if (['--help', '-h', 'help'].includes(command)) {
+        process.stdout.write('Aptly (preview)\n\nCommands:\n  serve                 Start the stdio MCP server (default: fixture/shadow).\n  capabilities          Print the active catalog; no API call.\n  catalog               Print the active catalog; no API call.\n  catalog refresh --output ABS_PATH  Fetch official model descriptions to a private cache.\n  recommend             Recommend for a task JSON on stdin; no host evidence required.\n  inspect CLIENT FILE   Inspect an explicit JSON settings inventory; no API call.\n  config CLIENT         Print an MCP registration fragment; does not edit settings.\n  setup                 Register MCP and automatic PreToolUse Hooks.\n  remove                Remove only unchanged Aptly-owned registration.\n  report                Write redacted local diagnostic attachments (default: md + json).\n    --format md|json|both  Select report formats.\n    --output-dir DIR      Private output directory (default: reports).\n  --version             Print the package version.\n\nSet OPENAI_API_KEY only in the MCP environment. Paid mode additionally requires\nROUTER_PROVIDER=decisions and an absolute ROUTER_LEDGER_PATH in a private directory.\nROUTER_CONFIG_PATH is an optional private operator configuration file.\n');
+    }
+    else if (command === '--version')
+        process.stdout.write(VERSION + '\n');
+    else if (command === 'report' && args.length === 1 && args[0] === '--help') {
+        process.stdout.write('Usage: aptly report [--format md|json|both] [--output-dir DIR]\nDefault: both formats in a private reports directory. No uploads or API probes.\n');
+    }
+    else if (command === 'report') {
+        const options = { format: 'both', outputDir: 'reports' };
+        const seen = new Set();
+        for (let i = 0; i < args.length; i++) {
+            const flag = args[i];
+            if (!['--format', '--output-dir'].includes(flag) || seen.has(flag) || !args[i + 1] || args[i + 1].startsWith('--'))
+                throw Object.assign(new Error('report_invalid_options'), { code: 'report_invalid_options' });
+            seen.add(flag);
+            options[flag === '--format' ? 'format' : 'outputDir'] = args[++i];
+        }
+        if (!['md', 'json', 'both'].includes(options.format))
+            throw Object.assign(new Error('report_invalid_options'), { code: 'report_invalid_options' });
+        output(exportDiagnosticReport({ diagnostic: collectDiagnostics(), ...options }));
+    }
+    else if (['setup', 'remove'].includes(command)) {
+        if (args.length === 1 && args[0] === '--help')
+            process.stdout.write('Usage: aptly setup [--client codex|claude|all] [--mode defaults|advisory] [--automatic]\n       aptly remove [--client codex|claude|all]\nSetup merges MCP and PreToolUse registration. Codex requires native /hooks trust review.\nAutomatic setup skips CI, APTLY_SKIP_SETUP=1, and absent host directories. No keys are stored.\n');
+        else {
+            let clients = ['codex', 'claude'];
+            let mode = 'defaults';
+            let automatic = false;
+            const seen = new Set();
+            for (let i = 0; i < args.length; i++) {
+                const flag = args[i];
+                if (seen.has(flag))
+                    throw new Error('setup_invalid_options');
+                seen.add(flag);
+                if (flag === '--automatic' && command === 'setup') {
+                    automatic = true;
+                    continue;
+                }
+                const value = args[++i];
+                if (flag === '--client' && ['codex', 'claude', 'all'].includes(value))
+                    clients = value === 'all' ? ['codex', 'claude'] : [value];
+                else if (flag === '--mode' && command === 'setup' && ['defaults', 'advisory'].includes(value))
+                    mode = value;
+                else
+                    throw new Error('setup_invalid_options');
+            }
+            const packageRoot = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../' : '../../', import.meta.url));
+            const result = command === 'setup' ? setupHosts({ clients, mode, automatic, packageRoot }) : removeSetup({ clients });
+            output(result);
+            if (result.status === 'partial' && !automatic)
+                process.exitCode = 1;
+        }
+    }
+    else if (command === 'serve' && args.length === 0)
+        await serve();
+    else if ((command === 'capabilities' || command === 'catalog') && args.length === 0) {
+        const { router, mode, modelInfo, disabledClients } = runtime();
+        output({ ...router.capabilities(), provider: mode, model_information: { status: modelInfo.status, account_access_verified: false }, disabled_clients: disabledClients });
+    }
+    else if (command === 'catalog' && args.length === 3 && args[0] === 'refresh' && args[1] === '--output') {
+        const snapshot = await fetchModelInfo();
+        saveModelInfo(args[2], snapshot);
+        output({ status: 'refreshed', facts: snapshot.facts.length, sources: snapshot.sources, account_access_verified: false });
+    }
+    else if (command === 'catalog' && args.length === 1 && args[0] === '--help') {
+        process.stdout.write('Usage: aptly catalog\n       aptly catalog refresh --output /absolute/private/model-info.json\nSet APTLY_MODEL_INFO_PATH to load the cache at server startup. No account access is certified.\n');
+    }
+    else if (command === 'recommend' && args.length === 1 && args[0] === '--help') {
+        process.stdout.write('Usage: aptly recommend < request.json\nRequired: request_id, client (codex|claude), task {summary, operation, context_sufficient}.\nOptional: eligible_profile_ids (defaults to client catalog), constraints (declared pins only).\nRecommendations are advisory_only; no host settings are inspected or changed.\nSee examples/recommend.codex.json and examples/recommend.claude.json.\n');
+    }
+    else if (command === 'recommend' && args.length === 0) {
+        const raw = readFileSync(0, 'utf8');
+        if (Buffer.byteLength(raw) > 16384)
+            throw new Error('input_too_large');
+        const { router, mode } = runtime();
+        output({ ...await router.advise(JSON.parse(raw)), provider: mode });
+    }
+    else if (command === 'inspect' && args.length === 2 && ['codex', 'claude'].includes(args[0])) {
+        const raw = readFileSync(args[1], 'utf8');
+        if (Buffer.byteLength(raw) > 65536)
+            throw new Error('input_too_large');
+        const inventory = JSON.parse(raw);
+        output(explainSettings({ ...inventory, client: args[0] }));
+    }
+    else if (command === 'config' && args.length === 1 && ['codex', 'claude'].includes(args[0])) {
+        const node = process.execPath, server = fileURLToPath(new URL(`../src/server${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+        if (args[0] === 'claude')
+            output({ mcpServers: { 'aptly': { command: node, args: [server], env: { ROUTER_PROVIDER: 'fixture' } } } });
+        else
+            process.stdout.write('[mcp_servers.aptly]\ncommand = ' + JSON.stringify(node) + '\nargs = [' + JSON.stringify(server) + ']\nenv_vars = ["OPENAI_API_KEY", "ROUTER_PROVIDER", "ROUTER_LEDGER_PATH", "ROUTER_CONFIG_PATH", "APTLY_CLAUDE_MODELS", "APTLY_CODEX_MODELS", "CLAUDE_MODELS", "CODEX_MODELS", "APTLY_MODEL_INFO_PATH"]\n');
+    }
+    else {
+        process.stderr.write('aptly: invalid_command (use --help)\n');
+        process.exitCode = 2;
+    }
+}
+catch (error) {
+    const codes = ['report_invalid_options', 'report_invalid_diagnostic', 'report_invalid_format', 'report_already_exists', 'report_output_unavailable'];
+    const caughtCode = errorCode(error);
+    const safeConfigurationCodes = ['catalog_configuration_invalid', 'catalog_configuration_conflict', 'catalog_environment_typo', 'catalog_facts_invalid', 'model_info_fetch_failed', 'model_info_unavailable', 'model_info_invalid', 'model_info_output_unavailable', 'model_info_path_invalid', 'model_info_refresh_failed', 'model_info_options_invalid', 'model_info_too_large', 'model_info_timeout', 'model_info_parse_failed', 'model_info_save_failed'];
+    const message = error instanceof Error ? error.message : undefined;
+    const configCode = [caughtCode, message].find(value => typeof value === 'string' && safeConfigurationCodes.includes(value));
+    const code = command === 'report' ? (caughtCode && codes.includes(caughtCode) ? caughtCode : 'report_failed') : configCode ?? 'operation_failed';
+    process.stderr.write('aptly: ' + code + '\n');
+    process.exitCode = 1;
+}

package/dist/src/automatic-hook.d.ts

@@ -0,0 +1,42 @@
+import { Router } from './core.ts';
+import type { HookOutput } from './hook.ts';
+export interface AutoPolicy {
+    schema_version: 1;
+    kind: 'aptly-auto-hook';
+    mode: 'defaults' | 'advisory';
+    issuer: 'operator_installation';
+    enabled: boolean;
+    state_directory: string;
+}
+export interface AutomaticHookObservation {
+    status: 'applied' | 'advisory' | 'preserved';
+    reason: string;
+    profile_id?: string;
+    request_id?: string;
+}
+export interface AutomaticHookResult {
+    output: HookOutput | {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse';
+            additionalContext: string;
+        };
+    };
+    observation: AutomaticHookObservation;
+}
+export interface AutomaticHookOptions {
+    client: unknown;
+    event: unknown;
+    router: Router;
+    /** Internal configuration only: callers read APTLY_HOOK_POLICY_PATH, never MCP arguments. */
+    policyPath?: unknown;
+    signal?: AbortSignal;
+    /** A caller may revoke the pending event; absence does not certify native dispatch. */
+    stillCurrent?: () => boolean | Promise<boolean>;
+}
+export declare function loadAutomaticHookPolicy(path: unknown): {
+    policy: AutoPolicy | null;
+    reason: string;
+    fingerprint?: string;
+};
+/** Operator default selection only. No provenance_verified/evidence_verified host claim. */
+export declare function automaticHook({ client, event, router, policyPath, signal, stillCurrent }: AutomaticHookOptions): Promise<AutomaticHookResult>;

package/dist/src/automatic-hook.js

@@ -0,0 +1,232 @@
+/** Explicit operator-installed Hook policy. This does not certify host settings. */
+import { createHash } from 'node:crypto';
+import { closeSync, openSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { Router } from './core.js';
+import { assertPrivateStatePath, readRegularFile } from './files.js';
+import { hookInput, hookOutput } from './hook.js';
+import { digestToolInput } from './provenance.js';
+const own = (object, key) => Object.hasOwn(object, key);
+const plain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const safeText = (value, max) => typeof value === 'string' && !!value.trim() && Buffer.byteLength(value) <= max;
+const sensitive = (value) => /\bsk-[A-Za-z0-9_-]{12,}|\bBearer\s+[A-Za-z0-9._~+\/-]{8,}={0,2}/i.test(value);
+const policyKeys = ['schema_version', 'kind', 'mode', 'issuer', 'enabled', 'state_directory'];
+export function loadAutomaticHookPolicy(path) {
+    if (path === undefined)
+        return { policy: null, reason: 'automatic_policy_missing' };
+    try {
+        assertPrivateStatePath(path);
+        const value = JSON.parse(readRegularFile(path, { privateFile: true, maxBytes: 4096 }).toString('utf8'));
+        if (!plain(value) || Object.keys(value).length !== policyKeys.length || Object.keys(value).some(key => !policyKeys.includes(key)) ||
+            value.schema_version !== 1 || value.kind !== 'aptly-auto-hook' || (typeof value.mode !== 'string' || !['defaults', 'advisory'].includes(value.mode)) ||
+            value.issuer !== 'operator_installation' || typeof value.enabled !== 'boolean' ||
+            typeof value.state_directory !== 'string' || !isAbsolute(value.state_directory))
+            throw new Error('invalid_policy');
+        // Validate an existing private state directory, without creating a path from untrusted event data.
+        assertPrivateStatePath(join(value.state_directory, '.aptly-state-check'));
+        const policy = Object.fromEntries(policyKeys.map(key => [key, value[key]]));
+        return { policy, fingerprint: hash(policy), reason: policy.enabled ? 'automatic_policy_enabled' : 'automatic_policy_disabled' };
+    }
+    catch {
+        return { policy: null, reason: 'automatic_policy_invalid' };
+    }
+}
+function readCall(client, event) {
+    try {
+        if ((client !== 'codex' && client !== 'claude') || !plain(event) || event.hook_event_name !== 'PreToolUse' ||
+            !safeText(event.session_id, 256) || !safeText(event.tool_use_id ?? event.tool_call_id, 512) ||
+            !(client === 'codex' ? ['spawn_agent', 'collaborationspawn_agent', 'Agent'] : ['Agent']).includes(String(event.tool_name)) ||
+            Buffer.byteLength(JSON.stringify(event)) > 65536)
+            return null;
+        const digest = digestToolInput({ client, event });
+        if (!digest)
+            return null;
+        let input = event.tool_input;
+        if (typeof input === 'string') {
+            if (client !== 'claude' || Buffer.byteLength(input) > 16384)
+                return null;
+            input = JSON.parse(input);
+        }
+        if (!plain(input))
+            return null;
+        return { client, event, input, digest,
+            payloadDigest: hash([digest, event.tool_name, event.cwd ?? null, event.turn_id ?? null, event.turnId ?? null]),
+            callKey: hash(['aptly-auto-hook-call-v1', client, event.session_id, event.tool_use_id ?? event.tool_call_id]) };
+    }
+    catch {
+        return null;
+    }
+}
+function preservation(call) {
+    const input = call.input;
+    if (own(input, 'model'))
+        return 'explicit_model';
+    if (['effort', 'reasoning_effort', 'model_reasoning_effort'].some(key => own(input, key)))
+        return 'explicit_effort';
+    if (['resume', 'resume_agent', 'agent_id'].some(key => own(input, key)))
+        return 'resumed_agent';
+    if (['role', 'agent_type'].some(key => own(input, key)) ||
+        (call.client === 'claude' && input.subagent_type !== 'general-purpose'))
+        return 'fixed_role';
+    if (['fork_context', 'fork', 'fork_session', 'inherit_history'].some(key => own(input, key)) ||
+        (call.client === 'codex' ? input.fork_turns !== 'none' : own(input, 'fork_turns')))
+        return 'inherited_fork';
+    return null;
+}
+function catalogFingerprint(policy) {
+    return hash([policy.version, policy.catalog_version, policy.provider_id ?? null, policy.profiles, policy.profile_descriptions ?? {}]);
+}
+function boundedSummary(call, maxBytes) {
+    const label = call.input[call.client === 'codex' ? 'task_name' : 'description'];
+    const body = call.input[call.client === 'codex' ? 'message' : 'prompt'];
+    if (typeof body !== 'string' || !body.trim())
+        return { reason: 'insufficient_context' };
+    // Check the entire bounded native body before clipping, so truncation cannot hide a key.
+    if (sensitive(body) || (typeof label === 'string' && sensitive(label)))
+        return { reason: 'sensitive_input' };
+    // Some Codex transports expose an opaque message to PreToolUse. Never decode
+    // it or forward it to the provider: a sufficiently descriptive visible name
+    // is a separate, explicitly labelled source of task advice only.
+    if (call.client === 'codex' && /^gAAAA[A-Za-z0-9_-]{75,}={0,2}$/.test(body)) {
+        if (!safeText(label, 512) || Buffer.byteLength(label) < 24 || !/^[a-z0-9]+(?:_[a-z0-9]+)*$/.test(label))
+            return { reason: 'insufficient_context' };
+        const words = label.split('_');
+        if (words.length < 6 || words.filter(word => /^[a-z]{2,}$/.test(word)).length < 3)
+            return { reason: 'insufficient_context' };
+        const summary = `Task summary from visible task_name only; opaque message not inspected: ${words.join(' ')}`;
+        if (Buffer.byteLength(summary) > Math.min(4000, maxBytes))
+            return { reason: 'insufficient_context' };
+        return { summary };
+    }
+    const first = body.trim().split(/\r?\n\s*\r?\n/, 1)[0];
+    if (first.length < 12 || first.trim().split(/\s+/u).length < 3 || (typeof label === 'string' && first.trim() === label.trim()))
+        return { reason: 'insufficient_context' };
+    const prefix = safeText(label, 512) ? `Task: ${label.trim()}\n` : '';
+    const budget = Math.min(4000, maxBytes) - Buffer.byteLength(prefix);
+    if (budget < 64)
+        return { reason: 'insufficient_context' };
+    // Clip by Unicode code point; never emit invalid UTF-8 at a byte boundary.
+    let clipped = '', bytes = 0;
+    for (const point of first) {
+        const size = Buffer.byteLength(point);
+        if (bytes + size > budget)
+            break;
+        clipped += point;
+        bytes += size;
+    }
+    return { summary: prefix + clipped };
+}
+function bindCall(call, policy, policyFingerprint, catalog) {
+    const binding = { schema_version: 1, input_digest: call.digest, payload_digest: call.payloadDigest, policy_fingerprint: policyFingerprint, catalog_fingerprint: catalog,
+        request_id: hash(['aptly-auto-hook-v1', call.callKey, call.payloadDigest, policyFingerprint, catalog]) };
+    const path = join(policy.state_directory, `hook-call-${call.callKey}.json`);
+    let fd;
+    try {
+        assertPrivateStatePath(path);
+        try {
+            fd = openSync(path, 'wx', 0o600);
+        }
+        catch (error) {
+            if (!plain(error) && !(error instanceof Error))
+                throw error;
+            if (error.code !== 'EEXIST')
+                throw error;
+            const previous = JSON.parse(readRegularFile(path, { privateFile: true, maxBytes: 2048 }).toString('utf8'));
+            if (!plain(previous) || Object.keys(previous).length !== Object.keys(binding).length ||
+                Object.entries(binding).some(([key, value]) => previous[key] !== value))
+                return { reason: 'call_conflict' };
+            return { request_id: binding.request_id };
+        }
+        // Immutable metadata is persisted before a potentially paid classification. A partial
+        // write fails closed on the next invocation rather than issuing a replacement ID.
+        writeFileSync(fd, JSON.stringify(binding));
+        return { request_id: binding.request_id };
+    }
+    catch {
+        return { reason: 'automatic_state_unavailable' };
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Operator default selection only. No provenance_verified/evidence_verified host claim. */
+export async function automaticHook({ client, event, router, policyPath, signal, stillCurrent }) {
+    const preserve = (reason, request_id) => ({ output: {}, observation: { status: 'preserved', reason, ...(request_id ? { request_id } : {}) } });
+    try {
+        const loaded = loadAutomaticHookPolicy(policyPath);
+        if (!loaded.policy || !loaded.policy.enabled || !loaded.fingerprint)
+            return preserve(loaded.reason);
+        const call = readCall(client, event);
+        if (!call)
+            return preserve('invalid_event');
+        const pinned = preservation(call);
+        if (pinned)
+            return preserve(pinned);
+        // Synthetic fixture output must never select a native child's defaults.
+        if (loaded.policy.mode === 'defaults' && router.policy.provider_id !== 'decisions')
+            return preserve('synthetic_provider');
+        const summary = boundedSummary(call, router.policy.max_summary_bytes);
+        if (!summary.summary)
+            return preserve(summary.reason ?? 'insufficient_context');
+        if (signal?.aborted || (stillCurrent && await stillCurrent() !== true))
+            return preserve('call_cancelled');
+        // Installing an operator policy must not bypass a historical strict-path
+        // unknown/complete record for this same native call with a new paid ID.
+        const beforePaid = readCall(client, event), policyBeforePaid = loadAutomaticHookPolicy(policyPath);
+        if (!beforePaid || beforePaid.callKey !== call.callKey || beforePaid.payloadDigest !== call.payloadDigest)
+            return preserve('call_changed');
+        if (!policyBeforePaid.policy?.enabled || policyBeforePaid.fingerprint !== loaded.fingerprint)
+            return preserve('automatic_policy_changed');
+        const legacyId = hookInput({ client, event, policy: router.policy })?.request_id ??
+            hash([call.client, call.event.session_id, call.event.tool_use_id ?? call.event.tool_call_id]);
+        try {
+            router.load();
+        }
+        catch {
+            return preserve('ledger_error');
+        }
+        if (own(router.state.requests, legacyId))
+            return preserve('legacy_request_exists', legacyId);
+        const catalog = catalogFingerprint(router.policy);
+        const bound = bindCall(call, loaded.policy, loaded.fingerprint, catalog);
+        if (!bound.request_id)
+            return preserve(bound.reason ?? 'automatic_state_unavailable');
+        const request_id = bound.request_id;
+        const snapshot = structuredClone(call.event);
+        const recommendation = await router.advise({ request_id, client: call.client,
+            task: { summary: summary.summary, operation: 'analysis', context_sufficient: true },
+            eligible_profile_ids: router.policy.profiles.filter(profile => profile.client === call.client).map(profile => profile.id),
+            constraints: { model_pinned: false, effort_pinned: false, role_pinned: false, fork_inherits: false },
+        });
+        if (signal?.aborted || (stillCurrent && await stillCurrent() !== true))
+            return preserve('call_cancelled', request_id);
+        const current = readCall(client, event), policyNow = loadAutomaticHookPolicy(policyPath);
+        if (!current || current.callKey !== call.callKey || current.digest !== call.digest || current.payloadDigest !== call.payloadDigest)
+            return preserve('call_changed', request_id);
+        if (!policyNow.policy?.enabled || policyNow.fingerprint !== loaded.fingerprint)
+            return preserve('automatic_policy_changed', request_id);
+        if (catalogFingerprint(router.policy) !== catalog)
+            return preserve('catalog_changed', request_id);
+        // The existing narrow catalog/tuple validator is reused. This local flag is an
+        // operator-policy decision, never a claim about complete host-setting evidence.
+        const candidate = hookOutput({ client, event: snapshot, recommendation, mode: 'apply', compatibilityVerified: true, policy: router.policy });
+        if (!candidate.hookSpecificOutput || recommendation.status !== 'recommended') {
+            const allowed = ['preserved_constraints', 'unsupported_profile', 'invalid_response', 'invalid_choice', 'provider_abstained', 'no_candidates', 'insufficient_context',
+                'provider_needs_context', 'budget_exhausted', 'concurrency_limit', 'ledger_locked', 'request_conflict', 'outcome_unknown', 'ledger_error', 'timeout', 'refused',
+                'truncated', 'invalid_json', 'unauthorized', 'rate_limited', 'network', 'provider_error', 'sensitive_input', 'invalid_input'];
+            return preserve(allowed.includes(recommendation.reason) ? recommendation.reason : 'recommendation_unavailable', request_id);
+        }
+        const profile = router.policy.profiles.find(profile => profile.id === recommendation.profile_id && profile.client === call.client);
+        if (loaded.policy.mode === 'advisory')
+            return { output: { hookSpecificOutput: { hookEventName: 'PreToolUse',
+                        additionalContext: `Aptly suggests ${profile.model}${profile.reasoning_effort ? ` with ${profile.reasoning_effort} reasoning effort` : ''} for this task (${profile.id}). This is task advice; the host retains execution and permission decisions.` } },
+                observation: { status: 'advisory', reason: 'operator_policy_advice', profile_id: profile.id, request_id } };
+        return { output: candidate, observation: { status: 'applied', reason: 'operator_policy_defaults', profile_id: profile.id, request_id } };
+    }
+    catch {
+        return preserve('automatic_hook_unavailable');
+    }
+}

package/dist/src/catalog.d.ts

@@ -0,0 +1,19 @@
+import type { Client, Profile } from './types.ts';
+/** Bounded official capability text only; this is not host availability evidence. */
+export interface ModelFact {
+    client: Client;
+    model: string;
+    description: string;
+}
+export interface ResolvedCatalog {
+    profiles: Profile[];
+    descriptions: Record<string, string>;
+    version: string;
+    disabled_clients: Client[];
+}
+/** Fresh copies prevent caller mutation from changing the trusted registry. */
+export declare function builtInProfiles(): Profile[];
+/** Exact finite profile tuples, including key coverage, not arbitrary model strings. */
+export declare function isSupportedProfile(value: unknown): value is Profile;
+/** Operator candidate filters and model facts never grant execution authority. */
+export declare function resolveCatalog(env?: NodeJS.ProcessEnv, facts?: ModelFact[]): ResolvedCatalog;