/** A tool call presented to a policy before it executes. */
export interface ToolCallRequest {
    toolName: string;
    args: unknown;
    toolCallId: string;
    /**
     * design/80 D-E-core: read-only per-run budget snapshot so a STATELESS policy can self-limit against
     * state that survives suspend/resume (a fresh in-memory counter would reset every leg — the supervisor
     * escalation-budget gap). Built by core at prepare time from the DURABLE resource ledger
     * ({@link import("./checkpoint-store.js").ResourceLedger}) + the durable suspend chain; the policy CANNOT
     * widen it (no write-back). Present on every gated `check()` once the runner builds the gate; absent only
     * when a policy is invoked directly (outside a Runner). A NORMAL-ask escalation policy reads it; a SAFETY
     * ask (egress / irreversible) ignores it and ALWAYS asks (invariant #2 stays structural — core mints
     * `irreversible_ask` for safety tools regardless of any budget).
     */
    budget?: {
        /**
         * Durable resource $ this run may STILL spend (micro-USD); `undefined` = no $ ceiling configured. Frozen
         * total, prior-wins → it monotonically SHRINKS across legs and is NEVER re-granted by a resume (a
         * deny-resume continues with the same frozen remaining). **NEVER falsy-test** (`0` = exhausted, NOT
         * "unlimited" — only `undefined` is unlimited).
         */
        resourceRemainingMicroUsd?: number;
        /** Durable cumulative resource $ already spent across all prior legs (micro-USD); accumulates, never refunded. */
        resourceSpentMicroUsd: number;
        /** How many times this run has already suspended (the durable suspend chain). Lets the policy tighten as
         *  the chain grows — the precise complement to the unconditional `suspendLoopCap` backstop. */
        suspendCount: number;
    };
}
/** Where a decision came from, for audit (design/37). */
export type DecisionReason = "rule" | "mode" | "hook" | "safety" | "classifier";
/**
 * A three-state permission decision for a tool call (design/37). Upgrades the old two-state
 * `{allow|deny}`:
 *  - `allow` may carry `updatedInput` — REWRITTEN args (redact a secret, clamp a path/value) that
 *    REPLACE the model's args before execution (re-validated against the tool schema first).
 *    `deny` may ALSO carry `updatedInput` (1.256 复审 MED-2): it never executes anything, but a
 *    combined-policy deny reports the ACCUMULATED pre-deny rewrite (policy A redacted → policy B
 *    denied) so a deny OBSERVER (`Hooks.permissionDenied`) sees the final post-rewrite args, not the
 *    stale un-redacted ones.
 *  - `ask` requests human confirmation; with no approver wired it resolves deterministically to deny
 *    (headless auto-deny, see `RunnerDeps.onAsk`).
 *  - `deny` blocks the call.
 * Human-readable text is `message` (preferred) or the legacy `reason`; read it via {@link decisionText}.
 * **Backward-compatible:** the old `{action:"allow"}` / `{action:"deny", reason}` are valid subsets.
 */
export type PermissionResult = {
    action: "allow";
    updatedInput?: unknown;
    message?: string;
    reason?: string;
    decisionReason?: DecisionReason;
} | {
    action: "ask";
    updatedInput?: unknown;
    message?: string;
    reason?: string;
    decisionReason?: DecisionReason;
} | {
    action: "deny";
    updatedInput?: unknown;
    message?: string;
    reason?: string;
    decisionReason?: DecisionReason;
};
/** @deprecated alias kept for back-compat — `PermissionResult` is the canonical three-state type (design/37). */
export type ToolDecision = PermissionResult;
/** The human/model-readable text of a decision: `message` wins, falling back to the legacy `reason`. */
export declare function decisionText(d: PermissionResult): string | undefined;
/**
 * Gates tool calls before they execute (the production safety layer for "processing/changing data").
 *
 * `check` runs before each tool call. Return `{ action: "deny", reason }` to block it — the model
 * receives an error tool result with the reason and can continue or report blocked. Return
 * `{ action: "allow" }` to permit it.
 *
 * `check` may be async, which is also how **human-in-the-loop approval** works: a deployment can
 * hold the promise open until an operator approves/denies. `signal` fires when the task aborts
 * (timeout / max turns / cancel) — honor it to release a pending approval instead of hanging (F4).
 * The Runner also races `check` against `signal` itself, so a policy that ignores it still cannot
 * hang the worker past the deadline; passing it through just lets you clean up the wait early.
 */
export interface ToolPolicy {
    check(req: ToolCallRequest, signal?: AbortSignal): ToolDecision | Promise<ToolDecision>;
}
/**
 * Name-based allow/deny. `deny` always wins. If `allow` is provided, only those tools are permitted
 * (everything else denied). Without `allow`, everything not in `deny` is permitted.
 */
export declare function createAllowDenyPolicy(opts: {
    allow?: string[];
    deny?: string[];
}): ToolPolicy;
/**
 * Human-in-the-loop approval for selected tools. Tools in `requireApproval` call `approve(req)` and
 * are allowed only if it resolves true; tools in `deny` are always blocked; everything else is allowed
 * (override with `denyByDefault: true` to allow only `requireApproval` + an explicit `autoAllow`).
 */
export declare function createApprovalPolicy(opts: {
    /** Tools that need an approval decision. */
    requireApproval: string[];
    /**
     * The approval decision (e.g. await an operator). Resolve true to allow, false to deny. `signal`
     * fires when the task aborts — race your wait against it (e.g. an OA approval callback) so a
     * never-answered request is released at the deadline rather than holding the worker.
     */
    approve: (req: ToolCallRequest, signal?: AbortSignal) => boolean | Promise<boolean>;
    /** Always-denied tools. */
    deny?: string[];
    /** Always-allowed tools (only meaningful with `denyByDefault`). */
    autoAllow?: string[];
    /** When true, deny anything not in `requireApproval` or `autoAllow`. Default false. */
    denyByDefault?: boolean;
    /**
     * Optional self-contained deadline (ms): if `approve` hasn't resolved by then, deny. Belt-and-
     * suspenders for **direct** callers — the Runner already races `check` against the task signal, so
     * a Runner-driven task is bounded regardless; this protects a caller invoking `check()` without a
     * signal. Omit to wait indefinitely on `approve`.
     */
    approvalTimeoutMs?: number;
}): ToolPolicy;
/**
 * Combine policies with the three-state fold **deny > ask > allow** (design/37): the WORST outcome
 * across all policies wins. A `deny` short-circuits (nothing can override it); an `ask` does NOT
 * short-circuit — scanning continues, because a later policy may still `deny` (which outranks ask).
 * With no deny, the first `ask` wins; with neither, `allow`.
 *
 * **Idempotency requirement:** because the fold continues past an `ask` to look for a later `deny`, a
 * policy's `check()` can be invoked even after an earlier policy returned `ask`. `check()` MUST be
 * idempotent — repeated calls with the same {@link ToolCallRequest} return the same decision and
 * accumulate no side effects (e.g. don't fire a duplicate approval notification on each call).
 */
export declare function combinePolicies(...policies: ToolPolicy[]): ToolPolicy;
/**
 * design/center §10 — a COARSE allow/deny gate keyed on the LEADING command NAME (`argv[0]`) of a single
 * simple shell command. It reuses the ONE shared simple-command parser
 * ({@link import("../tools/fs/index.js").parseLeadingCommandName}) — it does NOT re-implement argv[0] parsing
 * (a second parser would drift and open a bypass). For a `bash`/`bash_readonly` call it extracts the leading
 * command name and:
 *  - if the name is in `deny` → `deny` (deny-wins, matching {@link createAllowDenyPolicy}; NOT last-match-wins,
 *    which would fight {@link combinePolicies}'s deny>ask>allow fold);
 *  - else if `allow` is provided and the name is NOT in it → `defaultAction` (`"ask"` default, or `"deny"`);
 *  - else → `allow`.
 * A command the parser cannot reduce to a single bare name (it has shell operators / a path-prefix / a leading
 * env-assignment) is treated by `defaultAction` (fail-toward-gate): such a command is exactly what would bypass
 * an argv[0] filter, so it should not silently `allow`. NON-shell tools are out of scope → `allow` (this gate
 * only speaks about shell command names; compose it with other policies for the rest).
 *
 * **core ships NO opinionated command list** — only this mechanism. The actual `allow`/`deny` rule set is
 * injected by the profile/config/deployment.
 *
 * ⚠️ **NOT A SANDBOX — coarse filter / defense-in-depth only.** This matches `argv[0]` NAME and nothing else,
 * so the bypass surface is large and the gate MUST NOT be relied on as containment:
 *   - command substitution / subshells (`$(curl …)`, backticks), pipes, redirects, `;`/`&&` chaining — all
 *     rejected as un-parseable here (→ `defaultAction`), so they don't sneak past `allow`, but that is a GATE
 *     not a guarantee of safety;
 *   - an indirection wrapper runs an arbitrary inner program under an allowlisted `argv[0]`: `sh -c '…'`,
 *     `env FOO=bar curl …`, `sudo rm …`, `timeout 5 curl …`, `xargs curl`, `find . -exec rm {} \;`,
 *     `python -c '…'`, `npm run <script>`, `git <subcommand>` — the inner action is INVISIBLE to an
 *     argv[0]-name filter. Allowlisting any such wrapper effectively allowlists everything it can launch.
 * Real isolation is the deployment's sandboxed `executionEnv` (a remote/E2B container with no egress, a
 * read-only FS, dropped capabilities). Use this only as a cheap first-line coarse filter layered over that.
 *
 * 🪤 **TRAP #1 — `TaskSpec.toolPolicy` OVERRIDES (does not merge) `RunnerDeps.toolPolicy`.** A consumer that
 * sets `TaskSpec.toolPolicy = createCoarseCommandNamePolicy(…)` directly **silently discards the deployment's
 * baseline policy** (the runner does `spec.toolPolicy ?? deps.toolPolicy`). To LAYER this on top of a baseline
 * you MUST compose explicitly: `combinePolicies(deploymentBaseline, createCoarseCommandNamePolicy(…))`
 * (deny-wins — both policies' denies still fire). {@link tightenTaskSpec} does this for you.
 *
 * 🪤 **TRAP #2 — under `TaskSpec.shellGate: "classify"`, a plain `ask` from this policy is promoted to a
 * NON-budgetable `irreversible_ask`.** `shellGate:"classify"` statically marks `bash` `irreversibility:"maybe"`;
 * the safety gate keys the checkpoint axis on that STATIC tool mark (not on `decisionReason`), so a `bash`
 * command that doesn't prove reversible suspends as `irreversible_ask` — which a budget-aware escalation
 * resolver will NEVER auto-approve. Net: combining this policy's `ask` with `shellGate:"classify"` does NOT
 * give you a budgetable normal-ask on `bash`; it gives a hard human-approval suspend. Choose `shellGate` and a
 * `defaultAction:"ask"` deliberately.
 */
export declare function createCoarseCommandNamePolicy(opts: {
    /** Command names (argv[0]) explicitly allowed. If provided, a name NOT listed falls to `defaultAction`. */
    allow?: string[];
    /** Command names (argv[0]) explicitly denied — `deny` always wins (checked before `allow`). */
    deny?: string[];
    /** What to do for a command not matched by `allow` (or un-parseable): `"ask"` (default) or `"deny"`. */
    defaultAction?: "ask" | "deny";
    /** Override the shell tool names this gate parses (default `Bash` — bash + bash_readonly share the CC name). */
    tools?: string[];
}): ToolPolicy;
/**
 * Scan a (possibly compound) shell command for a recursive+forced delete whose target cannot be resolved from
 * the command text itself — the deterministic sema port of CC 2.1.206 "Unverifiable Deletion Target".
 * Returns a human/model-readable description of the first offending target, or `undefined` when clean.
 *
 * Fires on: `rm` with recursive (`-r`/`-R`/`--recursive`) AND force (`-f`/`--force`) flags whose target
 * contains command substitution, a positional/special parameter, or a variable with NO in-window assignment
 * (`VAR=…`, `export VAR=…`, `read VAR`, `for VAR in …` earlier in the SAME command string — our verification
 * window is the single command, stricter than CC's whole-transcript window); `… | xargs rm -rf` (the target
 * comes from pipe output no gate can see); and `Remove-Item -Recurse -Force` with a `$` target.
 * Does NOT fire on: literal paths (`rm -rf ./node_modules`), in-window-assigned variables, or
 * `$TMPDIR/<literal>` (safe-var carve-out; a glob after the safe var still fires).
 * Out of scope (different CC rules, not this port): `find -delete` sweeps, literal-path destruction.
 *
 * Exported for tests.
 */
export declare function findUnverifiableRecursiveDelete(command: string, safeVars?: ReadonlySet<string>): string | undefined;
/**
 * CC 2.1.206 "Unverifiable Deletion Target" parity (auto-mode rule, 2.1.205): DENY a recursive+forced delete
 * whose target is a variable / substitution that cannot be resolved from the command itself — fail-closed
 * («Fail closed», 206 bundle). See {@link findUnverifiableRecursiveDelete} for exact firing conditions.
 * The deny message carries the CC-sanctioned remediation: re-run with the resolved LITERAL path written into
 * the command (or assign the variable in the same command), so the target becomes verifiable.
 *
 * Deny (not ask) on purpose: `onAsk:"allow"` — sema's bypass-mode analog — would auto-approve an ask, and the
 * CC rule text forbids exactly that («must be explicitly approved … cannot be auto-allowed by a permission
 * rule»). A deny short-circuits the deny>ask>allow fold, making the invariant structural. Core wires this
 * policy ALWAYS-ON in the runner's gate composition (prepare-task); it is exported so deployments can also
 * compose/test it directly.
 */
export declare function createUnverifiableDeletePolicy(opts?: {
    /** Extra variable names treated as well-known-safe roots (default `TMPDIR`). */
    safeVars?: readonly string[];
    /** Override the shell tool names this gate parses (default `Bash`). */
    tools?: string[];
}): ToolPolicy;
/**
 * CC 2.1.206 "Session Transcript Tampering" parity (auto-mode rule, 2.1.205): DENY shell commands and
 * file-write tools that would modify sema's OWN session transcripts — the harness-written `.jsonl` session
 * state under `<dataRoot>/sessions/` (`$AGENT_DATA_DIR ?? ~/.ai-agent`, stores/file/session-store.ts; the
 * sema analog of CC's `~/.claude/projects/` transcripts, including the first-line `meta` record CC calls the
 * classifier ground-truth line). A tampered entry feeds every later leg once the session is resumed —
 * self-erasure of the audit trail — so the deny is unconditional (no ask; see the mapping note above).
 *
 * «Reading transcripts is routine and not this rule»: a SINGLE simple command whose argv[0] is in the
 * read-only allowlist ({@link BASH_READONLY_DEFAULT_ALLOW}) may reference the transcript dir (`ls`, `cat`,
 * `grep`, …). Anything else that references it — a write command, a redirect/pipe/compound command (which the
 * shared parser rejects → fail-closed), an `rm`/`mv`/`sed -i` — is denied. `Write`/`Edit` file tools are
 * denied on an absolute or `~`-rooted `file_path` inside the transcript dir.
 *
 * Coarse + textual by design (defense-in-depth, not containment): the match is against the RESOLVED data
 * root's absolute path plus its `~/…` and `$HOME/…` spellings — a command that reaches the same files through
 * an unrelated alias/symlink is the sandbox's job. Wired ALWAYS-ON by the runner (prepare-task); exported for
 * direct composition/tests.
 */
export declare function createTranscriptIntegrityPolicy(opts?: {
    /** Transcript directories to protect. Default: `($AGENT_DATA_DIR ?? ~/.ai-agent)/sessions`. */
    sessionsDirs?: readonly string[];
    /** argv[0] allowlist for read-only access to the transcript dir (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
    readAllow?: readonly string[];
    /** Override the shell tool names this gate parses (default `Bash`). */
    tools?: string[];
}): ToolPolicy;
/** The structured context an `onAsk` approver receives for an `ask` decision (design/37). */
export interface AskRequest {
    toolName: string;
    toolCallId: string;
    /** The (post-rewrite) args the tool would run with. */
    args: unknown;
    /** The human/model-readable prompt explaining what needs approval. */
    message: string;
    /** Runner-filled source identity (design S1d §1): the end-user {@link AskRequest} issuing task's
     *  `principal` (design/62). An AGGREGATING `onAsk` (one approver fanning over N delegated workers)
     *  attributes asks per-user by this. Worker/tool cannot set it (not a tool arg). Undefined ⇒ no principal.
     *  A non-aggregating `onAsk` simply ignores it (additive, no-op). `readonly`: Runner-populated metadata,
     *  not a caller/worker-settable field. Populated ONLY on the synchronous `resolveAsk`/`onAsk` path — a
     *  durable suspend/checkpoint flow does NOT invoke `onAsk` on the suspend side, so v1 ask-aggregation
     *  requires `checkpointStore` unset (design S1d §1.4 P-a). */
    readonly principal?: string;
    /** Runner-filled source-task identity (= the issuing task's session id). An aggregating `onAsk` uses it
     *  to tell which worker an ask came from (nested grandchildren each carry their own session id).
     *  **worker-unforgeable for Runner-created delegated subagents** (a child never sets sessionId — the
     *  Runner mints it); a top-level caller MAY continue its own session id via `TaskSpec.sessionId`, so this
     *  is NOT a global "never forgeable" run id — aggregation only aggregates delegated workers, the context
     *  where it holds (design S1d §1.3). `readonly` + same sync-path-only / P-a caveat as `principal`.
     *  Undefined ⇒ no source task id. */
    readonly sourceTaskId?: string;
}
/**
 * How an `ask` decision is resolved when a policy/hook requests human confirmation (design/37):
 *  - `"deny"` (and the default when omitted) — **headless auto-deny**: no approver, so `ask` resolves
 *    deterministically to `deny` with a model-readable reason. The safe default for stateless automation.
 *  - `"allow"` — auto-approve every `ask` (e.g. a trusted batch run).
 *  - a function — await an operator's decision (true=allow, false=deny). `signal` fires when the task
 *    aborts; race your wait against it so an unanswered ask is released at the deadline, not hung.
 *
 * **Contract:** the function MUST be fail-closed (a throw → deny, surfacing the real cause), idempotent
 * for a given request, and tolerant of being called after the task signal aborted.
 */
export type OnAsk = "deny" | "allow" | ((req: AskRequest, signal?: AbortSignal) => boolean | Promise<boolean>);
/**
 * Resolve an `ask` decision to a terminal `allow`/`deny` via {@link OnAsk}. Centralizes the headless
 * auto-deny default, fail-closed error handling, and stable deny reasons so every ask site is
 * consistent. Never returns `ask`.
 */
export declare function resolveAsk(req: AskRequest, onAsk: OnAsk | undefined, signal?: AbortSignal): Promise<PermissionResult>;
//# sourceMappingURL=tool-policy.d.ts.map