@yagni-app/code 1.0.5 → 1.0.7

package/dist/extension/permission/gate.d.ts

@@ -26,7 +26,7 @@
  * When the mode leaves plan, stale plan-context messages are filtered out of
  * the context so the model doesn't keep believing it is restricted.
  */
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolCallEvent, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
 import { type ApprovedPrefixGrant } from "./approvedPrefixes.js";
 import type { HookRunner } from "../hooks.js";
 import { type BlessStore } from "../bless.js";
@@ -53,6 +53,13 @@ export interface PermissionPolicy {
     reviewConfirmTools: string[];
     /** Consequential external writes that require fresh consent in every mode. */
     alwaysConfirmTools?: string[];
+    /**
+     * Optional predicate: this tool is a mutating action (an MCP server tool
+     * that writes, for instance) so it joins planBlock/reviewConfirm even
+     * though it was registered dynamically and never appears in the static
+     * lists above. Evaluated AFTER the static lists (a static entry wins).
+     */
+    isMutating?: (toolName: string) => boolean;
     /**
      * Optional: a recorded decision already blesses this action, so it auto-runs in
      * review mode instead of prompting. The hook for tying the gate to captured
@@ -87,6 +94,33 @@ export interface GateDecision {
      */
     classifyJustification?: string;
 }
+/**
+ * What the hard floors say about an ALLOW-rule verdict — the three invariants
+ * that outrank any user/project permission rule. Extracted from the inline
+ * allow path so the gate reads linearly and the floors are directly testable.
+ * PURE — no I/O, no session state:
+ *
+ *   "allow"   no floor applies — the rule's allow short-circuits everything
+ *   "block"   the exec-policy forbidden band holds despite the allow rule
+ *   "confirm" alwaysConfirmTools keeps its fresh-consent contract
+ *   "hold"    plan mode's no-mutation contract outranks the allow rule —
+ *             fall through to the normal plan-mode gate
+ *
+ * Order is deliberate: plan-mode first (its outcome routes to the EXISTING
+ * plan-mode machinery, not a bespoke block); then the terminal forbidden-band
+ * block; then the confirm deferral.
+ */
+export type AllowRuleFloorOutcome = {
+    kind: "allow";
+} | {
+    kind: "block";
+    reason: string;
+} | {
+    kind: "confirm";
+} | {
+    kind: "hold";
+};
+export declare function allowRuleFloorVerdict(toolName: string, params: Record<string, unknown>, mode: PermissionMode, policy: PermissionPolicy): AllowRuleFloorOutcome;
 /**
  * Pure permission decision for one tool call under a mode + policy. Auto allows
  * ordinary tools; plan blocks the write/exec set; review marks writes for confirmation
@@ -98,7 +132,7 @@ export declare function decideGate(toolName: string, params: Record<string, unkn
  * is emitted per terminal outcome; `consulted` says whether a Guardian LLM
  * call actually happened (grants/cache hits skip it).
  */
-export type GuardianGateOutcome = "prefix_allow" | "cached_allow" | "allow" | "deny" | "ask_approved" | "ask_approved_remembered" | "ask_denied" | "ask_headless_blocked" | "breaker_ask_approved" | "breaker_blocked" | GuardianError;
+export type GuardianGateOutcome = "prefix_allow" | "cached_allow" | "sandbox_auto_allow" | "allow" | "deny" | "ask_approved" | "ask_approved_remembered" | "ask_denied" | "ask_headless_blocked" | "breaker_ask_approved" | "breaker_blocked" | GuardianError;
 /**
  * Rich per-decision event for opt-in storage (YAG-510). Carries the RAW
  * command — the wiring layer (index.ts) hashes/redacts per the workspace's
@@ -122,6 +156,17 @@ export interface GuardianGateEvent {
      * error-fallback ask that the user then approved). */
     guardianError?: GuardianError;
 }
+/** Claude Code's decision sources for a tool permission outcome. */
+export type ToolDecisionSource = "config" | "hook" | "user_permanent" | "user_temporary" | "user_abort" | "user_reject";
+/** One terminal tool_call outcome, in Claude Code's telemetry shape. */
+export interface ToolDecisionEvent {
+    toolName: string;
+    toolCallId?: string;
+    decision: "accept" | "reject";
+    source: ToolDecisionSource;
+    /** For edit/write tools: the target path (language attribution). */
+    filePath?: string;
+}
 /** What was blessed with "don't ask again", handed to the capture hook. */
 export interface BlessRememberInfo {
     tool: string;
@@ -180,12 +225,55 @@ export interface RegisterPermissionDeps {
     /** Persist a new grant (fire-and-forget; the in-memory list is updated
      * either way). index.ts wires approvedPrefixes.appendGrant. */
     persistGrant?: (grant: ApprovedPrefixGrant) => void;
+    /**
+     * persist a user-level permission rule string (e.g.
+     * `Bash(git push:*)`) into ~/.yagni-code/config.json permissions.allow.
+     * Wired by index.ts; offered as a third option on Guardian ask dialogs.
+     * Fail-soft: the in-session approval applies even if the write fails.
+     */
+    persistUserRule?: (ruleString: string) => void;
     /**
      * Called (fire-and-forget) at every terminal prompt-band outcome with the
      * rich storage event (raw command — the wiring layer redacts/hashes).
      * Fail-soft; never blocks.
      */
     onGuardianEvent?: (event: GuardianGateEvent) => void;
+    /**
+     * Called (fire-and-forget) at EVERY terminal tool_call outcome, for every
+     * tool, with the Claude Code-shaped decision (accept/reject + source).
+     * Feeds the telemetry `tool_decision` event and the
+     * `code_edit_tool.decision` counter. Fail-soft; never blocks.
+     */
+    onToolDecision?: (event: ToolDecisionEvent) => void;
+    /**
+     * settings-based permission rules (user + project config.json).
+     * When present, evaluated at the TOP of the tool_call handler, before
+     * hooks: deny → ask → allow, first match wins. Deny/ask are final; allow
+     * short-circuits the Guardian but can never lift the exec-policy forbidden
+     * band or the alwaysConfirmTools contract (both re-checked below).
+     */
+    permissionRules?: readonly import("../permissionRules/loadConfig.js").PermissionRule[];
+    /** ~/.yagni-code — the user `/`-anchor base for path rules. */
+    rulesUserStateHome?: string;
+    /** Project root for project-source `/`-anchored path rules; null outside a repo. */
+    rulesProjectRoot?: string | null;
+    /** Overrides ~ expansion for path rules (tests). */
+    rulesHomeDir?: string;
+    /** Called (fire-and-soft) after every rule verdict for debug logging. */
+    onRuleVerdict?: (event: import("../permissionRules/engine.js").RuleEvaluation & {
+        toolName: string;
+        cwd: string;
+    }) => void;
+    /**
+     * Sandbox auto-allow (YAGNI Code sandbox): when present and true for this bash call,
+     * a prompt-band command runs sandboxed WITHOUT a Guardian consult or user
+     * prompt (Claude's autoAllowBashIfSandboxed). Consulted AFTER deny/ask
+     * rules, the exec-policy forbidden band, grants, and the session cache —
+     * never in plan mode (plan's no-mutation contract outranks it). The
+     * caller (session.ts) owns the decision: sandbox initialized + this
+     * command will be wrapped + autoAllow enabled.
+     */
+    sandboxAutoAllow?: (toolName: string, params: Record<string, unknown>) => boolean;
     /**
      * User-configurable lifecycle hooks (YAG-506). When present, PreToolUse
      * hooks run before decideGate and can short-circuit (allow/deny/ask),
@@ -210,9 +298,23 @@ export declare function buildModeContextMessage(mode: PermissionMode): string;
 export declare function filterStaleModeContext<T>(messages: T[], currentMode?: PermissionMode): T[];
 /** Legacy alias — the original plan-mode filter name. */
 export declare const filterStalePlanContext: typeof filterStaleModeContext;
+/** The decision source of ONE tool_call (telemetry), carried per invocation
+ * because tool calls run concurrently: refined by the user dialog, hooks,
+ * and Guardian outcomes as the call moves through the gate. */
+interface DecisionSlot {
+    source: ToolDecisionSource;
+}
+/**
+ * The pi tool_call handler wiring (crash-honest attribution). Extracted so
+ * the telemetry contract is testable against the production path: a thrown
+ * gate records reject — never accept — logs a gate_crashed line (metadata
+ * only), and rethrows so pi's handling of a crashed handler is unchanged.
+ */
+export declare function wireToolCallGate(pi: Pick<ExtensionAPI, "on">, run: (event: ToolCallEvent, ctx: ExtensionContext, slot: DecisionSlot) => Promise<ToolCallEventResult | undefined>, onToolDecision?: (ev: ToolDecisionEvent) => void): void;
 /**
  * Wire the tool_call gate + the /mode command onto a shared mode holder. Default
  * auto, so absent any /mode this is a no-op over today's behavior.
  */
 export declare function registerPermissionGate(pi: ExtensionAPI, deps?: RegisterPermissionDeps): void;
+export {};
 //# sourceMappingURL=gate.d.ts.map