@lucascouts/claude-agent-acp-plus 0.23.6 → 0.25.0

package/dist/classifier-escalation.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Story 016: a call the auto-mode classifier denies asks the operator instead
+ * of failing. An approval becomes a grant — memory only, scoped to one
+ * session — that the next matching call consumes to skip the classifier.
+ */
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import type { ClaudeAcpAgent, Logger, ToolUpdateMeta } from "./acp-agent.js";
+import { type ClassifierEscalationAnswer } from "./permissions/response.js";
+/**
+ * One string per (tool name, input): keys sorted recursively, array order kept,
+ * and the top-level Bash `description` dropped — a cosmetic label the model
+ * rewrites on retry. `undefined` when the input cannot be serialised (cyclic),
+ * which every caller treats as "no grant possible".
+ */
+export declare function fingerprint(toolName: string, input: unknown): string | undefined;
+export type GrantKind = "once" | "session";
+/** The grants of one session. Memory only: nothing here touches the disk. */
+export declare class GrantStore {
+    private readonly once;
+    private readonly session;
+    grantOnce(fp: string): void;
+    grantSession(fp: string): void;
+    /** Whether a grant matches, without consuming it. */
+    has(fp: string): boolean;
+    /** A session grant wins and stays; a once grant is deleted when consumed. */
+    consume(fp: string): GrantKind | undefined;
+    /** Turn end: an unused "Yes" does not outlive its turn. */
+    clearOnce(): void;
+    /** Session teardown. */
+    clear(): void;
+}
+/** How an escalated call ended: the operator's answer, or the fail-closed default. */
+export type EscalationOutcome = "approved" | "rejected" | "cancelled";
+/** A `permission_denied` frame, as the frame handler notes it. */
+export type DeniedFrame = {
+    toolUseId: string;
+    /** `decision_reason_type`: "classifier", "rule", "mode", … */
+    reasonType: string | undefined;
+    /** `decision_reason ?? message` — exactly the text today's failed update shows. */
+    reason: string;
+    /** A subagent's `agent_id`, when the denied call ran inside one. */
+    agentId?: string;
+    /**
+     * Today's `_meta` for the denied call's failed update (tool name, parent
+     * stamp, `toolResponse`), built by the frame handler where the session is in
+     * reach. Reused verbatim so a rejected update is byte for byte today's.
+     */
+    meta?: ToolUpdateMeta;
+    /**
+     * Whether the client was ever sent this call's `tool_call`. A fallback update
+     * for a call the client never saw is dropped, as today's handler drops it.
+     */
+    emitted?: boolean;
+};
+type ToolCallUpdate = Extract<SessionNotification["update"], {
+    sessionUpdate: "tool_call_update";
+}>;
+export type EscalationRegistryDeps = {
+    sessionId: string;
+    /** Sends one `tool_call_update` for the denied call to the client. */
+    emit: (toolUseId: string, update: ToolCallUpdate) => unknown;
+    logger: Logger;
+};
+/**
+ * Orders the two signals the CLI sends for one classifier denial — the
+ * `permission_denied` frame and the `PermissionDenied` hook, in either order,
+ * keyed by tool_use_id — and guarantees the denied call exactly one final
+ * `tool_call_update`: never zero (a call left pending), never two.
+ */
+export declare class EscalationRegistry {
+    private readonly sessionId;
+    private readonly emit;
+    private readonly logger;
+    private readonly frames;
+    private readonly waiters;
+    private readonly deadlines;
+    private readonly claimed;
+    private readonly abandoned;
+    private readonly settled;
+    constructor(deps: EscalationRegistryDeps);
+    /** Frame side. Answers any hook waiting on this id; a classifier frame arms the fallback. */
+    noteFrame(frame: DeniedFrame): void;
+    /** Hook side. The frame's reason type, or `undefined` after 5 s. Never rejects. */
+    awaitReasonType(toolUseId: string): Promise<string | undefined>;
+    /**
+     * The hook takes ownership: only `resolve` settles this id from now on.
+     * `false` when the call was already settled — the hook must not ask then.
+     */
+    claim(toolUseId: string): boolean;
+    /** The hook gave up (not the classifier's, or no frame in 5 s). */
+    abandon(toolUseId: string): void;
+    /** Idempotent: the first outcome for an id wins and is emitted once. */
+    resolve(toolUseId: string, outcome: EscalationOutcome): void;
+    /** True once claimed and until resolved. */
+    isEscalated(toolUseId: string): boolean;
+    /** True after `resolve(..., "approved")`; the `tool_result` path reads it. */
+    wasApproved(toolUseId: string): boolean;
+    /** Session teardown: drop every timer and every per-call record. */
+    clear(): void;
+    private settle;
+    private send;
+    private clearDeadline;
+}
+/** What the hook asks the operator about: the denied call, as the CLI reported it. */
+export type EscalationRequest = {
+    /** The denied call's own tool_use_id — the request references it, never a new one. */
+    toolUseId: string;
+    toolName: string;
+    input: unknown;
+    /** The classifier's reason, shown alongside the command. */
+    reason: string;
+    /** A subagent's `agent_id`, when the denied call ran inside one. */
+    agentId?: string;
+};
+/** Asks the operator one question; rejects when the client cannot answer. */
+export type AskOperator = (req: EscalationRequest, signal: AbortSignal) => Promise<ClassifierEscalationAnswer>;
+/**
+ * The only bridge from the hook to the client: one ACP permission request with
+ * the three classifier answers, referencing the denied call's own tool call
+ * (emitted first if the client has not seen it), and attributed to the
+ * spawning Agent/Task call when the denial happened inside a subagent.
+ */
+export declare function createAskOperator(agent: ClaudeAcpAgent, sessionId: string): AskOperator;
+export type PermissionDeniedHookDeps = {
+    session: {
+        sessionId: string;
+        classifierGrants: GrantStore;
+    };
+    logger: Logger;
+    escalations: Pick<EscalationRegistry, "awaitReasonType" | "claim" | "abandon" | "resolve">;
+    askOperator: AskOperator;
+};
+/**
+ * The `PermissionDenied` hook. A classifier denial becomes one question; "Yes"
+ * or "Yes for this session" becomes a grant plus `retry: true`, which only
+ * tells the model it may retry — the grant hook is what lets the retry run.
+ * Every other path (No, cancel, abort, a failing client, the 590 s bound, an
+ * input that cannot be fingerprinted) grants nothing: fail closed.
+ */
+export declare function createPermissionDeniedHook(deps: PermissionDeniedHookDeps): HookCallback;
+/**
+ * The `PreToolUse` side: a call matching a grant is allowed before the
+ * classifier sees it — measured in Task 1 to skip the classifier. Anything else
+ * returns `{}` and the CLI decides as usual.
+ *
+ * A grant answers a classifier denial, so it applies only while the CLI reports
+ * `auto` for this very call (story 029). In any other mode — or with no mode —
+ * it is held, not consumed: that mode's own checks decide, and the grant is
+ * still there when the session returns to `auto`. The mode is read from the
+ * hook input, never from the adapter's session state, which can lag a switch.
+ */
+export declare function createGrantPreToolUseHook(session: {
+    sessionId: string;
+    classifierGrants: GrantStore;
+}, logger: Logger): HookCallback;
+export {};
+//# sourceMappingURL=classifier-escalation.d.ts.map

package/dist/classifier-escalation.d.ts.map

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