Validate proposed code, config, shell commands, or text against CK policy before execution. Read-only — no changes are applied to the project. Returns a validation result with any policy violations as findings. content is required. kind classifies the artifact (code/config/shell/text) for policy routing. source_type identifies the content's origin (developer, tool_output, human_review, issue, pull_request, web) for trust-boundary checks; untrusted sources receive stricter scrutiny. domain_pack applies a domain-specific policy pack (e.g., hipaa, owasp). requested_capabilities declares what the content needs (network, filesystem, shell, deploy) so the trust boundary can evaluate the request. Call ck_validate before writing files, running shell commands, or executing generated code. If validation returns blocked findings, do not proceed — use ck_finding to record them.

Execute generated code only inside a configured non-local sandbox. Defaults to Docker, denies network/filesystem/secrets/shell/deploy, validates source first, and supports dry_run for planning.

Fetch the full governed session state: mission, budget, active findings, proof summary, planning context, workspace snapshot, drift signals, recent transcript events, resume packet, and ControlKeel instruction hierarchy. Read-only. detail_level compact (default) returns a token-efficient summary; use full only when raw workspace, resume, or transcript payloads are required. session_id defaults to the active bound session; pass project_root to resolve it automatically. Call ck_context at the start of every task to reacquire state. Prefer ck_context_pack when you need a focused, citation-enriched bundle for a specific retrieval query rather than the full session snapshot.

Build a compact, citation-enriched context bundle for the current session and task by combining task facts, proof state, resume highlights, and ranked memory excerpts. Read-only. query is an optional retrieval query; when omitted, ControlKeel synthesizes one from the current task title and session context. top_k controls how many memory hits to include (default 5). detail_level compact (default) keeps the bundle token-efficient. Prefer ck_context_pack over ck_context when you need a focused, query-driven bundle for a specific sub-task rather than the full session snapshot. Use ck_context at the start of a session for full mission state; use ck_context_pack mid-task to fetch targeted prior knowledge.

List files and directories inside the bound project root. Read-only — no files are modified. path is a relative directory path to list; omit to list the project root. Use ck_fs_ls to browse directory structure. Use ck_fs_find to locate files by name fragment. Use ck_fs_read to read a specific file. Use ck_fs_grep to search file contents.

Read a file from the bound project root. Read-only — no files are modified or created. path is required and must be relative to the project root (e.g., lib/my_module.ex). start_line (1-indexed) and max_lines enable windowed reads for large files. Omit both to read the entire file. Use ck_fs_read to inspect a file at a known path. Use ck_fs_find to locate a file by name fragment. Use ck_fs_grep to search inside files by content pattern. Use ck_fs_ls to list directory contents.

Find files or directories whose path contains a given fragment, searching within the bound project root. Read-only — no files are modified. query is the path fragment or glob pattern to match against file and directory names. path scopes the search to a subdirectory (relative to project root); omit to search the entire project. limit caps the number of results (default 50). Use ck_fs_find to locate files by name or path. Use ck_fs_grep to search by file content. Use ck_fs_read to read a file at a known path.

Search file contents inside the bound project root using grep-style pattern matching. Read-only — no files are modified. query is a regex pattern by default; set fixed_strings: true to match literal text without regex. Scope the search with path (a relative directory or glob); omit to search the entire project. Returns matching lines with file path and line numbers. limit caps results (default 50). Use ck_fs_grep to find code patterns or strings inside files. Use ck_fs_find to locate files by name fragment. Use ck_fs_read to read a specific file by path.

Generate a git diff between two refs and run CK validation on the resulting diff. Read-only — no commits are created. base_ref and head_ref are git refs (branch names, commit SHAs, or tags); omit both to diff staged changes against HEAD. Returns the diff text and any CK validation findings raised against it. Use ck_git_diff to review changes before committing or submitting a review. Use ck_git_status for a summary without the full diff. Use ck_git_commit to create the commit after reviewing.

Validate a commit message against CK governance policy and execute git commit if validation passes and no findings are blocked. Write operation — creates a git commit in the repository when validation succeeds. Returns validation result, any blocked findings, and the commit SHA on success. If blocked findings exist, the commit is not created and the findings are returned for remediation. Use ck_git_status first to confirm governance state, then ck_git_commit to create the commit. Does not push to remote — use git push separately after commit.

Get git working tree status correlated with CK governance findings for the current session. Returns staged, unstaged, and untracked files alongside any blocked or open findings from ck_validate or ck_review_submit. Read-only and side-effect free — no findings are created or modified. Use before ck_git_commit to verify governance state. Prefer ck_git_diff when you need the actual diff content; prefer ck_git_commit when ready to commit.

Persist a governed finding with a ruling decision (allow, warn, block, escalate_to_human). Findings are the durable audit trail in ControlKeel: every policy check, validation failure, or human review should produce a finding. Write operation — creates or updates a DB record. Idempotent for the same rule_id within a session. Returns the finding ID, status, and ruling state. Required fields: session_id, category (e.g., security/compliance/performance), severity (critical/high/medium/low), rule_id (dotted policy identifier such as CK-SEC-001), and plain_message. decision defaults to block; use allow for approved exceptions. Use ck_finding to record issues discovered during agent work; use ck_memory_record for general knowledge or decisions not tied to a policy rule.

Submit a governed plan, diff, or completion packet for human review and execution gating. Write operation — creates a review record and returns a review_id and browser URL. review_type controls what is being submitted: plan (before implementation), diff (before merging), or completion (task done). submission_body is the full content: plan text, diff, or completion description. For iterative plan refinement, pass previous_review_id and plan_phase (ticket → research_packet → design_options → narrowed_decision → implementation_plan → code_backed_plan). Returns review_id, status (pending), and a URL where the human reviewer can approve or deny. After submission, poll ck_review_status until the decision is approved or denied before proceeding. Use ck_review_feedback (human-facing) to record a decision on an existing review.

Fetch the latest decision status (pending/approved/denied), reviewer notes, and browser review URL for a previously submitted review. Read-only. Provide review_id (returned by ck_review_submit) for a specific review, or task_id to get the latest review for that task. review_type (plan/diff/completion) filters when task_id is used without review_id. Poll this after ck_review_submit to check whether a human has approved or denied the submission before proceeding with execution.

Approve or deny a submitted review and attach feedback notes or structured annotations. Write operation — updates the review record and unblocks or halts the execution gate. review_id (required) is the ID returned by ck_review_submit. decision must be approved or denied. feedback_notes is freeform text for the reviewer's rationale. annotations is a key-value object for machine-readable metadata. This tool is human-facing: agents call ck_review_submit to create a review, then a human (or authorized agent) calls ck_review_feedback to record the decision. After approval, the submitting agent can proceed with execution; after denial, the plan should be revised and resubmitted.

Record external regression-test evidence from CI/CD systems (Bug0, Passmark, custom runners) so proof bundles and release-readiness checks account for external validation. Write operation — creates a DB record. Returns the recorded result ID. Required: session_id, engine (name of the test system), flow_name (test suite or flow identifier), outcome (passed/failed/flaky/skipped). Optional: commit_sha to link results to a specific revision, environment (ci/staging/production), external_run_id for cross-referencing the originating system, evidence for a structured payload. Use after an external test run to close the proof loop before calling ck_review_submit for a completion review. Retrieve past results with ck_memory_search using record_type: regression.

Search governed typed memory for the current session to recover prior decisions, findings, proofs, and domain knowledge. Read-only. query is a freeform text search applied across record titles, bodies, and tags. record_type filters by type (decision, finding, proof, goal, brief, checkpoint); omit to search all types. top_k limits the number of ranked results (default 10). source_type and source_id filter by origin. Returns ranked records with citations and scores. Use ck_memory_search to retrieve what was recorded in prior steps or sessions. Use ck_memory_record to write new records. Use ck_experience_search for full-text search across findings and tasks workspace-wide.

Write a governed memory record so future agents can explicitly retrieve it via ck_memory_search. Write operation — persists to the database. Idempotent: re-submitting the same source_id updates the existing record rather than duplicating it. Pass memory as a plain string for quick notes, or as an object with body, title, summary, record_type, and tags for structured records. record_type controls retrieval filtering: use decision for architectural choices, finding for issues, proof for evidence, goal for intent, brief for task context. tags is a string or array of strings for categorization. source_id links the record to an external artifact (e.g., a review ID or commit SHA). Use ck_memory_record to persist knowledge that should survive session boundaries. Use ck_finding for policy violations with a ruling decision. Use ck_goal for durable multi-session intent.

Record, list, or update durable governed goals so long-running intent stays explicit, citable, and reviewable across sessions. Three modes: record (write — creates a new goal); list (read-only — returns goals filtered by status and horizon); update_status (write — updates an existing goal's status or progress). Required: session_id and mode. For record: provide goal (the statement text) and optionally title, horizon (task/session/workspace), and tags. For update_status: provide goal_id and the new status. horizon controls scope: task for short-lived intent, session for the current session, workspace for persistent cross-session goals. Use ck_goal for structured multi-session intent that should be explicitly tracked and reviewed. Use ck_memory_record for general decisions or notes not requiring status tracking.

Archive a memory record so it is excluded from future ck_memory_search results. Write operation — marks the record as archived in the database; it is not deleted. memory_id is the integer ID returned by ck_memory_record or ck_memory_search. Use when a record is stale, superseded by a newer decision, or contains information that should no longer guide future agents. To update a record's content instead of archiving it, call ck_memory_record again with the same source_id.

Estimate, record, or check the cost of an agent operation against session and daily spend budgets. Three modes: estimate (read-only, returns headroom and projected cost); commit (write — deducts estimated_cost_cents from the session budget); status (read-only, returns remaining budget). For commit mode: pass session_id, estimated_cost_cents, provider, model, input_tokens, and output_tokens. Pass include_token_overhead: true with project_root to attach a token overhead audit (rule files, skill duplicates, tool schemas) to the response. Check ck_budget before expensive multi-agent work or large model calls. Use ck_cost_optimizer for model price comparisons without recording spend.

Recommend the best available AI agent for a given task based on security tier, remaining budget, task type, and past performance data. Read-only — no session state is changed. task is a plain-language description of what needs to be done. risk_tier (low/medium/high/critical) filters out agents that are not cleared for the security level; defaults to medium. allowed_agents restricts routing to a specific subset of agent IDs; omit to allow all. Returns a ranked list of agent recommendations with rationale. Use ck_route to pick an agent, then ck_delegate to transfer the task. Use ck_cost_optimizer for a price-focused comparison without routing.

Hand off a governed task or session to another AI agent, transferring governance context (findings, budget, proofs) to the target. Mutates session state to reflect the delegation. Four modes: auto (ControlKeel picks the best agent), embedded (inline sub-agent), handoff (transfer session ownership), runtime (delegate to a pre-configured runtime agent). agent is the target agent ID (e.g., claude, opencode, cursor). Call ck_route first to identify the best agent, then ck_delegate to transfer. Prefer ck_route when you only need a recommendation without transferring; prefer ck_delegate when you are ready to hand off execution.

Get cost optimization suggestions or compare AI provider/model prices for a task. Read-only — no budget records are written (use ck_budget to record actual spend). Two modes: suggest returns optimization tips based on recent session spending patterns; compare returns a side-by-side price breakdown for the given task. For suggest mode, pass session_id. For compare mode, pass task_description and estimated_tokens along with top_provider and top_model as the baseline. Use ck_cost_optimizer before choosing a model for expensive multi-agent work; use ck_budget to record and enforce spend limits.

Analyze the project stack and suggest deployment platforms, or generate CI/CD and Docker configuration files. Three modes: analyze (read-only, returns platform recommendations based on detected stack); generate_files (write operation, creates Dockerfile and CI/CD configs in the project); dns_guide (read-only, returns DNS setup instructions for the recommended platform). project_root is required. Set dry_run: true with generate_files to preview what would be created without writing files. Use ck_deployment_advisor before deploying a new project or when setting up CI/CD for the first time. For budget and cost checks before deployment, use ck_budget.

Record session outcomes or retrieve agent performance leaderboards to close the reinforcement-learning feedback loop. Three modes: record persists a session outcome (write operation); get_session reads a specific outcome by session_id (read-only); get_leaderboard returns ranked agent performance (read-only). For record mode: pass session_id, outcome (success/partial/failure), agent_id, and task_type. For get_leaderboard: pass workspace_id and optional window (days) and limit. Call after task completion before ending the session so ck_route and ck_cost_optimizer have fresh performance data for future routing decisions.

Auto-discover tools from an external MCP server by querying its tools/list endpoint. This enables progressive discovery of MCP capabilities without manual configuration.

Audit project rule files (AGENTS.md, CLAUDE.md, etc.) and skills for token overhead. Returns word counts, token estimates, duplicate detection, and optimization recommendations.