Kawa Code

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).

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.

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.

REQUIRED before writing any code. Returns this session's current intent; if there is none, confirm the details with the user and call create_and_activate_intent. Intents are active PER SESSION — many can be active on one repo at once. hasActiveIntent reflects only YOUR session, while activeIntents lists every session's current intent (yours and teammates') and may be non-empty when you have none. A stale intent stays "active"; terminal states are committed / pushed / done / abandoned / superseded.

Mark the active intent completed and clear it. Call after a successful git commit, passing commitSha so code blocks are captured. status: committed (default, local commit) | pushed | done | abandoned. You MUST inspect the response: - success === true — done. If committedDecisionCount > 0, say N decisions were recorded; do NOT list them. If apiSyncDeferred, say the sync was deferred and will replay. If collisions is non-empty, relay it as an advisory coordination heads-up (collisions[].label + files) — the completion still succeeded. If deferredConflicts is non-empty, the completion ALSO succeeded; say "N decision(s) need a disposition in the Kawa Code panel" and do NOT re-run this tool. - success === false && reason === "transient-failure" — the intent stays active and nothing was lost. Report failedStage plus the error; retry once the cause clears, or abandon if it persists. Autonomous sessions: deferredConflicts is not a blocking state — log and continue.

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.

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.

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.

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`, `surface`, and related metadata. `found: false` when the id is unknown in this repo. References come pre-resolved, so describe them by name and never by ID alone: - `supersededDecisions` — the supersession chain, nearest first. Each carries `summary` and a `depth` (1 = directly superseded by this decision, 2 = what *that* one superseded). Use `depth` to render the chain correctly: with two entries at depth 1 this decision replaced both, whereas depth 1 then 2 is a lineage. `supersededOlderCount` > 0 means older ancestors exist beyond the cap — say "+N older". - `intents` — the intent(s) that produced this decision, with titles.

Intents with code blocks in a file, so you can see in-progress work and team conflicts before editing. Pass startLine + endLine to narrow to a range; the result then reports the exact overlap and warns when it hits a teammate's active intent.

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

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.

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 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

One-time-ish bootstrap: mine a repo's git history into intents and decisions. Rare — use it to seed a repo that has no recorded history yet, or to extend coverage after many new commits. NOT part of the per-turn workflow. Costs real money and time, so it is a two-step call: run with estimateOnly (the default) to preview tokens/cost, show the user, then re-call with estimateOnly: false only if they agree. The run is asynchronous and reports progress in the Kawa Code app; it resumes automatically if interrupted. Re-run guard — do not defeat this casually. If the repo already has intents and the run cannot cleanly resume, or HEAD is not on the default branch, the call STOPS and returns needsDecision rather than running, because re-running blind risks duplicate intents. Show the user the reason and only re-call with force: true if they confirm. Prefer running on main/master. Omit commits to resume from the last run. See the README for the full parameter list.

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.

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.

Resume an existing intent by ID in one call — activate it AND load its recorded decisions. Use this to pick up a handoff. When a prompt says "follow up on intent <id>" (or you otherwise want to continue a specific existing intent), call resume_intent(<id>) instead of creating a new one. It: - activates the intent as THIS session's current focus (multi-active — never displaces a teammate's active intent), and - returns the intent's title/description/status plus its recorded decisions (summary-only; call get_decision_detail(id) for full rationale on any one). This is the fast path for cross-developer handoff without a session or transcript export: the reasoning lives in Kawa Code, so a teammate resumes the thread from just the intent id. For the code itself, the intent's owner should have committed or pushed first (a prompt carries reasoning, not an uncommitted working tree). Returns { resumed, intentId, intent?, decisions[], count, message }. resumed=false with a message when the id can't be activated.

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.