get_policy_summary

Instructions

Implementation Reference

• src/core/policy.ts:193-206 (handler)

  Core handler function that loads the project policy and returns a high-level summary with boolean flags for each policy section and the full PolicyConfig details.

  export function getPolicySummary(projectPath?: string): {
    hasMcpPolicy: boolean;
    hasExecPolicy: boolean;
    hasSecretPolicy: boolean;
    details: PolicyConfig;
  } {
    const policy = loadPolicy(projectPath);
    return {
      hasMcpPolicy: !!policy.mcp,
      hasExecPolicy: !!policy.exec,
      hasSecretPolicy: !!policy.secrets,
      details: policy,
    };
  }

• src/mcp/tools/policy.ts:67-86 (handler)

  MCP tool handler that registers 'get_policy_summary' as a server tool, enforces its own policy gate, calls getPolicySummary, and returns formatted JSON.

  server.tool(
    "get_policy_summary",
    [
      "[policy] Return a high-level summary of the project's `.q-ring.json` governance policy — counts of allow/deny rules for tools, key reads, exec commands, plus approval and rotation requirements.",
      "Use to orient an agent (or the user) on what guardrails are active before attempting policy-restricted actions; prefer `check_policy` for a precise per-action verdict.",
      "Read-only. Returns pretty-printed JSON; missing policy file returns an empty/default summary rather than an error so callers can branch on the counts.",
    ].join(" "),
    {
      projectPath,
    },
    async (params) => {
      const toolBlock = enforceToolPolicy(
        "get_policy_summary",
        params.projectPath,
      );
      if (toolBlock) return toolBlock;
      const summary = getPolicySummary(params.projectPath);
      return text(JSON.stringify(summary, null, 2));
    },
  );

• src/core/policy.ts:11-30 (schema)

  Schema type definition for the policy configuration (PolicyConfig) that the summary reports on.

  export interface PolicyConfig {
    mcp?: {
      allowTools?: string[];
      denyTools?: string[];
      readableKeys?: string[];
      deniedKeys?: string[];
      deniedTags?: string[];
    };
    exec?: {
      allowCommands?: string[];
      denyCommands?: string[];
      maxRuntimeSeconds?: number;
      allowNetwork?: boolean;
    };
    secrets?: {
      requireApprovalForTags?: string[];
      requireRotationFormatForTags?: string[];
      maxTtlSeconds?: number;
    };
  }

• src/mcp/tool-registration.ts:19-30 (registration)

  Registration entry point that wires registerPolicyTools (which includes get_policy_summary) into the MCP server.

  export function registerMcpTools(server: McpServer): void {
    registerSecretTools(server);
    registerProjectTools(server);
    registerTunnelTools(server);
    registerTeleportTools(server);
    registerAuditTools(server);
    registerValidationTools(server);
    registerHookTools(server);
    registerToolingTools(server);
    registerAgentTools(server);
    registerPolicyTools(server);
  }

• src/mcp/tools/_shared.ts:39-48 (helper)

  Helper used by the tool handler to enforce its own policy gate before executing.

  export function enforceToolPolicy(toolName: string, projectPath?: string) {
    const decision = checkToolPolicy(toolName, projectPath);
    if (!decision.allowed) {
      return text(
        `Policy Denied: ${decision.reason} (source: ${decision.policySource})`,
        true,
      );
    }
    return null;
  }