koma-miko 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,271 @@
+# koma-miko (alpha)
+
+Deterministic skill and action contract verification for AI agent workflows.
+
+Think of each contract as an **Agent Spec**: a developer-owned executable test
+for how an agent prepares, acts, and completes work—not an enterprise policy
+console.
+
+Miko checks observable evidence at three points:
+
+1. **Prepare** — were the required skills and references loaded?
+2. **Pre-action** — is the proposed tool, risk, and path scope allowed?
+3. **Complete** — did the required tests, reviews, or artifacts actually happen?
+
+This source alpha is not published to npm yet. Its API may change before the
+first public release.
+
+## Why
+
+Agent instructions are useful guidance, but guidance is not enforcement. A skill
+may fail to activate, lose influence in a long session, or be followed initially
+while its completion checklist is skipped later. **Miko does not inspect hidden
+model state, measure whether instructions still influence a near-million-token
+context, or prove that an agent chose correctly among 100 skills.** A host
+records observable events, and Miko checks those events against explicit
+contracts.
+
+## Example
+
+The developer-facing project file is `miko.json`:
+
+```json
+{
+  "$schema": "./node_modules/koma-miko/schema/miko.schema.json",
+  "version": 1,
+  "specs": [
+    {
+      "id": "ui-change-v1",
+      "appliesWhen": {
+        "action": {
+          "tools": ["Edit", "Write"],
+          "pathPrefixes": ["src/ui"]
+        }
+      },
+      "requires": {
+        "skills": [
+          { "name": "product-design", "reloadAfterCompaction": true }
+        ]
+      },
+      "mode": "enforce"
+    }
+  ]
+}
+```
+
+The TypeScript API consumes the same spec objects directly:
+
+```ts
+import { createMiko } from 'koma-miko';
+
+const miko = createMiko({
+  contracts: [{
+    id: 'ui-change-v1',
+    // The host can activate this contract from the actual action, even when
+    // the agent forgot to label the task as UI work.
+    appliesWhen: {
+      action: {
+        tools: ['write_file'],
+        pathPrefixes: ['src/ui'],
+      },
+    },
+    requires: {
+      skills: [{ name: 'product-design', reloadAfterCompaction: true }],
+      references: ['docs/design-system.md'],
+    },
+    actions: {
+      allow: ['read_file', 'write_file', 'run_check'],
+      deny: ['delete_file'],
+      maxRisk: 'medium',
+      scope: {
+        tools: ['write_file'],
+        allowedPathPrefixes: ['src/ui'],
+      },
+    },
+    completion: {
+      evidence: [
+        { type: 'check_passed', name: 'rendered-ui-review' },
+        { type: 'check_passed', name: 'targeted-tests' },
+      ],
+    },
+    mode: 'review',
+  }],
+});
+
+miko.startTask({
+  sessionId: 'session-7',
+  taskId: 'new-settings-page',
+  tags: ['ui'],
+});
+
+// Missing preparation is REVIEW in review mode (DENY in enforce mode).
+miko.verifyPreparation('new-settings-page');
+
+miko.record({
+  taskId: 'new-settings-page',
+  type: 'skill_loaded',
+  name: 'product-design',
+  source: 'observed',
+});
+miko.record({
+  taskId: 'new-settings-page',
+  type: 'reference_read',
+  path: 'docs/design-system.md',
+  source: 'observed',
+});
+
+miko.verifyAction({
+  taskId: 'new-settings-page',
+  tool: 'write_file',
+  risk: 'medium',
+  arguments: { path: 'src/ui/Settings.tsx' },
+});
+
+// REVIEW until both completion checks have been recorded.
+miko.verifyCompletion('new-settings-page');
+```
+
+Every result is machine-readable and explainable:
+
+```ts
+{
+  decision: 'REVIEW',
+  checkpoint: 'COMPLETE',
+  reasonCode: 'COMPLETION_EVIDENCE_MISSING',
+  reason: 'Required completion evidence is missing.',
+  contractIds: ['ui-change-v1'],
+  missing: ['ui-change-v1:check_passed:rendered-ui-review']
+}
+```
+
+The plain-text renderer is intentionally developer-facing and bounded even when
+many Agent Specs overlap:
+
+```text
+🔴 Miko DENY · PREPARE — PREPARATION_EVIDENCE_MISSING
+Missing evidence:
+- ui-change-v1:skill_loaded:product-design
+Next: load the required skill/reference, then retry the blocked action.
+```
+
+## Claude Code hook mapping
+
+`toClaudePreToolUseDecision(result)` maps Miko decisions to Claude Code's
+structured `PreToolUse` output:
+
+- `ALLOW` → `allow`
+- `DENY` → `deny`
+- `REVIEW` → `ask`
+
+Non-ALLOW results also include a concise `systemMessage` for the user and
+`additionalContext` for the agent. Miko Verifier has no graphical UI: each host
+renders the same structured decision using its native text/approval surface.
+
+The included `koma-miko-claude-hook` executable provides a minimal durable
+Claude Code adapter. It observes automatic `Skill` calls, direct `/skill-name`
+expansions, `Read`, `Edit`, and `Write` events; persists a privacy-minimized
+JSONL ledger including non-ALLOW decisions; and can activate a contract from an
+observed tool/path instead of model-supplied tags. See
+[`examples/claude-code`](./examples/claude-code).
+
+Skills declared with `reloadAfterCompaction: true` become missing again after a
+Claude `PostCompact` event. The adapter keeps JSONL as the append-only audit
+record and uses a compact materialized snapshot so each Hook only replays events
+written after the latest snapshot. The ledger is auditable, not tamper-proof.
+
+To try the source alpha, build/install the package, copy the example `miko.json`
+to the project root, and merge the example hooks into
+`.claude/settings.json`. The example is intentionally not enabled automatically:
+its enforced `frontend-design` skill must actually exist in the target project.
+Miko writes session metadata under `.miko/state/`, which should stay ignored.
+Legacy `.miko/contracts.json` arrays remain readable but are no longer the
+preferred developer interface.
+
+Run an entirely offline preflight before spending model credits:
+
+```sh
+npx koma-miko doctor
+npx koma-miko doctor --strict --json
+```
+
+Doctor validates Agent Specs and reports project Skill discovery, required
+Claude Hook coverage, and whether `.miko/state/` is ignored. It never calls a
+model or reads an API key.
+
+Claude Code's local CLI, Desktop Code tab, and VS Code/Cursor extension share
+settings, hooks, and skills. Cloud/remote sessions have different configuration
+sources, and managed policies can disable project hooks, so adapters must expose
+their detected capabilities rather than promise identical behavior everywhere.
+See the official [platform overview](https://code.claude.com/docs/en/platforms),
+[Desktop shared configuration](https://code.claude.com/docs/en/desktop), and
+[VS Code settings](https://code.claude.com/docs/en/ide-integrations).
+
+## Automated replay
+
+`npm run eval:replay -w koma-miko` runs ten simplified skill contracts without
+an API key. For every skill it verifies three cases: missing evidence, an agent
+claim (`asserted`), and a host-observed load (`observed`). Only observed or
+external evidence can satisfy a contract. The first UI case is the narrow
+enforcement demo; the other nine remain review-only.
+`npm run eval:claude-hook -w koma-miko` additionally spawns three independent
+hook processes and verifies an audited `DENY → observed Skill → ALLOW` plus
+ledger privacy.
+`npm run eval:scale -w koma-miko` uses no API key. It benchmarks 100/1,000 Agent
+Specs, 10,000 indexed evidence events, 100 overlapping specs, and snapshot
+restore while checking that terminal output remains bounded.
+`npm run eval:audit-demo -w koma-miko` regenerates the 13-event fixture behind
+the public guided CLI simulation from real Verifier results.
+`eval:audit-demo:check` detects a stale fixture without changing it; the replay
+contains no prompt, code, or model response and needs no backend. The friendly
+terminal story is presentation only; expandable raw events preserve reason
+codes, provenance, and contract IDs for inspection.
+
+With `ANTHROPIC_API_KEY` set in the parent process,
+`npm run eval:claude-live -w koma-miko` runs one disposable, real Claude Code
+fixture. It exposes only `Read`, `Edit`, and `Skill`, defaults to Haiku, enforces
+a `$0.10` per-run cap, and checks this sequence:
+
+```text
+Read → Miko DENY → Claude loads frontend-design → Miko allows → Edit
+```
+
+The fixture is created inside the package workspace so Claude Code treats it as
+project content, then deleted. The runner never reads an env file. Override the
+defaults with `MIKO_LIVE_MODEL` and `MIKO_LIVE_MAX_BUDGET_USD` (capped by the
+runner at `$1`).
+
+For the 100-Skill long-context fixture, start without spending credits:
+
+```sh
+npm run eval:claude-scale-dry -w koma-miko
+```
+
+Then run one approximately 20k-token Haiku case with a `$0.12` hard cap:
+
+```sh
+MIKO_LIVE_CONTEXT_TOKENS=20000 \
+MIKO_LIVE_MAX_BUDGET_USD=0.12 \
+MIKO_LIVE_CAMPAIGN_BUDGET_USD=0.12 \
+npm run eval:claude-scale-live -w koma-miko
+```
+
+The runner accepts at most three comma-separated context sizes from 1,000 to
+190,000 tokens. It creates exactly 100 project Skills, exposes only
+`Read`/`Edit`/`Skill`, runs in a disposable directory, records cache and cost
+metrics, and never reads an env file. See the
+[alpha evaluation record](../../docs/evals/miko-claude-haiku-alpha.md).
+
+## Alpha boundaries
+
+- **No LLM call or semantic task classifier**
+- **No planner, router, or agent runtime**
+- **No context-window/token monitoring**
+- **One Haiku/100-Skill fixture has passed at approximately 20k tokens; this is not evidence for 100k, 190k, or near-million-token behavior**
+- **No hosted telemetry service** (the Claude adapter uses a local JSONL ledger)
+- **No automatic rewriting of tool calls**
+- **No claim that loading a skill proves the model understood, retained, or followed it**
+
+See the [design and discovery notes](../../docs/design/miko.md), including the
+first-hand failure case, public reports used as test discovery data, and the
+post-alpha questions. Product positioning and executable follow-up work live in
+the [developer roadmap](../../docs/design/miko-roadmap.md).

package/README.zh-CN.md

@@ -0,0 +1,233 @@
+# koma-miko（alpha）
+
+面向 AI agent 工作流的确定性 skill / action 契约验证器。
+
+可以把每份 Contract 理解成开发者维护的 **Agent Spec（智能体测试用例）**：
+它像测试代码一样约束 agent 如何准备、行动和完成任务，而不是企业治理控制台。
+
+Miko 在三个可观察节点检查证据：
+
+1. **准备阶段** — 必需的 skill 和参考文档是否真的被加载；
+2. **动作之前** — 工具、风险等级与路径范围是否符合契约；
+3. **完成之前** — 测试、UI 渲染检查或其他交付义务是否真的执行。
+
+当前是源码 alpha，尚未发布到 npm；首次公开发布前 API 仍可能调整。
+
+## 为什么
+
+Agent 指令是有用的引导，但不等于强制约束。Skill 可能没有被自动触发，
+也可能在长会话中逐渐失去影响，或者 agent 前半段遵守规则、结束时却跳过
+测试清单。**Miko 不检查隐藏的模型状态，无法测量指令在接近百万 token 的
+上下文中是否仍有影响，也无法证明 agent 能从 100 个 Skill 中选对一个。**
+宿主记录可观察事件，Miko 根据明确契约验证这些证据。
+
+## 最小示例
+
+开发者直接维护项目根目录的 `miko.json`：
+
+```json
+{
+  "$schema": "./node_modules/koma-miko/schema/miko.schema.json",
+  "version": 1,
+  "specs": [
+    {
+      "id": "ui-change-v1",
+      "appliesWhen": {
+        "action": {
+          "tools": ["Edit", "Write"],
+          "pathPrefixes": ["src/ui"]
+        }
+      },
+      "requires": {
+        "skills": [
+          { "name": "product-design", "reloadAfterCompaction": true }
+        ]
+      },
+      "mode": "enforce"
+    }
+  ]
+}
+```
+
+TypeScript API 可以直接使用同一批 Spec 对象：
+
+```ts
+import { createMiko } from 'koma-miko';
+
+const miko = createMiko({
+  contracts: [{
+    id: 'ui-change-v1',
+    appliesWhen: {
+      action: {
+        tools: ['write_file'],
+        pathPrefixes: ['src/ui'],
+      },
+    },
+    requires: {
+      skills: [{ name: 'product-design', reloadAfterCompaction: true }],
+      references: ['docs/design-system.md'],
+    },
+    actions: {
+      allow: ['read_file', 'write_file', 'run_check'],
+      deny: ['delete_file'],
+      maxRisk: 'medium',
+      scope: {
+        tools: ['write_file'],
+        allowedPathPrefixes: ['src/ui'],
+      },
+    },
+    completion: {
+      evidence: [
+        { type: 'check_passed', name: 'rendered-ui-review' },
+        { type: 'check_passed', name: 'targeted-tests' },
+      ],
+    },
+    mode: 'review',
+  }],
+});
+
+miko.startTask({
+  sessionId: 'session-7',
+  taskId: 'new-settings-page',
+  tags: ['ui'],
+});
+
+// 未记录 product-design 与 design-system 时返回 REVIEW。
+miko.verifyPreparation('new-settings-page');
+
+miko.record({
+  taskId: 'new-settings-page',
+  type: 'skill_loaded',
+  name: 'product-design',
+  source: 'observed',
+});
+miko.record({
+  taskId: 'new-settings-page',
+  type: 'reference_read',
+  path: 'docs/design-system.md',
+  source: 'observed',
+});
+
+miko.verifyAction({
+  taskId: 'new-settings-page',
+  tool: 'write_file',
+  risk: 'medium',
+  arguments: { path: 'src/ui/Settings.tsx' },
+});
+
+// 直到完成证据齐全前都返回 REVIEW。
+miko.verifyCompletion('new-settings-page');
+```
+
+`mode: 'review'` 会把缺失证据映射为 `REVIEW`；`mode: 'enforce'` 则映射为
+`DENY`。明确越权的工具、风险或路径在两种模式下都会返回 `DENY`。
+
+终端文字采用有阶段含义、且长度受限的开发者红绿灯；即使许多 Agent Spec
+重叠，也只展开最重要的前三项：
+
+```text
+🔴 Miko DENY · PREPARE — PREPARATION_EVIDENCE_MISSING
+Missing evidence:
+- ui-change-v1:skill_loaded:product-design
+Next: load the required skill/reference, then retry the blocked action.
+```
+
+`toClaudePreToolUseDecision(result)` 可将 `ALLOW / DENY / REVIEW` 映射到
+Claude Code `PreToolUse` 的 `allow / deny / ask`。非 ALLOW 结果还会同时
+向用户显示精简文字，并把恢复提示交给 agent。Miko Verifier 本身不带图形 UI；
+CLI、桌面端或 IDE 使用各自原生的文字与审批界面渲染同一结构化结果。
+
+包内的 `koma-miko-claude-hook` 提供最小可用的持久化 Claude Code 适配器：
+它观察自动 `Skill` 调用、用户直接输入的 `/skill-name`、`Read`、`Edit` 与
+`Write` 事件；使用仅含必要元数据、并记录非 ALLOW 决策的本地 JSONL 账本；
+并可根据真实工具与路径激活合约，不再只相信模型提供的任务标签。配置示例见
+[`examples/claude-code`](./examples/claude-code)。
+
+设置 `reloadAfterCompaction: true` 的 Skill 会在 Claude `PostCompact` 后重新
+变为缺失。adapter 保留 append-only JSONL 作为审计记录，同时使用紧凑 snapshot，
+每次 Hook 只需回放 snapshot 之后的尾部事件。该账本便于审计，但并非防篡改账本。
+
+试用源码 alpha 时，先构建/安装该包，把示例 `miko.json` 复制到项目根目录，
+再把示例 Hook 合并进 `.claude/settings.json`。
+示例不会自动启用，因为目标项目中必须真实存在被强制要求的
+`frontend-design` Skill。会话元数据写入 `.miko/state/`，该目录应保持忽略。
+旧 `.miko/contracts.json` 数组仍可读取，但不再是推荐的开发者入口。
+
+花费模型额度前，先运行完全离线的预检：
+
+```sh
+npx koma-miko doctor
+npx koma-miko doctor --strict --json
+```
+
+Doctor 会验证 Agent Spec，并报告项目 Skill、Claude Hook 覆盖范围以及
+`.miko/state/` 是否已忽略；它不会调用模型，也不会读取 API key。
+
+Claude Code 本地 CLI、Desktop Code tab 与 VS Code/Cursor 扩展共享 settings、
+Hooks 和 Skills；云端/远程会话的配置来源不同，企业策略也可能禁用项目 Hook，
+因此适配器应报告实际能力，而不是承诺所有表面完全一致。参见官方
+[平台概览](https://code.claude.com/docs/en/platforms)、
+[Desktop 共享配置](https://code.claude.com/docs/en/desktop) 与
+[VS Code 配置](https://code.claude.com/docs/en/ide-integrations)。
+
+## 自动化回放
+
+`npm run eval:replay -w koma-miko` 无需 API key，即可运行十个极简 Skill
+合约。每个 Skill 都验证三种情况：没有证据、agent 自述（`asserted`）以及
+宿主观察到的加载（`observed`）。只有 observed 或 external 证据能满足合约。
+第一个 UI 案例是窄范围强制演示，其余九个保持 review-only。
+`npm run eval:claude-hook -w koma-miko` 还会启动三个彼此独立的 Hook 进程，
+验证带审计记录的 `DENY → 观察到 Skill → ALLOW`，并确认账本没有保存代码内容。
+`npm run eval:scale -w koma-miko` 不需要 API key；它会测试 100/1,000 份
+Agent Spec、10,000 条索引证据、100 份重叠 Spec、snapshot 恢复和终端输出上限。
+`npm run eval:audit-demo -w koma-miko` 会用真实 Verifier 结果重新生成公开 CLI
+引导演示背后的 13 个事件；`eval:audit-demo:check` 只检查 fixture 是否过期。
+回放不包含 prompt、代码或模型回复，也不需要后端。终端故事只是展示层；可展开
+的原始事件仍保留 reason code、provenance 与 contract ID，供技术读者检查。
+
+父进程设置好 `ANTHROPIC_API_KEY` 后，
+`npm run eval:claude-live -w koma-miko` 会运行一个可自动删除的真实 Claude Code
+fixture。它只暴露 `Read`、`Edit` 与 `Skill`，默认使用 Haiku，单次硬上限为
+`$0.10`，并验证：
+
+```text
+Read → Miko DENY → Claude 加载 frontend-design → Miko 放行 → Edit
+```
+
+fixture 建在包工作区内，使 Claude Code 把它视为项目内容，结束后删除。runner
+不会自行读取任何 env 文件。可用 `MIKO_LIVE_MODEL` 与
+`MIKO_LIVE_MAX_BUDGET_USD` 覆盖默认值（runner 最高只接受 `$1`）。
+
+100 Skills 长上下文 fixture 应先离线检查，不消耗额度：
+
+```sh
+npm run eval:claude-scale-dry -w koma-miko
+```
+
+然后再运行约 20k-token、硬上限 `$0.12` 的单次 Haiku 测试：
+
+```sh
+MIKO_LIVE_CONTEXT_TOKENS=20000 \
+MIKO_LIVE_MAX_BUDGET_USD=0.12 \
+MIKO_LIVE_CAMPAIGN_BUDGET_USD=0.12 \
+npm run eval:claude-scale-live -w koma-miko
+```
+
+runner 最多接受三个以逗号分隔、范围为 1,000–190,000 的上下文档位；它会生成
+恰好 100 个项目 Skills，仅暴露 `Read`/`Edit`/`Skill`，在一次性目录运行并记录
+cache、turn 与成本。runner 不会读取 env 文件。结果见
+[alpha 评估记录](../../docs/evals/miko-claude-haiku-alpha.md)。
+
+## Alpha 边界
+
+- **不调用 LLM，不做语义任务分类；**
+- **不是 planner、router 或 agent runtime；**
+- **不监控 context window 或 token；**
+- **100-Skills fixture 仅在约 20k tokens 的一次 Haiku 测试中通过；这不能代表 100k、190k 或近百万 token 的行为；**
+- **暂无托管遥测和云端策略服务；** Claude 适配器仅使用本地 JSONL 账本；
+- **不自动改写工具调用；**
+- **不声称“加载过 Skill”就等于模型理解、持续记住或遵守了 Skill。**
+
+研究案例、契约模型和 alpha 后问题见
+[设计文档](../../docs/design/miko.md)；产品定位与可执行 TODO 见
+[开发者路线图](../../docs/design/miko-roadmap.md)。

package/dist/claude-code.d.ts

@@ -0,0 +1,42 @@
+import type { AdvanceContextResult, EvidenceEvent, Miko, RiskLevel, VerificationResult } from './index.js';
+interface ClaudeHookBase {
+    session_id: string;
+    cwd: string;
+    hook_event_name: string;
+}
+export interface ClaudePreToolUseInput extends ClaudeHookBase {
+    hook_event_name: 'PreToolUse';
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+}
+export interface ClaudePostToolUseInput extends ClaudeHookBase {
+    hook_event_name: 'PostToolUse';
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+}
+export interface ClaudeUserPromptExpansionInput extends ClaudeHookBase {
+    hook_event_name: 'UserPromptExpansion';
+    expansion_type: 'slash_command' | 'mcp_prompt';
+    command_name: string;
+}
+export interface ClaudePostCompactInput extends ClaudeHookBase {
+    hook_event_name: 'PostCompact';
+    trigger?: 'manual' | 'auto';
+}
+export type ClaudeHookInput = ClaudePreToolUseInput | ClaudePostToolUseInput | ClaudeUserPromptExpansionInput | ClaudePostCompactInput | ClaudeHookBase;
+export interface ClaudeHookHandlingResult {
+    output?: object;
+    evidence: EvidenceEvent[];
+    verification?: VerificationResult;
+    contextAdvance?: AdvanceContextResult;
+}
+export declare function toProjectRelativePath(value: string, cwd: string): string;
+export declare function riskForClaudeTool(tool: string): RiskLevel;
+export declare function evidenceFromClaudeEvent(input: ClaudeHookInput): EvidenceEvent[];
+/**
+ * Handles the host-specific surface while leaving persistence to the caller.
+ * No prompt, file contents, Bash command, or model response is copied into evidence.
+ */
+export declare function handleClaudeHookEvent(miko: Miko, taskId: string, input: ClaudeHookInput): ClaudeHookHandlingResult;
+export {};
+//# sourceMappingURL=claude-code.d.ts.map

package/dist/claude-code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../src/claude-code.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,IAAI,EACJ,SAAS,EACT,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAGpB,UAAU,cAAc;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,eAAe,EAAE,YAAY,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,eAAe,EAAE,aAAa,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,8BAA+B,SAAQ,cAAc;IACpE,eAAe,EAAE,qBAAqB,CAAC;IACvC,cAAc,EAAE,eAAe,GAAG,YAAY,CAAC;IAC/C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,eAAe,EAAE,aAAa,CAAC;IAC/B,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,eAAe,GACvB,qBAAqB,GACrB,sBAAsB,GACtB,8BAA8B,GAC9B,sBAAsB,GACtB,cAAc,CAAC;AAEnB,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAQD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAYxE;AAmCD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAIzD;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,aAAa,EAAE,CAqC/E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,eAAe,GACrB,wBAAwB,CAoC1B"}

package/dist/claude-code.js

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import { formatMikoDecision, toClaudePreToolUseDecision } from './index.js';
+const PATH_KEYS = ['file_path', 'path', 'filePath'];
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function toProjectRelativePath(value, cwd) {
+    const normalizedValue = value.replace(/\\/g, '/');
+    const normalizedCwd = cwd.replace(/\\/g, '/').replace(/\/$/, '');
+    if (normalizedValue === normalizedCwd)
+        return '.';
+    if (normalizedValue.startsWith(`${normalizedCwd}/`)) {
+        return normalizedValue.slice(normalizedCwd.length + 1);
+    }
+    if (path.isAbsolute(value)) {
+        const relative = path.relative(cwd, value).replace(/\\/g, '/');
+        return relative.startsWith('../') || relative === '..' ? normalizedValue : relative;
+    }
+    return normalizedValue.replace(/^\.\//, '');
+}
+function relativeToolInput(input, cwd) {
+    const next = { ...input };
+    for (const key of PATH_KEYS) {
+        if (nonEmptyString(next[key]))
+            next[key] = toProjectRelativePath(next[key], cwd);
+    }
+    return next;
+}
+function privacySafeArguments(input, cwd) {
+    const safe = {};
+    for (const key of PATH_KEYS) {
+        if (nonEmptyString(input[key]))
+            safe[key] = toProjectRelativePath(input[key], cwd);
+    }
+    return Object.keys(safe).length > 0 ? safe : undefined;
+}
+function pathFromInput(input, cwd) {
+    const value = PATH_KEYS.map((key) => input[key]).find(nonEmptyString);
+    return value ? toProjectRelativePath(value, cwd) : undefined;
+}
+function skillFromToolInput(input) {
+    return ['skill', 'name', 'command_name']
+        .map((key) => input[key])
+        .find(nonEmptyString);
+}
+function skillFromReadPath(filePath) {
+    const parts = filePath.replace(/\\/g, '/').split('/').filter(Boolean);
+    if (parts.at(-1)?.toLowerCase() !== 'skill.md' || parts.length < 2)
+        return undefined;
+    return parts.at(-2);
+}
+export function riskForClaudeTool(tool) {
+    if (tool === 'Bash' || tool.startsWith('mcp__'))
+        return 'high';
+    if (tool === 'Edit' || tool === 'Write')
+        return 'medium';
+    return 'low';
+}
+export function evidenceFromClaudeEvent(input) {
+    if (input.hook_event_name === 'UserPromptExpansion') {
+        const event = input;
+        if (event.expansion_type === 'slash_command' && nonEmptyString(event.command_name)) {
+            return [{ type: 'skill_loaded', name: event.command_name, source: 'observed' }];
+        }
+        return [];
+    }
+    if (input.hook_event_name !== 'PostToolUse')
+        return [];
+    const event = input;
+    const evidence = [];
+    if (event.tool_name === 'Skill') {
+        const skill = skillFromToolInput(event.tool_input);
+        if (skill)
+            evidence.push({ type: 'skill_loaded', name: skill, source: 'observed' });
+    }
+    const filePath = pathFromInput(event.tool_input, event.cwd);
+    if (event.tool_name === 'Read' && filePath) {
+        evidence.push({ type: 'reference_read', path: filePath, source: 'observed' });
+        const skill = skillFromReadPath(filePath);
+        if (skill)
+            evidence.push({ type: 'skill_loaded', name: skill, source: 'observed' });
+    }
+    if ((event.tool_name === 'Edit' || event.tool_name === 'Write') && filePath) {
+        evidence.push({ type: 'artifact_changed', path: filePath, source: 'observed' });
+    }
+    evidence.push({
+        type: 'tool_succeeded',
+        tool: event.tool_name,
+        ...(privacySafeArguments(event.tool_input, event.cwd)
+            ? { arguments: privacySafeArguments(event.tool_input, event.cwd) }
+            : {}),
+        source: 'observed',
+    });
+    return evidence;
+}
+/**
+ * Handles the host-specific surface while leaving persistence to the caller.
+ * No prompt, file contents, Bash command, or model response is copied into evidence.
+ */
+export function handleClaudeHookEvent(miko, taskId, input) {
+    const evidence = evidenceFromClaudeEvent(input);
+    for (const event of evidence)
+        miko.record({ taskId, ...event });
+    if (input.hook_event_name === 'PostCompact') {
+        return {
+            evidence,
+            contextAdvance: miko.advanceContext(taskId, 'compaction'),
+        };
+    }
+    if (input.hook_event_name === 'PreToolUse') {
+        const event = input;
+        if (event.tool_name === 'Skill')
+            return { evidence };
+        const verification = miko.verifyAction({
+            taskId,
+            tool: event.tool_name,
+            risk: riskForClaudeTool(event.tool_name),
+            arguments: relativeToolInput(event.tool_input, event.cwd),
+        });
+        return { output: toClaudePreToolUseDecision(verification), evidence, verification };
+    }
+    if (input.hook_event_name === 'Stop') {
+        const verification = miko.verifyCompletion(taskId);
+        if (verification.decision !== 'ALLOW') {
+            return {
+                output: { systemMessage: formatMikoDecision(verification) },
+                evidence,
+                verification,
+            };
+        }
+        return { evidence, verification };
+    }
+    return { evidence };
+}
+//# sourceMappingURL=claude-code.js.map