Call a tool by name with the given arguments.

Use this to execute tools discovered via search_tools.

Record a consultation for (source_session, workspace) and return the governing rules for the intent. Call before code/architectural work. trigger is 'explicit' (default: a deliberate consult, clears the gate) or 'prompt_hook' (an installer auto-consult: audited, never clears).

Retrieval is hard-filtered to the in-force class (active/accepted/ approved, within its validity window, and never a memory-inbox doc): an unreviewed proposed memory, a retired/superseded decision, an expired doc, or a legacy/forged inbox file is never returned as a governing rule.

pending_actions, when present, lists open maintenance items (missing status fields, recently-expired/expiring-soon docs); omitted when the corpus is clean. Surface it to the operator and act on it only with operator confirmation.

Return a verdict (allow | consult_required) for a pending code action. Governed actions require a fresh consultation on record. Records each check to the audit log (non-destructive; readOnlyHint=false is intentional). Use this in a PreToolUse hook to verify a specific pending action before execution; use kb_consult instead when proactively reading governing rules at the start of a session rather than checking individual actions.

Retrieve a document by id (STD-U-001, ADR-002, T-NNN, etc.). Returns the full content markdown plus metadata. Use this when you have a specific id (from kb_search results or session memory); use kb_search instead when you need to find a document by topic.

Always resolves regardless of expiry (ids never dangle): an expired document is still returned, with its full validity object and a computed freshness indicator (stale/expired/upcoming).

Derivation cues (ids only, for a person to review; nothing is filtered or demoted because of them): derived_from lists the documents this one draws from; derived_from_retired lists those that have left force, only while this document is itself in force; and dependents_to_review lists the in-force documents that derive from this one, only while this document is retired.

verbose: False (default) returns the full content_markdown body (kb_get exists to read the doc) with a trimmed envelope: path, git_remote_url, and last_modified_source are dropped and empty status/type/applies_when/description/validity/freshness are omitted; source_commit and last_modified provenance are kept, and in_force: false is emitted when the computed in-force predicate says the doc does NOT currently govern (deviation-only; an in-force doc omits the key). verbose=True returns the full legacy envelope with every field plus the computed in_force: bool (the single-sourced status + validity-window + not-inbox predicate; never stored in frontmatter).

Return service health: kb_commit, index_built_at, staleness, degraded flag, and write-side state (pending_count, push_queue_size, last_index_*).

verbose: False (default) returns a token-compact shape that keeps the core snapshot and OMITS diagnostic fields that are null/empty (e.g. last_index_error, remote_head_sha when unset). verbose=True returns every field including the nulls.

pending_actions, when present, lists open maintenance items (missing status fields, recently-expired/expiring-soon docs) computed at the last index build; it is omitted when the corpus is clean. Surface it to the operator and act on it only with operator confirmation.

Append a durable, non-destructive audit entry for a client-reported enforcement event. Requires write capability (not a read-only tool).

event_type is gate_bypass (agent proceeded despite a gate block) or gate_degraded (kb_gate_check was unavailable; last-known state used). workspace, agent_identity, source_session are required; reason is optional but recommended for gate_bypass entries.

Use this when an enforce hook bypassed or degraded the gate and the fallback must be recorded. To check gate status use kb_gate_check; to consult use kb_consult; to read back events use kb_audit or kb_compliance.

Full-text search across the KB.

Optional tier/category/status/type filters (status e.g. 'active', doc_type e.g. 'decision'). Returns ranked hits with snippets.

in_force: when true, HARD-filter to the in-force status class (active/accepted/approved) AND the validity window (not expired, not upcoming) before ranking, EXCLUDING superseded/deprecated/expired/ upcoming docs rather than only soft-downranking them. Composes with an explicit status (both must hold). Use this when you want only guidance that currently applies.

A doc past its valid_until date is EXCLUDED from every default search result (not just in_force=True): an expired doc has no named successor to outrank it, so left visible it could be the top hit and would govern. Set include_expired=true to see it anyway; it then carries freshness: "expired". A doc with a future valid_from ("upcoming") stays visible in default search, flagged freshness: "upcoming"; only in_force=true excludes it. validity_state is an audit-query facet: one of "expired", "stale", or "expiring_within:N" (N days) to list docs by validity condition; filtering for "expired" implies including them regardless of include_expired. "stale" here matches only recheck_by in the past -- narrower than the per-hit freshness: "stale" a hit can otherwise carry from verification age (see KB_REVIEW_DUE_AFTER_DAYS); use kb_curate to list every document currently showing freshness: "stale" for either reason.

abstain: when true, apply the signal gate. If the query matches no discriminating column (title/tags/applies_when) it is treated as out-of-scope and the search returns NO hits with abstained: true and an abstain_reason, instead of surfacing a weak keyword match. A query with a real signal retrieves normally. Distinguish abstained: true (no governing rule) from an ordinary empty result (abstained: false).

verbose: False (default) returns a token-compact shape. Each hit is {id, title, snippet} plus status only when a hit is NOT in-force (superseded/deprecated), type when set, and freshness only when a hit deviates (stale/expired/upcoming); the query echo, per-hit path, and score are dropped (fetch a hit's full metadata with kb_get(id); array order conveys rank). A compact hit additionally carries in_force: false when the computed in-force predicate (the single-sourced status + validity-window + not-inbox rule; never stored in frontmatter) says the doc does NOT currently govern -- emitted deviation-only, so an in-force hit's compact shape is unchanged. verbose=True restores the full legacy shape with query, path, score, status, type, freshness, and the computed in_force: bool on every hit, so a hit retrieved WITHOUT in_force=true can still be checked for whether it may govern now.

Read-only per-session write summary (issue #112 feedback loop): N committed, M demoted-to-pending, K rejected for source_session. Call this (or kb pending) whenever a write response indicated a demotion, to confirm the current tally before informing the operator.

Search for tools using natural language.

Returns matching tool definitions ranked by relevance, in the same format as list_tools.