@asc-agent/runtime 0.1.0

package/dist/adapters/claude-code/install.js

@@ -0,0 +1,231 @@
+// Claude Host 설치물 관리 — skill · guard hook · manifest (C-03 §5.1).
+//
+// spike 결론(B-15): user-scope Skill + user-scope settings hook. Plugin을 버린 이유는
+// marketplace 관리가 더 무겁고, enforcement 안정성은 설치 위치가 아니라 hook의 판별
+// 로직이 결정하기 때문이다. 프로젝트 tracked 파일은 만들지 않는다 —
+// `.claude/settings.local.json`은 gitignore 보장이 없어 배제했다(spike 실측).
+//
+// 설치는 계약이 셋이다 (C-03 §5.1):
+//   반복 install → idempotent
+//   같은 경로의 사용자 파일 → 무단 overwrite 금지 (digest 검증)
+//   uninstall → ASC가 설치했다고 manifest로 증명되는 것만 제거
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, rmdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { hookScript } from "./guard.js";
+import { skillBundle } from "./skill.js";
+const sha = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
+export const defaultPaths = () => ({ claudeHome: join(homedir(), '.claude') });
+const HOOK_MATCHER = 'Bash';
+const HOOK_MARKER = 'asc-external-write-guard';
+function locate(paths) {
+    return {
+        /** Bundle 전체. 파일이 늘어도 아래 계약(manifest·digest·멱등)은 그대로다 (C-05 §5). */
+        skills: skillBundle().map((skill) => ({
+            name: skill.name,
+            path: join(paths.claudeHome, 'skills', skill.name, 'SKILL.md'),
+            text: skill.text,
+        })),
+        /** hook은 **하나**로 둔다. guard는 안전 층이고 중복 등록은 그 자체가 위험이다. */
+        hook: join(paths.claudeHome, 'asc', 'guard-hook.mjs'),
+        settings: join(paths.claudeHome, 'settings.json'),
+        manifest: join(paths.claudeHome, 'asc', 'install-manifest.json'),
+    };
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function install(paths, now = () => new Date().toISOString(), opts = {}) {
+    const where = locate(paths);
+    const force = opts.force ?? false;
+    const manifest = (await readJson(where.manifest)) ?? {
+        files: {},
+        settingsHook: false,
+        installedAt: now(),
+    };
+    const written = [];
+    const skipped = [];
+    // 파일 배치. **세 경우를 가른다** (아래 `fileState` 와 같은 판정이다):
+    //   지금 source와 같다        → 그대로 둔다 (idempotent)
+    //   설치 당시와 같다(stale)    → 지금 source로 수렴시킨다 — 이것이 업그레이드다
+    //   둘 다 아니다(user-modified)→ 남긴다. uninstall이 보존하는 것을 install이 지우면 안 된다
+    for (const [path, content] of [
+        ...where.skills.map((skill) => [skill.path, skill.text]),
+        [where.hook, hookScript()],
+    ]) {
+        const existing = await readFile(path, 'utf8').catch(() => null);
+        const state = fileState(existing, content, manifest.files[path]);
+        if (state === 'current') {
+            manifest.files[path] = sha(content); // 내용 동일 — manifest만 확실히 잡는다
+            continue;
+        }
+        if (state === 'modified' && !force) {
+            skipped.push({
+                path,
+                reason: manifest.files[path] === undefined
+                    ? 'a file of yours is already there — not overwriting it'
+                    : 'you edited this after install — pass --force to overwrite',
+            });
+            continue;
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, 'utf8');
+        manifest.files[path] = sha(content);
+        written.push(path);
+    }
+    // settings.json에 PreToolUse hook 등록 — ASC 항목만 다루고 나머지는 손대지 않는다
+    const settings = (await readJson(where.settings)) ?? {};
+    const hooks = (settings.hooks ?? {});
+    const preToolUse = (hooks.PreToolUse ?? []);
+    const command = hookCommand(where.hook);
+    const ours = preToolUse.filter((entry) => entry.hooks?.some((h) => h._asc === HOOK_MARKER));
+    // 등록은 돼 있는데 **다른 곳을 가리키는** 경우가 있다 — 그 상태에서 "설치됨"이라고
+    // 하면 guard가 없는데 있다고 믿는다. 우리 항목만 지금 경로로 고친다.
+    const misdirected = ours.some((entry) => entry.hooks?.some((h) => h._asc === HOOK_MARKER && h.command !== command));
+    if (ours.length === 0) {
+        preToolUse.push({ matcher: HOOK_MATCHER, hooks: [{ type: 'command', command, _asc: HOOK_MARKER }] });
+    }
+    else if (misdirected) {
+        for (const entry of ours) {
+            for (const h of entry.hooks ?? [])
+                if (h._asc === HOOK_MARKER)
+                    h.command = command;
+        }
+    }
+    if (ours.length === 0 || misdirected) {
+        settings.hooks = { ...hooks, PreToolUse: preToolUse };
+        await mkdir(dirname(where.settings), { recursive: true });
+        await writeFile(where.settings, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+        written.push(`${where.settings} (PreToolUse hook)`);
+    }
+    manifest.settingsHook = true;
+    await mkdir(dirname(where.manifest), { recursive: true });
+    await writeFile(where.manifest, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    return { written, skipped, hookRegistered: true };
+}
+/** 한 파일의 3-way 판정. install과 verify가 **같은 함수**를 쓴다 — 둘이 다르면 그게 결함이다. */
+function fileState(existing, source, recorded) {
+    if (existing === null)
+        return 'missing';
+    const now = sha(existing);
+    if (now === sha(source))
+        return 'current';
+    if (recorded !== undefined && now === recorded)
+        return 'stale';
+    return 'modified';
+}
+function hookCommand(hookPath) {
+    return `node "${hookPath}"`;
+}
+export async function verifyInstall(paths) {
+    const where = locate(paths);
+    const manifest = (await readJson(where.manifest));
+    const expected = [
+        ...where.skills.map((skill) => [skill.path, skill.text]),
+        [where.hook, hookScript()],
+    ];
+    const files = [];
+    for (const [path, content] of expected) {
+        const existing = await readFile(path, 'utf8').catch(() => null);
+        files.push({ path, state: fileState(existing, content, manifest?.files[path]) });
+    }
+    const settings = await readJson(where.settings);
+    const preToolUse = (settings?.hooks?.PreToolUse ?? []);
+    const ourHooks = preToolUse.flatMap((entry) => (entry.hooks ?? []).filter((h) => h._asc === HOOK_MARKER));
+    const hookRegistered = ourHooks.length > 0;
+    // 등록은 있는데 다른 곳을 가리키면 설치본이 뒤처진 것이다 — 없는 것으로 치지 않고 stale로 본다
+    const hookMisdirected = hookRegistered && !ourHooks.some((h) => h.command === hookCommand(where.hook));
+    const status = (() => {
+        if (!manifest && files.every((f) => f.state === 'missing') && !hookRegistered)
+            return 'NOT_INSTALLED';
+        if (!manifest || files.some((f) => f.state === 'missing') || !hookRegistered)
+            return 'BROKEN';
+        if (files.some((f) => f.state === 'modified'))
+            return 'INSTALLED_MODIFIED';
+        if (files.some((f) => f.state === 'stale') || hookMisdirected)
+            return 'INSTALLED_STALE';
+        return 'INSTALLED_CURRENT';
+    })();
+    return { status, files, hookRegistered };
+}
+/**
+ * 설치가 지금 source 그대로인가. 기존 호출부(setup 판정·probe)는 참/거짓만 필요하다.
+ * **stale도 거짓이다** — 낡은 설치본을 "설치됨"이라 부르면 L-5가 그대로 남는다.
+ */
+export async function verifyInstalled(paths) {
+    return (await verifyInstall(paths)).status === 'INSTALLED_CURRENT';
+}
+/** 사람이 읽는 줄. 상태마다 다음에 할 일이 다르므로 그것까지 말한다. */
+export function installReportLines(report) {
+    const remedy = {
+        NOT_INSTALLED: 'not installed yet — run `asc host claude install`',
+        INSTALLED_CURRENT: 'matches the current source',
+        INSTALLED_STALE: 'the installation is behind the current source — `asc host claude install` converges it',
+        INSTALLED_MODIFIED: 'you edited some installed files — leave them, or overwrite with `install --force`',
+        BROKEN: 'part of the installation is missing, or the hook is not registered — `asc host claude install`',
+    };
+    const lines = [`Install state: ${report.status} — ${remedy[report.status]}`];
+    for (const file of report.files) {
+        if (file.state === 'current')
+            continue;
+        lines.push(`  [${file.state}] ${file.path}`);
+    }
+    if (!report.hookRegistered)
+        lines.push('  [missing] PreToolUse hook registration in settings.json');
+    return lines;
+}
+/** manifest로 증명되는 것만 제거한다. 사용자가 고친 파일은 남기고 이유를 말한다. */
+export async function uninstall(paths) {
+    const where = locate(paths);
+    const manifest = (await readJson(where.manifest));
+    const removed = [];
+    const kept = [];
+    if (!manifest)
+        return { removed, kept: [{ path: where.manifest, reason: 'no manifest — nothing is recorded as installed' }] };
+    for (const [path, digest] of Object.entries(manifest.files)) {
+        const existing = await readFile(path, 'utf8').catch(() => null);
+        if (existing === null)
+            continue;
+        if (sha(existing) !== digest) {
+            kept.push({ path, reason: 'edited after install — cannot prove ASC owns it, so it stays' });
+            continue;
+        }
+        await rm(path);
+        removed.push(path);
+    }
+    // settings에서 ASC hook 항목만 걷어낸다 — 무관한 설정은 그대로
+    const settings = await readJson(where.settings);
+    if (settings?.hooks) {
+        const hooks = settings.hooks;
+        const preToolUse = (hooks.PreToolUse ?? []);
+        const filtered = preToolUse.filter((entry) => !entry.hooks?.some((h) => h._asc === HOOK_MARKER));
+        if (filtered.length !== preToolUse.length) {
+            if (filtered.length > 0)
+                hooks.PreToolUse = filtered;
+            else
+                delete hooks.PreToolUse;
+            // 우리가 만든 hooks 컨테이너가 비면 키째 걷는다 — 빈 {}도 원래 없던 흔적이다
+            if (Object.keys(hooks).length === 0)
+                delete settings.hooks;
+            await writeFile(where.settings, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+            removed.push(`${where.settings} (PreToolUse hook entry)`);
+        }
+    }
+    await rm(where.manifest, { force: true });
+    await rm(dirname(where.manifest), { recursive: true, force: true }).catch(() => { });
+    // 파일만 지우면 빈 skills/<name>/ 이 남는다 (P1 관찰 ⑥). 우리가 만든 디렉터리이므로
+    // 우리가 걷되 **비어 있을 때만** 걷는다 — rmdir은 안에 무언가 남아 있으면 실패하고,
+    // 그 경우엔 남기는 것이 맞다(사용자가 넣은 것일 수 있다).
+    for (const skill of where.skills) {
+        await rmdir(dirname(skill.path)).catch(() => { });
+    }
+    return { removed, kept };
+}

package/dist/adapters/claude-code/observer.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { ScopedStore } from '../../ports/state-store.ts';
+export declare const Heartbeat: z.ZodObject<{
+    logicalSessionId: z.ZodString;
+    /** binding의 owner. subagent가 여럿이어도 heartbeat는 Logical Session당 하나다. */
+    physicalSessionId: z.ZodString;
+    /** 실제로 관찰된 세션 — owner일 수도 workerId일 수도 있다. */
+    observedSessionId: z.ZodString;
+    lastTool: z.ZodOptional<z.ZodString>;
+    lastActivityAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    logicalSessionId: string;
+    physicalSessionId: string;
+    observedSessionId: string;
+    lastActivityAt: string;
+    lastTool?: string | undefined;
+}, {
+    logicalSessionId: string;
+    physicalSessionId: string;
+    observedSessionId: string;
+    lastActivityAt: string;
+    lastTool?: string | undefined;
+}>;
+export type Heartbeat = z.infer<typeof Heartbeat>;
+export declare const heartbeatKey: (logicalSessionId: string) => string;
+/** 읽는 쪽. 깨진 기록은 없는 것으로 친다 — 관찰값 때문에 화면이 죽으면 안 된다. */
+export declare function readHeartbeat(scope: ScopedStore, logicalSessionId: string): Promise<Heartbeat | null>;
+/**
+ * hook에 텍스트로 삽입되는 observer 본문. hook은 의존성 없는 단일 파일이어야 하므로
+ * (guard.ts 주석) 저장 계약을 여기서 하드코딩한다 — 형식이 바뀌면 이 파일과
+ * Markdown ScopedStore가 함께 움직여야 한다.
+ *
+ * 규약 셋:
+ *   - 절대 throw하지 않는다. 호출자는 try/catch로 한 번 더 감싸지만 여기서도 삼킨다.
+ *   - 아무것도 반환하지 않는다 — 호출자의 분기에 영향을 줄 값이 없어야 한다.
+ *   - tmp+rename으로 쓴다. 반쯤 쓰인 파일을 다른 프로세스가 읽지 않도록.
+ */
+export declare function observerSnippet(): string;

package/dist/adapters/claude-code/observer.js

@@ -0,0 +1,77 @@
+// Runtime Observer — hook에서 관찰되는 활동 신호 (B-18).
+//
+// Safety Guard(guard.ts)와 코드를 나눈 이유: 둘은 실패의 의미가 다르다. 차단이 실패하면
+// 막아야 할 것이 나가고, 관찰이 실패하면 화면 한 줄이 비는 것뿐이다. 같은 hook 안에서
+// 돌더라도 telemetry가 safety 판정을 흔들 수 없어야 하고, 그 경계가 파일로 보여야 한다.
+//
+// 무엇을 기록하지 않는가가 더 중요하다:
+//
+//   heartbeat는 "worker가 살아 있다"가 아니라 **"Bash가 관찰됐다"** 까지다.
+//   파일만 고치는 구간, 모델이 생각하는 구간, subagent를 기다리는 구간에는 신호가 없다 —
+//   신호가 없다는 것이 멈췄다는 뜻이 아니다. 그래서 이 값으로 inactive·stale을
+//   판정하지 않는다 (Renderer 규칙: render.ts).
+//
+// 왜 RuntimeBinding에 쓰지 않는가: binding 파일은 guard가 "이 세션이 ASC-managed인가"를
+// 판별하는 근거다. 매 Bash마다 그 파일을 다시 쓰면, 쓰기 중 읽히거나 한 번 깨졌을 때
+// 세션이 unmanaged로 보이고 외부 write 차단이 통째로 풀린다. 관찰값이 안전 판정을
+// 망가뜨리는 구조는 만들지 않는다 — 그래서 별도 키다.
+import { z } from 'zod';
+export const Heartbeat = z.object({
+    logicalSessionId: z.string().min(1),
+    /** binding의 owner. subagent가 여럿이어도 heartbeat는 Logical Session당 하나다. */
+    physicalSessionId: z.string().min(1),
+    /** 실제로 관찰된 세션 — owner일 수도 workerId일 수도 있다. */
+    observedSessionId: z.string().min(1),
+    lastTool: z.string().optional(),
+    lastActivityAt: z.string().min(1),
+});
+export const heartbeatKey = (logicalSessionId) => `heartbeat:${logicalSessionId}`;
+/** 읽는 쪽. 깨진 기록은 없는 것으로 친다 — 관찰값 때문에 화면이 죽으면 안 된다. */
+export async function readHeartbeat(scope, logicalSessionId) {
+    try {
+        const raw = await scope.get(heartbeatKey(logicalSessionId));
+        if (!raw)
+            return null;
+        const parsed = Heartbeat.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * hook에 텍스트로 삽입되는 observer 본문. hook은 의존성 없는 단일 파일이어야 하므로
+ * (guard.ts 주석) 저장 계약을 여기서 하드코딩한다 — 형식이 바뀌면 이 파일과
+ * Markdown ScopedStore가 함께 움직여야 한다.
+ *
+ * 규약 셋:
+ *   - 절대 throw하지 않는다. 호출자는 try/catch로 한 번 더 감싸지만 여기서도 삼킨다.
+ *   - 아무것도 반환하지 않는다 — 호출자의 분기에 영향을 줄 값이 없어야 한다.
+ *   - tmp+rename으로 쓴다. 반쯤 쓰인 파일을 다른 프로세스가 읽지 않도록.
+ */
+export function observerSnippet() {
+    return `
+// ── 여기부터 telemetry다 ──────────────────────────────────────────────
+// 실패해도 차단 판정에 영향이 없어야 한다. 반환값 없음, 예외 없음.
+function recordActivity(ascRoot, entry, observedSessionId, toolName) {
+  try {
+    const dir = join(ascRoot, 'adapters', 'claude-code')
+    const key = 'heartbeat:' + entry.logicalSessionId
+    const file = join(dir, key.replace(/[^A-Za-z0-9._-]/g, '-') + '.json')
+    const value = JSON.stringify({
+      logicalSessionId: entry.logicalSessionId,
+      // owner를 적는다 — workerId로 매치됐어도 소유권 기록과 어긋나면 안 된다
+      physicalSessionId: entry.physicalSessionId,
+      observedSessionId,
+      lastTool: toolName,
+      lastActivityAt: new Date().toISOString(),
+    })
+    const tmp = file + '.tmp-' + process.pid
+    writeFileSync(tmp, JSON.stringify({ key, value }, null, 2), 'utf8')
+    renameSync(tmp, file)
+  } catch {
+    // 관찰 실패는 관찰 실패일 뿐이다
+  }
+}
+`;
+}

package/dist/adapters/claude-code/probe.d.ts

@@ -0,0 +1,53 @@
+export declare const CAPABILITIES: readonly ["cross_session_message", "list_live_sessions", "notify_when_idle", "fork_subagent", "background_agent", "agent_view_json", "worktree_isolation", "goal_loop", "hooks", "remote_control", "agent_teams", "dynamic_workflows", "external_write_guard"];
+export type CapabilityName = (typeof CAPABILITIES)[number];
+export type CapabilityVerdict = {
+    available: boolean | 'unknown';
+    source: 'cli-probe' | 'host-report' | 'not-probed';
+    detail?: string;
+};
+export type ProbeResult = {
+    claudeVersion: string | null;
+    probedAt: string;
+    capabilities: Record<CapabilityName, CapabilityVerdict>;
+};
+/** 안전에 필수인 capability — 없으면 degrade가 아니라 STOP이다 (C-03 §5.2). */
+export declare const SAFETY_CRITICAL: readonly CapabilityName[];
+/**
+ * 외부 명령 한 번. 실패 이유는 구분하지 않는다 — 미설치든 비정상 종료든 "실측하지 못했다"는
+ * 같은 결론이기 때문이다.
+ */
+export type CommandRunner = (command: string, args: string[]) => Promise<{
+    ok: boolean;
+    stdout: string;
+}>;
+/**
+ * CLI에서 실측 가능한 범위의 probe. runtime tool 여부는 unknown으로 남긴다.
+ * @param guardInstalled install manifest 검증 결과 — hook이 실제로 배치·등록됐는가.
+ */
+export declare function probe(input: {
+    /** user-scope: hook 스크립트·settings 등록이 온전한가 (3층). */
+    guardInstalled: boolean;
+    /** project-scope: worker-settings.json(permissions.deny)이 준비됐는가 (2층). 프로젝트 밖이면 undefined. */
+    workerSettingsReady?: boolean;
+    now?: () => string;
+    /**
+     * 외부 명령 실행 통로. 생략하면 실제 CLI를 부른다 — 테스트가 호스트에 무엇이 깔렸는지에
+     * 좌우되지 않도록 주입만 열어 두고, 기본값은 바꾸지 않는다.
+     */
+    run?: CommandRunner;
+}): Promise<ProbeResult>;
+/**
+ * 호스트 세션(Claude 자신)이 자기 도구 목록을 보고 채우는 경로.
+ * skill이 안내하는 self-report가 여기로 들어온다.
+ */
+export declare function applyHostReport(result: ProbeResult, report: Partial<Record<CapabilityName, boolean>>, at: string): ProbeResult;
+export type Readiness = {
+    ok: true;
+    degraded: CapabilityName[];
+} | {
+    ok: false;
+    reason: 'STOP';
+    missing: CapabilityName[];
+};
+/** optional 부재는 degrade, 안전 필수 부재·unknown은 STOP (C-03 §5.2). */
+export declare function assessReadiness(result: ProbeResult): Readiness;

package/dist/adapters/claude-code/probe.js

@@ -0,0 +1,129 @@
+// Capability Probe — 버전표가 아니라 실측 (C-03 §5.2).
+//
+// 공식 Docs와 CHANGELOG가 일시적으로 다를 수 있으므로 실제 확인이 우선한다. 다만 정직해야
+// 한다: CLI에서 실행해 알 수 있는 것과, Claude 세션 안에서만 보이는 것(runtime tool)은
+// 다르다. 후자를 CLI가 아는 척하면 probe가 버전표보다 나을 게 없다. 그래서 판정마다
+// 어떻게 알았는지(source)를 함께 기록하고, 모르는 것은 unknown으로 남긴다 —
+// 호스트 세션이 자기 도구 목록을 보고 채우는 것은 별도 경로(host-report)다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+export const CAPABILITIES = [
+    'cross_session_message',
+    'list_live_sessions',
+    'notify_when_idle',
+    'fork_subagent',
+    'background_agent',
+    'agent_view_json',
+    'worktree_isolation',
+    'goal_loop',
+    'hooks',
+    'remote_control',
+    'agent_teams',
+    'dynamic_workflows',
+    'external_write_guard',
+];
+/** 안전에 필수인 capability — 없으면 degrade가 아니라 STOP이다 (C-03 §5.2). */
+export const SAFETY_CRITICAL = ['external_write_guard'];
+const tryRun = async (command, args) => {
+    try {
+        const { stdout } = await run(command, args, { timeout: 15_000 });
+        return { ok: true, stdout };
+    }
+    catch {
+        return { ok: false, stdout: '' };
+    }
+};
+/**
+ * CLI에서 실측 가능한 범위의 probe. runtime tool 여부는 unknown으로 남긴다.
+ * @param guardInstalled install manifest 검증 결과 — hook이 실제로 배치·등록됐는가.
+ */
+export async function probe(input) {
+    const at = (input.now ?? (() => new Date().toISOString()))();
+    const exec = input.run ?? tryRun;
+    const version = await exec('claude', ['--version']);
+    const claudeVersion = version.ok ? version.stdout.trim().split(/\s/)[0] ?? null : null;
+    const unknown = (detail) => ({ available: 'unknown', source: 'not-probed', detail });
+    const capabilities = {};
+    if (!claudeVersion) {
+        for (const name of CAPABILITIES)
+            capabilities[name] = unknown('claude CLI를 찾지 못했다');
+        capabilities.external_write_guard = {
+            available: false,
+            source: 'cli-probe',
+            detail: 'claude CLI가 없으면 guard 등록을 확인할 수 없다',
+        };
+        return { claudeVersion, probedAt: at, capabilities };
+    }
+    // Agent View — 실제로 실행해 본다 (read-only)
+    const agents = await exec('claude', ['agents', '--json']);
+    let agentViewDetail = 'claude agents --json 실행 실패';
+    let agentViewOk = false;
+    if (agents.ok) {
+        try {
+            JSON.parse(agents.stdout);
+            agentViewOk = true;
+            agentViewDetail = 'claude agents --json 정상 파싱';
+        }
+        catch {
+            agentViewDetail = '실행은 됐으나 JSON이 아니다';
+        }
+    }
+    capabilities.agent_view_json = { available: agentViewOk, source: 'cli-probe', detail: agentViewDetail };
+    // Agent View가 돌면 background 세션 표면도 있는 것이다
+    capabilities.background_agent = { available: agentViewOk, source: 'cli-probe', detail: 'agent_view_json에서 추론' };
+    capabilities.list_live_sessions = { available: agentViewOk, source: 'cli-probe', detail: 'agent_view_json에서 추론' };
+    // hooks — 설정 표면이 있는지는 CLI로 단정할 수 없으나, guard 설치 검증이 실질 판정이다
+    capabilities.hooks = input.guardInstalled
+        ? { available: true, source: 'cli-probe', detail: 'ASC guard hook이 등록·검증됨' }
+        : unknown('guard 미설치 — asc host claude install 후 재probe');
+    // 안전 필수: 3층 중 enforcement 두 층(hook + worker permission deny)이 실제로 서 있는가.
+    // 프로젝트 밖에서는 worker-settings를 판정할 수 없으므로 false로 둔다 — worker는
+    // 프로젝트에서 돌고, 모르는 것을 있다고 치지 않는다.
+    const workerReady = input.workerSettingsReady === true;
+    capabilities.external_write_guard = {
+        available: input.guardInstalled && workerReady,
+        source: 'cli-probe',
+        detail: !input.guardInstalled
+            ? 'guard hook 미설치 — asc host claude install'
+            : !workerReady
+                ? 'worker-settings 미준비 — attach된 프로젝트에서 asc host claude guard'
+                : 'hook(3층) + worker permission deny(2층) 검증 통과',
+    };
+    // runtime tool — Claude 세션 안에서만 보인다. 아는 척하지 않는다
+    for (const name of [
+        'cross_session_message',
+        'notify_when_idle',
+        'fork_subagent',
+        'worktree_isolation',
+        'goal_loop',
+        'remote_control',
+        'agent_teams',
+        'dynamic_workflows',
+    ]) {
+        capabilities[name] = unknown('runtime tool — 호스트 세션의 self-report(host-report)로 채운다');
+    }
+    return { claudeVersion, probedAt: at, capabilities };
+}
+/**
+ * 호스트 세션(Claude 자신)이 자기 도구 목록을 보고 채우는 경로.
+ * skill이 안내하는 self-report가 여기로 들어온다.
+ */
+export function applyHostReport(result, report, at) {
+    const merged = { ...result, probedAt: at, capabilities: { ...result.capabilities } };
+    for (const [name, available] of Object.entries(report)) {
+        // cli-probe가 이미 확정한 것은 self-report가 덮지 못한다 — 실측이 자기 보고보다 세다
+        if (merged.capabilities[name]?.source === 'cli-probe')
+            continue;
+        merged.capabilities[name] = { available, source: 'host-report' };
+    }
+    return merged;
+}
+/** optional 부재는 degrade, 안전 필수 부재·unknown은 STOP (C-03 §5.2). */
+export function assessReadiness(result) {
+    const missing = SAFETY_CRITICAL.filter((name) => result.capabilities[name]?.available !== true);
+    if (missing.length > 0)
+        return { ok: false, reason: 'STOP', missing };
+    const degraded = CAPABILITIES.filter((name) => !SAFETY_CRITICAL.includes(name) && result.capabilities[name]?.available !== true);
+    return { ok: true, degraded };
+}

package/dist/adapters/claude-code/skill.d.ts

@@ -0,0 +1,8 @@
+/** 설치 단위. 파일이 늘어도 manifest 기반 설치·제거 계약은 그대로다 (C-05 §5). */
+export declare function skillBundle(): {
+    name: string;
+    text: string;
+}[];
+export declare function skillText(): string;
+export declare function inboxSkillText(): string;
+export declare function reviewSkillText(): string;