/** * The tool policy's refusals as exit 33 (Issue #4437), the way `role-failure.ts` maps * the role API's refusals. * * The server answers 409 `TOOL_POLICY_DENIED` (send / ask / respond, strict included) * or `RELAY_TOOL_POLICY_DENIED` (`POST /api/relays`) when antigravity may not be * driven from where this CLI runs (see `send-origin.ts`). Nothing was typed and no * relay was opened, and sending again gets the same answer: a usage declaration on * the server, or a person on the web UI or in a terminal, is what changes it. * * {@link ToolPolicyDeniedError} is deliberately NOT an `ApiError`. `ApiClient` throws * it for those two codes on the routes that type into a session and on relay * creation, so every catch written for HTTP failures lets it through: the strict * respond's 409 → exit 40 (`session_conflict`), `postMessage`'s "safe to send it * again" note and `registerRelay`'s exit 2 never see it. The commands catch it * and call {@link reportToolPolicyDenial}. * * Free of the file system, of child processes and of `api-client` (which imports this * module, and which `lib/brief` / `lib/handoff` reach: guards keep tmux out of that graph). * * @module cli/utils/tool-policy-failure */ import { RELAY_TOOL_POLICY_DENIED, TOOL_POLICY_DENIED } from '../../lib/tool-policy/policy'; import type { ToolPolicyDeniedResponse, ToolPolicyDetailResponse } from '../types/tool-policy-responses'; /** Whether a POST to `path` is one that types into a session. */ export declare function isSendFamilyRoute(path: string): boolean; /** * Where a 409 `TOOL_POLICY_DENIED` / `RELAY_TOOL_POLICY_DENIED` becomes a * {@link ToolPolicyDeniedError}: the routes that type into a session, relay creation, * and the writes a send makes before its message (Issue #4449). Elsewhere (the * Auto-Yes route, #4436) it stays an `ApiError`, read by that command's own handling; * `send --auto-yes` turns that one into a refusal itself * ({@link toolPolicyDenialFromResponse} reads its body too). */ export declare function isToolPolicyRoute(path: string): boolean; /** * Where `ApiClient` puts a construction warning (`--token` in the process list, a * token over plain HTTP) when the caller names no `onWarning` of its own: stderr at * once, or held while {@link holdClientWarnings} is on. The same idea as the * `auto-yes` command's held warnings (#4436): a refusal's reason comes first. */ export declare function clientWarning(line: string): void; /** * Hold construction warnings from here until {@link flushClientWarnings}: `send`, * `ask` and `respond` call it first, so a tool-policy refusal is stderr's first line * and the warnings follow it. Anything left held is printed when the process exits * (an exit from deep inside a command keeps its warning). */ export declare function holdClientWarnings(): void; /** Print what was held, and print at once from now on. */ export declare function flushClientWarnings(): void; /** The two refusal codes of the tool policy. */ export type ToolPolicyDenialCode = typeof TOOL_POLICY_DENIED | typeof RELAY_TOOL_POLICY_DENIED; /** The codes that map to exit 33 (and nothing else does). */ export declare const TOOL_POLICY_DENIAL_EXITS: Readonly>; /** What the refused request named, for `--json` when the command had not resolved it. */ export interface RefusedRequestTarget { instanceId?: string; cliToolId?: string; } /** * A request the tool policy refused: nothing typed, no relay opened (`sent: false`). * Carries exit 33 like {@link ApiError} carries its exit code, without being one. */ export declare class ToolPolicyDeniedError extends Error { readonly code: ToolPolicyDenialCode; /** The server's `policy`, or null when the body had none. */ readonly policy: ToolPolicyDetailResponse | null; readonly statusCode: number; readonly payload: ToolPolicyDeniedResponse; /** What the refused request named (its `instanceId` / `cliToolId`). */ readonly request: RefusedRequestTarget; readonly exitCode: number; /** Nothing was typed (I8). */ readonly sent: false; constructor(code: ToolPolicyDenialCode, /** The server's `policy`, or null when the body had none. */ policy: ToolPolicyDetailResponse | null, statusCode: number, payload: ToolPolicyDeniedResponse, /** What the refused request named (its `instanceId` / `cliToolId`). */ request?: RefusedRequestTarget); } /** Whether `error` is a tool-policy refusal (exit 33). */ export declare function isToolPolicyDenied(error: unknown): error is ToolPolicyDeniedError; /** * The refusal a failed response is, or null. Only a 409 with one of the two codes: * the code on another status, or another 409 (the role's 32, `PROMPT_WAITING`, a * relay chain), keeps its own handling. */ export declare function toolPolicyDenialFromResponse(status: number, payload: unknown, requestBody?: unknown): ToolPolicyDeniedError | null; /** * The stderr lines: the reason first (`Error []: `), the terms and the * FAQ second, then how to lift it and what was (not) done. */ export declare function formatToolPolicyDenialLines(error: ToolPolicyDeniedError): string[]; /** The `--json` answer of a refused `ask` / `respond` (design §3.4). */ export interface ToolPolicyRefusalJson { worktreeId: string; instanceId: string | null; cliToolId: string | null; sent: false; refusal: { code: ToolPolicyDenialCode; reason: string; operation: string; origin: string; message: string; links: { terms: string; faq: string; }; unlock: string; /** Relay only: the refused end. */ endpoint?: 'from' | 'to'; }; } /** The `--json` object of a refusal. The command's own target wins over the request's. */ export declare function toolPolicyRefusalJson(error: ToolPolicyDeniedError, worktreeId: string, target?: { instanceId?: string | null; cliToolId?: string | null; }): ToolPolicyRefusalJson; /** * Print a refusal and exit 33: the stderr lines always, and with `json` the §3.4 * object on stdout. A mocked `process.exit` returns; callers `return` after it. */ export declare function reportToolPolicyDenial(error: ToolPolicyDeniedError, options: { worktreeId: string; json?: boolean; target?: { instanceId?: string | null; cliToolId?: string | null; }; }): void; /** * The `--help` paragraph of `send`, `ask` and `respond` (design §2.2). One text, so * the three cannot drift apart. */ export declare const ANTIGRAVITY_GUARD_HELP = "Antigravity (Issue #4437): without a usage declaration, sending to an antigravity\ninstance from inside a CommandMate session, a Schedule run, an AI agent, or a\ncaller with no terminal is refused before anything is typed (exit 33), and\nrelays with antigravity at either end are refused (exit 33). The web UI and\ncommands typed in a terminal are not affected. The sender kind is what this CLI\nreads from its own environment and the server cannot verify it: this is a guard\nagainst accidental use, not a guarantee of compliance with the Google\nAntigravity terms (Section 6 / FAQ). A send that writes before its message\n(--register --role, --contract, --auto-yes) is refused by the server at that\nwrite, which then writes nothing. The first stderr line is\n\"Error [TOOL_POLICY_DENIED]: ...\" (RELAY_TOOL_POLICY_DENIED for a relay); the\nnext names the terms and the FAQ, then how to lift it (the server's\n`CM_ANTIGRAVITY_USAGE=api-key` or `enterprise`). Sending again is refused the same way."; //# sourceMappingURL=tool-policy-failure.d.ts.map