usesteady 0.1.0-alpha.1

package/dist/src/claude/adapters/stub-adapter.js

@@ -0,0 +1,114 @@
+/**
+ * Claude Stub Adapter — Phase 8B.
+ *
+ * ── Role ──────────────────────────────────────────────────────────────────────
+ *
+ *   The stub adapter is the first concrete implementation of ClaudeAgentPlugin.
+ *   It proves that the mechanism-agnostic contract works — the same delivery gate
+ *   operates identically whether the plugin returns a response immediately (stub)
+ *   or asynchronously (real Anthropic API client).
+ *
+ * ── Transport proof ───────────────────────────────────────────────────────────
+ *
+ *   ClaudeStubAdapter proves all three delivery paths:
+ *     - accepted:                       stub returns ClaudeAccepted
+ *     - refused_due_to_scope:           stub returns ClaudeRefusedDueToScope
+ *     - refused_due_to_execution_error: stub returns ClaudeRefusedDueToExecutionError
+ *
+ *   The gate does not change behavior based on which adapter is used.
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   In tests:
+ *     const plugin = ClaudeStubAdapter.accepted("session-xyz");
+ *     const gate   = new ClaudeDeliveryGate(plugin, storeDir, deps);
+ *     const result = await gate.deliver(approvedArtifact);
+ *     expect(result.outcome).toBe("accepted");
+ *
+ *   For a configurable sequence (scope refusal then accept):
+ *     const plugin = ClaudeStubAdapter.sequence([
+ *       ClaudeStubAdapter.scopeRefusalResponse({ questionKind: "need_file_path", ... }),
+ *       ClaudeStubAdapter.acceptedResponse("session-abc"),
+ *     ]);
+ *
+ * ── What this is NOT ──────────────────────────────────────────────────────────
+ *
+ *   This is not a fake Anthropic API. It does not execute tasks, read files,
+ *   or produce real agent outputs. It is purely for proving the delivery gate
+ *   contract works against all three response kinds.
+ *
+ * See: src/claude/delivery-gate.ts — ClaudeAgentPlugin interface
+ */
+// ─── Stub adapter ─────────────────────────────────────────────────────────────
+/**
+ * A configurable in-process ClaudeAgentPlugin.
+ *
+ * Configured at construction with a fixed response or a sequence of responses.
+ * Returns responses immediately (no async delay).
+ * Throws if a call is made beyond the configured responses.
+ */
+export class ClaudeStubAdapter {
+    responses;
+    callIndex = 0;
+    constructor(responses) {
+        if (responses.length === 0) {
+            throw new Error("ClaudeStubAdapter: responses must not be empty");
+        }
+        this.responses = responses;
+    }
+    async receive(request) {
+        const response = this.responses[this.callIndex];
+        if (response === undefined) {
+            throw new Error(`ClaudeStubAdapter: no response configured for call index ${this.callIndex} ` +
+                `(deliveryId=${request.deliveryId})`);
+        }
+        this.callIndex++;
+        return response;
+    }
+    /** How many times receive() has been called. */
+    get callCount() { return this.callIndex; }
+    // ─── Factory methods ───────────────────────────────────────────────────────
+    /** Adapter that always returns "accepted" with the given sessionId. */
+    static accepted(sessionId = "stub-session-id") {
+        return new ClaudeStubAdapter([ClaudeStubAdapter.acceptedResponse(sessionId)]);
+    }
+    /** Adapter that returns a scope refusal with the given question. */
+    static refusedScope(question) {
+        return new ClaudeStubAdapter([ClaudeStubAdapter.scopeRefusalResponse(question)]);
+    }
+    /** Adapter that returns an execution error with the given code. */
+    static refusedError(code = "stub_error", message = "Stub execution error.") {
+        return new ClaudeStubAdapter([ClaudeStubAdapter.executionErrorResponse(code, message)]);
+    }
+    /** Adapter that simulates a session interruption (A3: non-resumable). */
+    static sessionInterrupted() {
+        return new ClaudeStubAdapter([
+            ClaudeStubAdapter.executionErrorResponse("session_interrupted", "Claude managed session was interrupted. Non-resumable in V1."),
+        ]);
+    }
+    /** Adapter that returns responses in sequence. Throws if exhausted. */
+    static sequence(responses) {
+        return new ClaudeStubAdapter(responses);
+    }
+    // ─── Response builders ─────────────────────────────────────────────────────
+    static acceptedResponse(sessionId = "stub-session-id") {
+        return {
+            kind: "accepted",
+            sessionId,
+        };
+    }
+    static scopeRefusalResponse(question) {
+        return {
+            kind: "refused_due_to_scope",
+            question,
+        };
+    }
+    static executionErrorResponse(code = "stub_error", message = "Stub execution error.") {
+        return {
+            kind: "refused_due_to_execution_error",
+            code,
+            message,
+        };
+    }
+}
+//# sourceMappingURL=stub-adapter.js.map

package/dist/src/claude/adapters/stub-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-adapter.js","sourceRoot":"","sources":["../../../../src/claude/adapters/stub-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAYH,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,OAAO,iBAAiB;IACX,SAAS,CAA2B;IAC7C,SAAS,GAAG,CAAC,CAAC;IAEtB,YAAY,SAAmC;QAC7C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAA8B;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,4DAA4D,IAAI,CAAC,SAAS,GAAG;gBAC7E,eAAe,OAAO,CAAC,UAAU,GAAG,CACrC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,gDAAgD;IAChD,IAAI,SAAS,KAAa,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAElD,8EAA8E;IAE9E,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,SAAS,GAAG,iBAAiB;QAC3C,OAAO,IAAI,iBAAiB,CAAC,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,oEAAoE;IACpE,MAAM,CAAC,YAAY,CAAC,QAA6B;QAC/C,OAAO,IAAI,iBAAiB,CAAC,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACnF,CAAC;IAED,mEAAmE;IACnE,MAAM,CAAC,YAAY,CAAC,IAAI,GAAG,YAAY,EAAE,OAAO,GAAG,uBAAuB;QACxE,OAAO,IAAI,iBAAiB,CAAC,CAAC,iBAAiB,CAAC,sBAAsB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,kBAAkB;QACvB,OAAO,IAAI,iBAAiB,CAAC;YAC3B,iBAAiB,CAAC,sBAAsB,CACtC,qBAAqB,EACrB,8DAA8D,CAC/D;SACF,CAAC,CAAC;IACL,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,SAAmC;QACjD,OAAO,IAAI,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,8EAA8E;IAE9E,MAAM,CAAC,gBAAgB,CAAC,SAAS,GAAG,iBAAiB;QACnD,OAAO;YACL,IAAI,EAAO,UAAU;YACrB,SAAS;SACV,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,oBAAoB,CAAC,QAA6B;QACvD,OAAO;YACL,IAAI,EAAM,sBAAsB;YAChC,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,sBAAsB,CAC3B,IAAI,GAAM,YAAY,EACtB,OAAO,GAAG,uBAAuB;QAEjC,OAAO;YACL,IAAI,EAAE,gCAAgC;YACtC,IAAI;YACJ,OAAO;SACR,CAAC;IACJ,CAAC;CACF"}

package/dist/src/claude/artifact-mapper.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Claude artifact mapper — Phase 8B.
+ *
+ * ── Role ──────────────────────────────────────────────────────────────────────
+ *
+ *   Translates an IntakeResult (mode === "execute") into a ClaudeAgentHandoffArtifact
+ *   with eligibility: "pending_confirmation" and initial scope + tool constraints.
+ *
+ *   This is the ONLY place that produces executionDomain.
+ *   INVARIANT (A1): executionDomain is derived here from InterpretationResult or
+ *   IntentInterpretation category. No downstream layer may re-classify it.
+ *
+ * ── What this mapper does ─────────────────────────────────────────────────────
+ *
+ *   1. Derives executionDomain from the interpretation category.
+ *   2. Builds taskSpec from interpretation summary + parsedChange (if present).
+ *   3. Sets initial allowedFiles = [parsedChange.filePath] or [].
+ *   4. Sets initial prohibitedPatterns from OCD policy (defensive defaults).
+ *   5. Sets allowedTools from the provided tool policy.
+ *   6. Sets eligibility = "pending_confirmation".
+ *   7. Sets ocdClearance = "clear" (OCD evaluator updates this separately).
+ *
+ * ── What this mapper does NOT do ──────────────────────────────────────────────
+ *
+ *   - Does not read the filesystem
+ *   - Does not call the Claude API
+ *   - Does not set eligibility to "approved_for_agent" (only H does that)
+ *   - Does not validate H-provided paths (delivery gate's job)
+ *   - Does not re-classify executionDomain after building (A1)
+ *
+ * ── CONSTRUCTION RULE: undefined-free payloads ────────────────────────────────
+ *
+ *   All payload objects must be undefined-free per UCP protocol invariant.
+ *   Optional fields are omitted entirely when absent. Never assigned undefined.
+ *
+ * See: docs/claude-agent-phase-a-architecture.md
+ */
+import type { IntakeResult } from "../intake/types.js";
+import type { ReplaceChange } from "../understand/interpretation/types.js";
+type ParsedChange = ReplaceChange;
+import type { ClaudeAgentHandoffArtifact, ClaudeToolPolicy } from "./types.js";
+/**
+ * ClaudeOCDPolicy — the policy inputs for scope constraint building.
+ *
+ * Mirrors CursorOCDPolicy but applies to the Claude seam.
+ */
+export type ClaudeOCDPolicy = {
+    /** Globs that are always prohibited regardless of allowedFiles. */
+    readonly alwaysProhibitedGlobs: readonly string[];
+    /** Globs that are safe to write within. Empty = no positive restriction. */
+    readonly writeSafeGlobs: readonly string[];
+};
+/**
+ * Build the initial ClaudeAgentHandoffArtifact from an IntakeResult.
+ *
+ * PRECONDITION: intake.mode === "execute". Caller must verify this.
+ *
+ * @param intake       The completed intake result (mode must be "execute").
+ * @param intentId     The ucp.intent.v1 envelope id.
+ * @param responseId   The ucp.response.v1 envelope id.
+ * @param policy       The OCD policy for scope constraint building.
+ * @param toolPolicy   The tool policy (allowedTools, networkAccess, filesystemMode).
+ * @param parsedChange Optional parsed change from a structured edit command.
+ */
+export declare function buildClaudeHandoffArtifact(intake: IntakeResult, intentId: string, responseId: string, policy: ClaudeOCDPolicy, toolPolicy: ClaudeToolPolicy, parsedChange?: ParsedChange): ClaudeAgentHandoffArtifact;
+/**
+ * Approve the artifact — transitions eligibility from "pending_confirmation"
+ * to "approved_for_agent". Records the approval timestamp.
+ *
+ * H is the only actor that may call this. Called by the product session on
+ * H's explicit approval action.
+ */
+export declare function approveClaudeArtifact(artifact: ClaudeAgentHandoffArtifact, at?: number): ClaudeAgentHandoffArtifact;
+/**
+ * Narrow the artifact's allowed files to a subset.
+ *
+ * H may narrow (remove entries) but not widen (add new paths).
+ * The gate enforces this at delivery; this function enforces monotonicity
+ * structurally by filtering the current allowedFiles.
+ *
+ * Returns a new artifact with updated allowedFiles and a recomputed id.
+ */
+export declare function narrowClaudeArtifactScope(artifact: ClaudeAgentHandoffArtifact, allowedFiles: readonly string[]): ClaudeAgentHandoffArtifact;
+export {};
+//# sourceMappingURL=artifact-mapper.d.ts.map

package/dist/src/claude/artifact-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-mapper.d.ts","sourceRoot":"","sources":["../../../src/claude/artifact-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAA2B,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAwB,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAEjG,KAAK,YAAY,GAAG,aAAa,CAAC;AAGlC,OAAO,KAAK,EACV,0BAA0B,EAI1B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAIpB;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAS,SAAS,MAAM,EAAE,CAAC;CACnD,CAAC;AAIF;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAS,YAAY,EAC3B,QAAQ,EAAO,MAAM,EACrB,UAAU,EAAK,MAAM,EACrB,MAAM,EAAS,eAAe,EAC9B,UAAU,EAAK,gBAAgB,EAC/B,YAAY,CAAC,EAAE,YAAY,GAC1B,0BAA0B,CAmC5B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,0BAA0B,EACpC,EAAE,GAAQ,MAAmB,GAC5B,0BAA0B,CAO5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAM,0BAA0B,EACxC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,0BAA0B,CAW5B"}

package/dist/src/claude/artifact-mapper.js

@@ -0,0 +1,187 @@
+/**
+ * Claude artifact mapper — Phase 8B.
+ *
+ * ── Role ──────────────────────────────────────────────────────────────────────
+ *
+ *   Translates an IntakeResult (mode === "execute") into a ClaudeAgentHandoffArtifact
+ *   with eligibility: "pending_confirmation" and initial scope + tool constraints.
+ *
+ *   This is the ONLY place that produces executionDomain.
+ *   INVARIANT (A1): executionDomain is derived here from InterpretationResult or
+ *   IntentInterpretation category. No downstream layer may re-classify it.
+ *
+ * ── What this mapper does ─────────────────────────────────────────────────────
+ *
+ *   1. Derives executionDomain from the interpretation category.
+ *   2. Builds taskSpec from interpretation summary + parsedChange (if present).
+ *   3. Sets initial allowedFiles = [parsedChange.filePath] or [].
+ *   4. Sets initial prohibitedPatterns from OCD policy (defensive defaults).
+ *   5. Sets allowedTools from the provided tool policy.
+ *   6. Sets eligibility = "pending_confirmation".
+ *   7. Sets ocdClearance = "clear" (OCD evaluator updates this separately).
+ *
+ * ── What this mapper does NOT do ──────────────────────────────────────────────
+ *
+ *   - Does not read the filesystem
+ *   - Does not call the Claude API
+ *   - Does not set eligibility to "approved_for_agent" (only H does that)
+ *   - Does not validate H-provided paths (delivery gate's job)
+ *   - Does not re-classify executionDomain after building (A1)
+ *
+ * ── CONSTRUCTION RULE: undefined-free payloads ────────────────────────────────
+ *
+ *   All payload objects must be undefined-free per UCP protocol invariant.
+ *   Optional fields are omitted entirely when absent. Never assigned undefined.
+ *
+ * See: docs/claude-agent-phase-a-architecture.md
+ */
+import { hashObject } from "../ucp/hashes.js";
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Build the initial ClaudeAgentHandoffArtifact from an IntakeResult.
+ *
+ * PRECONDITION: intake.mode === "execute". Caller must verify this.
+ *
+ * @param intake       The completed intake result (mode must be "execute").
+ * @param intentId     The ucp.intent.v1 envelope id.
+ * @param responseId   The ucp.response.v1 envelope id.
+ * @param policy       The OCD policy for scope constraint building.
+ * @param toolPolicy   The tool policy (allowedTools, networkAccess, filesystemMode).
+ * @param parsedChange Optional parsed change from a structured edit command.
+ */
+export function buildClaudeHandoffArtifact(intake, intentId, responseId, policy, toolPolicy, parsedChange) {
+    // Derive executionDomain (A1 — mapper only)
+    const executionDomain = deriveExecutionDomain(intake, parsedChange);
+    // Build taskSpec
+    const taskSpec = buildTaskSpec(intake, parsedChange);
+    // Initial allowedFiles: [parsedChange.filePath] when available, else []
+    const allowedFiles = parsedChange?.filePath ? [parsedChange.filePath] : [];
+    // Prohibited patterns: always-prohibited globs from OCD policy
+    const prohibitedPatterns = [...policy.alwaysProhibitedGlobs];
+    // Artifact content fields for deterministic id
+    const content = {
+        mode: "execute",
+        executionDomain,
+        taskSpec,
+        allowedFiles,
+        prohibitedPatterns,
+        allowedTools: [...toolPolicy.allowedTools],
+        toolPolicy: { ...toolPolicy },
+        ocdClearance: "clear",
+        eligibility: "pending_confirmation",
+        intentId,
+        responseId,
+    };
+    const artifactId = hashObject(content);
+    return {
+        artifactId,
+        ...content,
+    };
+}
+/**
+ * Approve the artifact — transitions eligibility from "pending_confirmation"
+ * to "approved_for_agent". Records the approval timestamp.
+ *
+ * H is the only actor that may call this. Called by the product session on
+ * H's explicit approval action.
+ */
+export function approveClaudeArtifact(artifact, at = Date.now()) {
+    const updated = {
+        ...artifact,
+        eligibility: "approved_for_agent",
+        approvedAt: at,
+    };
+    return { ...updated, artifactId: hashObject(omitId(updated)) };
+}
+/**
+ * Narrow the artifact's allowed files to a subset.
+ *
+ * H may narrow (remove entries) but not widen (add new paths).
+ * The gate enforces this at delivery; this function enforces monotonicity
+ * structurally by filtering the current allowedFiles.
+ *
+ * Returns a new artifact with updated allowedFiles and a recomputed id.
+ */
+export function narrowClaudeArtifactScope(artifact, allowedFiles) {
+    const updated = {
+        ...artifact,
+        eligibility: "pending_confirmation",
+        allowedFiles: [...allowedFiles],
+        approvedAt: undefined,
+    };
+    // Remove approvedAt (undefined-free: omit the field)
+    const { approvedAt: _dropped, ...rest } = updated;
+    void _dropped;
+    return { ...rest, artifactId: hashObject(omitId(rest)) };
+}
+// ─── Internal ─────────────────────────────────────────────────────────────────
+/**
+ * Derive executionDomain from the intake result.
+ *
+ * A1 INVARIANT: this function is the single derivation point.
+ * No downstream layer may re-classify the returned value.
+ *
+ * Mapping from interpretation category:
+ *   visual_color, text_change → code_edit
+ *   config_change             → code_edit
+ *   workflow_operation        → ops_task
+ *   unknown (execute mode)    → code_edit (safe default for structured edits)
+ *
+ * When no interpretation category is available (no bridge, no change interp),
+ * defaults to "code_edit" as the conservative choice for mode === "execute".
+ */
+function deriveExecutionDomain(intake, parsedChange) {
+    // If a structured change was parsed, it's always a code edit
+    if (parsedChange)
+        return "code_edit";
+    // Use change interpretation category when available
+    const changeCategory = intake.interpretation?.category;
+    if (changeCategory) {
+        return mapCategory(changeCategory);
+    }
+    // Use intent interpretation category when available
+    const intentCategory = intake.guidance?.interpretation?.category;
+    if (intentCategory) {
+        return mapCategory(intentCategory);
+    }
+    // Default: conservative code_edit for execute mode
+    return "code_edit";
+}
+function mapCategory(category) {
+    switch (category) {
+        case "visual_color":
+        case "text_change":
+        case "config_change":
+            return "code_edit";
+        case "workflow_operation":
+            return "ops_task";
+        default:
+            return "code_edit";
+    }
+}
+function buildTaskSpec(intake, parsedChange) {
+    const interpretation = intake.interpretation;
+    const intentInterp = intake.guidance?.interpretation;
+    const category = interpretation?.category
+        ?? intentInterp?.category
+        ?? "unknown";
+    const summary = interpretation?.summary
+        ?? intentInterp?.summary
+        ?? intake.reason;
+    if (parsedChange) {
+        // Undefined-free: only include parsedChange fields that are present
+        const pc = {};
+        if (parsedChange.filePath)
+            pc.filePath = parsedChange.filePath;
+        if (parsedChange.oldValue)
+            pc.oldValue = parsedChange.oldValue;
+        if (parsedChange.newValue)
+            pc.newValue = parsedChange.newValue;
+        return { category, summary, parsedChange: pc };
+    }
+    return { category, summary };
+}
+function omitId(artifact) {
+    return artifact;
+}
+//# sourceMappingURL=artifact-mapper.js.map

package/dist/src/claude/artifact-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-mapper.js","sourceRoot":"","sources":["../../../src/claude/artifact-mapper.ts"],"names":[],"mappings":"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"}

package/dist/src/claude/delivery-gate.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Claude Delivery Gate — Phase 8B.
+ *
+ * ── Role ──────────────────────────────────────────────────────────────────────
+ *
+ *   The delivery gate is the ONLY path through which a ClaudeAgentHandoffArtifact
+ *   reaches Claude Managed Agents. It enforces these invariants before any delivery:
+ *
+ *     1. Eligibility: artifact.eligibility === "approved_for_agent"
+ *     2. Tool policy: toolPolicy.networkAccess === "deny" (V1 lock, A2)
+ *     3. Tool policy: toolPolicy.filesystemMode === "scoped_only"
+ *     4. Tool policy: allowedTools is non-empty
+ *     5. Persistence: ucp.claude_handoff.v1 persisted before Claude is called
+ *     6. Immutability: artifact delivered === artifact persisted (same id)
+ *
+ *   After delivery, it persists either ucp.claude_receipt.v1 (accepted) or
+ *   ucp.claude_refused.v1 (refused) based on Claude's response.
+ *
+ * ── Three delivery paths ──────────────────────────────────────────────────────
+ *
+ *   Path A (happy):  persist handoff → call Claude → accepted → persist receipt
+ *   Path B (scope):  persist handoff → call Claude → refused_due_to_scope
+ *                      → persist refused → surface scope question
+ *   Path C (error):  persist handoff → call Claude → refused_due_to_execution_error
+ *                      → persist refused → rejected
+ *
+ *   Unknown response kinds → treated as refused_due_to_execution_error (fail-closed).
+ *
+ * ── Plugin contract ───────────────────────────────────────────────────────────
+ *
+ *   ClaudeAgentPlugin.receive() is the only call the gate makes into Claude.
+ *   The plugin must:
+ *     - Accept only ClaudeDeliveryRequest
+ *     - Return only ClaudeDeliveryResponse (one of three kinds)
+ *     - NOT reach back into the intake pipeline (A4)
+ *     - NOT call persistEnvelope (the gate owns all persistence)
+ *
+ * ── Persistence semantics ─────────────────────────────────────────────────────
+ *
+ *   ucp.claude_handoff.v1  — safety-critical (persistStrict): blocks delivery if fails
+ *   ucp.claude_receipt.v1  — audit-critical (persistBestEffort): logs gap if fails
+ *   ucp.claude_refused.v1  — audit-critical (persistBestEffort): logs gap if fails
+ *
+ * ── deliveryId semantics ──────────────────────────────────────────────────────
+ *
+ *   deliveryId is a delivery-attempt identifier, NOT a content identifier.
+ *   Never use it for provenance chain links — use artifact.artifactId for those.
+ *
+ * See: docs/claude-agent-phase-a-architecture.md
+ */
+import type { UCPEnvelope } from "../ucp/types.js";
+import type { ClaudeAgentHandoffArtifact, ClaudeDeliveryRequest, ClaudeDeliveryResponse, ClaudeScopeQuestion } from "./types.js";
+/**
+ * The interface the delivery gate uses to communicate with Claude Managed Agents.
+ *
+ * This is the mechanism-agnostic seam. Implementations may use:
+ *   - Direct Anthropic API calls (real Claude adapter)
+ *   - Stub responses (test adapter)
+ *
+ * The plugin must NOT:
+ *   - Re-derive intent from context (A1)
+ *   - Reach back to the intake pipeline (A4)
+ *   - Execute outside allowedFiles (gate-enforced upstream)
+ *   - Use tools not in allowedTools (gate-enforced upstream)
+ *   - Call persistEnvelope (the gate owns all persistence)
+ */
+export interface ClaudeAgentPlugin {
+    receive(request: ClaudeDeliveryRequest): Promise<ClaudeDeliveryResponse>;
+}
+export type ClaudeDeliveryGateResult = {
+    readonly outcome: "accepted";
+    readonly deliveryId: string;
+    readonly handoffEnvelopeId: string;
+    readonly receiptEnvelopeId: string;
+    readonly sessionId: string;
+} | {
+    readonly outcome: "refused_due_to_scope";
+    readonly deliveryId: string;
+    readonly handoffEnvelopeId: string;
+    readonly refusedEnvelopeId: string;
+    readonly scopeQuestion: ClaudeScopeQuestion;
+} | {
+    readonly outcome: "refused_due_to_execution_error";
+    readonly deliveryId: string;
+    readonly handoffEnvelopeId: string;
+    readonly refusedEnvelopeId: string;
+    readonly errorCode: string;
+    readonly message: string;
+} | {
+    readonly outcome: "blocked_ineligible";
+    readonly reason: string;
+} | {
+    readonly outcome: "blocked_tool_policy";
+    readonly reason: string;
+} | {
+    readonly outcome: "blocked_persistence_failure";
+    readonly reason: string;
+};
+export type ClaudeGateDeps = {
+    /**
+     * Persistence function for the critical handoff envelope.
+     * MUST throw on failure — a failure blocks delivery entirely.
+     */
+    persistStrict?: (envelope: UCPEnvelope<unknown>) => void;
+    /**
+     * Persistence function for non-critical envelopes (receipt, refused).
+     * Must NOT throw — errors are swallowed.
+     */
+    persistBestEffort?: (envelope: UCPEnvelope<unknown>) => void;
+};
+export declare class ClaudeDeliveryGate {
+    private readonly plugin;
+    private readonly storeDir;
+    private readonly persistStrict;
+    private readonly persistBestEffort;
+    constructor(plugin: ClaudeAgentPlugin, storeDir: string, deps?: ClaudeGateDeps);
+    /**
+     * Deliver a ClaudeAgentHandoffArtifact to Claude Managed Agents.
+     *
+     * CONTRACT — callers must ensure:
+     *   - artifact.eligibility === "approved_for_agent" (gate re-checks and blocks if not)
+     *   - artifact.toolPolicy.networkAccess === "deny" (gate re-checks, A2)
+     *   - artifact.approvedAt is set (H has confirmed)
+     *
+     * CONTRACT — this function guarantees:
+     *   - ucp.claude_handoff.v1 persisted BEFORE Claude is called
+     *   - If persistence fails, Claude is NOT called (blocked_persistence_failure)
+     *   - ucp.claude_receipt.v1 persisted when Claude returns "accepted"
+     *   - ucp.claude_refused.v1 persisted when Claude returns any refusal
+     *   - Receipt/refusal persistence failures do not block the state transition
+     *   - Unknown response kinds map to refused_due_to_execution_error (fail-closed)
+     */
+    deliver(artifact: ClaudeAgentHandoffArtifact): Promise<ClaudeDeliveryGateResult>;
+    private tryPersistBestEffort;
+}
+//# sourceMappingURL=delivery-gate.d.ts.map

package/dist/src/claude/delivery-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-gate.d.ts","sourceRoot":"","sources":["../../../src/claude/delivery-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAA8B,iBAAiB,CAAC;AAQ3E,OAAO,KAAK,EACV,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,EAGtB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC1E;AAID,MAAM,MAAM,wBAAwB,GAChC;IACE,QAAQ,CAAC,OAAO,EAAa,UAAU,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAU,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAW,MAAM,CAAC;CACrC,GACD;IACE,QAAQ,CAAC,OAAO,EAAa,sBAAsB,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAU,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAO,mBAAmB,CAAC;CAClD,GACD;IACE,QAAQ,CAAC,OAAO,EAAa,gCAAgC,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAU,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAG,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAW,MAAM,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAa,MAAM,CAAC;CACrC,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,6BAA6B,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;CAC1B,CAAC;AAIN,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,aAAa,CAAC,EAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC7D;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CAC9D,CAAC;AAIF,qBAAa,kBAAkB;IAK3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+C;IAC7E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2C;gBAG1D,MAAM,EAAI,iBAAiB,EAC3B,QAAQ,EAAE,MAAM,EACjC,IAAI,GAAE,cAAmB;IAQ3B;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,QAAQ,EAAE,0BAA0B,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAgKtF,OAAO,CAAC,oBAAoB;CAO7B"}