Function registerAuditTool

pkg/cli/mcp_tools_privileged.go:323–503

registerAuditTool registers the audit tool with the MCP server. The audit tool requires write+ access and checks actor permissions. Returns an error if schema generation fails.

(server *mcp.Server, execCmd execCmdFunc, actor string, validateActor bool)

// The audit tool requires write+ access and checks actor permissions.
// Returns an error if schema generation fails.
func registerAuditTool(server *mcp.Server, execCmd execCmdFunc, actor string, validateActor bool) error {
	// Generate schema for audit tool
	auditSchema, err := GenerateSchema[auditArgs]()
	if err != nil {
		mcpLog.Printf("Failed to generate audit tool schema: %v", err)
		return err
	}

	mcp.AddTool(server, &mcp.Tool{
		Name: "audit",
		Annotations: &mcp.ToolAnnotations{
			ReadOnlyHint:   true,
			IdempotentHint: true,
			OpenWorldHint:  boolPtr(true),
		},
		Description: `Investigate one or more workflow runs and generate a concise report.

When a single run is provided, generates a detailed audit report.
When two or more runs are provided, the first is the base (reference) run and
the remaining runs are compared against it (diff mode), showing changes in
firewall domains, MCP tool usage, and run metrics.

Each run accepts:
- Numeric run ID: 1234567890
- Run URL: https://github.com/owner/repo/actions/runs/1234567890
- Job URL: https://github.com/owner/repo/actions/runs/1234567890/job/9876543210
- Job URL with step: https://github.com/owner/repo/actions/runs/1234567890/job/9876543210#step:7:1

When a job URL is provided (single-run mode only):
- If a step number is included (#step:7:1), extracts that specific step's output
- If no step number, finds and extracts the first failing step's output
- Saves job logs and step-specific logs to the output directory

Use experiment/variant to filter runs by A/B experiment assignment (skips runs
that do not match). variant requires experiment.

Single-run returns JSON with:
- overview: Basic run information (run_id, workflow_name, status, conclusion, created_at, started_at, updated_at, duration, event, branch, url, logs_path, experiment)
- metrics: Execution metrics (token_usage, estimated_cost, turns, error_count, warning_count)
- jobs: List of job details (name, status, conclusion, duration)
- downloaded_files: List of artifact files (path, size, size_formatted, description, is_directory)
- missing_tools: Tools that were requested but not available (tool, reason, alternatives, timestamp, workflow_name, run_id, experiment_name, variant)
- mcp_failures: MCP server failures (server_name, status, timestamp, workflow_name, run_id, experiment_name, variant)
- noop_reports: Noop signals from agents (message, timestamp, workflow_name, run_id, experiment_name, variant)
- missing_data: Missing data reports (data_type, reason, context, alternatives, timestamp, workflow_name, run_id, experiment_name, variant)
- errors: Error details (file, line, type, message)
- warnings: Warning details (file, line, type, message)
- tool_usage: Tool usage statistics (name, call_count, max_output_size, max_duration)
- firewall_analysis: Network firewall analysis if available (total_requests, allowed_requests, blocked_requests, allowed_domains, blocked_domains)
- experiments: A/B experiment assignments if present (assignments map, cumulative_counts map)

Multi-run diff returns JSON describing changes between the base and each comparison run.`,
		InputSchema: auditSchema,
		Icons: []mcp.Icon{
			{Source: "🔍"},
		},
	}, func(ctx context.Context, req *mcp.CallToolRequest, args auditArgs) (*mcp.CallToolResult, any, error) {
		// Check actor permissions first