Get a task by ID.

The response includes a board_hint field summarizing other active tasks in the same project so the agent can decide whether to call task_list() for coordination.

List tasks, optionally filtered by status, repo, or free-text query.

Use this to inspect project state before planning or mutating work. Pass query to search tasks by text within the active project.

Create one or more tasks on the active board.

For a single task, pass title directly. For multiple tasks, pass tasks as a list of entries (each with at least a title). Include acceptance criteria when you want downstream review to stay concrete.

Update task fields or transition task status.

Check the verification payload to confirm the requested changes were applied.

Delete a task permanently.

Fetch paginated execution events for a task.

Use include_payload=True to inspect full event data. Payloads are automatically truncated to keep responses bounded.

Wait for tasks to reach completion or target statuses.

Use this to gate dependent work or synchronize concurrent agents.

Start a managed or attached run for a task.

Creates the task worktree first if one does not already exist.

Cancel a task run and stop its active session.

Get the latest task and session status for a task.

When a session exists, also returns context window usage fields: context_window_used, context_window_size, usage_ratio, needs_compaction.

Detach from an interactive session and update task state.

Summarize runs, sessions, worktrees, and token usage for tasks.

Record the outcome of a plan step verification.

Call this after completing each major step in a task to signal whether the step passed or failed verification. verdict must be one of: PASS, FAIL, SKIP.

step_index is the 0-based position of the step in the plan. step_description is a short human-readable label for the step. reason is a one-line justification with evidence.

Returns dict with: task_id, session_id, step_index, step_description, verdict, reason, verified_at.

Return aggregated step verification results for a task.

If session_id is provided, only steps from that session are included.

Returns dict with: task_id, session_id, total, passed, failed, all_passed, steps (list of step dicts).

Create a git-tag checkpoint at the current worktree HEAD.

Captures the current HEAD commit of the task's worktree as a named checkpoint so the session can be rewound to this point later.

task_id is the ID of the task whose worktree to snapshot. step_index is a caller-assigned integer identifying this checkpoint (should be monotonically increasing within a session). description is an optional human-readable label for the checkpoint.

Returns dict with: task_id, session_id, step_index, commit_sha, tag_name, description, created_at.

List all checkpoints for the task's current session.

Returns checkpoints sorted by step_index (ascending). task_id is the ID of the task to query.

Returns dict with: task_id, session_id, checkpoints (list of checkpoint dicts).

Rewind the task's worktree to the commit captured at step_index.

Performs a hard reset of the worktree to the checkpoint's commit SHA. Any uncommitted changes and commits after the checkpoint are discarded.

task_id is the ID of the task to rewind. step_index identifies which checkpoint to restore.

Returns dict with: task_id, session_id, step_index, commit_sha.

Add a project insight for a task.

Insights are categorized observations extracted from agent sessions. Valid categories: pattern, error, architecture, preference, dependency. The insight is persisted as a TaskNote and will be surfaced in future task prompts alongside [LEARNING] notes.

List all insights recorded for a task.

Returns insights grouped by category with their content.

Remove an insight from a task by matching its content text.

Performs a case-insensitive exact content match. Returns removed=True if a matching insight was found and deleted, removed=False otherwise.

List all projects with repos inlined and active status.

Returns each project with its attached repositories and whether it is the currently active project.

Create a new project, optionally attach repos and set it active.

Args: name: Project name (required). repo_paths: Optional list of repository paths to attach. set_active: Whether to set this project as active (default True).

Update an existing project: set active, add repo, set default branch, or delete.

Args: project_id: The project to update (required). set_active: If True, set this project as the active project. add_repo_path: Path of a repository to attach. repo_id: Repository ID (required when setting default_branch). default_branch: New default branch for the repo identified by repo_id. delete: If True, delete the project and return early.

Approve or reject a review-ready task.

verdict must be "approve" or "reject". feedback is required when verdict is "reject" and ignored on "approve".

Merge an approved task into its base branch.

Start, continue, or abort a rebase of the task branch onto its base branch.

action must be "start", "continue", or "abort".

Return merge or rebase conflict details for a task.

Record a pass or fail verdict for a single acceptance criterion.

Call this once per criterion during review, BEFORE calling review_decide. verdict must be 'pass' or 'fail'. reason is a one-line justification.

Clear all AI review verdicts for a task. Call before starting a new review.

Read allowlisted runtime settings.

Update one allowlisted setting value.

Audit and preview a persona preset repository before import.

Returns trust assessment including:

• trust_tier: low_risk, medium_risk, or high_risk

• trust_score: 0.0-1.0 reputation score

• findings: security audit results

• personas: preview of available personas

Import persona presets from GitHub into Kagan.

Progressive trust behavior:

• Low risk: Auto-imported (with auto_confirm=True)

• Medium risk: Imported; trust assessment returned for review

• High risk: Requires acknowledge_risk=True flag

Export local persona presets to GitHub.

Manage trusted persona preset repositories.

Args: action: One of "list", "add", "remove". repo: Repository identifier (required for "add" and "remove").

List recent audit log entries.

Preview issues from a GitHub repository without importing.

Returns a list of issues matching the filters so the user can select which ones to import via integration_sync with issue_numbers.

Args: integration: Integration name (e.g. "github"). repo: Repository in owner/repo format. state: Issue state filter — "open", "closed", or "all". labels: Filter by labels (AND logic). limit: Maximum issues to fetch (1-500).

Sync external items from an integration source into the active project.

Imports issues from the specified repository as kagan tasks. Labels like priority:high on GitHub issues auto-map to task properties. Operation is idempotent — previously synced issues are skipped.

Args: integration: Integration to sync (e.g. "github"). repo: Repository in owner/repo format. state: Issue state filter — "open", "closed", or "all". labels: Only sync issues with ALL of these labels. limit: Maximum issues to fetch (1-500). issue_numbers: Import only these specific issue numbers.

Check whether an integration's external dependencies are satisfied.

Returns pass/warn/fail checks for the requested integration (or all integrations). For github: verifies gh CLI is installed and authenticated.

Args: integration: Integration to check. If omitted, checks all enabled integrations.

Per-backend session stats: count, success rate, avg duration, retry rate.

Daily session counts by status over a given period.

Export combined analytics (backend stats + session timeline) as JSON.

Read a file from disk and return its content as text.

Returns: {"path", "content", "eol_style", "has_bom", "encoding"}.

Write content to a file, creating or overwriting it.

Use this for new files or full rewrites. Does not preserve existing BOM or EOL style — use fs_edit_file for that.

Returns: {"path", "bytes_written", "bom_preserved", "eol_style"}.

Apply one or more old→new text replacements to an existing file.

Preserves the file's original BOM and line-ending style (CRLF/LF). Each edit must supply "old_text" (unique substring) and "new_text".

Returns: {"path", "bytes_written", "bom_preserved", "eol_style"}.

Raises on: empty old_text, text not found, duplicate matches, overlapping edits, replacement produces identical content.

Execute a shell command and return its combined output.

Streams each stdout/stderr line as a tool_execution_update event on the per-task event stream when a task context is available (i.e. the server was started with a bound session_id linked to a task).

Parameters

command: Shell command string (passed to /bin/sh -c or cmd.exe /c). cwd: Working directory. Defaults to the server process cwd. timeout: Wall-clock timeout in seconds (default 300). Pass null for no limit (use with care on long-running commands).

Returns

{"output": str, "exit_code": int, "timed_out": bool}

Run a long-running terminal command and stream its output.

Designed for commands that produce output over time: test runners, build pipelines, or any program that writes incrementally to stdout.

Each output line is forwarded as a tool_execution_update event on the per-task event stream when a task context is available, allowing clients to render partial output in real time.

Parameters

command: Shell command string (passed to /bin/sh -c or cmd.exe /c). cwd: Working directory. Defaults to the server process cwd. timeout: Wall-clock timeout in seconds (default 600 — 10 minutes). Pass null for no limit. max_output_lines: Maximum lines retained in the final output field. Lines beyond this limit are still forwarded to the event stream but are not included in the final return value.

Returns

{"output": str, "exit_code": int, "timed_out": bool}