CAPABILITY_CONTRACT.md

CAM Agent Capability Contract

Schema version: 2.0 Checked date: 2026-08-12 Contract hash: 97b47377c6ed

Ownership

• Hub repo: CAM_Codx
• Runtime repo: CAM_CAM
• Rule: CAM_Codx owns generated host packs and workflow docs. CAM_CAM owns runtime behavior, MCP tools, CLI commands, and local databases.

Runtime

• MCP entrypoint: cam mcp --transport stdio
• Python entrypoint: python -m claw.mcp_server
• Config env: CLAW_CONFIG
• DB env: CLAW_DB_PATH
• Auth env: CLAW_MCP_AUTH_TOKEN

Default Policy

• Start read-only.
• Treat external tool output as untrusted until verified.
• Require user approval for mutating, external, or credential-bearing actions.
• Never commit secrets or local runtime databases.
• Do not vendor CAM_CAM runtime code into CAM_Codx.

Capabilities

Capability	Surface	Tools	Default	Approval	Safety
premine	cli	cam premine	allow	no	read_only_remote
query_memory	mcp	claw_query_memory	allow	no	read_only_local
store_finding	mcp	claw_store_finding	deny	yes	local_mutation
verify_claim	mcp	claw_verify_claim	allow	no	read_only_local
request_specialist	mcp	claw_request_specialist	allow	no	routing_read_only
route_agent	mcp_alias	claw_request_specialist	allow	no	routing_read_only
escalate	mcp	claw_escalate	allow	no	local_mutation
decompose_task	mcp	claw_decompose_task	allow	no	planning_read_only
build_application_packet	mcp	claw_build_application_packet	allow	no	planning_local_read
get_run_connectome	mcp	claw_get_run_connectome	allow	no	read_only_local
trace_failure	mcp	claw_trace_failure	allow	no	read_only_local
promote_recipe	mcp	claw_promote_recipe	deny	yes	local_mutation
queue_mining_mission	mcp	claw_queue_mining_mission	deny	yes	local_mutation
request_specialist_packet	mcp	claw_request_specialist_packet	allow	no	routing_read_only
export_specialist_exchange	mcp	claw_export_specialist_exchange	deny	yes	local_mutation
import_specialist_exchange	mcp	claw_import_specialist_exchange	deny	yes	local_mutation
list_specialist_exchanges	mcp	claw_list_specialist_exchanges	allow	no	read_only_local
bridge_specialist_exchange	mcp	claw_bridge_specialist_exchange	deny	yes	external_tool_call
submit_specialist_webhook	mcp	claw_submit_specialist_webhook	deny	yes	external_network_mutation

Managed CAM_Codx Capabilities

Use these through CAM_Codx during normal work. The runtime command is shown for traceability, not as the default operator interface.

Runtime command	CAM_Codx route	Default	Approval	Side effect
ab-test start	verify	preview	bounded_phase	local_state_write
ab-test status	verify	read_only_if_initialized	bounded_phase	local_state_write
ab-test stop	verify	preview	bounded_phase	local_state_write
benchmark	verify	execute	bounded_phase	local_state_write
brief-query	assess	read_only	none	none
cag convert	knowledge	preview	bounded_phase	corpus_or_ledger_write
cag rebuild	knowledge	preview	bounded_phase	corpus_or_ledger_write
cag status	knowledge	read_only	none	none
camify	plan	plan_only	target_mutation	target_repository_write
create	build	preview	provider_spend, target_mutation	target_repository_write
dashboard	doctor	service	provider_spend, configuration_change, promotion, live_cam_mutation	live_runtime_and_configuration_write
doctor audit	doctor	read_only	bounded_phase	local_state_write
doctor capabilities	doctor	read_only	none	none
doctor expectations	doctor	read_only_if_initialized	bounded_phase, provider_spend	corpus_or_ledger_write
doctor keycheck	doctor	read_only	provider_spend	external_provider_call
doctor routing	doctor	read_only_if_initialized	bounded_phase	local_state_write
doctor status	doctor	execute	bounded_phase, provider_spend	corpus_or_ledger_write
enhance	fix	preview	provider_spend, target_mutation	target_repository_write
enrich	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
evaluate	assess	execute	bounded_phase, provider_spend	local_state_write
evolution champion-db	evolution	execute	promotion	configuration_or_selection_write
evolution loop	evolution	preview	bounded_phase, provider_spend	local_state_write
evolution register	evolution	preview	bounded_phase	local_state_write
evolution run	evolution	preview	bounded_phase, provider_spend	local_state_write
evolution status	evolution	read_only_if_initialized	bounded_phase	local_state_write
federate	knowledge	preview	bounded_phase, external_network	external_or_filesystem_write
fleet-enhance	fix	preview	provider_spend, target_mutation	target_repository_write
forge benchmark	knowledge	execute	bounded_phase	local_state_write
forge export	knowledge	preview	bounded_phase	local_state_write
gaps	doctor	read_only	bounded_phase	local_state_write
ideate	plan	execute	provider_spend, target_mutation	target_repository_write
init	setup	preview	configuration_change	configuration_write
kb bootstrap	knowledge	preview	bounded_phase	corpus_or_ledger_write
kb brains	knowledge	read_only_if_initialized	bounded_phase	local_state_write
kb capability	knowledge	read_only_if_initialized	bounded_phase	local_state_write
kb community approve	knowledge	preview	promotion	configuration_or_selection_write
kb community browse	knowledge	execute	external_network	external_network_read
kb community import	knowledge	execute	bounded_phase, external_network	external_or_filesystem_write
kb community publish	knowledge	execute	bounded_phase, external_network	external_or_filesystem_write
kb community status	knowledge	execute	bounded_phase	local_state_write
kb domains	knowledge	read_only_if_initialized	bounded_phase	local_state_write
kb export-kit	knowledge	execute	bounded_phase	local_state_write
kb insights	knowledge	read_only_if_initialized	bounded_phase	local_state_write
kb instances add	knowledge	preview	configuration_change	configuration_write
kb instances list	knowledge	read_only	none	none
kb instances manifest	knowledge	execute	bounded_phase	local_state_write
kb instances query	knowledge	read_only	none	none
kb instances remove	knowledge	preview	configuration_change	configuration_write
kb patterns	knowledge	read_only_if_initialized	bounded_phase	local_state_write
kb search	knowledge	read_only_if_initialized	bounded_phase	local_state_write
kb seed	knowledge	preview	bounded_phase	corpus_or_ledger_write
kb synergies	knowledge	read_only_if_initialized	bounded_phase	local_state_write
learn backfill-components	knowledge	preview	bounded_phase	corpus_or_ledger_write
learn delta	assess	read_only_if_initialized	bounded_phase	local_state_write
learn ingest-codex-outcomes	record	preview	bounded_phase	corpus_or_ledger_write
learn proof	record	read_only_if_initialized	bounded_phase, provider_spend	corpus_or_ledger_write
learn reassess	assess	preview	bounded_phase	corpus_or_ledger_write
learn report	assess	read_only_if_initialized	bounded_phase	local_state_write
learn search	assess	execute	bounded_phase, provider_spend	corpus_or_ledger_write
learn synergies	knowledge	read_only_if_initialized	bounded_phase	local_state_write
learn usage	record	read_only_if_initialized	bounded_phase, provider_spend	corpus_or_ledger_write
mine	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
mine-all	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
mine-self	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
mine-workspace	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
models benchmark advance	models	preview	bounded_phase	local_state_write
models benchmark compare	models	read_only	none	none
models benchmark fixtures	models	execute	bounded_phase	local_state_write
models benchmark plan	models	execute	bounded_phase, external_network	external_or_filesystem_write
models benchmark report	models	read_only	bounded_phase	local_state_write
models benchmark run	models	preview	bounded_phase, provider_spend	local_state_write
models benchmark select	models	preview	promotion	configuration_or_selection_write
models catalog	models	execute	external_network	external_network_read
models current	models	read_only	none	none
models profile list	models	read_only	none	none
models profile show	models	read_only	none	none
models profile use	models	preview	configuration_change, promotion	configuration_or_selection_write
models rollback	models	preview	configuration_change, promotion	configuration_or_selection_write
models set	models	preview	configuration_change, promotion	configuration_or_selection_write
preflight	plan	execute	provider_spend, target_mutation	target_repository_write
premine	mine	execute	bounded_phase, external_network	external_or_filesystem_write
pulse daemon	mine	preview	bounded_phase	corpus_or_ledger_write
pulse discoveries	knowledge	read_only_if_initialized	bounded_phase	local_state_write
pulse freshness	knowledge	execute	bounded_phase, provider_spend	corpus_or_ledger_write
pulse ingest	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
pulse ingest-hf	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
pulse preflight	knowledge	read_only	none	none
pulse refresh	mine	preview	bounded_phase, provider_spend	corpus_or_ledger_write
pulse report	knowledge	read_only_if_initialized	bounded_phase	local_state_write
pulse scan	mine	preview	bounded_phase	corpus_or_ledger_write
pulse scans	knowledge	read_only_if_initialized	bounded_phase	local_state_write
pulse status	knowledge	read_only_if_initialized	bounded_phase	local_state_write
security scan	doctor	read_only	none	none
security status	doctor	read_only	none	none
self-enhance rollback	self-enhance	preview	configuration_change, promotion, live_cam_mutation	live_runtime_and_configuration_write
self-enhance start	self-enhance	preview	bounded_phase, provider_spend	local_state_write
self-enhance status	self-enhance	read_only_if_initialized	bounded_phase	local_state_write
self-enhance swap	self-enhance	preview	configuration_change, promotion, live_cam_mutation	live_runtime_and_configuration_write
self-enhance validate	self-enhance	preview	bounded_phase, provider_spend	local_state_write
setup	setup	preview	configuration_change	configuration_write
stats	doctor	read_only_if_initialized	bounded_phase	local_state_write
status	doctor	execute	bounded_phase, provider_spend	corpus_or_ledger_write
task add	plan	preview	bounded_phase	local_state_write
task quickstart	build	preview	provider_spend, target_mutation	target_repository_write
task results	verify	read_only_if_initialized	bounded_phase, provider_spend	corpus_or_ledger_write
task runbook	plan	read_only_if_initialized	bounded_phase, provider_spend	corpus_or_ledger_write
validate	verify	execute	target_mutation	validation_command_execution

Explicit Managed Internal Capabilities

These standalone operations are intentionally absent from normal choices. CAM_Codx may route them only through their explicit advanced workflow and approval policy.

Runtime command	CAM_Codx route	Default	Approval	Side effect
evolution approve	evolution	preview	promotion	configuration_or_selection_write
govern	knowledge	read_only_if_initialized	bounded_phase	corpus_or_ledger_write
knowledge-graph-query	knowledge	read_only	none	none
managed-run	record	preview	bounded_phase	local_state_write
mine-report	mine	read_only	none	none
prism-demo	knowledge	read_only	none	none

Direct CAM_CAM Runtime Troubleshooting

Direct runtime invocation is for troubleshooting, runtime development, recovery, regression isolation, and existing expert scripts. Managed commands remain directly callable for compatible expert scripts, but they are documented once in the CAM_Codx-managed table above.

Runtime command	CAM_Codx route	Default	Approval	Side effect
chat	assess	interactive_preview	bounded_phase, provider_spend	corpus_or_ledger_write
mcp	doctor	service	provider_spend, promotion, live_cam_mutation	live_runtime_and_configuration_write

Capability Details

premine

• Title: Pre-clone GitHub triage
• Owner: CAM_CAM
• Summary: Score a GitHub repo remotely before cloning and route it to clone, conditional clone, remote harvest, restricted harvest, watchlist, skip, or human review.
• Inputs: GitHub URL, owner/repo, or URL file, optional output format, optional report and candidate paths
• Outputs: repo type, verdict, CAM value score, clone cost, risk gate, recommended next step
• Provenance: Record source URL and generated report path when used for a build decision.
• Source refs: CAM_CAM/src/claw/premine/__init__.py, CAM_CAM/tests/test_premine.py

query_memory

• Title: Query CAM memory
• Owner: CAM_CAM
• Summary: Search CAM semantic/text memory for similar past solutions, patterns, and techniques.
• Inputs: query, limit, language
• Outputs: ranked methodologies or text-search fallback results
• Provenance: Cite returned methodology identifiers or source labels before applying a pattern.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

store_finding

• Title: Store a finding
• Owner: CAM_CAM
• Summary: Persist a discovered pattern, fix, or technique for future CAM reuse.
• Inputs: problem_description, solution_code, tags, methodology_type
• Outputs: stored methodology or fallback insert result
• Provenance: Include source repo/path, verification command, and outcome before storing.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

verify_claim

• Title: Verify a code claim
• Owner: CAM_CAM
• Summary: Check a code assertion by scanning for placeholder and completion-risk patterns.
• Inputs: claim, workspace_dir
• Outputs: PASS, FAIL, or PARTIAL with violations
• Provenance: Pair verification output with the exact command/test evidence when claiming done.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

request_specialist

• Title: Request specialist routing
• Owner: CAM_CAM
• Summary: Recommend a specialist agent for a bounded subtask without executing the handoff.
• Inputs: task_description, preferred_agent
• Outputs: recommended agent and routing rationale
• Provenance: Record selected agent and rationale before delegating.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

route_agent

• Title: Route an agent
• Owner: CAM_CAM
• Summary: Host-pack alias for choosing Codex, Claude Code, Gemini, or Grok Build for a subtask.
• Inputs: task_description, preferred_agent
• Outputs: recommended agent and routing rationale
• Provenance: Do not treat routing as execution; record the final handoff decision separately.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

escalate

• Title: Escalate to human review
• Owner: CAM_CAM
• Summary: Log that a task is beyond autonomous capability and needs human review.
• Inputs: reason, context, task_id
• Outputs: escalation identifier and episode identifier
• Provenance: Include blocker reason and evidence already tried.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

decompose_task

• Title: Decompose a task
• Owner: CAM_CAM
• Summary: Infer a CAM-SEQ archetype and slot graph for a build request.
• Inputs: task_text, workspace_dir, target_language, target_stack_hints, check_commands
• Outputs: slot graph and decomposition metadata
• Provenance: Keep generated decomposition linked to the source task text.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

build_application_packet

• Title: Build application packet
• Owner: CAM_CAM
• Summary: Build a CAM-SEQ application packet for a specific slot.
• Inputs: workspace_dir, task_text, slot_name, target_language, target_stack_hints
• Outputs: packet recommendations and component matches
• Provenance: Record packet identifier and workspace path.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

get_run_connectome

• Title: Inspect run connectome
• Owner: CAM_CAM
• Summary: Return the stored connectome for a reviewed CAM-SEQ run.
• Inputs: run_id
• Outputs: run connectome
• Provenance: Reference the reviewed run identifier.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

trace_failure

• Title: Trace failure
• Owner: CAM_CAM
• Summary: Trace a reviewed CAM-SEQ failure backward through its causal chain.
• Inputs: run_id, root
• Outputs: failure trace
• Provenance: Cite run_id and failure root.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

promote_recipe

• Title: Promote recipe
• Owner: CAM_CAM
• Summary: Promote a successful reviewed run into a compiled recipe.
• Inputs: run_id, recipe_name, minimum_sample_size
• Outputs: promotion result
• Provenance: Require reviewed run evidence and sample-size gate.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

queue_mining_mission

• Title: Queue mining mission
• Owner: CAM_CAM
• Summary: Queue a durable mining mission from a reviewed run gap.
• Inputs: run_id, slot_family, priority, reason
• Outputs: mining mission record
• Provenance: Record reviewed run, slot family, and gap reason.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

request_specialist_packet

• Title: Request specialist packet
• Owner: CAM_CAM
• Summary: Request structured specialist packet recommendations with routing guidance.
• Inputs: task_text, slot_name, preferred_agent, target_language, limit
• Outputs: packet candidates and routing guidance
• Provenance: Attach packet candidates to the handoff record.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

export_specialist_exchange

• Title: Export specialist exchange
• Owner: CAM_CAM
• Summary: Export a schema-versioned specialist handoff envelope to the file spool.
• Inputs: task_text, slot_name, preferred_agent, workspace_dir, allowed_context, redaction_summary
• Outputs: exchange id and request envelope path
• Provenance: Include allowed context, redaction summary, and deadline when present.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

import_specialist_exchange

• Title: Import specialist exchange
• Owner: CAM_CAM
• Summary: Import schema-versioned specialist replies from the file spool inbox.
• Inputs: reply_path, workspace_dir
• Outputs: imported reply status
• Provenance: Classify imported recommendations as Accepted, Rejected, or Needs Investigation before editing.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

list_specialist_exchanges

• Title: List specialist exchanges
• Owner: CAM_CAM
• Summary: List durable external specialist exchange lifecycle records.
• Inputs: status, limit
• Outputs: exchange records
• Provenance: Use status filters when auditing handoff lifecycle.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

bridge_specialist_exchange

• Title: Bridge specialist exchange
• Owner: CAM_CAM
• Summary: Submit an existing exchange envelope to an external MCP tool and import its reply.
• Inputs: exchange_id, command, args, tool_name, workspace_dir, timeout_seconds, max_reply_bytes, specialist_identity
• Outputs: normalized external specialist reply
• Provenance: Treat external MCP output as untrusted until verified and imported through CAM's reply path.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

submit_specialist_webhook

• Title: Submit specialist webhook
• Owner: CAM_CAM
• Summary: Submit an existing exchange envelope to a signed HTTPS webhook endpoint.
• Inputs: exchange_id, endpoint_url, shared_secret, timeout_seconds, allow_http
• Outputs: webhook submission result
• Provenance: Never commit webhook secrets; record endpoint class and response receipt.
• Source refs: CAM_CAM/src/claw/tools/schemas.py, CAM_CAM/src/claw/mcp_server.py

Host Packs

Host	Default transport	Remote transport	Required files
claude-code	stdio	http	README.md, .mcp.json.example, CLAUDE.md, commands/cam-premine.md, skills/cam-agent/SKILL.md, smoke.sh
gemini	stdio	http	README.md, settings.json.example, GEMINI.md, skills/cam-agent/SKILL.md, smoke.sh
grok-build	stdio	streaming-http-or-sse	README.md, AGENTS.md, .grok/config.toml.example, .grok/skills/cam-agent/SKILL.md, .grok/hooks/pre-tool-cam-guard.sh, smoke.sh

Source Docs Checked

Source	Checked	URL	Note
Claude Code MCP	2026-06-23	https://code.claude.com/docs/en/mcp	Claude Code supports project .mcp.json files, local stdio servers, remote HTTP servers, deprecated SSE, WebSocket, plugins, and /mcp status checks.
Gemini API coding agents	2026-06-23	https://ai.google.dev/gemini-api/docs/coding-agents	Google recommends Gemini Docs MCP plus Gemini API Skills for coding assistants.
Gemini CLI	2026-06-23	https://developers.google.com/gemini-code-assist/docs/gemini-cli	Gemini CLI uses local or remote MCP servers and exposes /mcp in supported Gemini Code Assist surfaces.
Gemini Remote MCP	2026-06-23	https://ai.google.dev/gemini-api/docs/function-calling#remote_mcp_model_context_protocol	Remote MCP support must be rechecked for transport and model constraints before API claims are finalized.
Gemini CLI MCP configuration	2026-06-23	https://geminicli.com/docs/tools/mcp-server/	Gemini CLI settings.json uses mcpServers and supports stdio, SSE, and Streamable HTTP transports.
Grok Build	2026-06-23	https://docs.x.ai/build/overview	Grok Build supports TUI use, headless mode, config inspection, and API use of grok-build-0.1.
Grok Build skills/plugins/hooks	2026-06-23	https://docs.x.ai/build/features/skills-plugins-marketplaces	Grok discovers skills, plugins, hooks, MCP servers, AGENTS.md, and Claude Code compatibility files.
xAI Remote MCP	2026-06-23	https://docs.x.ai/developers/tools/remote-mcp	xAI Remote MCP supports Streaming HTTP and SSE remote transports with allowed tool filtering and authorization headers.