@lucascouts/claude-agent-tui 0.1.0

package/dist/permissions/permission-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-mode.d.ts","sourceRoot":"","sources":["../../src/permissions/permission-mode.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAElG,2EAA2E;AAC3E,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,mBAAmB,CAAC;AAEpE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ5E;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,UAAU,0DAE5E;AAED,uGAAuG;AACvG,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,mBAAmB,CA2B9E"}

package/dist/permissions/permission-mode.js

@@ -0,0 +1,100 @@
+// Story 033 / Task 3.2 — the `--permission-mode acceptEdits`/`bypassPermissions` deny-only alternative,
+// with billing UNCHANGED (R4.1, R4.2).
+//
+// THE ALTERNATIVE (IMPLEMENTACAO-FORK-ACP.md §9): spawn the TUI with `--permission-mode acceptEdits`
+// (or `bypassPermissions`) so the TUI AUTO-APPROVES, paired with the PreToolUse hook acting as a
+// DENY-ONLY gate: dangerous tools are denied; the rest auto-approve in the TUI with NO second prompt.
+// This removes the #52822 double-prompt surface entirely on the allow path while keeping a deny safety
+// net — a structurally simpler posture than the keystroke-injection mitigation (allow-inject.ts).
+//
+// BILLING IS SACRED (§10 / story 022): switching the permission MODE does NOT change billing.
+//   - the spawn argv stays interactive-only (no `-p`/`stream-json`), so the run still labels
+//     `entrypoint=='cli'` ORGANICALLY (the E1 keystone);
+//   - `CLAUDE_CODE_ENTRYPOINT` is NEVER spoofed (forcing it toward 'cli' would be evasion — the
+//     OpenClaw case);
+//   - the story-022 guard-rail is RE-ASSERTED on the first observed message: a `sdk-*`/`print` label
+//     ABORTS the session with the observed entrypoint named (we never proceed on a credit-class label).
+//
+// This module owns the flag/matcher selection + the guard-rail re-assertion; the actual spawn wiring
+// in `startEngine` consumes {@link permissionModeFlag} and the deny-only matcher.
+import { guardEvent } from "../billing/entrypoint-guard.js";
+/**
+ * Build the `--permission-mode <mode>` spawn flag fragment for the alternative (R4.1). Returns the two
+ * argv tokens; the spawn path appends them to the interactive `claude` argv. NOTE: this flag changes
+ * only how the TUI PROMPTS — it does NOT add `-p`/`stream-json` and therefore does NOT change billing.
+ *
+ * @param mode `acceptEdits` (the safe default) or `bypassPermissions`.
+ * @returns the argv tokens `['--permission-mode', mode]`.
+ * @throws {Error} on an unrecognized mode (never silently fall through to a non-gating flag).
+ */
+export function permissionModeFlag(mode) {
+    if (mode !== "acceptEdits" && mode !== "bypassPermissions") {
+        throw new Error(`permissionModeFlag: unsupported alternative permission mode ${JSON.stringify(mode)} — ` +
+            `expected 'acceptEdits' or 'bypassPermissions'.`);
+    }
+    return ["--permission-mode", mode];
+}
+/**
+ * Decide whether the deny-only hook should DENY this tool (R4.1). Returns true iff the tool matches a
+ * deny matcher (exact name or `"*"`); otherwise the tool is allowed to auto-approve in the TUI.
+ *
+ * @param policy the deny-only policy (the dangerous-tool matchers).
+ * @param toolName the tool from the hook payload.
+ * @returns true → the hook denies this tool; false → auto-approve.
+ */
+export function denyOnlyShouldDeny(policy, toolName) {
+    return policy.denyMatchers.some((m) => m === "*" || m === toolName);
+}
+/**
+ * Re-assert the story-022 billing guard-rail (§10) for one observed message under the alternative mode
+ * (R4.2). This is the SAME guard-rail the read-only pump runs — re-asserted here so enabling
+ * auto-approve does NOT weaken billing. Delegates to {@link guardEvent} (it never re-derives the class
+ * and never mutates/spoofs `entrypoint`): on a `sdk-*`/`print` (or unknown) label it alerts + stops the
+ * session via the injected hooks; on `cli` it is a silent no-op.
+ *
+ * @param event one watched message event (the story-015 watcher shape).
+ * @param hooks the alert/stop sink (wired to the engine-lifecycle stop in production).
+ * @returns the guard decision (`allow`/`abort`/`skip`) so the caller can branch.
+ */
+export function reassertBillingGuard(event, hooks) {
+    return guardEvent(event, hooks);
+}
+/**
+ * Convenience post-spawn assertion (R4.2): given the FIRST observed billing message's entrypoint
+ * self-label, decide whether the alternative-mode session may proceed. ABORTS (`ok:false`) on anything
+ * that is not the subscription `cli` label, naming the observed entrypoint in the reason — never
+ * proceeds on a `sdk-*`/`print` label and never spoofs the value toward `cli`.
+ *
+ * This is a thin, pure wrapper over {@link guardEvent} for the spawn path that wants a boolean rather
+ * than the hook side-effects; the side-effecting {@link reassertBillingGuard} is used by the live pump.
+ *
+ * @param event the first observed `assistant`/`user` event under the alternative mode.
+ * @returns `{ ok:true, entrypoint }` for `cli`; `{ ok:false, entrypoint, reason }` otherwise.
+ */
+export function assertEntrypointCli(event) {
+    const captured = [];
+    const hooks = {
+        alert() {
+            /* captured via stopSession below */
+        },
+        stopSession(info) {
+            captured.push({ entrypoint: info.entrypoint, entrypointClass: info.entrypointClass });
+        },
+    };
+    const decision = guardEvent(event, hooks);
+    const aborted = captured[0] ?? null;
+    if (decision.action === "abort" || aborted !== null) {
+        const ep = aborted?.entrypoint ?? (decision.action === "abort" ? decision.entrypoint : "");
+        const cls = aborted?.entrypointClass ?? (decision.action === "abort" ? decision.entrypointClass : "unknown");
+        return {
+            ok: false,
+            entrypoint: ep,
+            reason: `[billing §10] alternative permission-mode session observed a ${cls}-class entrypoint ` +
+                `"${ep}" — aborting (the run would bill on API credit, not the subscription). The entrypoint ` +
+                `is NOT being rewritten toward 'cli'.`,
+        };
+    }
+    // 'allow' (subscription cli) — proceed. 'skip' (lightweight) is treated as not-yet-decided → proceed.
+    const entrypoint = decision.action === "allow" ? decision.entrypoint : "";
+    return { ok: true, entrypoint };
+}

package/dist/permissions/request-permission.d.ts

@@ -0,0 +1,102 @@
+/** The kind hint on a permission option (ACP `PermissionOptionKind`). */
+export type PermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+/** One permission option offered to the user (the ACP `PermissionOption` subset the gate emits). */
+export interface PermissionOption {
+    optionId: string;
+    name: string;
+    kind: PermissionOptionKind;
+}
+/** The tool-call detail carried in the ACP request (`RequestPermissionRequest.toolCall`). */
+export interface ToolCallUpdateLike {
+    toolCallId: string;
+    title?: string;
+    rawInput?: unknown;
+}
+/** The ACP `session/request_permission` params the gate sends. */
+export interface RequestPermissionParams {
+    sessionId: string;
+    toolCall: ToolCallUpdateLike;
+    options: PermissionOption[];
+}
+/** The ACP `RequestPermissionResponse` outcome union. */
+export type RequestPermissionOutcome = {
+    outcome: "cancelled";
+} | {
+    outcome: "selected";
+    optionId: string;
+};
+/** The ACP `RequestPermissionResponse` the client returns. */
+export interface RequestPermissionResult {
+    outcome: RequestPermissionOutcome;
+}
+/**
+ * The minimal ACP client surface the bridge needs — structurally satisfied by the kept
+ * `AgentSideConnection` (`client.requestPermission(params)`). Injected so a unit test drives the bridge
+ * with a fake client OFFLINE (no AgentSideConnection, no Zed).
+ */
+export interface PermissionClient {
+    requestPermission(params: RequestPermissionParams): Promise<RequestPermissionResult>;
+}
+/** The forwarded tool call (hook payload subset) the bridge correlates + asks permission for. */
+export interface PermissionToolCall {
+    /** The correlation key: hook `tool_use_id` == JSONL `tool_use.id`. */
+    toolUseId: string;
+    /** The tool name (`tool_use.name`) — shown in the Zed prompt title. */
+    toolName: string;
+    /** The tool input (`tool_use.input`) — forwarded as `rawInput` for the Zed prompt. */
+    toolInput?: unknown;
+}
+/** The two option ids the gate offers. Fixed so the response mapping is unambiguous. */
+export declare const ALLOW_OPTION_ID = "allow";
+export declare const DENY_OPTION_ID = "deny";
+/** Build the fixed [allow, deny] option set the gate presents in Zed (R2.2). */
+export declare function buildPermissionOptions(): PermissionOption[];
+/**
+ * A correlation map keyed by `tool_use.id`: the JSONL `tool_use` events the story-015 watcher has
+ * observed, so a hook tool call can be matched to a REAL transcript tool_use before it is approved.
+ *
+ * `register(id)` is idempotency-aware: it records each id ONCE and flags a re-registration so a
+ * DUPLICATE id (id reuse / re-entrancy) can be detected and failed closed. `decide(id)` consumes the
+ * correlation: a missing OR duplicate id yields `deny`, a clean single match yields `allow-eligible`
+ * (the call may proceed to the ACP prompt). The map is per-session (tool_use ids are session-scoped).
+ */
+export declare class ToolUseCorrelator {
+    /** ids observed in the JSONL `tool_use` stream, with a count so duplicates are detectable. */
+    private readonly seen;
+    /** ids already consumed by a permission decision — a second consume is a duplicate (re-entrancy). */
+    private readonly consumed;
+    /**
+     * Record a JSONL `tool_use.id` from the story-015 watcher. Increments its count so a second
+     * observation marks it duplicate. Returns true on the FIRST registration, false on a duplicate.
+     */
+    register(toolUseId: string): boolean;
+    /** True iff `toolUseId` was observed EXACTLY once in the JSONL and has not yet been consumed. */
+    isCleanMatch(toolUseId: string): boolean;
+    /**
+     * Consume the correlation for `toolUseId` and decide whether the call may proceed to the ACP prompt.
+     * FAIL CLOSED: a missing id (never seen in the JSONL), a DUPLICATE id (seen >1× → id reuse), or an
+     * already-consumed id (re-entrancy) all yield `'deny'`. A clean single, first-time match yields
+     * `'proceed'`. Marks the id consumed so a later re-ask is treated as a duplicate.
+     */
+    decide(toolUseId: string): "proceed" | "deny";
+}
+/** Options for {@link requestPermission}. */
+export interface RequestPermissionOptions {
+    client: PermissionClient;
+    sessionId: string;
+    toolCall: PermissionToolCall;
+    /** The per-session correlator seeded from the JSONL `tool_use` events (story 015). */
+    correlator: ToolUseCorrelator;
+    /** Optional sink for the fail-closed diagnostics (defaults to no-op; production wires the logger). */
+    onWarn?: (message: string) => void;
+}
+/**
+ * Correlate a forwarded tool call by `tool_use.id` and raise ACP `session/request_permission`,
+ * resolving to the enforced decision (R2.2). FAILS CLOSED to `'deny'` on a missing/duplicate id, an
+ * ACP transport error, or a `cancelled`/unrecognized outcome — never approves an uncorrelated call.
+ *
+ * @returns `'allow'` ONLY when the id is a clean single JSONL match AND Zed returns the allow option;
+ *   `'deny'` otherwise.
+ */
+export declare function requestPermission(opts: RequestPermissionOptions): Promise<"allow" | "deny">;
+//# sourceMappingURL=request-permission.d.ts.map

package/dist/permissions/request-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-permission.d.ts","sourceRoot":"","sources":["../../src/permissions/request-permission.ts"],"names":[],"mappings":"AAoBA,yEAAyE;AACzE,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,eAAe,CAAC;AAEnG,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,oBAAoB,CAAC;CAC5B;AAED,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,yDAAyD;AACzD,MAAM,MAAM,wBAAwB,GAChC;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,GACxB;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,wBAAwB,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtF;AAED,iGAAiG;AACjG,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wFAAwF;AACxF,eAAO,MAAM,eAAe,UAAU,CAAC;AACvC,eAAO,MAAM,cAAc,SAAS,CAAC;AAErC,gFAAgF;AAChF,wBAAgB,sBAAsB,IAAI,gBAAgB,EAAE,CAK3D;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,8FAA8F;IAC9F,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,qGAAqG;IACrG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAE9C;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAMpC,iGAAiG;IACjG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIxC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;CAS9C;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sFAAsF;IACtF,UAAU,EAAE,iBAAiB,CAAC;IAC9B,sGAAsG;IACtG,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAiDjG"}

package/dist/permissions/request-permission.js

@@ -0,0 +1,124 @@
+// Story 033 / Task 2.2 — correlate by tool_use.id and raise ACP session/request_permission, failing
+// CLOSED (deny) on a missing/duplicate id or an ACP transport error (R2.2).
+//
+// FLOW (IMPLEMENTACAO-FORK-ACP.md §9): the loopback hook server (hook-server.ts) forwards a tool call
+// over IPC; the fork correlates it against the JSONL `tool_use` event by `tool_use.id` (the SAME id
+// claude wrote into the transcript and into the hook payload — §9 "correlacionar por tool_use.id"),
+// raises `session/request_permission` in Zed with options [allow, deny], awaits the user's
+// `RequestPermissionResponse`, and maps the chosen option back to `'allow'`/`'deny'`.
+//
+// FAIL CLOSED (the load-bearing safety posture — design.md "Fail closed everywhere"):
+//   - a tool_use_id NOT seen in the JSONL correlation map → deny (an uncorrelated call is never
+//     approved — it might be a spoofed/stale id);
+//   - a DUPLICATE tool_use_id (already pending or already decided) → deny (re-entrancy / id reuse must
+//     not silently ride a prior approval);
+//   - an ACP transport error (client.requestPermission throws) → deny;
+//   - a `cancelled` outcome from Zed → deny (a cancel is NOT an approval).
+//
+// This module owns NO server and NO PTY; it is a pure correlation + ACP-bridge unit driven by an
+// injectable client surface so a unit test runs it OFFLINE against a fake ACP client.
+/** The two option ids the gate offers. Fixed so the response mapping is unambiguous. */
+export const ALLOW_OPTION_ID = "allow";
+export const DENY_OPTION_ID = "deny";
+/** Build the fixed [allow, deny] option set the gate presents in Zed (R2.2). */
+export function buildPermissionOptions() {
+    return [
+        { optionId: ALLOW_OPTION_ID, name: "Allow", kind: "allow_once" },
+        { optionId: DENY_OPTION_ID, name: "Deny", kind: "reject_once" },
+    ];
+}
+/**
+ * A correlation map keyed by `tool_use.id`: the JSONL `tool_use` events the story-015 watcher has
+ * observed, so a hook tool call can be matched to a REAL transcript tool_use before it is approved.
+ *
+ * `register(id)` is idempotency-aware: it records each id ONCE and flags a re-registration so a
+ * DUPLICATE id (id reuse / re-entrancy) can be detected and failed closed. `decide(id)` consumes the
+ * correlation: a missing OR duplicate id yields `deny`, a clean single match yields `allow-eligible`
+ * (the call may proceed to the ACP prompt). The map is per-session (tool_use ids are session-scoped).
+ */
+export class ToolUseCorrelator {
+    constructor() {
+        /** ids observed in the JSONL `tool_use` stream, with a count so duplicates are detectable. */
+        this.seen = new Map();
+        /** ids already consumed by a permission decision — a second consume is a duplicate (re-entrancy). */
+        this.consumed = new Set();
+    }
+    /**
+     * Record a JSONL `tool_use.id` from the story-015 watcher. Increments its count so a second
+     * observation marks it duplicate. Returns true on the FIRST registration, false on a duplicate.
+     */
+    register(toolUseId) {
+        const count = this.seen.get(toolUseId) ?? 0;
+        this.seen.set(toolUseId, count + 1);
+        return count === 0;
+    }
+    /** True iff `toolUseId` was observed EXACTLY once in the JSONL and has not yet been consumed. */
+    isCleanMatch(toolUseId) {
+        return this.seen.get(toolUseId) === 1 && !this.consumed.has(toolUseId);
+    }
+    /**
+     * Consume the correlation for `toolUseId` and decide whether the call may proceed to the ACP prompt.
+     * FAIL CLOSED: a missing id (never seen in the JSONL), a DUPLICATE id (seen >1× → id reuse), or an
+     * already-consumed id (re-entrancy) all yield `'deny'`. A clean single, first-time match yields
+     * `'proceed'`. Marks the id consumed so a later re-ask is treated as a duplicate.
+     */
+    decide(toolUseId) {
+        const count = this.seen.get(toolUseId) ?? 0;
+        if (count !== 1 || this.consumed.has(toolUseId)) {
+            // Missing (0), duplicate (>1), or re-entrant (already consumed) → never approve.
+            return "deny";
+        }
+        this.consumed.add(toolUseId);
+        return "proceed";
+    }
+}
+/**
+ * Correlate a forwarded tool call by `tool_use.id` and raise ACP `session/request_permission`,
+ * resolving to the enforced decision (R2.2). FAILS CLOSED to `'deny'` on a missing/duplicate id, an
+ * ACP transport error, or a `cancelled`/unrecognized outcome — never approves an uncorrelated call.
+ *
+ * @returns `'allow'` ONLY when the id is a clean single JSONL match AND Zed returns the allow option;
+ *   `'deny'` otherwise.
+ */
+export async function requestPermission(opts) {
+    const { client, sessionId, toolCall, correlator, onWarn } = opts;
+    // 1) Correlate by tool_use.id BEFORE asking — an uncorrelated/duplicate call is denied, not prompted.
+    const correlation = correlator.decide(toolCall.toolUseId);
+    if (correlation === "deny") {
+        onWarn?.(`[gate §9] FAIL CLOSED: tool_use ${toolCall.toolUseId} (tool "${toolCall.toolName}") is not a ` +
+            `clean single match in the JSONL correlation map (missing or duplicate) — denying rather than ` +
+            `approving an uncorrelated call.`);
+        return "deny";
+    }
+    // 2) Raise session/request_permission in Zed with [allow, deny]; await the user's choice.
+    let result;
+    try {
+        result = await client.requestPermission({
+            sessionId,
+            toolCall: {
+                toolCallId: toolCall.toolUseId,
+                title: toolCall.toolName,
+                rawInput: toolCall.toolInput,
+            },
+            options: buildPermissionOptions(),
+        });
+    }
+    catch (err) {
+        onWarn?.(`[gate §9] FAIL CLOSED: session/request_permission transport error for tool_use ` +
+            `${toolCall.toolUseId} (${err instanceof Error ? err.message : String(err)}) — denying.`);
+        return "deny";
+    }
+    // 3) Map the outcome back to the enforced decision. Only an explicit allow selection approves;
+    //    a cancel or any unrecognized optionId fails closed.
+    const outcome = result.outcome;
+    if (outcome.outcome === "selected" && outcome.optionId === ALLOW_OPTION_ID) {
+        return "allow";
+    }
+    if (outcome.outcome === "selected" && outcome.optionId === DENY_OPTION_ID) {
+        return "deny";
+    }
+    // 'cancelled' or an unknown optionId → deny (a cancel is not an approval).
+    onWarn?.(`[gate §9] FAIL CLOSED: tool_use ${toolCall.toolUseId} resolved to ` +
+        `${outcome.outcome === "selected" ? `unknown option "${outcome.optionId}"` : "cancelled"} — denying.`);
+    return "deny";
+}

package/dist/settings.d.ts

@@ -0,0 +1,68 @@
+import { type Settings } from "@anthropic-ai/claude-agent-sdk";
+export interface SettingsManagerOptions {
+    onChange?: () => void;
+    logger?: {
+        log: (...args: any[]) => void;
+        error: (...args: any[]) => void;
+    };
+}
+/**
+ * Manages Claude Code settings using the SDK's `resolveSettings` merge engine
+ * so the values we see match what `query()` would observe.
+ *
+ * Watches the user/project/local/managed settings files for changes and
+ * re-resolves through the SDK on update. Escalating `permissions.defaultMode`
+ * values from repo-committed sources are filtered out via
+ * `filterEscalatingDefaultMode`, matching the CLI's trust policy.
+ */
+export declare class SettingsManager {
+    private cwd;
+    private effective;
+    private watchers;
+    private onChange?;
+    private logger;
+    private initialized;
+    private disposed;
+    private debounceTimer;
+    private initPromise;
+    constructor(cwd: string, options?: SettingsManagerOptions);
+    /**
+     * Initialize the settings manager by loading all settings and setting up file watchers
+     */
+    initialize(): Promise<void>;
+    /**
+     * Paths the SDK reads when resolving settings for this cwd. Watching the
+     * containing directories means we pick up file creation as well as edits.
+     */
+    private getWatchedPaths;
+    /**
+     * Resolves the effective settings via the SDK and applies the CLI's trust
+     * filter for escalating `permissions.defaultMode` values.
+     */
+    private loadAllSettings;
+    /**
+     * Sets up file watchers for all settings files
+     */
+    private setupWatchers;
+    /**
+     * Handles settings file changes with debouncing to avoid rapid reloads
+     */
+    private handleSettingsChange;
+    /**
+     * Returns the current merged settings
+     */
+    getSettings(): Settings;
+    /**
+     * Returns the current working directory
+     */
+    getCwd(): string;
+    /**
+     * Updates the working directory and reloads project-specific settings
+     */
+    setCwd(cwd: string): Promise<void>;
+    /**
+     * Disposes of file watchers and cleans up resources
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=settings.d.ts.map

package/dist/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,gCAAgC,CAAC;AA0BxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE;QAAE,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAC7E;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,MAAM,CAAqE;IACnF,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,WAAW,CAA8B;gBAErC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;IAMzD;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBjC;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;OAGG;YACW,eAAe;IAU7B;;OAEG;IACH,OAAO,CAAC,aAAa;IAyBrB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxC;;OAEG;IACH,OAAO,IAAI,IAAI;CAehB"}

package/dist/settings.js

@@ -0,0 +1,182 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+// resolveSettings and filterEscalatingDefaultMode are marked @alpha in the
+// SDK; API may shift in a future release.
+import { filterEscalatingDefaultMode, resolveSettings, } from "@anthropic-ai/claude-agent-sdk";
+import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
+/**
+ * Permission rule format examples:
+ * - "Read" - matches all Read tool calls
+ * - "Read(./.env)" - matches specific path
+ * - "Read(./.env.*)" - glob pattern
+ * - "Read(./secrets/**)" - recursive glob
+ * - "Bash(npm run lint)" - exact command prefix
+ * - "Bash(npm run:*)" - command prefix with wildcard
+ *
+ * Docs: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
+ */
+function getManagedSettingsPath() {
+    switch (process.platform) {
+        case "darwin":
+            return "/Library/Application Support/ClaudeCode/managed-settings.json";
+        case "win32":
+            return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
+        default:
+            return "/etc/claude-code/managed-settings.json";
+    }
+}
+/**
+ * Manages Claude Code settings using the SDK's `resolveSettings` merge engine
+ * so the values we see match what `query()` would observe.
+ *
+ * Watches the user/project/local/managed settings files for changes and
+ * re-resolves through the SDK on update. Escalating `permissions.defaultMode`
+ * values from repo-committed sources are filtered out via
+ * `filterEscalatingDefaultMode`, matching the CLI's trust policy.
+ */
+export class SettingsManager {
+    constructor(cwd, options) {
+        this.effective = {};
+        this.watchers = [];
+        this.initialized = false;
+        this.disposed = false;
+        this.debounceTimer = null;
+        this.initPromise = null;
+        this.cwd = cwd;
+        this.onChange = options?.onChange;
+        this.logger = options?.logger ?? console;
+    }
+    /**
+     * Initialize the settings manager by loading all settings and setting up file watchers
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.disposed = false;
+        this.initPromise = this.loadAllSettings().then(() => {
+            if (!this.disposed) {
+                this.setupWatchers();
+                this.initialized = true;
+            }
+            this.initPromise = null;
+        });
+        return this.initPromise;
+    }
+    /**
+     * Paths the SDK reads when resolving settings for this cwd. Watching the
+     * containing directories means we pick up file creation as well as edits.
+     */
+    getWatchedPaths() {
+        return [
+            path.join(CLAUDE_CONFIG_DIR, "settings.json"),
+            path.join(this.cwd, ".claude", "settings.json"),
+            path.join(this.cwd, ".claude", "settings.local.json"),
+            getManagedSettingsPath(),
+        ];
+    }
+    /**
+     * Resolves the effective settings via the SDK and applies the CLI's trust
+     * filter for escalating `permissions.defaultMode` values.
+     */
+    async loadAllSettings() {
+        try {
+            const resolved = await resolveSettings({ cwd: this.cwd });
+            this.effective = filterEscalatingDefaultMode(resolved);
+        }
+        catch (error) {
+            this.logger.error("Failed to resolve settings:", error);
+            this.effective = {};
+        }
+    }
+    /**
+     * Sets up file watchers for all settings files
+     */
+    setupWatchers() {
+        for (const filePath of this.getWatchedPaths()) {
+            try {
+                const dir = path.dirname(filePath);
+                const filename = path.basename(filePath);
+                if (fs.existsSync(dir)) {
+                    const watcher = fs.watch(dir, (eventType, changedFilename) => {
+                        if (changedFilename === filename) {
+                            this.handleSettingsChange();
+                        }
+                    });
+                    watcher.on("error", (error) => {
+                        this.logger.error(`Settings watcher error for ${filePath}:`, error);
+                    });
+                    this.watchers.push(watcher);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Failed to set up watcher for ${filePath}:`, error);
+            }
+        }
+    }
+    /**
+     * Handles settings file changes with debouncing to avoid rapid reloads
+     */
+    handleSettingsChange() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(async () => {
+            this.debounceTimer = null;
+            if (this.disposed) {
+                return;
+            }
+            try {
+                await this.loadAllSettings();
+                if (!this.disposed) {
+                    this.onChange?.();
+                }
+            }
+            catch (error) {
+                this.logger.error("Failed to reload settings:", error);
+            }
+        }, 100);
+    }
+    /**
+     * Returns the current merged settings
+     */
+    getSettings() {
+        return this.effective;
+    }
+    /**
+     * Returns the current working directory
+     */
+    getCwd() {
+        return this.cwd;
+    }
+    /**
+     * Updates the working directory and reloads project-specific settings
+     */
+    async setCwd(cwd) {
+        if (this.cwd === cwd) {
+            return;
+        }
+        this.dispose();
+        this.cwd = cwd;
+        await this.initialize();
+    }
+    /**
+     * Disposes of file watchers and cleans up resources
+     */
+    dispose() {
+        this.disposed = true;
+        this.initialized = false;
+        this.initPromise = null;
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        for (const watcher of this.watchers) {
+            watcher.close();
+        }
+        this.watchers = [];
+    }
+}

package/dist/stop-reason-map.d.ts

@@ -0,0 +1,17 @@
+import type { StopReason } from "@agentclientprotocol/sdk";
+/** Telemetry sink for an unmapped stop_reason (drift). Structural — the acp-agent logger satisfies it. */
+export interface StopReasonLogger {
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Map a raw `message.stop_reason` to the ACP {@link StopReason} (R3.1–R3.3):
+ * - `end_turn` / `stop_sequence` → `"end_turn"`
+ * - `max_tokens` → `"max_tokens"`
+ * - `refusal` → `"refusal"`
+ * - any unrecognized NON-NULL value → the defined fallback `"end_turn"`, AND the raw value is logged
+ *   for drift telemetry (never silently dropped).
+ *
+ * Total: never throws. `null`/`undefined` (absence, not drift) return the fallback without logging.
+ */
+export declare function mapStopReason(raw: unknown, logger?: StopReasonLogger): StopReason;
+//# sourceMappingURL=stop-reason-map.d.ts.map

package/dist/stop-reason-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-reason-map.d.ts","sourceRoot":"","sources":["../src/stop-reason-map.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,0GAA0G;AAC1G,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,UAAU,CAgBjF"}

package/dist/stop-reason-map.js

@@ -0,0 +1,33 @@
+// === Story 024 / Task 4.1 — map raw JSONL `message.stop_reason` to the ACP stopReason taxonomy ====
+//
+// §7 translation JSONL→ACP. The model's terminal `stop_reason` is mapped to the ACP `StopReason`
+// the rewritten prompt() loop answers with (§5, §17 acp-agent.ts PromptResponse). The map is TOTAL:
+// it never throws, and an unrecognized non-null variant is surfaced (logged) and defaulted rather
+// than silently dropped, so model/stop-reason drift is observable for telemetry (R3.3).
+/**
+ * Map a raw `message.stop_reason` to the ACP {@link StopReason} (R3.1–R3.3):
+ * - `end_turn` / `stop_sequence` → `"end_turn"`
+ * - `max_tokens` → `"max_tokens"`
+ * - `refusal` → `"refusal"`
+ * - any unrecognized NON-NULL value → the defined fallback `"end_turn"`, AND the raw value is logged
+ *   for drift telemetry (never silently dropped).
+ *
+ * Total: never throws. `null`/`undefined` (absence, not drift) return the fallback without logging.
+ */
+export function mapStopReason(raw, logger) {
+    switch (raw) {
+        case "end_turn":
+        case "stop_sequence":
+            return "end_turn";
+        case "max_tokens":
+            return "max_tokens";
+        case "refusal":
+            return "refusal";
+        default:
+            if (raw !== null && raw !== undefined) {
+                // Drift: a non-null stop_reason outside the known set. Surface it (R3.3) — don't drop it.
+                logger?.error("[stop-reason-map] unmapped stop_reason, defaulting to end_turn:", raw);
+            }
+            return "end_turn";
+    }
+}