Find past intents and decisions relevant to the current user request.

When to use:

• After you have done a quick initial exploration of the user's request and know which files are involved. Calling earlier with only a vague prompt gives weak results.

• To pull task-specific context instead of dumping all recent activity — preferred for large projects.

Inputs of note:

• prompt: the user request, in their words or your paraphrase.

• activeFiles (recommended): files you have identified as relevant to the request. Significantly improves relevance.

• maxIntents, maxDecisions, minRelevance: result-shaping caps and threshold.

Returns:

• relevantIntents: past work units (intents) related to the task, scored by relevance.

• relevantDecisions: prior decisions related to the task — both intent-scoped and repo-scoped. Summary-only (no inline rationale, to keep context lean); call get_decision_detail(decisionId) for the full rationale/context/consequences of any decision you want to open.

Recommended sequence:

1. check_active_intent at session start to resume any existing work.

2. Briefly explore the user's request to identify involved files.

3. get_relevant_context with the prompt and activeFiles to inform the approach.

REQUIRED: Call this tool BEFORE writing any code.

Returns THIS session's current intent (intent / hasActiveIntent) if one is set. If not, ask the user to confirm intent details and then call create_and_activate_intent.

Multi-active model: the active intent is PER SESSION. Many intents can be active on a repo at once — your current is independent of other sessions'/teammates'. The response also includes activeIntents: the repo's full active set (every session's current intent, with id/title/status/createdBy/author) for awareness and orchestration. hasActiveIntent reflects only YOUR session; activeIntents may be non-empty even when you have no current.

An active intent tracks what the user is working on, enabling:

• Better code context for AI-generated changes

• Conflict detection with team members

• Automatic assignment of code blocks to the intent

Status semantics:

• "active" — normal, in-progress. A stale intent simply stays "active"; the sweeper preserves its work without any status transition.

• terminal states — committed / pushed / done / abandoned / superseded.

Create a new intent from the user's request and mark it as active for THIS session.

Call this when check_active_intent returns no active intent for your session. Before calling:

1. Summarize what the user is asking for

2. Ask the user to confirm the intent details (title, description, type)

3. Then call this tool with the confirmed details

This ensures all AI-generated code gets properly tracked and attributed.

Multi-active model: many intents can be active on a repo at once (one per session/teammate). Creating + activating one only sets YOUR session's current focus — it never blocks or displaces another session's active intent, so there is no lock conflict to resolve.

If the tool returns conflicts (action="conflict"), it found an existing team-member intent that overlaps semantically or in files. Present the conflict details to the user and ask whether to proceed. If yes, retry with force=true to bypass conflict detection.

Activate an existing intent by ID — sets it as THIS session's current focus.

Use this to:

• Switch your current focus to a different intent found via list_team_intents or get_relevant_context

• Re-activate an intent that was deactivated (e.g., to complete it)

• Resume work on a previously created intent

• Resume an "abandoned" intent (see below)

Accepts both cloud IDs (from get_relevant_context / API) and local UUIDs (from list_team_intents).

Multi-active model: activating an intent only moves YOUR session's current pointer. Many intents can be active on a repo at once (one current per session/teammate), so this never blocks on or displaces another session's active intent — there is no lock to take over.

Resuming abandoned intents:

• Abandoned intents have their decisions soft-deleted (invisible to recall and get_relevant_context). Activating one transparently restores them — single-intent decisions for this intent get their soft-delete cleared so the prior reasoning becomes visible again. Multi-intent decisions stay visible throughout (they were never soft-deleted).

Get all intents that have code blocks in this file.

Use this before modifying a file to:

• See what work is already in progress

• Identify potential conflicts with team members

• Understand the context of existing code changes

Returns intent details including author, status, and specific line ranges.

Get intents covering a specific line range.

Use this before modifying specific lines to check for conflicts:

• Warns if the lines overlap with another team member's active intent

• Shows the exact overlap range

• Helps avoid merge conflicts and duplicate work

Returns overlap details so you can work around or coordinate with team members.

List intents from team members for this repository.

Use this to:

• See what your team is working on

• Check for potential overlapping work before starting a new task

• Review the status of various features/refactors in progress

Filtering (status, author, date range) and pagination are applied server-side across the full result set (default: 50 per page; use limit/offset to page). count is the total number of matching intents, not just the returned page.

Get uncommitted changes in the repository along with the active intent info.

Use this tool before prompting the user about committing to show:

• The active intent title and description

• Number of modified, added, and untracked files

• Any warnings (e.g., pre-existing changes from before intent activation)

This helps you construct an informative commit prompt like: "You have uncommitted work on '[intent title]' (N files changed)..."

Mark the active intent as completed and clear it.

Call this after a successful git commit to:

1. Update the intent status (committed/pushed/done/abandoned)

2. Store the commit SHA for tracking

3. Clear the active intent so a new one can be started

Status values:

• "committed": Code is committed locally (default)

• "pushed": Code has been pushed to remote

• "done": Work is fully complete

• "abandoned": Work was discarded without committing

REQUIRED: Inspect the response after calling this tool. Three outcomes:

1. response.success === true: The task is complete. Briefly acknowledge the commit and — if response.committedDecisionCount > 0 — mention that N distilled architectural decisions were recorded for the intent. Do NOT enumerate the decisions inline; they're visible via the orchestration panel and via get_intent_decisions / get_relevant_context if the user wants details. If response.apiSyncDeferred === true, also mention that the API sync was deferred; the queued writes will replay on the next sync tick. If response.collisions is non-empty, a live collaborator's (HAI's) in-progress edits overlap the work you just completed — surface it as a coordination heads-up (who, and which files), naming response.collisions[].label and the files. It's advisory, not a failure; the completion still succeeded. If response.deferredConflicts is non-empty, the distillation produced N decisions that conflict with existing standards — the completion STILL SUCCEEDED (the commit landed: status flipped, code blocks captured). Those decisions are deferred: parked for a disposition in the Orchestration panel, where the user picks per decision: supersede the standard, keep both (records a "contradicts" edge for a deliberate divergence / false positive), or reject the distilled decision. Tell the user "N decision(s) need a disposition in the panel." There is NOTHING to retry — do NOT re-run complete_intent.

2. response.success === false AND response.reason === "transient-failure": The distiller LLM call or the conflict-check API call errored. The ephemerals are preserved (the bucket is intact), and the intent stays "active". Tell the user the failure stage (response.failedStage) and the underlying error, then suggest retrying once the issue clears, or abandoning if the failure persists.

3. In a non-interactive (autonomous) session: if response.deferredConflicts is non-empty, log it at INFO and continue — the commit already landed and the decisions await disposition in the panel. There is no blocking state.

Update an active intent's title, description, scope, or constraints.

Use this to reformulate an intent as understanding evolves during work. Intents are living documents — they should be updated to reflect what the work actually became, not left as the initial guess. Common triggers for reformulation:

• The real problem turned out to be different from the initial hypothesis

• Scope expanded or narrowed during investigation

• The approach changed after discovering constraints

If no intentId is provided, the currently active intent is updated.

DEPRECATED — trivial changes (typos, one-line fixes, obvious bugs, doc updates, config changes) should skip the intent workflow entirely: just make the change and commit, no intent needed. Do not call this tool. Kept available for backwards compatibility only and will be removed in a future release.

Silently record a decision point during development.

Call this tool when you:

• Choose between multiple alternatives (type: fork)

• Try an approach that fails or is rejected (type: abandoned)

• Find unexpected behavior or limitations (type: discovery)

• Identify a hard constraint that must be respected (type: constraint)

• Make an explicit trade-off between competing concerns (type: tradeoff)

• Select an external library or dependency (type: dependency)

Decisions can be intent-scoped (tied to a specific work unit) or repo-scoped (general knowledge like discoveries and constraints). Omit intentId for repo-scoped decisions.

Decisions are accumulated silently during the session and presented for review before commit. This creates a "reasoning changelog" that captures not just what was done, but why.

IMPORTANT: Include constraintViolations when alternatives are rejected due to architectural constraints.

Get all decisions recorded in the current session for an intent.

Use this before committing to review what decisions were captured during development. Decisions are presented for user review and can be edited or removed before being persisted.

Returns:

• intentId: The intent these decisions belong to

• decisions: Array of decision points (summary-only — call get_decision_detail(decisionId) for full rationale/context/consequences/alternatives)

• count: Number of decisions recorded

Get all decisions recorded for a project across all intents.

Use this to review the project's decision history:

• See what architectural decisions have been made

• Understand past trade-offs and their rationale

• Find decisions affecting specific files

• Review constraint violations that were avoided

Returns:

• decisions: Array of decisions with their intent context

• count: Total number of decisions

Each decision includes (summary-only, to keep context lean — call get_decision_detail(decisionId) for full rationale/context/consequences/alternatives):

• intentIds: The intents this decision belongs to (array — a decision can span multiple intents)

• type: fork, abandoned, discovery, constraint, tradeoff, or dependency

• summary: Brief description of the decision

• relatedFiles: Files affected by this decision

• constraintViolations: Options that were rejected due to constraints

Expand one decision to its full detail.

Recall surfaces (get_relevant_context, get_project_decisions, get_session_decisions) return decisions summary-only to keep context lean. Use this to pull the full reasoning for a single decision you want to open — pay for detail only where you ask for it.

Inputs:

• decisionId: the decision to expand (the id / decisionId from a recall result).

Returns the decision's rationale, context, consequences, alternatives, symptom, appliesWhen, and related metadata. found: false when the id is unknown in this repo.

Edit or delete a decision in the current session.

Use this when reviewing decisions before commit:

• action: "update" - Modify the decision fields

• action: "delete" - Remove the decision entirely

Only ephemeral (in-flight) session decisions are editable. Once a decision is synced to Kawa Code, it is immutable — refine it instead by recording a new decision with supersedes: [<id>].

This allows users to curate their decision history before it's persisted.

Find intents from other team members that potentially conflict with the active intent.

When to use:

• Before committing, to surface overlapping team work so the user can coordinate before merging.

Inputs of note:

• intentId: the active intent to check against.

• minScore (optional): minimum match score to include in results.

Returns scored conflict candidates with:

• score: how strongly the candidate matches (higher = more likely conflict).

• overlappingFiles: files affected by both intents.

• decisions: decisions attached to the conflicting intent.

• author: who is working on the conflicting intent.

The list is informational — review candidates and their decisions to decide whether coordination is needed.

Analyze a repository's git commit history and produce structured development knowledge (intents and decisions) for the repo.

When to use:

• To bootstrap a repository that has no recorded intents/decisions yet.

• To extend coverage for new commits since the last run (resumes automatically when no commits value is provided).

Inputs of note:

• estimateOnly (default true): returns a token/cost estimate without running. Call with estimateOnly: true first to preview cost, then re-call with estimateOnly: false to run.

• commits (optional): how many recent commits to analyze. Omit to resume from where the last run stopped (or fall back to a sensible default on first run).

• commitRange (optional): git revspec selecting a specific window — "sha1..sha2", "branch1..branch2", "sha1^!" for a single commit. Mutually exclusive with commits. Useful for recovering from dropped batches or backfilling specific PRs / branches without re-running the full history.

• contextIssues: include PR/MR descriptions and issue discussions when an authenticated forge CLI (gh or glab) is available; auto-skipped otherwise.

• allowCommitSplitting: enable when commit history is messy and a single commit may cover unrelated changes.

• model, maxStories: Anthropic model and per-run cap.

• force (default false): override the re-run guard (see Behavior).

Behavior:

• A run is asynchronous — returns immediately with a started/pending status; progress is reported separately.

• Results are persisted as intents and decisions for the repo on completion.

• If interrupted, re-running resumes from where it left off.

• Re-run guard: a clean incremental resume runs automatically. But if the repo already has intents and the run cannot cleanly resume (missing/unreachable cursor), or HEAD is not on the default branch, the call STOPS and returns needsDecision instead of running — re-running blind there risks duplicate intents. Present the reason to the user and, if they confirm, re-call with force: true. Run on the default branch (main/master) whenever possible; inferring a feature branch is what force is for.

• GitHub and GitLab are supported; the forge is detected from the remote origin.

Curate a set of previously extracted stories so that only the decisions still worth keeping are persisted.

When to use:

• After running infer_history in story-only mode (rare — infer_history already chains this step automatically).

• When you have a pre-existing set of stories you want to re-curate without re-running history extraction.

Inputs:

• stories: array of story objects from a previous infer_history run.

• repoPath (optional): when provided, curated results are persisted as intents and decisions for the repo after curation finishes.

• model (optional): Anthropic model used for the curation pass.

Behavior:

• Runs asynchronously — returns immediately with a started/pending status while progress is reported separately.

Update the project's feature catalog from its recorded intents.

Additively groups any intents that are not yet assigned to a feature into the running catalog (an incremental "extend"), without disturbing existing features. The feature catalog is the high-level "what does this project actually do?" view, derived from the repo's intents.

When to use:

• After recording or completing intents, to keep the feature list current.

• On demand, when you want the catalog refreshed with recent work.

Behavior:

• Additive only — never deletes or re-derives existing features.

• Intents already assigned to a feature are skipped; only unassigned ones are processed.

• Runs in the Kawa Code desktop app and returns the resulting feature count.

Check whether the line range about to be edited has prior recorded reasoning attached.

Call this BEFORE editing code in a kawa-indexed repo. Surfaces:

• Tier 1a — overlapping intents whose blocks cover these lines (line-precise team coordination + intent-scoped decisions)

• Tier 1b — repo decisions whose relatedFiles include this file (file-coarse, catches infer_history-extracted constraints)

(Live-collaborator code-collision awareness is no longer reported here — it now arrives once per turn at the Stop hook. This tool is purely the semantic, decision-based check.)

Decisions already overridden via record_decision(supersedes=...) are filtered out automatically.

Recommendation maps to action:

• "proceed" — nothing relevant; safe to edit

• "review" — surfaced context worth inspecting before editing

• "investigate-upstream" — prior constraint or abandoned approach matches; don't proceed without reading the rationale and either revising the change or recording a new fork decision that supersedes the old one

Also returns the smallest enclosing function/method symbol via tree-sitter (Rust/TS/JS/Python only; null for other languages) for warning readability.

Mark decisions as consciously overridden for the rest of this session.

Phase 3's PreToolUse hook calls this when the agent passes force: true on an Edit tool call to bypass a pre_edit_decision_check block. Adds the surfaced decision IDs to an in-memory session cache; subsequent pre_edit_decision_check fires filter those IDs out so the same block doesn't re-fire.

The cache resets when the MCP server process exits (= the agent session ends). For persistent override across sessions, record a fork decision via record_decision(type: "fork", supersedes: [<id>]) instead.

Returns:

• acknowledged: number of newly-added IDs (existing IDs are deduped silently)

• cacheSize: total IDs currently in the session override cache

Resolve a live code collision with a peer BEFORE you write (Layer C resolution handoff).

Call this when the Stop hook's collision report (or complete_intent's resolution_required gate) surfaced a live peer (a teammate or AI agent editing the same lines). Pass that collision's uid as peerUid and its overlapping ranges. You get back:

• peerSnippet — the peer's actual (decrypted) code at the overlapping lines, so you can see what they wrote.

• decisions — recorded reasoning attached to this file (region context).

• guardrail — the policy you must follow when resolving: • Never overwrite a peer's COMMITTED work — yield or merge. Only override an uncommitted live diff, and only with a recorded rationale. • Your resolution is an ordinary git edit (revert/diff is the undo) — stay in your own working tree; build no bespoke undo. • Before completing, record_decision(type=fork|tradeoff, …) explaining how you resolved (and supersedes the peer's decision if you overrode it). • Choose or synthesize ONE coherent result — never blindly interleave both diffs.

This is advisory and proactive (no lock). Use it to adapt your edit and avoid the conflict.

Get Kawa Code's AI verdict for live code overlaps with peers — SUGGEST-ONLY, never writes. For each overlap ({peerUid, filePath, ranges} from the Stop collision report), Kawa decrypts the peer's version locally (zero-knowledge) and judges it compatible / auto_resolvable / conflict, with confidence, a perf/security risk read, and a tier (0 no-op · 1 trivially auto-appliable · 2 draft-and-confirm · 3 conflict). Use it to understand a forming conflict before acting. For a surfaced tier-2/3 overlap, call get_resolution_context to read the peer's actual code. To actually apply the safe tier, use arbiter_apply.

Resolve live code overlaps and AUTO-APPLY the safe tier. Kawa judges → adversarially verifies → and, for the trivial tier only (high-confidence single-range merge that passes verify), writes the merge to your worktree, records a decision, and republishes. Writes happen ONLY in an agent-owned worktree (a linked git worktree); on a human checkout — or when a peer holds the file-set lock — it behaves like arbiter_resolve (suggest-only, no writes). Returns per-overlap outcomes { tier, applied, announcement, verifyIssue?, verdict }. Call it when you are ready to incorporate the result, then RE-READ any file it applied to (it changed on disk). For surfaced (not-applied) overlaps, use get_resolution_context to see the peer code and resolve manually.