code operations

The exact fields each code.* operation takes and returns.

Every op is POST /v1/<op> over HTTP and the MCP tool loom_<op>. The identity fields (org, namespace, agent, user_id, session_id) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but code.* and tracker.* (which keep their plane's), and on some ops its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

code.ask

Ask a QUESTION about this codebase and get a grounded answer with [file:line] citations — 'how does TTL drop old rows', 'where is the memory limit enforced'.

POST /v1/code.ask · MCP loom_code_ask · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
question	str	required	The question to answer about the indexed code (grounded on a code.search of it).
synthesize	bool	True	False = retrieval-only (agent synthesizes); True = grounded server-side answer with citations, memoized across agents and invalidated when any cited file changes at merge.
rerank	str	''	Reranker for the retrieval: "" = the deployment default (LOOM_CODE_SEARCH_RERANK_DEFAULT), "none" = off for this request, "builtin:openai" / "builtin:cohere", or the name of an endpoint in LOOM_RERANK_ENDPOINTS_JSON (not a URL).
no_cache	bool	False	Skip the cache lookup and synthesize fresh (the fresh answer still refreshes the cache entry).
token_budget	int \| None	None	Retrieval context handed to synthesis, in tokens.

Output field	Type	Meaning
answer	str	The grounded answer text; "" on an abstain or when synthesize=false.
citations	list[dict[str, Any]]	The units the answer used (or was shown when none is cited): {path, start_line, end_line, symbol, unit_id} each; the retrieved units when synthesize=false.
source	Literal['cached', 'synthesized', 'abstained']	cached = served from the answer cache | synthesized = answered now (or retrieval-only when synthesize=false) | abstained = no grounded answer (abstain_reason says why).
cache_similarity	float	Cosine between this question and the served cached question; 0.0 unless source=cached.
cache	str	What the answer cache did. hit (a cached answer whose key, identifiers and files all matched) | miss | stale (the nearest entry's files, prompt version or age invalidated it) | guarded (the nearest cached question names different…
cache_saved_ms	int	On a served entry: the synthesis wall (ms) and upstream cost (USD) the entry recorded when it was written, i.e. what this call did not pay.
cache_saved_usd	float	Upstream LLM cost in USD the served cache entry recorded; 0.0 when nothing was served.
abstain	bool	true when no grounded answer is returned; abstain_reason says why.
abstain_reason	str	Why it abstained (no strong match, off-repository question, ...); "" otherwise.
retrieval_confidence	float	The underlying code.search's calibrated confidence (0-1); 0.0 when it did not run.
tokens_returned	int	Estimated tokens of the answer text (characters / 4); 0 when there is no answer.
context_tokens	int	Retrieval context (tokens) the synthesis was grounded on; 0 for cached hits and abstains.
trace_run_id	str	Id of the loom.code_search_trace row the server writes for this call.
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS).

code.backport_gap

Which release branches still carry the bug this fix removed, and the exact PR to cherry-pick there?

POST /v1/code.backport_gap · MCP loom_code_backport_gap · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
pr_number	int	0	The merged trunk fix to check; 0 = take it from issue_number.
issue_number	int	0	An issue the fix closes: the tracker graph's fixes edges name the PR.
branches	list[str]	(computed)	Release branches to check, as namespaces or versions (26.4), at most 8; empty = every configured release branch of the repository the caller can read.
max_symbols	int	8	At most this many touched functions (1–8) are looked up on each branch.
exact	bool	False	Hunk-level presence per branch, on request (one chunk read per branch and the fix's diff sections from the tracker record)
history	bool	False	For the branches the lines leave undecided, the fix's removed lines on the branch's own history in the mirror (git grep at the tip, git log -S over the first-parent history; at most 3 lines, 2 s per branch) — the pre-image at the tip is…

Output field	Type	Meaning
skipped_branches	list[dict[str, str]]	Configured release branches this caller cannot read, skipped (never silently): [{namespace, reason}].
verdict	str	gap | pending | covered | not_affected | unknown — the worst branch's word
causes	list[str]	tracker_unbound | tracker_unavailable | fix_not_found | no_fix | no_branches | per-branch unknown reasons (deadline, no_index, no_branch_version, …)
fix	dict[str, Any]	{pr_number, title, url, base_branch, minor_version, merged_at, merge_sha, changelog_category, src_components, files, hunk_contexts, ledger} plus, under exact, patch: {files, hunks, added, removed, symbols}
issue	dict[str, Any]	from issue_number:
fixes	list[dict[str, Any]]	every PR the issue's fixes edges name, with merged / backport flags
symbols	list[str]	the touched functions presence was tested with (from the hunk headers)
files	list[str]	the fix's source files (the file leg when no hunk named a function)
branches	list[dict[str, Any]]	one row per branch, gaps first, newest branch first: {namespace, branch, verdict, epistemic exact|lower_bound, basis, reason, backport, presence, cherry_pick {pr_number, merge_sha}, evidence [...]}; under exact, presence.patch = {mode…
summary	dict[str, list[str]]	verdict → [branch versions]
fix_candidate	dict[str, Any] \| None	When no fixes edge named a trunk PR, the link pass's top candidate above LOOM_TRACKER_LINKS_MIN_SCORE stood in as the fix ({pr_number, score, rank, why, features, …, epistemic candidate}) and fix.source reads candidate; absent…
tracker_namespace	str	The tracker namespace bound to the trunk namespace that was read; "" when none is bound.
tracker_unavailable	bool	True when a tracker is bound but its read failed.
ms	int	Wall time of the whole read, in milliseconds.
stage_ms	dict[str, int]	{fix: ms of the record + ledger stage, presence: ms of the presence stage, patch: ms of the hunk-level stage (under exact only)}
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.backport_gaps

The set-wide backport report: which merged fixes labelled for backport does a release branch still owe?

POST /v1/code.backport_gaps · MCP loom_code_backport_gaps · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
branch	str	''	One release branch, as a namespace or a version (26.6); "" = every configured release branch the caller can read.
wanted_only	bool	True	Keep only the fixes labelled for backport; false also returns unlabelled fixes.
days	int	90	Only fixes merged in the last this many days (1–365).
limit	int	500	At most this many rows (1–5000).

Output field	Type	Meaning
skipped_branches	list[dict[str, str]]	Configured release branches this caller cannot read, skipped (never silently): [{namespace, reason}].
branch	str	the branch asked for ('' = every configured release branch)
branch_namespace	str	The namespace of the branch asked for; "" when every branch was read.
branches	list[str]	the release-branch namespaces the rows cover, newest first
rows	list[dict[str, Any]]	one row per (fix, branch), gaps first, wanted-on-this-branch first, newest fix first: {pr_number, title, merged_at, minor_version, branch, branch_namespace, verdict, epistemic, basis, reason, cherry_pick {pr_number, merge_sha}…
counts	dict[str, int]	verdict → rows returned
counts_by_branch	dict[str, dict[str, int]]	branch version → verdict → rows
fixes	int	How many distinct fixes the returned rows cover.
wanted_only	bool	Echo of the request's wanted_only.
since	str	The merge-time lower bound applied (ISO-8601 UTC): now minus days.
computed	dict[str, Any]	the table's state for this trunk:
stale	bool	no pass has written this trunk yet, or the last pass is older than two intervals
ms	int	Wall time of the read, in milliseconds.

code.bisect_candidates

Rank PRs that may have introduced a bug; Loom does not test or reproduce it.

POST /v1/code.bisect_candidates · MCP loom_code_bisect_candidates · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
symbols	list[str]	(computed)	Crashing frames from the stack trace (qualified symbol names, at most 12); the code index resolves them to files, and their specific bare names rank the diffs.
paths	list[str]	(computed)	Repo-relative source paths to scan (at most 20), beside the frames' files.
patterns	list[str]	(computed)	Greppable literals from the report (an error code, an identifier in the message, a setting name); with issue_number they are also derived from the issue's text.
issue_number	int	0	A tracker issue number: Loom reads but does not verify its previously recorded triage observations for the release range, its text for patterns, and its caused_by / fixes edges for the named culprit and fix. 0 = none.
text	str	''	The report's own words (title, body, error) when there is no tracker issue to read them from — they feed the fusion's vector and lexical legs and the suspects the report names.
rerank	bool	False	One LLM call reranks the fused top 20 (+~2 s); a weak fused top reranks without asking
deadline_ms	int \| None	None	Answer within this many milliseconds with the best candidates found so far.
fix_pr	int	0	The PR that fixed the regression, when one exists — its rewritten lines, blamed at its parent, name the change that broke them.
bad_version	str	''	The first release on which the caller or an upstream test observed the bug (26.3, or a full version cut to its minor); Loom does not test it, and the value wins over the issue's reproduces_on. "" = from the issue.
before	str	''	The inclusive upper bound of an approximate merge-time investigation window when release observations are unavailable; it narrows candidate history and does not mean Loom reproduced the bug.
after	str	''	Optional lower bound of the merge-time window (ISO-8601); must be earlier than before.
bad_sha	str	''	A commit (hex) whose commit time on the code mirror becomes before when before is unset; a sha the mirror lacks is refused with BAD_SHA.
good_version	str	''	The newest release that the caller or an upstream test observed as clean; Loom does not test it, and the value wins over the issue's clean_on. "" = from the issue, or a lookback from bad_version.
widen_to_directories	bool	True	widen the candidate set from the frames' files to their directories when frames or patterns can rank within it
wideners	list[str]	(computed)	What may bound the scan when no frame resolves to a file — patterns (the window's diffs carrying the issue's rarest identifiers), component (the directories the issue's component touches), fix_candidate (the fix's own files: the…
rescan	bool	False	Run the scan even when the record already names the culprit (an introducing commit or a caused_by edge) — to check a pin; introduced_commit / named_by_graph still say what the record holds
limit	int	10	At most this many candidates (1–25).
marks	bool	True	Marks on the candidates (backport, revert, reverted, re-land, whitespace / rename-only, touches_symbol, named); false returns the ranked candidate dicts unmarked

Output field	Type	Meaning
verdict	str	candidates | no_candidates | already_bisected | graph_named | unknown
candidates_from	str	Where the candidates came from — tracker (its PR diff scan), code_history (loom's own PR ledger of the repository, when no tracker is linked or it holds no changed files), or none
causes	list[str]	Why the answer is thin or empty: tracker_unbound | tracker_unavailable | no_failing_version | no_resolved_paths | introduced_commit_known | caused_by_edge.
epistemic	str	always lower_bound: the upstream file list and the diff text are what was searched; an empty answer excludes nothing
candidates	list[dict[str, Any]]	{pr_number, title, author, merged_at, minor_version, matched_paths, matched_symbols, matched_patterns, added_patterns, kind change|meta, has_test, url, score, merge_commit_sha, merge_sha_source stored|mirror|"", named_by?}; with marks…
marks	dict[str, Any]	what the marks stage did:
named_by_graph	list[int]	PR numbers the tracker graph's caused_by edges name for the issue; when set, the candidates are these and no scan ran
fix_blame	dict[str, Any]	What blaming the fix's rewritten lines found — the fix, its parent, the ranges blamed and the PRs they name; absent without a fix
fusion	dict[str, Any]	What the fusion read — {window_prs, signals: {name: count}, suspects: {named, mentioned}, rerank?}; each fused candidate carries why (the signals that ranked it in their top 10); absent when fusion did not run.
patterns	list[str]	the greppable literals the ranking used (given ∪ derived from the issue)
pattern_weights	dict[str, float]	IDF over the issue corpus per pattern — what each is worth in the ranking; absent when the vocabulary was not read
scope	str	file | directory | patterns — how wide the candidate set was drawn
widened_by	list[str]	Which frameless wideners bounded the scan — patterns | component | fix_candidate — in the order they applied; absent when a frame or a path resolved
dupcheck_fix	dict[str, Any]	With no fix_pr and no issue, the duplicate check matched the report to a reported issue whose linked merged fix became fix_pr — {issue, fix_pr, match: duplicate, namespace}; absent otherwise
component	str	the issue's QA component and the directories it widened the scan to
component_dirs	list[str]	The directories the issue's component widened the scan to; absent when none did.
dropped_after_report	int	Scanned PRs merged AFTER the issue was opened — the fix, or nothing — left out of the list; absent when none was
versions_searched	list[str]	The release minors whose PRs were scanned; empty when a time window bounded it.
bad_version	str	The failing release the range used (given, else the issue's); "" when unknown.
good_version	str	The clean release the range used (given, else the issue's); "" when unknown.
window	str	clean_to_bad_plus_slack | lookback_from_bad | master_after_clean — how the release range was drawn
hub_paths_dropped	list[str]	hub files (Settings.cpp, CMake, docs, …) left out of the file filter
resolved	list[dict[str, Any]]	[{symbol, paths}] — what the code index resolved each frame to
paths	list[str]	The files the scan filtered on: fix files, given paths, the frames' files and the widening's, with hub files removed.
frames	list[str]	The bare frame names the diffs were ranked by: distinct, at least 6 characters, generic names dropped.
issue	dict[str, Any]	the issue's QA fact, as the tracker serves it, when issue_number was given
introduced_commit	str	The introducing commit the issue record holds; "" when none.
fix_candidate	dict[str, Any] \| None	The issue's probable fix from the link pass when no caused_by edge and no introducing commit exist (score above the floor) — or the record's own fixes edge (source: record); paths_used on it when its source files became the scan's…
tracker_namespace	str	The tracker namespace bound to this code namespace that was read; "" when none is bound.
tracker_unavailable	bool	True when a tracker is bound but its read failed.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.
partial	bool	deadline_ms cut an optional stage: the candidates are the best found in the budget, and partial_reason names the stages that did not run or finish.
partial_reason	str
before	str	The time window the scan ran under, when no release versions bounded it ("" otherwise).
after	str	The window's lower bound (ISO-8601 UTC); "" when releases bounded the scan or no lower bound was given.

code.blame_range

Which merged PRs last touched these lines, between release A and B?

POST /v1/code.blame_range · MCP loom_code_blame_range · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
path	str	required	The repo-relative file to blame (a leading / is stripped).
start_line	int	required	First line of the range, 1-based, at the window's upper end.
end_line	int	required	Last line, inclusive; a range over 400 lines is cut to 400 from start_line.
from_version	str	''	Window start as a release (26.3 or a full tag version); "" with no from_sha = the oldest release cut.
to_version	str	''	Window end as a release; "" with no to_sha = this namespace's head.
from_sha	str	''	Window start as a commit sha; give a version or a sha, not both.
to_sha	str	''	Window end as a commit sha; give a version or a sha, not both.
limit	int	10	At most this many candidates (1–25).
reviews_per_pr	int	3	review comments per candidate inside the range (0 = none)
stage	Literal['introduced', 'last_touched']	'introduced'	introduced: rank toward the change that introduced the behaviour; last_touched: the blame order only
mentions	str	''	what misbehaves, in words: a candidate whose linked issue or title names them ranks first

Output field	Type	Meaning
verdict	str	candidates | no_candidates | unknown | introduced_unknown (stage introduced: blame saw no in-window line; the list is the file-touching fallback)
causes	list[str]	window_unresolved | path_not_indexed | blame_failed | ledger_failed | tracker_unavailable
epistemic	str	exact when the blame leg ran (line attribution), lower_bound when only the ledger answered (file-level) or the introduced stage is blameless
stage	Literal['introduced', 'last_touched']	the order candidates is in
note	str	What the answer can and cannot claim (last touched, not introduced), plus lines blame could not map to a PR.
path	str	The path blamed, normalized.
path_indexed	bool	True when the code index holds the path as a live file.
range	dict[str, Any]	{start, end, requested_end, truncated}
window	dict[str, Any]	{from_ref, to_ref, from_sha, to_sha, base_sha, from_time, to_time, sources{from,to: namespace_head|mirror_ref|sha|default}, error}
candidates	list[dict[str, Any]]	ranked: {pr_number, title, author, merged_at, first_release, lines_blamed, share_of_range, touches_file, evidence blame|ledger|both, kind, merge_commit_sha, merge_sha_source stored|mirror|"", url, has_test?, caused_by?[], fixes?[]}; stage…
last_touched	list[dict[str, Any]]	the first stage's order, always:
symbol	dict[str, Any]	the enclosing function of the range when the index has one:
latest_pr	int	the newest PR among those blame named (0 when none)
lines	dict[str, Any]	{total, attributed, noise, outside_window, unmapped}
legs	dict[str, Any]	{blame{status, warm, ms, window_commits, graph_truncated}, ledger{status, skipped: [{namespace, reason: not_readable}] when the trunk is unreadable}, introduced{status ok|skipped, ms, git_calls, demoted, promoted, blameless}}
first_release_basis	str	How first_release was derived; "" when the mirror has no branch-cut tags.
tracker_namespace	str	The tracker namespace bound to this code namespace; "" when none is bound.
tracker_unavailable	bool	True when a tracker is bound but its read failed; the candidates stand without has_test / caused_by / fixes.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.calibrate

Derive code-specific abstention thresholds from the authored probe corpus (query/positive/hard-distractor triples over the indexed repo) and persist them as this namespace's calibration.

POST /v1/code.calibrate · MCP loom_code_calibrate · role admin · write · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)

Output field	Type	Meaning
noise_floor	float	Cosine below which a hit is noise: the distractors' 90th percentile plus 0.02.
abstain_threshold	float	Cosine below which the search abstains: noise_floor plus 0.05.
embedder_model	str	The embedding model the probes ran against; the calibration applies to it.
positives	int	Query/positive pairs read from the probe corpus.
distractors	int	Query/distractor pairs read from the probe corpus.

code.callees

What does this symbol call — forward call edges (depth<=3), tier-marked like code.callers.

POST /v1/code.callees · MCP loom_code_callees · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
pr_files	dict[str, str]	(computed)	Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each).
pr_diff	str	''	The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes.
pr_head_sha	str	''	The PR's head and base commits as the caller knows them; they label the answer (overlay_head_sha) and never reach git. '' = derived from the text.
pr_base_sha	str	''
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	''	Bare, qualified or partly qualified name of the seed symbol, or path:line for the innermost function containing that line.
symbol_id	str	''	An index symbol id for the seed; wins over name.
depth	int	1	How many hops to walk out from the seed (1–3); 1 = direct callers / callees.
max_nodes	int	200	At most this many edges across all hops (1–500); truncated says when it held.
min_confidence	float	0.0	Drop parser-tier edges below this confidence.
include_ambiguous	bool \| None	None	Widen the answer from "what calls it" to "what MAY call it".
candidate_min_confidence	float \| None	None	Unset = on; candidates below candidate_min_confidence (default the deployment floor, 0.2) are counted in the block's note and not returned. 0 shows every site.
pr_number	int	0	An OPEN pull request whose head the mirror holds (refs/pull/N/head).
edge_kinds	list[str]	(computed)	The edge kinds the walk follows — a subset of calls | inherits | overrides | fixture_use | reads | writes.

Output field	Type	Meaning
edges	list[CodeEdgeWire]	The call-graph edges found, hop by hop; the far end (from_* for callers, to_* for callees) is the answer.
seed_symbols	list[str]	Qualified names of the definitions the walk started from; empty when refused as ambiguous.
overlay	bool	On the wire only when pr_number was given.
overlay_head_sha	str	The PR head commit whose post-image was parsed; "" when there is no overlay.
overlay_added	int	How many functions the PR adds in its parsed files.
overlay_note	str	Why the overlay is off: head_not_in_mirror, no_merge_base or no_repo_entry; when it is on, "" or how many changed files it did not fully read.
resolved_by	str	How an over-qualified name bound when the exact form missed — anonymous_namespace ((anonymous namespace):: segments stripped) or tail (a namespace the definition does not carry dropped; one definition fit), or registration when a…
ambiguous	bool	A bare short name that resolves to many unrelated definitions (setColumns on 60 classes) is not walked: ambiguous is set, candidates lists the qualified names to pick from, and edges is empty.
candidates	list[str]	With ambiguous: up to 20 qualified names to pick from.
dispatch_seeds	list[dict[str, str]]	Virtual dispatch: when the seed is an override, calls in the code go to the BASE declaration, so its callers are included and listed here as {"symbol", "via": "overrides" | "inherits" | "virtual_by_name"}.
note	str	Plain-text notes on how the walk ran: dispatch or member folding, the ambiguity refusal, declined call sites, stale compiler-tier files; "" when none apply.
truncated	bool	True when the walk stopped short: max_nodes held or a hop's edge read hit its cap.
counts_floor	bool	Epistemic contract: edge counts are FLOORS, never totals.
unresolved_calls	int	HOW LOW the floor may be (callers direction): call sites in the fast tier's files whose callee is NAMED like the seed but which the resolver declined to bind — unresolved (no definition of that name in the index) or ambiguous (several…
ambiguous_calls	int	Declined call sites named like the seed with several same-named definitions, none pinned (see unresolved_calls).
epistemic	str	Epistemic envelope.
causes	list[str]	Why epistemic is lower_bound, from the set above; empty when it is exact.
by_hop_counts	dict[int, int]	Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}.
candidate_sites	CodeCandidateSitesWire \| None	Declined call sites as ranked candidates, on request only (include_ambiguous).
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.callers

Who calls this symbol — exact reverse call edges (depth<=3), compiler-resolved where available; edge_kinds: ['inherits'] narrows the walk to what implements or extends a type.

POST /v1/code.callers · MCP loom_code_callers · role viewer · read

Input field	Type	Default	Meaning
pr_files	dict[str, str]	(computed)	Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each).
pr_diff	str	''	The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes.
pr_head_sha	str	''	The PR's head and base commits as the caller knows them; they label the answer (overlay_head_sha) and never reach git. '' = derived from the text.
pr_base_sha	str	''
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	''	Bare, qualified or partly qualified name of the seed symbol, or path:line for the innermost function containing that line.
symbol_id	str	''	An index symbol id for the seed; wins over name.
depth	int	1	How many hops to walk out from the seed (1–3); 1 = direct callers / callees.
max_nodes	int	200	At most this many edges across all hops (1–500); truncated says when it held.
min_confidence	float	0.0	Drop parser-tier edges below this confidence.
include_ambiguous	bool \| None	None	Widen the answer from "what calls it" to "what MAY call it".
candidate_min_confidence	float \| None	None	Unset = on; candidates below candidate_min_confidence (default the deployment floor, 0.2) are counted in the block's note and not returned. 0 shows every site.
pr_number	int	0	An OPEN pull request whose head the mirror holds (refs/pull/N/head).
edge_kinds	list[str]	(computed)	The edge kinds the walk follows — a subset of calls | inherits | overrides | fixture_use | reads | writes.

Output field	Type	Meaning
edges	list[CodeEdgeWire]	The call-graph edges found, hop by hop; the far end (from_* for callers, to_* for callees) is the answer.
seed_symbols	list[str]	Qualified names of the definitions the walk started from; empty when refused as ambiguous.
overlay	bool	On the wire only when pr_number was given.
overlay_head_sha	str	The PR head commit whose post-image was parsed; "" when there is no overlay.
overlay_added	int	How many functions the PR adds in its parsed files.
overlay_note	str	Why the overlay is off: head_not_in_mirror, no_merge_base or no_repo_entry; when it is on, "" or how many changed files it did not fully read.
resolved_by	str	How an over-qualified name bound when the exact form missed — anonymous_namespace ((anonymous namespace):: segments stripped) or tail (a namespace the definition does not carry dropped; one definition fit), or registration when a…
ambiguous	bool	A bare short name that resolves to many unrelated definitions (setColumns on 60 classes) is not walked: ambiguous is set, candidates lists the qualified names to pick from, and edges is empty.
candidates	list[str]	With ambiguous: up to 20 qualified names to pick from.
dispatch_seeds	list[dict[str, str]]	Virtual dispatch: when the seed is an override, calls in the code go to the BASE declaration, so its callers are included and listed here as {"symbol", "via": "overrides" | "inherits" | "virtual_by_name"}.
note	str	Plain-text notes on how the walk ran: dispatch or member folding, the ambiguity refusal, declined call sites, stale compiler-tier files; "" when none apply.
truncated	bool	True when the walk stopped short: max_nodes held or a hop's edge read hit its cap.
counts_floor	bool	Epistemic contract: edge counts are FLOORS, never totals.
unresolved_calls	int	HOW LOW the floor may be (callers direction): call sites in the fast tier's files whose callee is NAMED like the seed but which the resolver declined to bind — unresolved (no definition of that name in the index) or ambiguous (several…
ambiguous_calls	int	Declined call sites named like the seed with several same-named definitions, none pinned (see unresolved_calls).
epistemic	str	Epistemic envelope.
causes	list[str]	Why epistemic is lower_bound, from the set above; empty when it is exact.
by_hop_counts	dict[int, int]	Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}.
candidate_sites	CodeCandidateSitesWire \| None	Declined call sites as ranked candidates, on request only (include_ambiguous).
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.context_pack

Briefing at the START of a task, instead of exploring file by file.

POST /v1/code.context_pack · MCP loom_code_context_pack · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
pr_number	int	0	Indexed merged PR -> precomputed pack; 0 -> orientation map; unknown PR -> explicit abstention. ge=0 because a negative number would reach ClickHouse as a UInt32 bind and surface as a 500.
task	str	''	The change about to be made ("add a new tracker op").
token_budget	int	2500	Token budget for context (200..8000): a precomputed pack is cut to it, a task briefing or orientation map is built within it.
sections	list[Literal['symbols', 'co_change', 'tests', 'reviews', 'prs', 'qa', 'files']]	(computed)	Precomputed packs only.

Output field	Type	Meaning
context	str	The pack as Markdown text; for unavailable, a short note saying the PR has no pack yet.
tokens_used	int	Estimated tokens of context.
source	Literal['precomputed', 'task', 'orientation', 'unavailable']	precomputed (the PR's stored pack) | task (a briefing for task) | orientation (the repository map) | unavailable (no pack for the PR).
truncated	bool	True when a precomputed pack was cut to token_budget; false for the other sources.
merge_commit_sha	str	The PR's merge commit, for a precomputed pack; '' otherwise.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.context_packs

List the stored per-PR context packs of a repository, optionally for one PR.

POST /v1/code.context_packs · MCP loom_code_context_packs · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
limit	int	50	At most this many packs per page, newest first (1..200).
offset	int	0	Packs to skip before the page starts.
pr_number	int	0	Optional exact PR filter (0 = all).

Output field	Type	Meaning
rows	list[CodeContextPackRow]	Live packs, newest built first; title, author and merged_at are '' when the PR history lacks the PR.
total	int	Every live pack matching the filter, not only this page.

code.conventions

The repository's recurring maintainer checks as facts over one PR's diff: a setting added or re-defaulted without a SettingsChangesHistory entry; the same setting's docs mention; a new…

POST /v1/code.conventions · MCP loom_code_conventions · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
pr_number	int	0	A merged PR in the ledger: its title, labels and merge commit's diff are checked; 0 = none.
head_sha	str	''	A commit the mirror holds: the diff from its merge-base with the branch tip is checked; falls back to the ledger's merge commit when the mirror lacks it.
files	list[str]	(computed)	An open PR's changed paths; with diff they replace any ledger file list.
diff	str	''	An open PR's unified diff; its hunks are what the rules check (with files).
rules	list[str]	(computed)	The rules to run (names from the conventions rule table); empty = every rule.

Output field	Type	Meaning
pr_number	int	The PR asked about; 0 when none was named.
source	str	ledger | head_sha | supplied
title	str	The ledger PR's title; '' when the PR is not in the ledger or none was named.
labels	list[str]	The ledger PR's labels.
category	str	bug_fix | improvement | new_feature | performance | not_for_changelog | build | ci | documentation | backward_incompatible | experimental | ''
category_source	str	Where category came from: label:<name>, changelog_bullet (the PR body), or ''.
merged_at	str	When the ledger PR merged; '' without a ledger row.
merge_commit_sha	str	The ledger PR's merge commit; '' without a ledger row.
head_sha	str	The commit the diff was read at when source is head_sha; otherwise the head_sha sent.
files_total	int	Changed paths known for the change (name-status list plus the diff's files).
files_in_diff	int	Files whose hunks were parsed from the diff; fewer than files_total when it was cut.
diff_bytes	int	Size of the diff text read, in characters; 0 without a diff.
diff_truncated	bool	True when the mirror diff hit code_conventions_diff_max_bytes and its last file was dropped; notes says how many files were parsed.
rules	list[dict[str, Any]]	[{rule, verdict: violated|satisfied|not_applicable|unknown|unusual, evidence: [{path, line, text, ...}], epistemic: exact|lower_bound, note}]
summary	dict[str, int]	verdict -> count over rules
control	dict[str, Any]	{coverage_symbol, ok, ran}: the coverage control rule 7 depends on
notes	list[str]	Why part of the answer is weaker: PR not in the ledger, merged into another branch, commit not in the mirror, diff cut, supplied-diff pre-image; empty when none applies.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.coverage

Report how much of a repository the index covers at its head: per language, per tier, and the gaps.

POST /v1/code.coverage · MCP loom_code_coverage · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
as_of_commit	str	git_head
languages	list[CodeLanguageCoverage]	One row per language, the most files first.
tiers	list[CodeTierCoverage]	Call-graph edge counts per tier.
gaps	CodeCoverageGaps \| None	None when the gap queries failed — absence, never a fabricated zero.
pr_history_from	str	The oldest merge time among the stored merged PRs; '' when none are stored.
pr_history_to	str	The newest merge time among the stored merged PRs; '' when none are stored.
pr_history_last_fetch_at	str	When the PR-history poller last wrote a row; '' never.
pr_history_enabled	bool	Whether the PR-history poller is enabled on this deployment.
pr_history_auth	str	token | anonymous (60 req/h GitHub limit)
context_packs_last_at	str	When the newest live PR context pack was built; '' when none exists.
summaries_last_at	str	When the newest chunk context description was written; '' when none exists.

code.coverage.unwatch

Cancel a coverage watch on a commit.

POST /v1/code.coverage.unwatch · MCP loom_code_coverage_unwatch · role viewer · idempotent · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
commit	str	required	The watched commit: a full 40-hex SHA, or a 7..39-hex abbreviation the mirror resolves.
inbox	str	required	The inbox the watch posts to; the caller must be a writer on its owner namespace.

Output field	Type	Meaning
commit	str	The full SHA the abbreviation resolved to.
inbox	str	The inbox, as sent.
removed	bool	False when no live watch existed.

code.coverage.watch

Ask for a task-inbox message when the index covers a commit, instead of polling for it.

POST /v1/code.coverage.watch · MCP loom_code_coverage_watch · role viewer · idempotent · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
commit	str	required	Merge commit SHA to watch.
inbox	str	required	Task inbox that receives the code.coverage.ready event; the caller must be a writer on its owner namespace.

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
commit	str	the full SHA
inbox	str	The inbox the event is posted to, as sent.
ready	bool	True once every tier covers the commit; the event is then on the inbox.
emitted	bool	True when this call posted the event (an already-covered commit).
delivered_at	datetime \| None	When the ready event was posted to the inbox; None while the commit is not covered.
event_id	str	The event's task_id on the inbox, fixed per (namespace, commit, inbox).
commit_coverage	CodeCommitCoverage \| None	The commit's per-tier coverage at this call, as code.index_status reports it.

code.coverage_claim

Is this already tested?

POST /v1/code.coverage_claim · MCP loom_code_coverage_claim · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
symbol	str	''	The subject as a symbol name (qualified or bare) or a SQL-level function name.
path	str	''	The subject as a repository-relative source path.
setting	str	''	The subject as a setting name.
limit	int	20	At most this many tests rows (at most 100).

Output field	Type	Meaning
subject	str	The subject as given (the one of symbol, path, setting that was set).
subject_kind	str	symbol | path | setting
verdict	str	covered_by | weak_evidence | uncovered | unknown
tests	list[dict[str, Any]]	{test_path, methods: [...], tier, confidence, evidence}
tests_total	int	Tests found before limit (the larger of the rows and the grep's match count).
src_paths	list[str]	The source files the subject lives in: the path itself, the files defining the resolved symbol (first 20), or [] for a setting.
epistemic	str	exact when a test names the subject or the include graph reaches it; lower_bound when only mined co-occurrence or a path convention says so
strongest_tier	str	The strongest evidence tier among the rows (executed | exact_scoped | pr_cooccurrence | short_name_grep | file_reference | path_convention), '' when no test was found.
search_terms	dict[str, str]	The literals the grep ran, each with the tier a hit counts as — the SQL names the class registers and the qualified form are exact_scoped, the bare method name short_name_grep.
resolved_by	str	registration when the subject was a SQL-level name bound to its implementing class through the registration statement; '' and off the wire otherwise.
control	dict[str, Any]	{symbol, ok[, via]}: the positive control this call ran; ok=False ⇒ unknown.
measured	dict[str, Any]	What the newest imported coverage run measured, {} when no run covered the subject's files: {measured, executed, paths, hits: {path: [[start, end], ...]}, commit}.
trace_run_id	str	Id of this call's row in loom.code_search_trace.

code.enclosing

Batched path:line -> enclosing function.

POST /v1/code.enclosing · MCP loom_code_enclosing · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
locations	list[str]	required	"src/Foo.cpp:123" — repo-relative path, 1-based line.
include_body	bool	False	include_body: ship the enclosing function's whole body with each resolved location, so a grep hit becomes the function it sits in without a follow-up code.symbol or a file read (most index answers are otherwise followed by a read of the…
token_budget	int	4000	With include_body: token budget for the bodies (200..12000); bodies past it ship elided.
neighbours	bool \| None	None	neighbours: a graph evidence block per distinct enclosing function: up to neighbour_k callers, callees (compiler tier preferred, symbols outside the repo dropped, parser guesses below 0.8 confidence dropped) and mapped tests, the module…
neighbour_k	int	5	With neighbours: at most this many callers and callees per function (1..20).

Output field	Type	Meaning
results	list[dict[str, Any]]	one entry per input location, input order preserved: {path, line, symbol, symbol_id, qualified_name, signature, tier, kind, start_line, end_line} kind is "function" / "method" / "fixture" for a line inside a function body; "class"…
resolved	int	Locations that landed inside a function, type, or document section.
paths_indexed	int	distinct input paths that have any symbol rows
paths_total	int	Distinct paths among the parseable input locations.
took_ms	int	Server-side wall time of the call, in milliseconds.
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS).
bodies_returned	int	include_body accounting: distinct bodies served / withheld for budget
bodies_elided	int	Distinct bodies withheld because token_budget ran out.
tokens_returned	int	include_body bodies + the neighbours block, in tokens
neighbours	list[dict[str, Any]]	neighbours=true: one entry per distinct enclosing function in first- appearance order, at most 20: {symbol_id, qualified_name, path, module, callers: [qualified names], callees: [...], tests: [paths], epistemic, causes}.
anchors	int	distinct enclosing functions the block covers
anchors_capped	bool	more resolved functions than the 20 cap
neighbour_tokens	int	Tokens of the neighbours block alone; 0 when neighbours is off.

code.examples

Real call sites of a symbol, ranked test-covered-first — a current, tested usage example beats the deprecated one grep finds first.

POST /v1/code.examples · MCP loom_code_examples · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	''	The symbol: a qualified name or a path:line inside it; ignored when symbol_id is set.
symbol_id	str	''	The symbol's id from an earlier code.* answer; wins over name.
top_k	int	3	At most this many call sites (1..10).

Output field	Type	Meaning
examples	list[dict[str, Any]]	Call sites, test-covered callers first: {caller, path, line, tier, test_covered, body}, body = the smallest chunk around the line (up to 4,000 chars, '' when none).
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.files

Which indexed files have this NAME — an rg-style glob (tests/queries/0_stateless/05138_*, /*Parquet*.cpp), a basename stem (05138_with_fill matches the stem exactly or as its leading prefix…

POST /v1/code.files · MCP loom_code_files · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
glob	str	''	An rg-style glob over the repo-relative path (/*Parquet*.cpp); '' = no glob filter.
stem	str	''	A basename without extension, matched exactly or as its leading prefix; exact matches sort first. '' = no stem filter.
path_prefix	str	''	Only paths under this prefix; '' = no prefix filter.
limit	int	50	At most this many files (1..500).

Output field	Type	Meaning
files	list[dict[str, Any]]	{path, lang, size_bytes, loc, indexed_commit}; exact stem matches first, then path order.
total	int	matching files before limit
truncated	bool	True when total is larger than the files returned.
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS).
not_covered	bool	True when path_prefix lies outside the indexed prefixes; files is then empty.
note	str	With not_covered: which prefixes the index holds; '' otherwise.
trace_run_id	str	Id of this call's trace row ('' on a not_covered answer); pass it to code.outcome.

code.first_build

Which CI build first carried this commit?

POST /v1/code.first_build · MCP loom_code_first_build · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
sha	str	''	A commit sha, 7–40 hex characters; an abbreviated one is expanded on the mirror.
pr_number	int	0	A merged PR; the ledger supplies its merge commit and time. 0 = use sha.

Output field	Type	Meaning
verdict	str	built | not_yet_built | unknown
causes	list[str]	tracker_unbound | tracker_unavailable | sha_unknown | candidates_exhausted | pr_not_merged
epistemic	str	exact: a run names the sha (or the PR's own head builds); lower_bound: the earliest of ≤ 10 checked bases descends from it
sha	str	The full commit sha the answer is about (from the input, the mirror or the ledger).
pr_number	int	The PR the commit merged, from the input or the ledger; 0 when unknown.
merged_at	str	When the PR merged, from the ledger (ISO-8601); "" when the ledger has no row.
commit_time	str	The commit's time on the mirror (ISO-8601); "" when the mirror lacks the sha.
ledger_known	bool	True when the PR ledger knows the subject.
mirror_known	bool	True when the code mirror holds the commit.
first_build	dict[str, Any]	{kind named|carrier|own, check_start_time, version, docker_tag, minor_version, git_ref, pull_request_number, commit_sha, base_sha}
lag_hours	float \| None	hours from the merge (or commit) to the first carrying run
later_builds	int	runs started after it inside the window (later bases not individually checked)
window_hours	int	How many hours after the merge (or commit) runs are read for carriers.
candidates_checked	int	How many run bases were checked on the mirror for descent from the commit.
candidates_total	int	How many candidate run bases the window held.
own_builds	list[dict[str, Any]]	the PR's own head builds, oldest first (≤ 8)
containing_branches	list[str]	mirror branches whose head contains the sha, and the namespaces on them
containing_namespaces	list[str]	The repository's namespaces whose branch contains the commit.
nearest_namespace	str	the lowest release-branch namespace containing it, else the own branch's
note	str	What the tracker's build view can show; "" when the tracker was not read.
tracker_namespace	str	The tracker namespace bound to this code namespace; "" when none is bound.
tracker_unavailable	bool	True when a tracker is bound but its read failed.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.grep

Exact-match lookup over the indexed corpus.

POST /v1/code.grep · MCP loom_code_grep · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
pattern	str	required	The text to find: a literal substring, or an RE2 expression with regex.
regex	bool	False	True reads pattern as RE2; an invalid expression is a 422.
case_sensitive	bool	True	False matches pattern regardless of letter case.
path_prefix	str	''	Only paths under this repo-relative prefix; '' = the whole index.
cursor	str	''	Continuation (matches mode): the next_cursor of an earlier response to this pattern; the next page of matching lines is one point read of what the first call extracted.
exclude_unit_ids	list[str]	(computed)	The caller's seen-set.
mode	Literal['matches', 'files', 'presence', 'message']	'matches'	matches: up to limit matching LINES with text + enclosing scope. files: up to limit matching FILES (path, matching chunk count, first line) and no line text — the coverage question ("which files mention X?") that a 20-line cap cannot…
limit	int \| None	None	Default depends on mode: 20 lines, or the 500-file ceiling — a files answer capped at 20 reads like a complete coverage answer to a caller that did not know to send a limit. matches mode is clamped to 200 lines.
path_globs	list[str]	(computed)	File filters, rg -g / -t style: keep paths matching any glob, drop paths matching any exclude, restrict to a language's extension set.
exclude_globs	list[str]	(computed)	Drop paths matching any of these rg-style globs.
langs	list[str]	(computed)	Keep only files with these languages' extensions (rg -t names: cpp, py, ts, go, …); an unknown name is a 422 that lists the known ones.
namespaces	list[str]	(computed)	Several namespaces, mode="presence" only: at most 8, trimmed, duplicates removed; namespace, when set and absent, leads the list.
neighbours	bool \| None	None	The neighbours graph block in the SAME call, matches mode only: the hits' enclosing functions become anchors (at most 20, first appearance) and each carries up to neighbour_k callers, callees and mapped tests at edge confidence >= 0.8…
neighbour_k	int	5	With neighbours: at most this many callers and callees per anchor (1..20).
deadline_ms	int \| None	None	The request's wall-clock budget in ms, from arrival (values under 200 read as 200).

Output field	Type	Meaning
matches	list[dict[str, Any]]	{path, line, text, scope, scope_start_line, scope_end_line} per matching LINE, path/line ordered. scope_* is the span of the enclosing unit named by scope (0/0 when the line sits in no unit) — enough to decide whether to fetch the body…
next_cursor	str	Continuation: cursor for the next page of matching lines, "" when the extracted set is exhausted. has_more mirrors it.
has_more	bool	True when next_cursor is set.
files	list[dict[str, Any]]	mode=files: {path, chunks, first_line} per matching file, path ordered.
files_total	int	distinct matching files before limit (mode=files)
chunks_matched	int	Indexed chunks read that contain the pattern (matches mode over-fetches up to 200).
truncated	bool	True when more lines or files match than were returned, or the chunk read hit its cap.
coverage_floor	bool	Chunk coverage is not byte-complete for a file: absence here cannot prove absence in the repo (same floor contract as code.verify).
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS).
not_covered	bool	True when path_prefix lies outside the indexed prefixes (hits are then empty by construction, not by absence).
neighbours	list[dict[str, Any]]	The neighbours graph block: one entry per anchor — symbol_id, qualified_name, path, module, callers, callees, tests, epistemic, causes; empty unless neighbours ran.
anchors	int	distinct enclosing functions the block covers
anchors_capped	bool	more resolved functions than the 20 cap
neighbour_tokens	int	Tokens of the neighbours block alone; 0 when it did not run.
note	str	A caveat on the answer: the pattern was re-read as a regex or matched literally, the prefix is outside the index, or the embedding coverage is low; '' when none.
verdict	str	mode=message only (dropped from the wire otherwise): raised_at | no_template_match; the message's {} template; the ErrorCodes name for a Code: N prefix ("" when unmapped); the best statement's coverage (matched message characters…
template	str	mode=message: the message with {} where arguments stood.
error_code	str	mode=message: the ErrorCodes name for a Code: N prefix; '' when unmapped.
coverage	float	mode=message: the best statement's matched share of the message characters (0..1).
presence	list[dict[str, Any]]	mode=presence: one row per requested namespace, in request order — {namespace, verdict: present | absent | unknown, path, start_line, end_line, tier: "", files_total, indexed_commit, index_status, ms, reason}.
summary	dict[str, list[str]]	mode=presence: {present, absent, unknown}, each the namespaces with that verdict.
trace_run_id	str	Id of this call's trace row ('' on a not_covered answer); pass it to code.outcome.
partial	bool	deadline_ms stopped the scan (or skipped a later read): the hits are those found in the budget and partial_reason says what was cut.
partial_reason	str	What the deadline cut, as deadline N ms: <stage>; <stage>.
fallback	Literal['', 'literal']	mode=message whose pattern matched no statement template: "literal" when the same pattern was then run as a plain matches grep and matches are its lines (the verdict fields stay the message read's).

code.history

The merged PRs that most recently touched a symbol or path: number, title, author, labels, and what reviewers said about that file — up to reviews_per_pr (default 3, 0 = none) human review comments…

POST /v1/code.history · MCP loom_code_history · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	''	A symbol name or path:line; the PRs over its definitions' files are returned.
symbol_id	str	''	An index symbol id; wins over name.
path	str	''	A repo-relative file; wins over name / symbol_id.
numbers	list[int]	(computed)	Issue / PR numbers: the item facts and the merged PRs that are or close them, from the same reads code.search's history section uses.
limit	int	5	At most this many PRs (1–20).
reviews_per_pr	int	3	review comments per PR row on the queried file (0 = none)

Output field	Type	Meaning
prs	list[dict[str, Any]]	Merged PRs, newest first: {pr_number, title, author, merged_at, labels, body_excerpt} plus reviews / review_count when asked; number lookups return the history rows.
paths	list[str]	The files the PRs were read for; for number lookups, the files the returned PRs touched.
items	list[dict[str, Any]]	number lookups only: what each number is (issue / pr, state, title)
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.impact

Symbol-shaped (name/symbol_id) or diff-shaped (files/diff) blast radius.

POST /v1/code.impact · MCP loom_code_impact · role viewer · read

Input field	Type	Default	Meaning
pr_files	dict[str, str]	(computed)	Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each).
pr_diff	str	''	The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes.
pr_head_sha	str	''	The PR's head and base commits as the caller knows them; they label the answer (overlay_head_sha) and never reach git. '' = derived from the text.
pr_base_sha	str	''
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	''	Symbol shape: the seed's bare, qualified or partly qualified name, or path:line.
symbol_id	str	''	Symbol shape: an index symbol id for the seed; wins over name.
depth	int	2	How many caller hops the radius walks from the seeds (1–2).
files	list[str]	(computed)	Diff shape: repo-relative changed paths, and/or a unified diff whose hunk line ranges narrow the touched set from whole files to the symbols actually edited.
diff	str	''	A unified diff (at most 200,000 chars); its hunk ranges pick the edited functions as seeds.
exclude_authors	list[str]	(computed)	Left out of owners: the change's own author(s) are not its reviewers.
summary_only	bool	False	Hub-safe ergonomics.
per_hop_limit	int	200	At most this many impacted_symbols rows from each hop (1–500).
offset	int	0	Rows to skip within each hop before per_hop_limit applies; pages a hub's radius.
pr_number	int	0	An OPEN pull request whose head the mirror holds.

Output field	Type	Meaning
impacted_symbols	list[dict[str, Any]]	Each row {qualified_name, path, hop, tier}; a row whose function is a registration function (REGISTER_FUNCTION(X), registerStorageFoo) carries via: "registration" — the seed is reached through a registry; the key is absent otherwise.
impacted_tests	list[dict[str, Any]]	Tests the test map ties to the seed and impacted paths: {test_path, src_path, confidence}.
co_change_files	list[dict[str, Any]]	Files changed in the same merged PRs as the seed paths, most often first ({path, prs}, at most 20): the last 10 PRs for the symbol shape, 50 for the diff shape.
blast_radius_score	float	impacted/50 + tests/40, capped at 1.
touched_symbols	list[dict[str, Any]]	Diff shape only: the symbols the change touches (hunk-overlap when a diff was given, else every function in the files), and the files that historically co-change with the touched set but are absent from it — the "did you forget to update…
co_change_missing	list[dict[str, Any]]	Diff shape: co-change files absent from the change ({path, prs, of}, at most 5, support at least 4 PRs and 15%); empty for the symbol shape.
owners	list[dict[str, Any]]	Who to ask: {author, share, prs, reviews, last_merged_at} from merged PRs over the seed paths — the PRs a person AUTHORED (prs) and the ones they REVIEWED (reviews, inline comments), recency-decayed (120-day half-life), share floor, at…
reverts	list[dict[str, Any]]	Merged PRs over the seed paths that were REVERTS ({pr_number, title, merged_at}, newest first, <=5): the one kind of history that says what not to do, invisible to symbol lookups (the code is back) and to co-change (same files as the…
counts_floor	bool	Same epistemic contract as code.callers: radius counts are floors.
unresolved_calls	int	Symbol shape: call sites named like the seed(s) that the fast tier declined to bind — the size of the floor.
ambiguous_calls	int	Declined call sites with several same-named definitions (see unresolved_calls).
epistemic	str	Epistemic envelope.
causes	list[str]	Why epistemic is lower_bound, from the set above; empty when it is exact.
by_hop_counts	dict[int, int]	Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}.
truncated	bool	True when impacted_symbols is a page of the radius (per_hop_limit / offset sliced it, or the per-hop edge read hit its cap).
resolved_by	str	anonymous_namespace | tail when the symbol shape's name bound through symbol-form tolerance; "" and off the wire otherwise.
verdict	str	Why the radius is empty, '' when it is not.
paths_seen	list[dict[str, str]]	Diff shape: every path the request named, with its class — test | doc | config | unindexed (outside the indexed prefixes, or a source path the index holds no file row for) | src — so the verdict is actionable without re-deriving…
overlay	bool	On the wire only when pr_number was given — see CodeCallersOutput.
overlay_head_sha	str	The PR head commit whose post-image was parsed; "" when there is no overlay.
overlay_added	int	How many functions the PR adds in its parsed files, each a touched_symbols seed.
overlay_note	str	Why the overlay is off: head_not_in_mirror, no_merge_base or no_repo_entry; when it is on, "" or how many changed files it did not fully read.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.index_errors

List the files the code index failed to parse or ingest, with the error and the commit.

POST /v1/code.index_errors · MCP loom_code_index_errors · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
limit	int	100	At most this many files, newest first (1..1000).

Output field	Type	Meaning
rows	list[CodeIndexErrorRow]	Files whose last ingest recorded an error, newest first.
total	int	Every errored live file in the namespace, not only the rows returned.

code.index_status

Health of the code index: indexed head commit, compiler-tier commit, row counts, watermarks, and the weekly tables' state (symbol_stats_rows/at, unit_risk_rows/at; 0 = not written yet).

POST /v1/code.index_status · MCP loom_code_index_status · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
commit	str	''	Optional merge commit SHA: report whether every index tier covers it (commit_coverage.ready).
paths	list[str]	(computed)	With commit: the PR's changed paths; the answer lists those a later merge changed.
brief	bool \| None	None	Compact answer without state/op catalogue/workers.

Output field	Type	Meaning
repo	str	The repository identity.
branch	str	The branch this entry indexes.
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
provider	str
profile	str
compiler_candidates	list[str]	Compiler tiers inferred from the indexed tree, even before a compiler worker has produced its first watermark.
quality_warnings	list[str]	Actionable readiness gaps.
git_head	str	The fast tier's watermark: the last commit whose files are ingested; '' before the first pass.
scip_commit	str	scip_commit / scip_lag are the ENTRY'S compiler tier — the one scip_producer names — not the C++ key by name; a TypeScript repository reports its scip-typescript watermark here.
scip_commit_py	str	The scip-python watermark by name, whatever the entry's primary tier; '' when unset.
scip_producer	str	The primary compiler tier's producer (clang | typescript | go | python); '' when no tier has a watermark.
compiler_tiers	list[CodeCompilerTier]	Every compiler tier with a watermark or configured for the entry, the primary first.
tier_health	list[CodeTierHealth]	The last recorded outcome of each tier that has one (fetch, ingest, the compiler tiers and the weekly C++ full run): a failing tier names its error kind, since when, and the fix.
pr_cursor	str	The PR-history poller's cursor: the newest updated_at (ISO-8601) of the merged PRs it fetched; '' before its first pass.
commit_coverage	CodeCommitCoverage \| None	Set when the request named a commit.
clone_head	str	Freshness. clone_head is the bare clone's branch tip as of the last poller fetch (<= interval old); *_lag = first-parent commits between a watermark and that tip, -1 when a watermark is unset or the clone is unreadable. 0 everywhere ==…
clone_fetched_at	str	When the ingest pass last fetched this entry's mirror (the clone_head row's updated_at, ISO-8601 UTC; '' unknown) and whether that is older than code_fetch_stale_after_seconds.
fetch_overdue	bool	True when clone_fetched_at is older than code_fetch_stale_after_seconds.
fast_tier_lag	int	First-parent commits between git_head and clone_head; -1 when either is unknown.
scip_lag	int	First-parent commits between scip_commit and clone_head; -1 when either is unknown.
scip_py_lag	int	First-parent commits between scip_commit_py and clone_head; -1 when either is unknown.
last_refresh_at	str	Last code.refresh request (the CI hook).
last_refresh_detail	str	The caller of that request, as agent=<agent> expected_head=<first 12 hex>; a field the caller left empty is left out.
org_readable	bool	Deployment-level read rule (LOOM_CODE_ORG_READABLE / per-entry): when true every org principal reads this entry regardless of visibility.
path_prefixes	list[str]	The path prefixes the entry indexes; [""] = the whole tree.
counts	dict[str, int]	Live row counts per code table (code_files, code_chunks, code_symbols, …); empty in the brief answer.
state	dict[str, dict[str, str]]	Every code_index_state row: {key: {value, detail, updated_at}}.
workers	dict[str, CodeWorkerStatus]	Per code_* worker, its enabled flag, interval and last pass; empty in the brief answer.
build_commit	str	Capability catalogue: the build this server runs and every served code.* operation with the request fields its input model accepts, so a client checks for a route or a field instead of probing for a 404 or a 422.
ops	list[str]	Every served code.* operation, sorted; empty in the brief answer.
request_fields	dict[str, list[str]]	Per served op, the request fields its input model accepts; empty in the brief answer.
op_maturity	dict[str, str]	Per served op, its maturity (stable | experimental) and the reach kinds a caller has to it.
op_reach	dict[str, list[str]]	Per served op, its reach kinds (mcp_core | mcp_atomic | mcp_all | sdk_method | sdk_example | plugin_hook | dashboard | http_only); empty in the brief answer.
op_toolsets	dict[str, list[str]]	Per served op, every MCP toolset whose listing carries it (core | coding | atomic | all; empty when hidden).
symbol_stats_rows	int	The weekly symbol fan-in table for this namespace — live rows with callers and the newest pass stamp (ISO 8601, UTC). 0 / "" = the pass has not written it: every fan_in field, the fan-in sort and the rank prior answer empty.
symbol_stats_at	str	The newest fan-in pass stamp (ISO-8601 UTC); '' when the pass has not written the table.
unit_risk_rows	int	The precomputed risk table for this namespace — live rows and the newest stamp (ISO 8601, UTC), so an operator sees the weekly leg's progress and a resumed pass's remainder. 0 / "" = no row written (every served unit is read live).
unit_risk_at	str	The newest risk-table stamp (ISO-8601 UTC); '' when no row is written.
chunks_total	int	Live chunks, those carrying a vector, and their ratio (0..1; reference fixtures unembedded by design are outside the denominator).
chunks_embedded	int	Live chunks that carry an embedding vector.
embedding_coverage	float	Embedded share of the embeddable chunks (0..1); 1.0 when the counts do not carry it.

code.map

PageRank-ordered orientation map of the indexed repository with per-file summary cards, token-budgeted.

POST /v1/code.map · MCP loom_code_map · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
token_budget	int	1000	Token budget for the map (200..4000); entries past it are dropped.
module_prefix	str	''	Only modules and hubs under this repo-relative prefix; '' = the whole repository.

Output field	Type	Meaning
map	str	The repository map as Markdown: module cards and call-graph hubs, then the most-called symbols when the fan-in stats exist.
tokens_used	int	Estimated tokens of map.
commit_sha	str	The fast-tier watermark (git_head) the map reflects; '' before the first pass.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.outcome

Tell loom what you did with a code answer, by its trace_run_id: 'used_in_answer', 'opened_file' (targets = the paths), 'fell_back_grep' or 'ignored'.

POST /v1/code.outcome · MCP loom_code_outcome · role viewer · idempotent · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
trace_run_id	str	''	Required for retrieval outcomes; optional (empty) for shunt_* only.
action	Literal['opened_file', 'used_in_answer', 'fell_back_grep', 'ignored', 'shunt_hit', 'shunt_pass']	required	What happened after the answer: opened_file (a returned file was read), used_in_answer, fell_back_grep, ignored; or a batch of shunt-hook decisions (shunt_hit | shunt_pass).
targets	list[str]	(computed)	opened_file: the paths read (matched to the trace's returned paths); shunt_*: one tool name per decision.
source	str	''	Who / why.
tokens_saved	int	0	shunt_hit: bytes of the file/grep result the model did not ingest ÷ 4. shunt_pass: the same estimate for what the pass LET IN (the addressable tokens, summed per reason). 0 when unknowable (grep).
spans	list[str]	(computed)	Aligned with targets: the line span each decision / open covered, as path:start-end (shunt rows: the file and the lines the Read would cover), start-end (opened_file: the Read's offset/limit against the target path) or '' when…
reason	str	''	fell_back_grep / ignored: WHY, from OUTCOME_REASONS.

Output field	Type	Meaning
recorded	bool	True when the row was written; false when the trace log is disabled or the write failed.

code.outline

"What is in this file?" — the question a whole-file read answers at the price of the whole file.

POST /v1/code.outline · MCP loom_code_outline · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
path	str	required	repo-relative path ("src/Foo.cpp"); a leading ./ is tolerated
kinds	list[str]	(computed)	Declaration kinds to list (function, class, job, …); the default covers every kind the symbol table records for code, SQL tests, build files and data models.
token_budget	int	1500	Whole-row budgeted: an entry ships complete (signature included) or not at all; the first elided entry names its own code.symbol call.

Output field	Type	Meaning
path	str	The repo-relative path read, normalised from the request.
entries	list[dict[str, Any]]	source order:
total	int	declarations found for the requested kinds
returned	int	Entries in entries.
elided	int	Declarations left out because token_budget ran out (total - returned).
next	str	code.symbol name=<qualified_name> of the first elided entry ("" when nothing was elided); a larger token_budget re-fetches the whole list.
indexed	bool	False when the path has no live symbol rows: unindexed, renamed, or the index has not caught up — read the file.
verdict	str	Why entries is empty, '' when it is not.
tokens_returned	int	Estimated tokens of the entries (and head) returned.
took_ms	int	Server-side wall time of the call, in milliseconds.
head	str	A reference fixture (lang reference) declares nothing; its indexed head (first 4,000 chars) is returned here instead, with head_truncated when the file is longer.
head_truncated	bool	True when the fixture is longer than the head returned; omitted with head.
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS).
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.path_guards

The conditions that stand on the call path from from_symbol to to_symbol: the verify(reaches) chain, and for each hop the guards the call site sits under inside its caller…

POST /v1/code.path_guards · MCP loom_code_path_guards · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
from_symbol	str	required	The symbol the call path starts from.
to_symbol	str	required	a symbol name, or a path prefix (contains '/') like verify(reaches)
mentions	str	''	the identifier the question asks about ('' lists the guards only)
depth	int	4	The most call hops the walk follows (1..4).

Output field	Type	Meaning
verdict	Literal['guarded_by', 'no_guard_named', 'path_found', 'path_not_found', 'unknown']	guarded_by a guard on some hop names mentions no_guard_named the path was found, no guard on it names mentions path_found the path was found and mentions was empty (listing) path_not_found the bounded walk emptied its frontier…
causes	list[str]	Machine-readable causes behind unknown, and the standing floors of a syntactic read otherwise (empty on guarded_by/no_guard_named/path_found only when nothing further limited the answer).
epistemic	Literal['lower_bound']	Always lower_bound: guards are read syntactically inside each caller only.
explanation	str	A human-readable account of how the verdict was reached.
hops	list[dict[str, Any]]	One entry per hop, seed first.
named_at	list[str]	The hops whose guards name mentions, as "path:line" — the places to read
visited_symbols	int	Symbols the bounded call walk visited.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.pr_check

A PR draft asks whether a PR like it already exists.

POST /v1/code.pr_check · MCP loom_code_pr_check · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
title	str	''	The draft's title; its tokens (with the symbols') are matched against PR titles.
body	str	''	The draft's description: Fixes #N links and #N mentions add issues, and its words (template boilerplate stripped) add match tokens.
paths	list[str]	(computed)	repository-relative paths the draft changes
symbols	list[str]	(computed)	symbols the draft adds or changes (function / class / method names)
issues	list[int]	(computed)	issues the draft closes, beside the ones its text names (Fixes #123, #123)
pr_number	int	0	the PR already opened for this draft: excluded from the candidates
top_k	int	5	At most this many candidates in items (1..20).

Output field	Type	Meaning
verdict	str	duplicate_of | related | none — none carries no items (open it)
items	list[dict[str, Any]]	[{pr_number, state: open|merged|closed, title, author, opened_at, merged_at, closed_at, relation: duplicate|related, score, evidence: [str], shared_paths, files_total, linked_issues, labels, found_by: [leg], features}]
undecided	bool	the top candidate sits in the upper related band: a human should look
epistemic	str	heuristic (every leg read) | lower_bound (a leg was unavailable) | unavailable
thresholds	dict[str, float]	The score cut-offs the verdict used: {duplicate, related}.
legs	dict[str, Any]	rows read per leg, or "unavailable: "
draft	dict[str, Any]	what the draft became: title_tokens, paths, symbols, issues
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.recent_commits

List the most recently indexed commits of a repository, decorated with subject and time from the clone.

POST /v1/code.recent_commits · MCP loom_code_recent_commits · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
limit	int	20	At most this many commits, newest ingest first (1..100).

Output field	Type	Meaning
rows	list[CodeRecentCommitRow]	Commits the fast tier wrote files at, newest ingest first.

code.refresh

CI calls this right after a merge lands: run one ingest pass now instead of waiting for the poll interval.

POST /v1/code.refresh · MCP loom_code_refresh · role writer · write · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
expected_head	str	''	The commit CI just merged; advisory, recorded in last_refresh_detail and never checked.
wait	bool	False	wait=True blocks until the pass completes (CI wants a sync signal); default fire-and-forget returns immediately.
wait_timeout_seconds	int	300	With wait: seconds to wait for the pass (10..900); the call fails when the pass outlasts it.

Output field	Type	Meaning
triggered	bool	True when this call started an ingest pass; false when one was already running.
already_running	bool	True when a pass for this namespace was already in flight; this call started none.
head_before	str	The fast-tier watermark (git_head) before the pass; '' when the namespace has none.
head_after	str	With wait: the fast-tier watermark after the pass; '' otherwise.

code.reindex

Operator repair: move the git watermark (e.g. back N commits after a bad pass, or to a specific sha).

POST /v1/code.reindex · MCP loom_code_reindex · role admin · write · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
git_head	str	required	full 40-char sha to move the ingest watermark to

Output field	Type	Meaning
previous_head	str	The fast-tier watermark before the move; '' when it was unset.
new_head	str	The watermark now set; the ingest worker re-walks from it.

code.repo.add

Add a repository's branch as a new read-only index.

POST /v1/code.repo.add · MCP loom_code_repo_add · role viewer · write · audited

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
repo	str	required	GitHub owner/name or an HTTPS/SSH Git URL.
branch	str	''	Blank asks the remote for its symbolic default branch.
join_policy	Literal['open', 'approval']	'open'	open: any org member joins at once; approval: a maintainer approves each request.
classification	Literal['standard', 'restricted']	'standard'	standard or restricted (a reader needs an approved grant and a token that names the namespace).
access_token	str	''	Token for a private HTTPS remote; stored encrypted, never returned.
path_prefixes	list[str]	(computed)	Path prefixes to index (src/, lib/); blank entries are dropped, [] indexes the whole tree.
exclude	list[str]	(computed)	Globs never indexed for this repository (vendor/, *.generated.go); [] keeps the deployment's default exclude list.
exclude_generated	bool	True	Refuse generated content (Go's // Code generated … DO NOT EDIT. header, the @generated marker, the repository's .gitattributes linguist rules) — on unless the maintainer says otherwise
scip_producer	Literal['', 'go', 'typescript', 'clang', 'python']	''	The compiler tier's producer; "" infers it from the tree's manifests (go.mod → go, tsconfig / package.json → typescript, a root CMakeLists.txt → clang, pyproject → python)
branches	list[str]	(computed)	More branches chosen at add time, each its own index sharing the mirror and inheriting rule, token and paths; per-branch refusals come back in skipped, never undoing the ones registered.

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
repo	str	Stable repository identity.
remote	str
provider	str
branch	str	The branch the new index follows.
join_policy	str	The join policy as registered (approval for a restricted repository).
classification	str	The classification as registered: standard or restricted.
index_stage	str	queued at creation; the worker moves it (see CodeRepoSummary.stage)
my_role	str	admin when the caller became the index's first maintainer; '' for a caller with no subject.
remote_head	str	The branch head SHA the remote answered with at add time.
also	list[dict[str, str]]	The other branches registered in the same call ({branch, namespace, remote_head})
skipped	list[dict[str, str]]	The extra branches refused, per branch {branch, reason}; the others stay registered.

code.repo.add_branch

Index another branch of a repository the caller maintains.

POST /v1/code.repo.add_branch · MCP loom_code_repo_add_branch · role admin · write · audited

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
branch	str	required	The branch to index as a new namespace; it must exist on the remote.

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
repo	str	Stable repository identity.
remote	str
provider	str
branch	str	The branch the new index follows.
join_policy	str	The join policy as registered (approval for a restricted repository).
classification	str	The classification as registered: standard or restricted.
index_stage	str	queued at creation; the worker moves it (see CodeRepoSummary.stage)
my_role	str	admin when the caller became the index's first maintainer; '' for a caller with no subject.
remote_head	str	The branch head SHA the remote answered with at add time.
also	list[dict[str, str]]	The other branches registered in the same call ({branch, namespace, remote_head})
skipped	list[dict[str, str]]	The extra branches refused, per branch {branch, reason}; the others stay registered.

code.repo.remote_branches

What a Git remote shows before anything is written — every branch with its head, the default branch, the ones that look like release branches, and the ones indexed here already — so the add dialog…

POST /v1/code.repo.remote_branches · MCP loom_code_repo_remote_branches · role viewer · read

Input field	Type	Default	Meaning
org	str	required	The org adding the repository.
repo	str	required	GitHub owner/name or an HTTPS/SSH Git URL.
access_token	str	''	Token for a private HTTPS remote; used once.
query	str	''	Case-insensitive substring of the branch name to match.
limit	int	60	How many matching branches to return (default 60).

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
repo	str	Stable repository identity.
remote	str
provider	str
warnings	list[str]
default_branch	str	The branch the remote reports as its default.
branches	list[dict[str, str]]	[{name, sha}] — default first, then release-shaped, then the rest
suggested	list[str]	release-shaped branches not indexed yet (26.8, release/1.2, stable-x)
indexed	list[dict[str, str]]	[{branch, namespace}] already indexed in this org
cap	int	how many more indexes the org may add (code_self_service_max_repos − active)
total	int	branches is the first limit matches of query over total heads (the default and the indexed ones always included); truncated says a search is needed to see the rest
matched	int	How many heads match query (all of them when it is empty).
truncated	bool	True when some matching heads are not in branches.
query	str	The filter as applied: trimmed and lower-cased; '' = no filter.

code.repo.remove

Retire a repository index a person added.

POST /v1/code.repo.remove · MCP loom_code_repo_remove · role admin · idempotent · audited

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
confirm	str	''	Must equal namespace, or the call is refused with CONFIRM_REQUIRED.

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
repo	str	The retired index's GitHub owner/name.
branch	str	The branch the retired index followed.
registry_deactivated	bool	True when the registry row went inactive by this call.
directory_deactivated	bool	True when the namespace's directory row was deleted.
purged_tables	int	How many code tables keyed by the namespace the erasure saga purges.
erasure_id	str	The erasure saga that purges them — follow it with erasure.status; erasure_recovery resumes it.
mirror_removed	bool	True when the bare mirror was deleted because no other branch of the repository uses it.
sources_deactivated	list[str]	The document sources registered on the namespace (knowledge.source.add), now inactive with their credentials cleared.

code.repo.set_access

A maintainer sets a repository's access — its classification (standard | restricted) and join policy (open | approval | closed).

POST /v1/code.repo.set_access · MCP loom_code_repo_set_access · role admin · idempotent · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
classification	str	required	standard or restricted (case-insensitive); anything else is BAD_CLASSIFICATION.
join_policy	str	required	open, approval or closed (case-insensitive); open with restricted is refused.
confirm	str	''	Must equal namespace when the call widens restricted to standard, which also needs an admin grant of the caller's own there (a copy that does not come from one of the repository's operator entries does not count); else unused.

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
repo	str	The repository's GitHub owner/name.
classification	str	The classification as written (lower-cased).
join_policy	str	The join policy as written (lower-cased).
previous_classification	str	The entry's classification before this call: restricted when either the entry, as this process last read it, or its directory row said so.
previous_join_policy	str	The directory row's join policy before this call (when it had none: open for a public entry, else approval).
directory_updated	bool	True when the namespace's directory row got the new access too, a branch added from the page with no row yet getting its first one; False for an operator entry with no directory row.
effective_within_s	int	every process re-reads the access row within this many seconds

code.repo.set_source

A maintainer sets the trackers this repository reads (records of issues, PRs, tests and incidents registered with tracker.source.add), in order.

POST /v1/code.repo.set_source · MCP loom_code_repo_set_source · role admin · idempotent · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
tracker_namespaces	list[str]	required	Tracker namespaces of this org, primary first (duplicates dropped; [] unlinks all); a new link needs the tracker's admin.

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
tracker_namespaces	list[str]	the links as written (primary first)
previous_tracker_namespaces	list[str]	The links before this call, primary first ([] = none).
effective_within_s	int	Seconds within which every process re-reads the links.
not_covering	list[str]	Linked trackers that do not list this repository (they read only the repositories they name, so they answer nothing here), and the sentence that says so
warning	str	One clause per not_covering tracker naming the repositories it reads, and one naming the registered branches that read these links too; '' when neither.

code.repos

Lists the code namespaces (repo@branch entries) configured on this deployment that the caller is authorized to read, across orgs — each row carries its org.

POST /v1/code.repos · MCP loom_code_repos · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
repo	str	''	A caller standing in one checkout (the plugin's code shunt, from the origin remote) names it, and the answer is that repository's entries only — one status read instead of one per configured repository.
repos	list[str]	(computed)	The checkout's remotes as ordered candidates (origin, upstream, then the rest; each owner/name or a URL, as repo).
fields	list[str] \| None	None	The output fields the caller reads (a whitelist resolved against the row model; an unknown name is a 422); unset, every field.

Output field	Type	Meaning
repos	list[CodeRepoSummary]	One row per entry the caller reads (plus unreadable rows an org admin may adopt), narrowed to the repo / repos match when either was given; [] when none.

code.review_brief

A merged PR's review brief: the point read of what the ingest built at merge — touched symbols with callers and fan-in, coverage verdicts, setting facts, regression history, blame of the deleted…

POST /v1/code.review_brief · MCP loom_code_review_brief · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
pr_files	dict[str, str]	(computed)	Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each).
pr_diff	str	''	The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes.
pr_head_sha	str	''	The PR's head and base commits as the caller knows them; they label the answer (overlay_head_sha) and never reach git. '' = derived from the text.
pr_base_sha	str	''
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
pr_number	int	0	The PR to brief; 0 = find it by merge_sha.
merge_sha	str	''	The PR's merge commit (hex, up to 40 chars); '' = find it by pr_number.
sections	list[Literal['paths', 'symbols', 'tests', 'settings', 'history', 'blame', 'qa', 'risk', 'do_not_flag', 'rationale']]	(computed)	Serve only these of the tier's sections; empty = every section the tier carries.
tier	Literal['trivial', 'standard', 'full']	'standard'	Which sections and default budget: trivial (paths, symbols), standard (+ tests, settings, history, risk, rationale) or full (+ blame, qa).
token_budget	int	0	Token budget for the served sections; 0 = the tier's (700 / 2,500 / 4,000).
store	bool	True	Whether a brief this call builds on a miss is stored for the next reader (the default).
open	bool	False	The PR is OPEN — brief its head (refs/pull/N/head on the mirror) diffed against its merge-base with the indexed branch, with the post-image overlay on the impact read (added functions are seeds).

Output field	Type	Meaning
pr_number	int	The PR the brief is of (from the stored brief when the request named only merge_sha).
merge_sha	str	The PR's merge commit; '' on an open brief or when no brief was found.
source	Literal['precomputed', 'built', 'built_from_mirror', 'missing']	precomputed (the ingest built it) | built (this call built it from the ledger's row) | built_from_mirror (no ledger row; the merge commit, title and files came from the mirror's first-parent chain and the reviewers from the tracker record)…
ledger	Literal['', 'present', 'absent']	what the ledger said: present (this build read its row) | absent (this or the stored build came from the mirror because the ledger had no row) | "" (not consulted: the ingest built the row)
stored	bool	True when this call built the brief and stored it
provenance	dict[str, Any]	A mirror-built brief's disclosure — source, ledger, merge_commit, files, title (qa | mirror), qa status, reviewers, author, has_test, is_backport_pr; {} for a ledger- or ingest-built brief
overlay	bool	On the wire only for open: true.
overlay_head_sha	str	The open PR's head the brief was read or built at; '' when the mirror lacks it.
overlay_added	int	Functions the open PR adds (the symbols section's via: added rows).
overlay_note	str	Why no open brief exists (head_not_in_mirror | no_merge_base | no_repo_entry); when one was served, '' or how many changed files its overlay did not fully read (a brief whose overlay left files unreached is not stored).
tier	str	The tier served.
built_at	str	When the brief was built (ISO-8601 UTC); '' when source is missing.
indexed_commit	str	The fast-tier watermark the brief was built against; '' when it was unread.
build_ms	int	How long building the brief took, in milliseconds (at build time, not this call).
tokens_used	int	Estimated tokens of the sections served.
token_budget	int	The budget the sections were cut to: the request's, else the tier's.
decisions	dict[str, bool]	one-bit answers read off the section verdicts: test_only, symbol_with_regressions, uncovered_symbol, randomized_setting, deleted_lines_blamed
sections	dict[str, dict[str, Any]]	name ->
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.scip_ingest

Accept one part of a SCIP index upload (compiler-tier symbols and references) for a batch.

POST /v1/code.scip_ingest · MCP loom_code_scip_ingest · role writer · idempotent · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
batch_id	str	required	The staging tables key on a UUID column: a malformed id is refused here, not by the insert.
seq	int	required	This part's position in the batch, 0-based (0 <= seq < total_parts).
total_parts	int	required	How many parts the batch has; capped by code_scip_max_parts.
commit_sha	str	''	The commit the index was built at; once applied it becomes the producer's tier watermark.
base_sha	str	''	The commit the delta was computed from; recorded on the batch row.
producer	str	''	The indexer that built the delta (scip-clang, scip-python, scip-typescript, scip-go); it picks the watermark key the batch advances, '' = the C++ key scip_commit.
payload	str	required	one part of the JSON-encoded ScipDelta
entry_lease_holder	str	''	The holder of the entry's lease the delta was built under (loom code entry-lock hands it to its command); when set, the part is refused unless that holder still holds the lease. '' = unfenced (CI pushes).

Output field	Type	Meaning
batch_id	str	The batch this part was stored under, as sent.
parts_received	int	Distinct parts of the batch stored so far.
total_parts	int	The batch's part count, as sent.
complete	bool	True once every part is stored; the apply worker then picks the batch up.

code.scip_status

Report the progress of a SCIP upload batch: parts received and apply status.

POST /v1/code.scip_status · MCP loom_code_scip_status · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
batch_id	str	required	The UUID the parts were uploaded under.

Output field	Type	Meaning
batch_id	str	The batch asked about.
status	str	pending | applied | failed
parts_received	int	Distinct parts of the batch stored so far.
total_parts	int	The batch's part count, as uploaded.
error	str	Why the apply failed (exception type and message); '' unless status is failed.
commit_sha	str	The commit the batch was built at.
applied_at	str	When the apply worker applied the batch; '' until then.

code.search

Search the shared code index of this repository (fresh to the last merged PR).

POST /v1/code.search · MCP loom_code_search · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
query	str	required	The question, identifier or phrase to search for; a symbol-shaped query tries the symbol table first (route says which path answered).
top_k	int	5	At most this many results per page (1-25).
token_budget	int \| None	None	Response budget in tokens; results are whole units, overflow elides.
path_prefix	str	''	Keep only units whose path starts with this prefix; "" = the whole namespace.
cursor	str	''	Continuation: the next_cursor of an earlier response to this query.
exclude_unit_ids	list[str]	(computed)	The caller's seen-set: unit ids not to serve again.
rerank	str	''	Reranker over the fused pool: "" = the deployment default (LOOM_CODE_SEARCH_RERANK_DEFAULT, for prose questions of its kinds), "none" = off for this request, "builtin:openai" / "builtin:cohere", or the name of an endpoint in…
expand	bool	False	Vocabulary bridge: one LLM hop proposes codebase identifiers for the lexical leg (natural-language wording often misses the implementing subsystem's vocabulary).
annotate	bool	True	Risk annotations + one-hop callee context per result (churn/amp/tested/ callees on each unit).
bodies	Literal['auto', 'none'] \| None	None	"auto" (default): granularity scales with budget-per-slot — cards when the budget can't fit any body (~<200 tok/slot), whole units in the normal range, and top hits expand toward their WHOLE FILE when the budget is generous. "none": cards…
kind_prior	Literal['off', 'default', 'flat', 'structural'] \| None	None	Chunk-kind prior override for A/B: None = the served "flat" table; "default" / "flat" pick a table, "structural" applies only the phrasing rule, "off" disables.
pr_leg_before	datetime \| None	None	Only PRs merged strictly before this instant may vote — the time-travel pin a bench mined from merged PRs needs so the fix PR cannot vote for its own files.
embedding_model	str	''	Bench-only override of the embedding_model label the legs read: "" = the deployment embedder's model name.
fresh	bool	False	true = bypass the served-response memo and compute.
min_fan_in	int	0	Symbol fan-in (loom.code_symbol_stats, weekly).
sort_by	Literal['score', 'fan_in']	'score'	"score" = ranked relevance order; "fan_in" = order the pool by fan_in, most-called first.
pattern	str	''	Constrained search: a literal (default) or RE2 regex that every returned chunk must contain — applied to BOTH legs' pools before ranking, so one call replaces grep-then-search.
regex	bool	False	true = pattern is an RE2 regex (an invalid one is a 422); false = a literal substring.
case_sensitive	bool	False	true = pattern matches case-sensitively; false (default) ignores case.
path_globs	list[str]	(computed)	Indexed-route file filters, rg -g / -t style: keep paths matching any glob (*.cpp, src/Parsers/), drop paths matching any exclude, restrict to a language's extension set (cpp, python, sql, ...).
exclude_globs	list[str]	(computed)	Drop paths matching any of these globs (same syntax as path_globs); at most 8.
langs	list[str]	(computed)	Keep only files of these languages by extension (cpp, c, python/py, js, ts, go, rust, java, sql, md, ...); an unknown name is a 422 listing the known ones.
legs	Literal['hybrid', 'lexical', 'vector'] \| None	None	Leg ablation for A/B: None/"hybrid" = both legs; "lexical" skips the vector leg AND the embedding call; "vector" skips the lexical leg.
track_path	str	''	Developer diagnostic, not exposed to the shunt: the path of the file the caller EXPECTED to see.
vector_model	str	''	Second vector model: the spec of an embedder the deployment lists in LOOM_CODE_SEARCH_VECTOR_MODELS.
vector_shortlist	int \| None	None	With vector_model set: > 0 = the second model shortlists this many chunk ids and the served model's vectors rescore them exactly; 0 = the second model's own distances rank the pool; None = the deployment's code_search_vector_shortlist.
llm_legs	Literal['auto', 'none'] \| None	None	none skips the model-backed legs — HyDE (an LLM passage, a second embed and a full scan) and a model-named concept source; auto (None = the deployment default, LOOM_CODE_SEARCH_LLM_LEGS_DEFAULT) runs what the deployment configures.
deadline_ms	int \| None	None	The request's wall-clock budget in ms, from arrival (values under 200 read as 200).
namespaces	list[str]	(computed)	Several namespaces at once: the single-namespace search runs once per entry, concurrently, and the rankings are interleaved by RANK in this order — scores are not comparable across namespaces (the lexical idf is per namespace).

Output field	Type	Meaning
results	list[CodeUnit]	The ranked units served on this page, cut to top_k and the token budget; empty on an abstain with no pool or a not-covered path.
route	str	symbol_exact | hybrid | symbol_miss_hybrid
next_cursor	str	Continuation: opaque cursor for the next page of the ranked pool, "" when nothing ranked remains past this page (symbol routes issue none). has_more mirrors it.
has_more	bool	true when next_cursor is set, i.e. more ranked results remain past this page.
history	dict[str, Any]	History section: {intent: number|phrase, numbers, items: [{number, kind, state, title, ...}], prs: [{pr_number, title, author, merged_at, files, files_total, role}], anchored: [{path, placed}], tokens}.
abstain	bool	true = the server does not stand behind these results (they may still be listed); abstain_code says why.
abstain_code	Literal['', 'no_match', 'below_threshold', 'low_calibrated_confidence', 'not_covered', 'pattern_too_broad', 'identifier_absent', 'off_domain']	Why it abstained: no_match (nothing survived) | below_threshold (top cosine under the abstain threshold) | low_calibrated_confidence | not_covered (path outside the index) | pattern_too_broad | identifier_absent (no file names it) |…
abstain_reason	str	Human-readable reason for the abstain, with what to do instead; "" when not abstaining.
retrieval_risk	Literal['low', 'medium', 'high', 'abstain']	Calibrated risk band from retrieval_confidence: low (>= 0.75), medium (>= 0.55), high, or abstain (below the abstain cut-off or the top cosine under its threshold).
retrieval_confidence	float	Calibrated confidence 0-1 from the top similarity, its margin over the second hit, route_agreement and the pool size; 0.0 on an abstain with no results.
route_agreement	float	Share (0-1) of the retrieval routes that ran and agreed: the primary hit, lexical and vector legs sharing a top-10 chunk, a fuzzy-symbol hit; 1.0 on an exact symbol hit.
calibration_explanation	str	The calibration inputs as text (top_similarity, margin, route_agreement, ...), plus the legs the answer ranked without past the deadline.
tokens_returned	int	Estimated tokens of the served page (results, history section and annotations).
constrained	bool	Constrained search: true when a pattern / path filter narrowed the pool; matched_files is the pre-count of files the constraint admits (0 when unconstrained or not counted).
matched_files	int	How many files the pattern / path constraint admits; 0 when unconstrained or not counted.
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS).
score_explanation	str	How the answer was reached as text: fusion kind and leg row counts, legs agreement, the constraint and matched_files, priors and history votes that applied.
retrieval_work	dict[str, int \| str]	Counters per stage, plus risk_source — "table" | "live" | "mixed": where the served risk block came from when the precomputed table is on.
trace_run_id	str	Id of the loom.code_search_trace row the server writes for this call.
top_similarity	float	Raw cosine of the top vector-leg hit (0.0 when the vector leg did not run or the route was symbol_exact).
tracked	dict[str, Any]	track_path diagnostic: {path, verdict, chunks, pool, best: {chunk_id, scope, start_line, lexical_rank, vector_rank, lex_score, distance, served_rank}, lexical_floor, vector_ceiling}.
fanout	dict[str, Any]	Fan-out disclosure: {namespaces, interleave: "rank", timeout_ms, per_namespace: {ns: {ms, results, abstain, route, commit, trace_run_id}}, dropped: [ns...]}.
note	str	e.g. "lexical only until embeddings finish (41% embedded)" while the namespace's vector leg covers less than LOOM_CODE_READY_EMBED_COVERAGE of its chunks (a first index still embedding, a backfill without --embed); "" otherwise.
legs_timed_out	list[str]	The legs the deadline (or the model-leg grace) dropped — their rows are not in the ranking — and epistemic "partial" then, or when a content leg failed (retrieval_work names it).
epistemic	Literal['', 'partial']	"partial" when a leg timed out or a content leg failed; off the wire otherwise.
partial	bool	deadline_ms cut something (a leg, rerank, a late stage): the page is the best found in the budget, and partial_reason names what did not finish.
partial_reason	str	What the deadline cut, as deadline N ms: <stage>; <stage>; off the wire otherwise.

code.setting_facts

One ClickHouse setting, the four places that define it: its declaration and tier (production / important / beta / experimental / obsolete), every default change with the release it shipped in…

POST /v1/code.setting_facts · MCP loom_code_setting_facts · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	required	The setting name as declared (max_threads); a name that cannot be a setting answers not_a_setting.
history_limit	int	10	At most this many default changes in history, newest release first (1..50).

Output field	Type	Meaning
name	str	The setting asked about, trimmed.
verdict	str	known | not_a_setting | unknown
causes	list[str]	control_failed | no_declaration | invalid_name | history_unread
declaration	dict[str, Any]	{file, line, type, default, description, tier, alias}
tier	str	The declaration's tier (production | important | beta | experimental | obsolete); '' without a declaration.
history	list[dict[str, Any]]	[{version, old, new, reason, line}], newest release first
randomized_in_ci	dict[str, Any]	{randomized, file, line, sampler, randomizer}
tests_total	int	test files under tests/ whose chunks name the setting (a floor)
control	dict[str, Any]	{setting, ok}: the positive control this call ran; ok=False ⇒ unknown
trace_run_id	str	Id of this call's trace row ('' for an invalid name); pass it to code.outcome.

code.symbol

Exact symbol lookup: definition, signature, doc comment, and body of a function/class/enum by (qualified) name — compiler-grade where available (tier='scip'), resolved across C++ overloads…

POST /v1/code.symbol · MCP loom_code_symbol · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	''	bare, qualified, or partially qualified name — or path:line ("src/Foo.cpp:123"), which resolves to the innermost function containing that line: a grep hit or review comment becomes the whole function in one call.
symbol_id	str	''	An index symbol id (a definition's unit_id, an edge's *_symbol_id); when set it wins over name and resolves exactly that definition.
include_body	bool	True	Read each definition's body; a 200+ line class ships its skeleton plus member outline instead.
include_history	bool	True	Attach recent_prs (merged PRs over the definitions' paths) to the first definition.
include_examples	bool	True	Attach examples (call sites that use the symbol) to the first definition.
include_lessons	bool	True	Attach lessons to the first definition: the memories linked to the symbol from lesson_namespaces (over MCP the caller's memory home by default) and the repository's team namespace, each with its code_state (fresh, moved, or…
lesson_namespaces	list[str]	(computed)	The memory namespaces whose linked memories lessons reads besides the repository's team rules (over MCP the caller's memory home by default); one the caller cannot read is skipped.
token_budget	int	2500	Estimated-token budget for the answer; definitions past it are served elided (signature, doc, pointer), and the uses_brief block is paid out of it first.
min_fan_in	int	0	Definitions carry fan_in when the weekly stats are enabled; min_fan_in drops the rest, sort_by='fan_in' puts the most-called definition of an overloaded/ambiguous name first.
sort_by	Literal['score', 'fan_in']	'score'	score keeps the resolver's order; fan_in puts the most-called definition first.
uses	bool \| None	None	uses=true returns the definition AND the lines that mention its bare name — what a separate code.grep on the name would return, read beside the definition from the same chunk index — minus the definition's own span(s).
uses_limit	int	50	At most this many uses lines (1–200) when uses is true.
uses_brief	bool	False	Serve the compact uses block when the lookup resolves to one definition; ignored when uses is true.
near_paths	list[str]	(computed)	When several definitions match, rank them by the change at hand — the files in near_paths (<= 20) or the merged PR's file list for pr_number from the ledger: same file, same directory, co-change in code_pr_history, then path distance.
pr_number	int	0	A merged PR whose file list (from the PR ledger) ranks several matching definitions; 0 = no PR ranking.
namespaces	list[str]	(computed)	Presence on several namespaces: presence: true runs the resolve once per entry of namespaces (at most 8; namespace, when set and absent, leads the list; unset list = the addressed namespace alone), concurrently under…
presence	bool	False	Answer per namespace in namespaces whether the definition is there (the presence / summary blocks) instead of returning definitions.
neighbours	bool \| None	None	The neighbours graph block for the resolved definitions themselves — k callers, callees, tests and citing documents per definition, in the same call.
neighbour_k	int	5	How many callers, callees, tests and citing documents (each) the neighbours block lists per definition.

Output field	Type	Meaning
definitions	list[CodeUnit]	The resolved definitions (at most 10), fitted to token_budget; empty when nothing resolved (see candidates) or on a presence answer.
ambiguous	bool	True when the served definitions carry more than one distinct name/signature pair.
hierarchy	dict[str, list[dict[str, Any]]]	For a class / interface / enum definition, its type hierarchy from the inherits edges of both tiers, folded by qualified name: {"supertypes": [...], "subtypes": [...]} of {symbol, kind, via (extends | implements), tier, confidence, path…
candidates	list[dict[str, Any]]	When nothing resolved: cheap fuzzy candidates (names + paths only).
tokens_returned	int	Estimated tokens of the answer: definitions, uses, cited documents, neighbours and hierarchy blocks together.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.
uses	list[dict[str, Any]] \| dict[str, Any]	uses=true: {path, line, text, scope, scope_start_line, scope_end_line, kind} per line mentioning the symbol's bare name, path/line ordered, the definition span(s) excluded.
uses_truncated	bool	True when the uses list stopped at uses_limit.
uses_tokens	int	Estimated tokens the compact uses block cost out of token_budget.
picked_by	str	Which context key ranked the definitions when near_paths / pr_number was given — same_file | same_dir | co_change | path_distance | none. "" and off the wire when no context was given.
resolved_by	str	anonymous_namespace | tail when an over-qualified name bound through symbol-form tolerance; "" and off the wire otherwise.
documented_in	list[dict[str, Any]]	The document sections that cite the definition (the Markdown lane's reads edges) — section qualified name, path, line; at most five distinct sections, first by confidence.
neighbours	list[dict[str, Any]]	The neighbours graph block on the definitions (one entry per definition anchor); empty unless neighbours ran.
anchors	int	How many definitions the neighbours block was built for; 0 when it is off.
neighbour_tokens	int	Estimated tokens the neighbours block cost (counted in tokens_returned).
presence	list[dict[str, Any]]	presence=true: one row per requested namespace, in request order — {namespace, verdict: present | absent | unknown, path, start_line, end_line, tier, indexed_commit, index_status, ms, reason, definitions}.
summary	dict[str, list[str]]	Presence summary: {present, absent, unknown} lists of namespaces; also filled from the entry's depends_on namespaces when the name is not defined here.

code.symbol_history

The regression history of one function: the merged PRs that touched it (with linked issues, reverts, inline review comments inside its span), and — through the tracker namespace bound to this code…

POST /v1/code.symbol_history · MCP loom_code_symbol_history · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
name	str	''	A qualified symbol name or path:line.
symbol_id	str	''	An index symbol id; wins over name.
limit	int	15	At most this many PR rows (1–60).

Output field	Type	Meaning
verdict	str	history | no_history | unknown
causes	list[str]	symbol_unresolved | symbol_ambiguous | tracker_unavailable
epistemic	str	Always lower_bound: the PRs are those the ledger holds over the definition's file.
symbol	dict[str, Any]	{qualified_name, path, start_line, end_line, tier}
ambiguous	bool	As on code.callers: the name resolved to several distinct definitions; no history was read, candidates are their qualified names (qualify the name or pass symbol_id).
candidates	list[str]	With ambiguous: up to 20 qualified names to pick from.
prs	list[dict[str, Any]]	newest first: {pr_number, title, author, merged_at, is_revert, is_fix, touches_symbol true|named|false|unknown, linked_issues[{number,title,state}], comments_on_symbol, qa{has_test, ci_result, first_release, caused[], names[]}}
review_comments	list[dict[str, Any]]	inline review comments inside the symbol's span, newest first (≤5)
open_issues_naming	list[dict[str, Any]]	open issues whose text names the function (QA), most severe first (≤5)
summary	dict[str, Any]	{prs_total, named_prs, fix_prs, named_fix_prs, reverts, caused_issues[], open_issues_naming, last_touched, oldest_in_window, authors[], note}
tracker_namespace	str	The tracker namespace that answered the QA side; "" when none is bound or its read failed.
tracker_unavailable	bool	True when a tracker is bound but its read failed.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.test_gate

The pre-PR question in one call: for THIS change, which tests must run, and which touched code no test reaches.

POST /v1/code.test_gate · MCP loom_code_test_gate · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
files	list[str]	(computed)	Changed file paths; a test file here is itself a test to run.
diff	str	''	A unified diff; its hunks (line spans, hunk-header names) pick the touched functions.
depth	int	2	Reverse-edge hops to look for tests through.
limit	int	30	At most this many rows in each of tests and untested (at most 200).

Output field	Type	Meaning
tests	list[dict[str, Any]]	{test_path, why, evidence, run, run_unknown, [src_path], [confidence], [hop]} why in {changed_test, stem_partner, test_map, graph_hop}, strongest first.
untested	list[dict[str, Any]]	Touched source symbols no test reaches by any evidence class: {qualified_name, path, start_line}.
changed_files	list[str]	The change as the gate saw it.
touched_symbols	list[dict[str, Any]]	The source symbols the change touches, {qualified_name, path, start_line, tier}, by path and line (first 200).
obligations	bool	True while either list is non-empty: run the tests, then rely on green; write a test for (or explain) the untested rows.
tests_total	int	Rows of tests before limit.
untested_total	int	Rows of untested before limit.
tests_capped	bool	True when limit cut tests short of tests_total.
untested_capped	bool	True when limit cut untested short of untested_total.
counts_floor	bool	Same epistemic contract as code.callers: the graph is a floor, so "no test reaches this" means none the index can see.
epistemic	str	Epistemic envelope, as on code.callers: "exact" when the compiler tier covers every seed file, no call site named like a seed was declined, and no override seed lacks its base; otherwise "lower_bound" with causes from {unresolved_calls…
causes	list[str]	Why epistemic is lower_bound (values above); [] when it is exact.
by_hop_counts	dict[int, int]	Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}.
trace_run_id	str	Id of this call's row in loom.code_search_trace.

code.test_home

Where does a new test case belong?

POST /v1/code.test_home · MCP loom_code_test_home · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
file_stems	list[str]	(computed)	Source file stems the change affects (a path or extension is stripped); matched in test content and against indexed source paths.
settings	list[str]	(computed)	Setting names the test uses (lower snake_case); others are dropped.
engine	str	''	The engine class (MergeTree; parameters stripped), matched as ENGINE = <name>.
symbols	list[str]	(computed)	Symbols the test exercises; the part after the last :: is what is matched.
limit	int	10	At most this many candidates (at most 50).

Output field	Type	Meaning
verdict	str	add_case_to | new_file_justified | unknown
home	str	The top candidate's path when the verdict is add_case_to; '' otherwise.
candidates	list[dict[str, Any]]	{path, matched: ["setting:x", "engine:MergeTree", …], map_confidence, score, reference: the candidate's indexed expectation file or null}
parts	list[str]	The fingerprint as normalized, kind:value per part (stem, setting, engine, symbol).
src_paths	list[str]	Indexed source files whose stem is one of file_stems (first 20).
next_free_stateless_number	int	The highest stateless test number in the index plus one; 0 when none was found.
control	dict[str, Any]	{symbol, ok}: the positive control this call ran; ok=False ⇒ unknown
trace_run_id	str	Id of this call's row in loom.code_search_trace.

code.tests_for

Which stateless tests carry EVERY named facet: the tests that SET a setting, call a function, create an ENGINE, read a system.* table, use a FORMAT, carry a -- Tags: tag, or expect an error…

POST /v1/code.tests_for · MCP loom_code_tests_for · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
facets	list[dict[str, str]]	required	{kind, name} per facet (kinds above; an unknown kind or an empty name is refused); duplicates are dropped.
limit	int	50	At most this many tests rows (at most 500).
closest	bool	False	closest: true answers "the existing test most like this one" instead of "the tests carrying every facet": candidates share at least one facet and rank by a weighted per-kind Jaccard over their whole facet sets; each row carries…

Output field	Type	Meaning
tests	list[dict[str, Any]]	{path, ordinals, lines, confidence, same_statement}, keyword-bound matches (confidence 1.0) before call-shaped ones (0.8), then by path; with closest: {path, similarity, shared, missing, extra_facets} by similarity descending.
total	int	matching tests before limit
truncated	bool	True when total exceeds the rows returned.
facets	list[dict[str, str]]	as resolved
verdict	str	'' when rows were returned; no_match when the namespace holds facet rows of every asked kind but none carry these names (an answer); not_covered when some asked kind has no row in the namespace at all (its lanes never wrote that kind…
abstain	bool	True only for not_covered (the index cannot answer; grep instead).
uncovered_kinds	list[str]	the kinds behind not_covered
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS), status.
tokens_returned	int	Estimated tokens of the returned paths (about 4 characters per token).
took_ms	int	Server time spent on the call, in milliseconds.
trace_run_id	str	Id of this call's row in loom.code_search_trace.

code.trace

Paste a stack trace / backtrace; get each frame resolved to its definition in one call — the incident-workflow entry point.

POST /v1/code.trace · MCP loom_code_trace · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
trace	str	required	The stack trace or backtrace text; qualified a::b names and C/C++ dir/file.cpp:N locations are read as frames (std::, boost::, absl::, __* frames skipped).
max_frames	int	15	Resolve at most this many distinct frames, in trace order (1..40).
token_budget	int	3000	Token budget for definitions (200..12000); units past it are dropped.

Output field	Type	Meaning
frames	list[dict[str, Any]]	One entry per recognized frame, trace order: {frame, qualified_name, path, line, symbol_id, resolved}.
definitions	list[CodeUnit]	The resolved definitions, whole units within token_budget.
tokens_returned	int	Estimated tokens of definitions.
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.verify

Verify one closed-form claim against the index and return a three-valued verdict.

POST /v1/code.verify · MCP loom_code_verify · role viewer · read

Input field	Type	Default	Meaning
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
kind	Literal['calls', 'unused', 'defines', 'contains', 'reaches']	required	The claim's shape: calls | unused | defines | contains | reaches (see above).
subject	str	required	What the claim is about: a symbol name, or a repo-relative path for defines/contains.
object	str	''	The claim's other end: a symbol, a literal (contains) or a path prefix (reaches); '' for unused.
depth	int	4	For calls and reaches: the most call hops the walk follows (1..6).

Output field	Type	Meaning
verdict	Literal['confirmed', 'refuted', 'not_established']	A subject or object that resolves no symbol is a RESOURCE_NOT_FOUND refusal, not a verdict; its detail carries role (subject | object) and did_you_mean, up to 5 of code.symbol's near misses {qualified_name, path, kind, tier…
reason	str	Machine-readable cause, stable for bots to branch on.
explanation	str	A human-readable account of how the verdict was reached.
evidence	list[dict[str, Any]]	Positive rows behind the verdict: edges (a call chain, in order), symbol rows, or content excerpts — shape depends on kind.
floors	dict[str, Any]	Why refutation was unavailable when the verdict is not_established: what was searched, how far, and which blind spots apply.
index_verdict	str	The index's own verdict behind a not_established claim ('' otherwise).
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.

code.verify_citations

Every citation a draft carries, resolved against the index before the draft is posted somewhere public and irreversible.

POST /v1/code.verify_citations · MCP loom_code_verify_citations · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
pr_files	dict[str, str]	(computed)	Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each).
pr_diff	str	''	The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes.
pr_head_sha	str	''	The PR's head and base commits as the caller knows them; they label the answer (overlay_head_sha) and never reach git. '' = derived from the text.
pr_base_sha	str	''
org	str	''	The tenant (first element of the identity tuple).
namespace	str	''	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
user_id	str	'-'	The end user the row belongs to; '-' for none.
consumer	str	''	trace attribution: which integration is calling (clickgap|claude-code|…)
text	str	required	The draft to check: a review comment, PR body or answer, as plain text or Markdown.
at_commit	str	''	The commit the draft was written against; '' = check against the index head only (or the PR's merge commit with pr_number).
pr_number	int	0	The reviewed PR; 0 = no PR-diff leg
base_namespace	str	''	Namespace read after the addressed one for citations it did not resolve; '' = the mirror's default-branch entry when the addressed one is a release branch.
limit	int	200	citations verified per call, first-appearance order; the rest are counted in truncated

Output field	Type	Meaning
verdict	str	all_resolved | has_unresolved | has_stale | no_citations.
counts	dict[str, int]	total, resolved, unresolved, stale, ambiguous, kind_ counts
citations	list[dict[str, Any]]	one per distinct citation, first-appearance order: {kind, text, verdict, reason, epistemic, occurrences, path?, start_line?, end_line?, number?, name?, rev?, form?, in_pr_diff?, in_code_block?, target?, candidates?}. form: basename |…
skipped	list[dict[str, Any]]	names not verified because their outermost scope is an external library (std::, boost::, …):
truncated	bool	True when the draft held more distinct citations than limit; the rest are unchecked.
epistemic	dict[str, str]	per check: path / number / name / commit -> exact; line -> lower_bound
at_commit	dict[str, Any]	{requested, sha, known, calls, capped, ms, error} — the mirror leg
pr_diff	dict[str, Any]	only with pr_number:
namespaces	list[str]	The namespaces read, in order: the addressed one, then the base one if any.
took_ms	int	Server-side wall time of the call, in milliseconds.
as_of	dict[str, Any]	Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS).
note	str	How far the checks can be trusted, plus why a leg was cut (unknown commit, capped mirror leg, PR not found, truncated citations).
trace_run_id	str	Id of this call's trace row; pass it to code.outcome.