Wire ControlKeel into the current agent host (Claude Code, Cursor, Codex, OpenCode, etc.). Closes the gap for users who installed ControlKeel via a one-line MCP-add command but skipped controlkeel attach <host>. Installs the host-specific hooks (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit), skills directory, slash commands, AGENTS.md/CLAUDE.md preamble, and subagent profiles for the requested host. Idempotent — re-running refreshes artifacts to the current version. Writes only inside project_root; no network egress. Call this once after a one-line MCP install when the host lacks ControlKeel hooks/skills. Use ck_mcp_discover first if unsure which host ID to pass.

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.

Create a workspace checkpoint capturing git state, workspace context, and metadata for migration or rollback.

List all checkpoints for a session, optionally filtered by type.

Restore session state from a previous checkpoint, updating session metadata with checkpoint information.

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.

Real-time collaborative channel where human actions stream to the agent. Build software for humans and agents to use together — agents can see when a human is viewing, editing, or approving. Modes: subscribe (receive events), publish (emit an event), presence (who is active), history (recent events).

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.

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.

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.

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.

List recent prior sessions in the same workspace and the read-only experience artifacts available for each run. Pass query for freeform keyword search across session titles, task titles, and finding descriptions — useful for questions like 'has this deployment pattern caused a blocked finding before?'

Read one prior-run artifact such as a session summary, audit log, trace packet, or proof summary from the workspace experience archive.

Freeform full-text search across findings and tasks within the current workspace. Returns ranked results with citations. Useful for questions like 'has this deployment pattern caused a blocked finding before?' or 'what did we do about the SQL performance issue?'

Track and govern agent interactions with external SaaS APIs. Rate limits per service, cost attribution, and PII redaction. Modes: record (log an interaction with auto-redaction), summary (aggregated view per service), rate_limit_status (current rates against limits), top_services (ranked by volume and cost).

Cluster recurring failure modes across recent session traces in the same workspace and return reusable eval candidates.

Record or disposition a governed finding. mode=create (default) persists a finding with a ruling decision (allow, warn, block, escalate_to_human); findings are the durable audit trail in ControlKeel. mode=resolve|dismiss|escalate disposition EXISTING findings so the agent that created them can also clear them: pass finding_id for a single finding, or rule_id/category/status to bulk-disposition all matching active findings in the session (resolve->approved, dismiss->rejected, escalate->escalated). Write operation. For create, required fields are session_id, category, severity, rule_id, plain_message; decision defaults to warn, use allow for an approved exception (which also auto-resolves matching open/blocked findings). Returns finding_id + status for create, or disposed_count + disposed_finding_ids for disposition. Use ck_finding to record and clear policy findings; use ck_memory_record for general knowledge not tied to a policy rule.

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 uses fixed-string search by default; set fixed_strings: false to treat it as a 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.

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.

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.

Generate a git diff 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 or pass empty strings to diff the working tree 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.

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.

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.

Fallback for clients that do not support MCP resources or native bulk skill loading. Load one or more CK resource URIs such as skills://; pass multiple skills:// URIs to activate several skills in one governed CK call.

Create and govern a bounded iterative loop without executing worker code. The contract freezes verifier paths and hashes, separates mutable paths, classifies artifact longevity, and enforces metric, iteration, cost, duration, no-progress, blocked-finding, and lasting-code architecture stop conditions. Modes: create, record, status, stop, promote. Rejected iterations require an explicit audited rollback.

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

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.

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.

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.

Read local observability reports for sessions, loop status, problems, memory, costs, trends, evals, generated benchmarks, history, and advisory promotion candidates. Read-only: no benchmark execution, draft approval, materialization, or promotion mutation.

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.

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.

Peek at the full stdout of a previously completed ck_delegate embedded run without loading it all into context. Use result_ref and package_root returned by ck_delegate to locate the stored output. Supports byte-range reads: pass peek_bytes to limit how much to load, and offset to skip ahead. Use result_length (returned by ck_delegate) to decide whether to peek, pass the ref downstream, or skip loading entirely. This is the RLM variable-encapsulation pattern: treat large sub-agent outputs as named references, not inline blobs.

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.

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.

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). The plan-quality scorer evaluates structured fields, not just submission_body — populate research_summary, options_considered, selected_option, rejected_options, implementation_steps, validation_plan, code_snippets, alignment_context, consulted_roles, codebase_findings, prior_art_summary, agent_spec_id, task_spec_id, agent_role, task_scope, out_of_scope, business_rules, domain_terms, allowed_actions, prohibited_actions, robustness_requirements, linked_policy_packs, linked_benchmark_suites, promotion_gates, allowed_semantic_changes, forbidden_semantic_changes, invariant_boundaries, requires_reapproval_if, harness_quality_checks, and scope_estimate for a strong score. 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.

Execute a governed rollback of an agent's work. Records a git checkpoint before each task and provides a single action to revert. Safety-checked: refuses if downstream tasks depend on the changes. Creates an audit finding on every rollback. Modes: checkpoint (capture git HEAD before task), execute (revert agent's changes), status (check snapshot state), list (all snapshots for session).

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.

Enumerate and manage governed sessions. Three modes: list (enumerate sessions for the project); status (get current session details, resolves from project binding if session_id omitted); switch (change active session binding — REQUIRES confirm: true).

Generate a condensed, human-scannable digest of what happened in a session — tasks completed, findings raised, budget spent, reviews pending, and notable highlights. Three modes: generate (create a new digest), latest (return the most recent), list (paginated history). Designed for the forward-deployed engineer who needs an 'inbox that summarizes what happened' without reading raw event streams.

Synthesize a deduplicated skill-evolution packet from recent traces and recurring failure clusters, including anti-patterns, reinforced practices, and a ready-to-merge skill draft. Set validate_only=true to run the Self-Harness validation stage (held-in/held-out + regression) without writing. Set install=true to validate and then materialize the draft into .agents/skills//SKILL.md under project_root, preserving the previous file as .bak.

List all available AgentSkills for this project. Returns names, descriptions, and scopes. Call this to discover capabilities you can activate, then use ck_skill_load to load a skill's full instructions.

Load the full instructions for a named AgentSkill. Returns the SKILL.md body wrapped in <skill_content> tags plus a list of bundled resource files. Call after ck_skill_list to activate a specific skill.

Validate skill output against a JSON Schema defined in the skill's result-schema frontmatter field. Skills can define a result_schema in their frontmatter; agents call this tool after running a skill to enforce typed, structured output. Accepts output + schema directly, or output + skill_name to validate against the skill's built-in schema.

Manage governed tasks within a session. Six modes: status (return task details for a given task_id); claim (claim an available task for execution); complete (mark a task as done, blocked if unresolved findings exist); heartbeat (signal the agent is alive and working on a task); checks (record task quality check results); report (submit a task report with output and metadata).

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

Analyze governance coverage across recent sessions in the workspace — which CK governance tools (ck_validate, ck_review_submit, ck_budget, ck_memory_record, ck_goal) are load-bearing, active, low-usage, or unused — and return actionable recommendations for gaps.

Export a structured session or task trace packet with failure patterns and eval candidates for trace-centered improvement loops.

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.

Manage workspace agent roles: one primary 'super-agent' per workspace maintained by a forward-deployed engineer, specialized agents for specific domains, and ephemeral agents for short-lived tasks. Modes: register (create agent, only one primary per workspace), update (change scope/budget/status), list (all agents for workspace), health (aggregated health indicator), retire (deactivate agent).

List all git worktrees in the current repository with their branch, HEAD, and status information.

Switch the current session to a different git worktree and update session metadata accordingly.