Claude code学习10 Permission 与 Hooks 系统

// src/types/permissions.ts
export type PermissionBehavior = "allow" | "deny" | "ask";

export type PermissionRule = {
  source: PermissionRuleSource;
  ruleBehavior: PermissionBehavior;
  ruleValue: PermissionRuleValue;
};

export type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
};

// src/utils/permissions/permissions.ts
const PERMISSION_RULE_SOURCES = [
  ...SETTING_SOURCES,    // userSettings, projectSettings, localSettings, flagSettings, policySettings
  <!--下面的都是运行时的配置-->
  'cliArg',              // 命令行参数
  'command',             // 运行时命令
  'session',             // 会话级临时规则
] as const satisfies readonly PermissionRuleSource[]

function toolMatchesRule(tool: Pick<Tool, "name" | "mcpInfo">, rule: PermissionRule): boolean {
  // 规则不含 ruleContent 时，匹配整个工具
  if (rule.ruleValue.ruleContent !== undefined) {
    return false;
  }
  const nameForRuleMatch = getToolNameForPermissionCheck(tool);
  if (rule.ruleValue.toolName === nameForRuleMatch) {
    return true;
  }
  // MCP 服务级权限：规则 "mcp__server1" 匹配 "mcp__server1__tool1"
  const ruleInfo = mcpInfoFromString(rule.ruleValue.toolName);
  const toolInfo = mcpInfoFromString(nameForRuleMatch);
  return (
    ruleInfo !== null &&
    toolInfo !== null &&
    (ruleInfo.toolName === undefined || ruleInfo.toolName === "*") &&
    ruleInfo.serverName === toolInfo.serverName
  );
}

// src/utils/permissions/permissions.ts
export const hasPermissionsToUseTool: CanUseToolFn = async (tool, input, context, assistantMessage, toolUseID): Promise<PermissionDecision> => {
  const result = await hasPermissionsToUseToolInner(tool, input, context);

  // 成功的工具调用重置连续拒绝计数
  if (result.behavior === "allow") {
    // ...重置 denial tracking
    return result;
  }

  // dontAsk 模式：将 ask 转换为 deny
  if (result.behavior === "ask") {
    const appState = context.getAppState();
    if (appState.toolPermissionContext.mode === "dontAsk") {
      return {
        behavior: "deny",
        message: DONT_ASK_REJECT_MESSAGE(tool.name),
      };
    }
    // auto 模式：使用分类器代替人工确认
  }
  return result;
};

/**
 * Resolve a PreToolUse hook's permission result into a final PermissionDecision.
 *
 * Encapsulates the invariant that hook 'allow' does NOT bypass settings.json
 * deny/ask rules — checkRuleBasedPermissions still applies (inc-4788 analog).
 * Also handles the requiresUserInteraction/requireCanUseTool guards and the
 * 'ask' forceDecision passthrough.
 *
 * Shared by toolExecution.ts (main query loop) and REPLTool/toolWrappers.ts
 * (REPL inner calls) so the permission semantics stay in lockstep.
 */
export async function resolveHookPermissionDecision(
  hookPermissionResult: PermissionResult | undefined,
  tool: Tool,
  input: Record<string, unknown>,
  toolUseContext: ToolUseContext,
  canUseTool: CanUseToolFn,
  assistantMessage: AssistantMessage,
  toolUseID: string,
): Promise<{
  decision: PermissionDecision
  input: Record<string, unknown>
}

    'Use the classify_result tool to report your classification.'
    '## Output Format',
    '',
    'If the action should be blocked:',
    '<block>yes</block><reason>one short sentence</reason>',
    '',
    'If the action should be allowed:',
    '<block>no</block>',
    '',
    'Do NOT include a <reason> tag when the action is allowed.',
    'Your ENTIRE response MUST begin with <block>. Do NOT output any analysis, reasoning, or commentary before <block>. No "Looking at..." or similar preamble.',

      // In fast-only mode, stage 1 is final — handle block + unparseable here.
      if (mode === 'fast') {
        if (stage1Block === null) {
          logAutoModeOutcome('parse_failure', model, { classifierType })
          return {
            shouldBlock: true,
            reason: 'Classifier stage 1 unparseable - blocking for safety',
            model,
            usage: stage1Usage,
            durationMs: stage1DurationMs,
            promptLengths,
            stage: 'fast',
            stage1RequestId,
            stage1MsgId,
          }
        }
        // stage1Block === true
        logAutoModeOutcome('success', model, {
          classifierType,
          durationMs: stage1DurationMs,
        })
        return {
          shouldBlock: true,
          reason: parseXmlReason(stage1Text) ?? 'Blocked by fast classifier',
          model,
          usage: stage1Usage,
          durationMs: stage1DurationMs,
          promptLengths,
          stage: 'fast',
          stage1RequestId,
          stage1MsgId,
        }
      }
    }

const XML_S2_SUFFIX =
'Review the classification process and follow it carefully,
making sure you deny actions that should be blocked.
 As a reminder, explicit (not suggestive or implicit) user confirmation is required to override blocks.
 Use <thinking> before responding with <block>.'

return {
  shouldBlock: true,
  reason: tooLong
    ? "Classifier transcript exceeded context window"
    : stage1Usage
      ? "Stage 2 classifier error - blocking based on stage 1 assessment"
      : "Classifier unavailable - blocking for safety",
  model,
  unavailable: stage1Usage === undefined,
  transcriptTooLong: Boolean(tooLong),
  stage: stage1Usage ? "thinking" : undefined,
  durationMs: Date.now() - overallStart,
  errorDumpPath,
  ...(stage1Usage && {
    usage: stage1Usage,
    stage1Usage,
    stage1DurationMs,
    stage1RequestId,
    stage1MsgId,
  }),
  promptLengths,
};

/**
 * Resolve a PreToolUse hook's permission result into a final PermissionDecision.
 *
 * Encapsulates the invariant that hook 'allow' does NOT bypass settings.json
 * deny/ask rules — checkRuleBasedPermissions still applies (inc-4788 analog).
 * Also handles the requiresUserInteraction/requireCanUseTool guards and the
 * 'ask' forceDecision passthrough.
 *
 * Shared by toolExecution.ts (main query loop) and REPLTool/toolWrappers.ts
 * (REPL inner calls) so the permission semantics stay in lockstep.
 */
export async function resolveHookPermissionDecision(
  hookPermissionResult: PermissionResult | undefined,
  tool: Tool,
  input: Record<string, unknown>,
  toolUseContext: ToolUseContext,
  canUseTool: CanUseToolFn,
  assistantMessage: AssistantMessage,
  toolUseID: string
): Promise<{
  decision: PermissionDecision;
  input: Record<string, unknown>;
}> {
  const requiresInteraction = tool.requiresUserInteraction?.();
  const requireCanUseTool = toolUseContext.requireCanUseTool;

  if (hookPermissionResult?.behavior === "allow") {
    const hookInput = hookPermissionResult.updatedInput ?? input;

    // Hook provided updatedInput for an interactive tool — the hook IS the
    // user interaction (e.g. headless wrapper that collected AskUserQuestion
    // answers). Treat as non-interactive for the rule-check path.
    const interactionSatisfied = requiresInteraction && hookPermissionResult.updatedInput !== undefined;

    if ((requiresInteraction && !interactionSatisfied) || requireCanUseTool) {
      logForDebugging(`Hook approved tool use for ${tool.name}, but canUseTool is required`);
      return {
        decision: await canUseTool(tool, hookInput, toolUseContext, assistantMessage, toolUseID),
        input: hookInput,
      };
    }

    // Hook allow skips the interactive prompt, but deny/ask rules still apply.
    const ruleCheck = await checkRuleBasedPermissions(tool, hookInput, toolUseContext);
    if (ruleCheck === null) {
      logForDebugging(
        interactionSatisfied
          ? `Hook satisfied user interaction for ${tool.name} via updatedInput`
          : `Hook approved tool use for ${tool.name}, bypassing permission prompt`
      );
      return { decision: hookPermissionResult, input: hookInput };
    }
    if (ruleCheck.behavior === "deny") {
      logForDebugging(`Hook approved tool use for ${tool.name}, but deny rule overrides: ${ruleCheck.message}`);
      return { decision: ruleCheck, input: hookInput };
    }
    // ask rule — dialog required despite hook approval
    logForDebugging(`Hook approved tool use for ${tool.name}, but ask rule requires prompt`);
    return {
      decision: await canUseTool(tool, hookInput, toolUseContext, assistantMessage, toolUseID),
      input: hookInput,
    };
  }

  if (hookPermissionResult?.behavior === "deny") {
    logForDebugging(`Hook denied tool use for ${tool.name}`);
    return { decision: hookPermissionResult, input };
  }

  // No hook decision or 'ask' — normal permission flow, possibly with
  // forceDecision so the dialog shows the hook's ask message.
  const forceDecision = hookPermissionResult?.behavior === "ask" ? hookPermissionResult : undefined;
  const askInput = hookPermissionResult?.behavior === "ask" && hookPermissionResult.updatedInput ? hookPermissionResult.updatedInput : input;
  return {
    decision: await canUseTool(tool, askInput, toolUseContext, assistantMessage, toolUseID, forceDecision),
    input: askInput,
  };
}

const resolved = await resolveHookPermissionDecision(
  hookPermissionResult, // 来自 runPreToolUseHooks
  tool,
  input,
  toolUseContext,
  canUseTool, // useCanUseTool 返回的函数
  assistantMessage,
  toolUseID
);