docs(session): correct DefaultSessionDir convention comment

- Stale comment showed ~/.kit/sessions/--<cwd-path>--/ which does not match the actual encoding (no leading/trailing dashes) - Update to reflect the real format and point to encodeCwdForDir for full rules
fix(session): strip illegal characters from windows session dir (#18 )
2026-06-14 03:30:26 +00:00 · 2026-05-05 14:54:20 +03:00 · 2026-05-05 14:46:36 +03:00 · 2026-05-04 19:30:15 +03:00 · 2026-05-04 17:06:11 +03:00 · 2026-05-04 17:01:47 +03:00
30 changed files with 2256 additions and 172 deletions
@@ -13,8 +13,6 @@
 // - No channels in maps (Yaegi panics on range over map[string]chan)
 // - All ctx.* calls guarded with nil checks
 // - Simple data structures only
-// - The extension runner serializes handler calls per-extension, so
-//   concurrent subagent events cannot race on this shared state.
 package main

 import (
@@ -45,8 +43,7 @@ const (
 )

 // ---------------------------------------------------------------------------
-// Package-level state — safe because the runner serializes all handler
-// invocations for the same extension (per-extension reentrant mutex).
+// Package-level state - all simple types
 // ---------------------------------------------------------------------------

 var (
@@ -285,8 +282,8 @@ func Init(api ext.API) {

 		submonPushWidget()

-		// Remove the entry — build a new slice to avoid aliasing bugs
-		newEntries := make([]*submonEntry, 0, len(submonEntries))
+		// Remove the entry immediately (no goroutine to avoid races)
+		newEntries := submonEntries[:0]
 		for _, en := range submonEntries {
 			if en.callID != e.ToolCallID {
 				newEntries = append(newEntries, en)
@@ -0,0 +1,47 @@
+---
+description: Open a GitHub PR for the current branch using the repo's PR template
+---
+
+Open a GitHub pull request for the current branch, filling out the repository's PR template with a description grounded in the actual commits and diff.
+
+## Steps
+
+1. **Verify the branch is pushed**:
+   - `git status -sb` and `git log @{u}..HEAD --oneline 2>/dev/null` — if there is no upstream or unpushed commits, run `git push -u origin "$(git branch --show-current)"` first
+   - If the working tree is dirty, stop and tell the user to commit first (suggest `/commit-push`)
+2. **Gather context**:
+   - `git log origin/main..HEAD --oneline` — list of commits going into the PR
+   - `git diff origin/main...HEAD --stat` then `git diff origin/main...HEAD` — read the actual changes
+   - Identify the linked issue (from commit messages, branch name, or extra user input: $@) — capture as `Fixes #N` if applicable
+3. **Locate the PR template**:
+   - Check `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, or `docs/pull_request_template.md`
+   - If none exists, use a minimal `## Description` / `## Type of Change` / `## Checklist` structure
+4. **Draft the PR body** by filling out the template:
+   - **Description**: 1–3 short paragraphs explaining *what* changed and *why*, grounded in the diff. Include a brief before/after example for new APIs when useful.
+   - **Fixes #N**: only if there is a real linked issue
+   - **Type of Change**: tick the single most accurate box with `[x]` (leave others as `[ ]`)
+   - **Checklist**: tick items that are genuinely true (style, self-review, tests added, docs updated)
+   - **Additional Information**: bullet list of added / modified files and any backward-compatibility notes
+   - Remove template sections explicitly marked "remove if not applicable" (e.g. MCP Spec Compliance) when they don't apply
+5. **Write the body to a temp file**: `/tmp/pr-body-<branch-or-issue>.md` — never inline a long body via `--body`, always use `--body-file`
+6. **Choose the title**: prefer the subject of the primary commit if it already follows Conventional Commits; otherwise craft one in the same style (`<type>(<scope>): <imperative summary>`, ≤72 chars)
+7. **Create the PR**:
+   ```
+   gh pr create \
+     --title "<title>" \
+     --body-file /tmp/pr-body-<...>.md \
+     --base main \
+     --head "$(git branch --show-current)"
+   ```
+   Use the repo's actual default branch if it isn't `main` (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`)
+8. **Report the PR URL** returned by `gh` and stop
+
+## Guidelines
+
+- Read the diff and commit messages — do **not** invent features that aren't in the code
+- One PR per logical change; if the branch contains unrelated commits, surface that and ask before continuing
+- Keep the description focused on reviewer-relevant information (what / why), not a replay of the diff
+- Only check checklist boxes that are actually satisfied; leave the rest unchecked rather than lying
+- If `gh` is not authenticated (`gh auth status` fails), stop and tell the user
+
+$@
@@ -2,7 +2,7 @@
 description: Create a feature request using the GitHub template
 ---

-Create a feature request for the Kit repository. The user wants to request: $+
+Create a feature request for the Kit repository. The user wants to request: $@

 ## Feature Request Template

@@ -16,7 +16,7 @@ This prompt uses the `feature_request` GitHub template which requires:

 ## Steps

-1. **Understand the request** from `$+`
+1. **Understand the request** from the user input: $@
   - What capability is missing?
   - What would the ideal behavior look like?

@@ -2,7 +2,7 @@
 description: File a GitHub issue using the appropriate template
 ---

-File a GitHub issue for the Kit repository. The user wants to create an issue about: $+
+File a GitHub issue for the Kit repository. The user wants to create an issue about: $@

 ## Issue Templates Available

@@ -16,7 +16,7 @@ This repository has structured issue templates. You MUST use the appropriate tem

 ## Steps

-1. **Determine the issue type** from `$+`:
+1. **Determine the issue type** from the user input: $@
   - Bug → use `--template bug_report`
   - Feature → use `--template feature_request`  
   - Documentation → use `--template documentation`
@@ -0,0 +1,61 @@
+---
+description: Implement the fix/feature/docs change requested by a GitHub issue
+---
+
+Resolve GitHub issue #$1 by reading it, classifying it, and producing the appropriate code or doc change. **Stop once the working tree contains the change** — committing, pushing, and opening a PR are handled by `/commit-push` and `/create-pr`.
+
+## Steps
+
+1. **Fetch the issue**:
+   - Run: gh issue view $1 --json number,title,body,labels,state,author,comments
+   - If the issue is closed, stop and ask the user whether to proceed
+   - Read the **entire** thread including comments — the latest comment often refines the ask
+
+2. **Classify the issue** from labels, title prefix, and body content:
+   - `bug` / `fix:` → reproduce, then fix
+   - `enhancement` / `feature` / `feat:` → design, then implement
+   - `documentation` / `docs:` → locate and update docs
+   - `question` / `discussion` → answer in a comment, do **not** write code
+   - Anything else → ask the user how to proceed
+
+3. **Create a working branch** off the default branch:
+   - `git checkout main && git pull --ff-only`
+   - Branch name: <type>/$1-<slug> (e.g. `fix/42-borderColor-ignored`, `feat/57-keyboard-clear`, `docs/63-widget-lifecycle`)
+
+4. **Do the work** based on type:
+
+   ### Bug (`bug` label / `fix:` title)
+   - Reproduce the failure first (write a failing test if feasible) — if you cannot reproduce, comment on the issue asking for clarification and stop
+   - Locate the root cause; do not patch symptoms
+   - Add or extend a regression test that fails before and passes after the fix
+   - Run `go test ./... -race` and `golangci-lint run`
+
+   ### Feature (`enhancement` / `feature` label / `feat:` title)
+   - Re-read the motivation and proposed implementation in the issue body
+   - For large, ambiguous, or breaking changes, sketch the design in a comment on the issue and wait for sign-off before writing code
+   - Implement behind sensible defaults; add godoc on every exported symbol
+   - Add unit tests covering the new behaviour and edge cases
+   - Update `README.md` / `docs/` if the public surface changed
+   - Run `go test ./... -race` and `golangci-lint run`
+
+   ### Documentation (`documentation` label / `docs:` title)
+   - Open the file/URL referenced in the issue's "Documentation Location"
+   - Apply the suggested improvement; verify code samples compile (`go build ./...`)
+   - No tests required, but run `golangci-lint run` if Go files were touched
+
+5. **Report**:
+   - Branch name (`git branch --show-current`)
+   - Summary of files changed (`git status -s`) and the diff highlights
+   - Test/lint results (pass/fail with key output)
+   - Suggest the next step explicitly:
+     - `/commit-push` to commit with a Conventional Commit subject (the message should reference `(#$1)` and include `Fixes #$1` so merge auto-closes)
+     - then `/create-pr $1` to open the pull request
+
+## Guidelines
+
+- This prompt **stops at a clean working tree with the change applied** — do not run `git commit`, `git push`, or `gh pr create`
+- If the issue is unclear, post a clarifying comment on the issue and stop; do not guess
+- Keep the change scoped to the issue; surface unrelated cleanups separately
+- For breaking changes or architecture shifts, propose the design on the issue first and wait for maintainer sign-off
+- If the issue is a duplicate or already fixed on `main`, comment with the reference and stop
+- Do not close the issue manually — the eventual PR's `Fixes #$1` handles that on merge
@@ -2,7 +2,7 @@
 description: Scaffold a new prompt template in .kit/prompts/
 ---

-Create a new kit prompt template. The user wants a prompt that does: $+
+Create a new kit prompt template. The user wants a prompt that does: $@

 ## What a prompt template is

@@ -16,30 +16,64 @@ It becomes a `/slug` slash command in the kit input box — typed as `/filename`
 description: One-line description shown in autocomplete
 ---

-Body text of the prompt. Use $@ for all user-supplied arguments,
-$1 $2 etc. for positional arguments.
+Body text of the prompt. Reference user-supplied arguments
+with positional placeholders (see "Argument placeholders" below).
 ```

 - **Filename** → slug: `commit-push.md` becomes `/commit-push`
 - **Frontmatter**: only `description` is recognised; keep it under ~80 chars
 - **Body**: plain markdown; the full text is submitted as the user's message when the template fires
- **Arguments**: `$+` expands to everything the user typed after the slash command name
-  (requires at least one argument); `$@` is the same but allows zero arguments;
-  `$1`, `$2` for individual positional args; omit entirely if no arguments are needed
+- **Required args**: kit infers required positional args from the highest `$N` it finds *outside* backtick/tilde code fences — a stray `$2` in active prose means kit will refuse to run without 2 arguments
+
+## Argument placeholders
+
+kit performs shell-style substitution before sending the prompt to the model:
+
+- `$1`, `$2`, … — positional arguments (1-indexed)
+- `${1}`, `${2}`, … — same, brace form (use when followed by digits/letters: `${1}_suffix`)
+- `$@` — all arguments joined by spaces (zero or more, optional)
+- `$+` — all arguments, **at least one required**
+- `$ARGUMENTS` / `${ARGUMENTS}` — alias for `$@`
+- `${@:N}` — args from the Nth onwards (1-indexed, bash-style)
+- `${@:N:L}` — `L` args starting from the Nth
+
+### ⚠️ Critical: code fences and inline code preserve placeholders verbatim
+
+Anything inside triple-backtick fences, `~~~` fences, or single-backtick `inline` code spans is **left untouched** so example code samples don't get corrupted. That means:
+
+- An inline-coded `gh issue view $1` stays literal `$1` in the model's input ❌
+- The same command without backticks: gh issue view $1 → expands to `gh issue view 42` ✓
+
+**Rule of thumb:** if you want a placeholder to substitute, keep it outside backticks and fences. If you want a literal `$1` in the output (e.g. teaching the user shell syntax), put it inside backticks.
+
+### Workarounds for "I want it to look like code AND substitute"
+
+1. **Drop the backticks** around just the placeholder portion — the rest can still read as a command line in prose
+2. **Use a 4-space-indented code block** instead of a triple-backtick fence — kit only skips backtick/tilde fences, so indentation-style code blocks still get substitution:
+
+       git push -u origin "$(git branch --show-current)"
+       gh pr create --title "fix: ... (#$1)" --base main
+
+3. **Bind once, reference loosely**: put `Issue: $1` at the top in prose, then leave the backticked examples literal — the model will substitute mentally

 ## Steps

-1. **Understand the workflow** the user described in `$+` — ask a clarifying question if the intent is ambiguous
+1. **Understand the workflow** the user described in $@ — ask a clarifying question if the intent is ambiguous
 2. **Choose a filename**: short, lowercase, hyphen-separated, descriptive (e.g. `code-review.md`)
 3. **Write the description**: one sentence, imperative, fits in autocomplete
-4. **Draft the body**:
-   - Open with a single sentence stating the goal
+4. **Decide on arguments**:
+   - No args needed → omit placeholders entirely
+   - One required value (issue number, PR url, file path) → use `$1`
+   - Free-form trailing context → end with a single `$@` line
+   - Multiple distinct values → use `$1`, `$2`, … and document each at the top
+5. **Draft the body**:
+   - Open with a single sentence stating the goal, weaving in `$1`/`$@` where the value belongs
   - Use `## Steps` for multi-step workflows; use plain prose for simple prompts
   - Be specific: name commands, flags, and file paths where relevant
-   - End with `$+` on its own line if the user must pass context; use `$@` if arguments
-     are optional; omit if the prompt is self-contained
-5. **Write the file** to `.kit/prompts/<slug>.md`
-6. **Confirm** by showing the final file content and the slash command that activates it
+   - **Audit every backtick and code fence**: any `$N` or `$@` inside them will not expand — was that intentional? If not, apply one of the workarounds above
+6. **Write the file** to `.kit/prompts/<slug>.md`
+7. **Verify substitution** by mentally (or actually) replacing `$1`/`$@` with a sample value and confirming every reference resolves — and that the prompt's *own* example snippets don't accidentally bump the required-arg count (wrap illustrative `$N` examples in triple-backtick fences, not 4-space indentation, so `RequiredArgs()` ignores them)
+8. **Confirm** by showing the final file content and the slash command that activates it (e.g. `/code-review 42`)

 ## Guidelines

@@ -47,3 +81,4 @@ $1 $2 etc. for positional arguments.
 - Prefer concrete steps over vague instructions
 - A prompt that does one thing well beats one that tries to cover every edge case
 - If the workflow already exists as a prompt, suggest extending it instead of duplicating
+- When in doubt about substitution behaviour, write the file and run `/<slug> testvalue` once to confirm — wrong placement of backticks is the #1 failure mode
@@ -0,0 +1,52 @@
+---
+description: Audit and update project documentation (README and docs site) for a recent change
+---
+
+Review recent code changes, identify all documentation surfaces that should
+mention them, and update each one — grounded in the actual diff, not guesses.
+
+## Steps
+
+1. **Identify the change**:
+   - If the user input ($@) names a commit / PR / branch / topic, use that as the focus
+   - Otherwise inspect `git log origin/main..HEAD --oneline` and `git diff origin/main...HEAD --stat` to discover what shipped on the current branch
+   - Read the actual diff (`git diff origin/main...HEAD`) — never document features that aren't in the code
+
+2. **Inventory the doc surfaces**:
+   - `README.md` at the repo root
+   - Any docs site (commonly `www/`, `docs/`, `site/`) — list its pages and identify the one(s) most thematically related to the change
+   - Inline godoc / API reference comments on the new exported symbols
+   - `CHANGELOG.md` if the project keeps one
+   - Any `examples/` directory entries that demonstrate the affected area
+
+3. **Audit each surface** with `grep`:
+   - Search for the names of related existing APIs (e.g. if you added `IterTools`, grep for `ListTools`) to find every page that already discusses the area
+   - Decide for each hit: does it need a cross-reference, a side-by-side comparison, or to stay untouched?
+
+4. **Decide where new content lives**:
+   - Prefer extending an existing page over creating a new one
+   - For a docs site, place new sections near related content (check the page's `## Heading` outline first)
+   - Skip surfaces that genuinely don't apply (e.g. a server-focused README for a client-only change) and say so explicitly
+
+5. **Draft the updates**:
+   - Lead with a one-sentence statement of what's new and why
+   - Show concrete code examples copied from real signatures — verify against the source files
+   - Include a comparison / "when to use which" table when adding an alternative to an existing API
+   - Note backwards-compatibility behaviour if relevant
+
+6. **Verify the docs build** before committing:
+   - For vocs / docusaurus / mkdocs sites, run the local build command (e.g. `npx vocs build`, `mkdocs build`) and fix any MDX/markdown errors
+   - For godoc, run `go vet ./...` and `go doc <pkg> <Symbol>` to sanity-check rendering
+
+7. **Report**:
+   - List every file changed and every file deliberately left alone (with a one-line reason)
+   - Suggest the next step (typically `/commit-push`) — do not auto-commit unless asked
+
+## Guidelines
+
+- Read the diff before writing anything — invented API names erode trust faster than missing docs
+- One change per doc commit; keep doc updates separate from code changes when possible
+- Match the existing voice and formatting of each surface (headings, code-fence languages, table styles)
+- Prefer linking between pages over duplicating content
+
+$@
@@ -162,6 +162,11 @@ mcpServers:
    type: remote
    url: "https://pubmed.mcp.example.com"
    noOAuth: true  # skip OAuth for public servers that don't require auth
+
+  builds:
+    type: remote
+    url: "https://builds.mcp.example.com"
+    tasksMode: always  # async task execution — see MCP Tasks below
 ```

 ## CLI Reference
@@ -626,6 +631,36 @@ in a custom `MCPTokenStoreFactory` for encrypted, DB-backed, or in-memory
 storage. See the [SDK options docs](/sdk/options#mcp-oauth-authorization) for
 the full matrix.

+### MCP Tasks (long-running tools)
+
+Kit advertises [MCP task support](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
+during `initialize`, so cooperating MCP servers can respond to `tools/call`
+with a `taskId` instead of blocking the connection. Kit then polls
+`tasks/get` / `tasks/result` until the task reaches a terminal state, and
+best-effort `tasks/cancel`s on context cancellation.
+
+Defaults are safe — a server that doesn't advertise task capability runs
+synchronously, exactly as before. Opt in per server via `tasksMode` in
+`.kit.yml` (`auto` | `never` | `always`) or programmatically through the SDK:
+
+```go
+host, _ := kit.New(ctx, &kit.Options{
+    MCPTaskMode: map[string]kit.MCPTaskMode{
+        "build-server": kit.MCPTaskModeAlways,
+    },
+    MCPTaskTimeout:  15 * time.Minute,
+    MCPTaskProgress: func(p kit.MCPTaskProgress) {
+        log.Printf("%s: %s", p.TaskID, p.Status)
+    },
+})
+
+tasks, _ := host.ListMCPTasks(ctx, "build-server")
+_, _    = host.CancelMCPTask(ctx, "build-server", tasks[0].TaskID)
+```
+
+See the [configuration docs](/configuration#mcp-tasks-long-running-tools) and
+[SDK options → MCP Tasks](/sdk/options#mcp-tasks) for the full surface.
+
 ### Custom Tools

 Create custom tools with automatic schema generation — no external dependencies needed:
@@ -5,24 +5,24 @@ go 1.26.2
 require (
 	charm.land/bubbles/v2 v2.1.0
 	charm.land/bubbletea/v2 v2.0.6
-	charm.land/fantasy v0.21.0
+	charm.land/fantasy v0.23.0
 	charm.land/huh/v2 v2.0.3
 	charm.land/lipgloss/v2 v2.0.3
-	github.com/alecthomas/chroma/v2 v2.23.1
+	github.com/alecthomas/chroma/v2 v2.24.1
 	github.com/atotto/clipboard v0.1.4
 	github.com/aymanbagabas/go-udiff v0.4.1
 	github.com/charmbracelet/fang v1.0.0
 	github.com/charmbracelet/log v1.0.0
 	github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266
-	github.com/charmbracelet/ultraviolet v0.0.0-20260422141423-a0f1f21775f7
+	github.com/charmbracelet/ultraviolet v0.0.0-20260428153724-66037269d7be
 	github.com/charmbracelet/x/editor v0.2.0
 	github.com/clipperhouse/displaywidth v0.11.0
 	github.com/clipperhouse/uax29/v2 v2.7.0
-	github.com/coder/acp-go-sdk v0.12.0
-	github.com/fsnotify/fsnotify v1.9.0
+	github.com/coder/acp-go-sdk v0.12.2
+	github.com/fsnotify/fsnotify v1.10.1
 	github.com/indaco/herald v0.13.0
 	github.com/indaco/herald-md v0.3.0
-	github.com/mark3labs/mcp-go v0.49.0
+	github.com/mark3labs/mcp-go v0.51.0
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/traefik/yaegi v0.16.1
@@ -37,20 +37,20 @@ require (
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.1 // indirect
 	github.com/Azure/azure-sdk-for-go/sdk/internal v1.12.0 // indirect
-	github.com/aws/aws-sdk-go-v2 v1.41.6 // indirect
-	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9 // indirect
-	github.com/aws/aws-sdk-go-v2/config v1.32.16 // indirect
-	github.com/aws/aws-sdk-go-v2/credentials v1.19.15 // indirect
-	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22 // indirect
-	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8 // indirect
-	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22 // indirect
-	github.com/aws/aws-sdk-go-v2/service/signin v1.0.10 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sso v1.30.16 // indirect
-	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20 // indirect
-	github.com/aws/aws-sdk-go-v2/service/sts v1.42.0 // indirect
+	github.com/aws/aws-sdk-go-v2 v1.41.7 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 // indirect
+	github.com/aws/aws-sdk-go-v2/config v1.32.17 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.16 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.0.11 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 // indirect
 	github.com/aws/smithy-go v1.25.1 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
@@ -59,9 +59,9 @@ require (
 	github.com/charmbracelet/harmonica v0.2.0 // indirect
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
-	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260426004601-d5e63ff0b9ca // indirect
+	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260503005035-c113ba3d2310 // indirect
 	github.com/charmbracelet/x/exp/ordered v0.1.0 // indirect
-	github.com/charmbracelet/x/exp/slice v0.0.0-20260426004601-d5e63ff0b9ca // indirect
+	github.com/charmbracelet/x/exp/slice v0.0.0-20260503005035-c113ba3d2310 // indirect
 	github.com/charmbracelet/x/exp/strings v0.1.0 // indirect
 	github.com/charmbracelet/x/json v0.2.0 // indirect
 	github.com/charmbracelet/x/termios v0.1.1 // indirect
@@ -69,30 +69,31 @@ require (
 	github.com/dlclark/regexp2 v1.12.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
-	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260430182902-b6187a392ed4 // indirect
 	github.com/go-logfmt/logfmt v0.6.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
-	github.com/google/jsonschema-go v0.4.2 // indirect
+	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.3.15 // indirect
 	github.com/googleapis/gax-go/v2 v2.22.0 // indirect
 	github.com/gorilla/websocket v1.5.3 // indirect
-	github.com/kaptinlin/go-i18n v0.4.4 // indirect
-	github.com/kaptinlin/jsonpointer v0.4.19 // indirect
-	github.com/kaptinlin/jsonschema v0.7.11 // indirect
-	github.com/kaptinlin/messageformat-go v0.6.0 // indirect
+	github.com/kaptinlin/go-i18n v0.4.7 // indirect
+	github.com/kaptinlin/jsonpointer v0.4.21 // indirect
+	github.com/kaptinlin/jsonschema v0.7.13 // indirect
+	github.com/kaptinlin/messageformat-go v0.6.3 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
 	github.com/muesli/mango v0.2.0 // indirect
 	github.com/muesli/mango-cobra v1.3.0 // indirect
 	github.com/muesli/mango-pflag v0.2.0 // indirect
 	github.com/muesli/roff v0.1.0 // indirect
-	github.com/pelletier/go-toml/v2 v2.3.0 // indirect
+	github.com/pelletier/go-toml/v2 v2.3.1 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
@@ -115,10 +116,10 @@ require (
 	golang.org/x/net v0.53.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	google.golang.org/api v0.276.0 // indirect
-	google.golang.org/genai v1.54.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529 // indirect
-	google.golang.org/grpc v1.80.0 // indirect
+	google.golang.org/api v0.277.0 // indirect
+	google.golang.org/genai v1.55.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260427160629-7cedc36a6bc4 // indirect
+	google.golang.org/grpc v1.81.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )
@@ -2,8 +2,8 @@ charm.land/bubbles/v2 v2.1.0 h1:YSnNh5cPYlYjPxRrzs5VEn3vwhtEn3jVGRBT3M7/I0g=
 charm.land/bubbles/v2 v2.1.0/go.mod h1:l97h4hym2hvWBVfmJDtrEHHCtkIKeTEb3TTJ4ZOB3wY=
 charm.land/bubbletea/v2 v2.0.6 h1:UHN/91OyuhaOFGSrBXQ/hMZD8IO1Uc4BvHlgHXL2WJo=
 charm.land/bubbletea/v2 v2.0.6/go.mod h1:MH/D8ZLlN3op37vQvijKuU29g3rqTp+aQapURFonF9g=
-charm.land/fantasy v0.21.0 h1:fYeW5axjn7KxJFvXavYhToZDG83zM+or1XEpHqX/GAo=
-charm.land/fantasy v0.21.0/go.mod h1:GYYvvDAS3u/Wpb5hX0VxCJPhQCaffHNNeBRtGw04IBI=
+charm.land/fantasy v0.23.0 h1:pocjwC5CxfEg1Bpwb0raML2d5ijo3op33Mmd6hYJyo4=
+charm.land/fantasy v0.23.0/go.mod h1:4yzSsd9XmFEVjRnF1P0LTEbLTmQX6OLnPkrHaf7iruo=
 charm.land/huh/v2 v2.0.3 h1:2cJsMqEPwSywGHvdlKsJyQKPtSJLVnFKyFbsYZTlLkU=
 charm.land/huh/v2 v2.0.3/go.mod h1:93eEveeeqn47MwiC3tf+2atZ2l7Is88rAtmZNZ8x9Wc=
 charm.land/lipgloss/v2 v2.0.3 h1:yM2zJ4Cf5Y51b7RHIwioil4ApI/aypFXXVHSwlM6RzU=
@@ -28,40 +28,40 @@ github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ
 github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
 github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
-github.com/alecthomas/chroma/v2 v2.23.1 h1:nv2AVZdTyClGbVQkIzlDm/rnhk1E9bU9nXwmZ/Vk/iY=
-github.com/alecthomas/chroma/v2 v2.23.1/go.mod h1:NqVhfBR0lte5Ouh3DcthuUCTUpDC9cxBOfyMbMQPs3o=
+github.com/alecthomas/chroma/v2 v2.24.1 h1:m5ffpfZbIb++k8AqFEKy9uVgY12xIQtBsQlc6DfZJQM=
+github.com/alecthomas/chroma/v2 v2.24.1/go.mod h1:l+ohZ9xRXIbGe7cIW+YZgOGbvuVLjMps/FYN/CwuabI=
 github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs=
 github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
 github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
-github.com/aws/aws-sdk-go-v2 v1.41.6 h1:1AX0AthnBQzMx1vbmir3Y4WsnJgiydmnJjiLu+LvXOg=
-github.com/aws/aws-sdk-go-v2 v1.41.6/go.mod h1:dy0UzBIfwSeot4grGvY1AqFWN5zgziMmWGzysDnHFcQ=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9 h1:adBsCIIpLbLmYnkQU+nAChU5yhVTvu5PerROm+/Kq2A=
-github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.9/go.mod h1:uOYhgfgThm/ZyAuJGNQ5YgNyOlYfqnGpTHXvk3cpykg=
-github.com/aws/aws-sdk-go-v2/config v1.32.16 h1:Q0iQ7quUgJP0F/SCRTieScnaMdXr9h/2+wze1u3cNeM=
-github.com/aws/aws-sdk-go-v2/config v1.32.16/go.mod h1:duCCnJEFqpt2RC6no1iK6q+8HpwOAkiUua0pY507dQc=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.15 h1:fyvgWTszojq8hEnMi8PPBTvZdTtEVmAVyo+NFLHBhH4=
-github.com/aws/aws-sdk-go-v2/credentials v1.19.15/go.mod h1:gJiYyMOjNg8OEdRWOf3CrFQxM2a98qmrtjx1zuiQfB8=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22 h1:IOGsJ1xVWhsi+ZO7/NW8OuZZBtMJLZbk4P5HDjJO0jQ=
-github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.22/go.mod h1:b+hYdbU+jGKfXE8kKM6g1+h+L/Go3vMvzlxBsiuGsxg=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22 h1:GmLa5Kw1ESqtFpXsx5MmC84QWa/ZrLZvlJGa2y+4kcQ=
-github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.22/go.mod h1:6sW9iWm9DK9YRpRGga/qzrzNLgKpT2cIxb7Vo2eNOp0=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22 h1:dY4kWZiSaXIzxnKlj17nHnBcXXBfac6UlsAx2qL6XrU=
-github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.22/go.mod h1:KIpEUx0JuRZLO7U6cbV204cWAEco2iC3l061IxlwLtI=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23 h1:FPXsW9+gMuIeKmz7j6ENWcWtBGTe1kH8r9thNt5Uxx4=
-github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.23/go.mod h1:7J8iGMdRKk6lw2C+cMIphgAnT8uTwBwNOsGkyOCm80U=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8 h1:HtOTYcbVcGABLOVuPYaIihj6IlkqubBwFj10K5fxRek=
-github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.8/go.mod h1:VsK9abqQeGlzPgUr+isNWzPlK2vKe9INMLWnY65f5Xs=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22 h1:PUmZeJU6Y1Lbvt9WFuJ0ugUK2xn6hIWUBBbKuOWF30s=
-github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.22/go.mod h1:nO6egFBoAaoXze24a2C0NjQCvdpk8OueRoYimvEB9jo=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.10 h1:a1Fq/KXn75wSzoJaPQTgZO0wHGqE9mjFnylnqEPTchA=
-github.com/aws/aws-sdk-go-v2/service/signin v1.0.10/go.mod h1:p6+MXNxW7IA6dMgHfTAzljuwSKD0NCm/4lbS4t6+7vI=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.16 h1:x6bKbmDhsgSZwv6q19wY/u3rLk/3FGjJWyqKcIRufpE=
-github.com/aws/aws-sdk-go-v2/service/sso v1.30.16/go.mod h1:CudnEVKRtLn0+3uMV0yEXZ+YZOKnAtUJ5DmDhilVnIw=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20 h1:oK/njaL8GtyEihkWMD4k3VgHCT64RQKkZwh0DG5j8ak=
-github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.20/go.mod h1:JHs8/y1f3zY7U5WcuzoJ/yAYGYtNIVPKLIbp61euvmg=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.0 h1:ks8KBcZPh3PYISr5dAiXCM5/Thcuxk8l+PG4+A0exds=
-github.com/aws/aws-sdk-go-v2/service/sts v1.42.0/go.mod h1:pFw33T0WLvXU3rw1WBkpMlkgIn54eCB5FYLhjDc9Foo=
+github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
+github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10/go.mod h1:qqY157uZoqm5OXq/amuaBJyC9hgBCBQnsaWnPe905GY=
+github.com/aws/aws-sdk-go-v2/config v1.32.17 h1:FpL4/758/diKwqbytU0prpuiu60fgXKUWCpDJtApclU=
+github.com/aws/aws-sdk-go-v2/config v1.32.17/go.mod h1:OXqUMzgXytfoF9JaKkhrOYsyh72t9G+MJH8mMRaexOE=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.16 h1:r3RJBuU7X9ibt8RHbMjWE6y60QbKBiII6wSrXnapxSU=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.16/go.mod h1:6cx7zqDENJDbBIIWX6P8s0h6hqHC8Avbjh9Dseo27ug=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23 h1:UuSfcORqNSz/ey3VPRS8TcVH2Ikf0/sC+Hdj400QI6U=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.23/go.mod h1:+G/OSGiOFnSOkYloKj/9M35s74LgVAdJBSD5lsFfqKg=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23 h1:GpT/TrnBYuE5gan2cZbTtvP+JlHsutdmlV2YfEyNde0=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.23/go.mod h1:xYWD6BS9ywC5bS3sz9Xh04whO/hzK2plt2Zkyrp4JuA=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23 h1:bpd8vxhlQi2r1hiueOw02f/duEPTMK59Q4QMAoTTtTo=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.23/go.mod h1:15DfR2nw+CRHIk0tqNyifu3G1YdAOy68RftkhMDDwYk=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24 h1:OQqn11BtaYv1WLUowvcA30MpzIu8Ti4pcLPIIyoKZrA=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.4.24/go.mod h1:X5ZJyfwVrWA96GzPmUCWFQaEARPR7gCrpq2E92PJwAE=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9 h1:FLudkZLt5ci0ozzgkVo8BJGwvqNaZbTWb3UcucAateA=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.9/go.mod h1:w7wZ/s9qK7c8g4al+UyoF1Sp/Z45UwMGcqIzLWVQHWk=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23 h1:pbrxO/kuIwgEsOPLkaHu0O+m4fNgLU8B3vxQ+72jTPw=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.23/go.mod h1:/CMNUqoj46HpS3MNRDEDIwcgEnrtZlKRaHNaHxIFpNA=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.11 h1:TdJ+HdzOBhU8+iVAOGUTU63VXopcumCOF1paFulHWZc=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.11/go.mod h1:R82ZRExE/nheo0N+T8zHPcLRTcH8MGsnR3BiVGX0TwI=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.17 h1:7byT8HUWrgoRp6sXjxtZwgOKfhss5fW6SkLBtqzgRoE=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.17/go.mod h1:xNWknVi4Ezm1vg1QsB/5EWpAJURq22uqd38U8qKvOJc=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21 h1:+1Kl1zx6bWi4X7cKi3VYh29h8BvsCoHQEQ6ST9X8w7w=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.21/go.mod h1:4vIRDq+CJB2xFAXZ+YgGUTiEft7oAQlhIs71xcSeuVg=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 h1:F/M5Y9I3nwr2IEpshZgh1GeHpOItExNM9L1euNuh/fk=
+github.com/aws/aws-sdk-go-v2/service/sts v1.42.1/go.mod h1:mTNxImtovCOEEuD65mKW7DCsL+2gjEH+RPEAexAzAio=
 github.com/aws/smithy-go v1.25.1 h1:J8ERsGSU7d+aCmdQur5Txg6bVoYelvQJgtZehD12GkI=
 github.com/aws/smithy-go v1.25.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
@@ -86,8 +86,8 @@ github.com/charmbracelet/log v1.0.0 h1:HVVVMmfOorfj3BA9i8X8UL69Hoz9lI0PYwXfJvOdR
 github.com/charmbracelet/log v1.0.0/go.mod h1:uYgY3SmLpwJWxmlrPwXvzVYujxis1vAKRV/0VQB7yWA=
 github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266 h1:BW/sZtyd1JyYy0h5adMm3tzpNyL857LWjuTRET6OhpY=
 github.com/charmbracelet/openai-go v0.0.0-20260319145158-d0740cc34266/go.mod h1:1DahUaExbUZx/jD+FNT2PKP4L9rLE5+ZBRuI8mZjd/E=
-github.com/charmbracelet/ultraviolet v0.0.0-20260422141423-a0f1f21775f7 h1:PeRlqWGEoO0apcS62iEgxQhVnFCTOYyQvi2sUTdf6IE=
-github.com/charmbracelet/ultraviolet v0.0.0-20260422141423-a0f1f21775f7/go.mod h1:3YdTxlnV/L0bQ3VN8WOSw8doF7LZV/xawUQ4MuAPDvo=
+github.com/charmbracelet/ultraviolet v0.0.0-20260428153724-66037269d7be h1:j7w8VP/D4lu5+/4GamMmFy8nrtadcl82/fjvDgSHwLo=
+github.com/charmbracelet/ultraviolet v0.0.0-20260428153724-66037269d7be/go.mod h1:3YdTxlnV/L0bQ3VN8WOSw8doF7LZV/xawUQ4MuAPDvo=
 github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
 github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
 github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
@@ -98,14 +98,14 @@ github.com/charmbracelet/x/editor v0.2.0 h1:7XLUKtaRaB8jN7bWU2p2UChiySyaAuIfYiIR
 github.com/charmbracelet/x/editor v0.2.0/go.mod h1:p3oQ28TSL3YPd+GKJ1fHWcp+7bVGpedHpXmo0D6t1dY=
 github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86 h1:JSt3B+U9iqk37QUU2Rvb6DSBYRLtWqFqfxf8l5hOZUA=
 github.com/charmbracelet/x/errors v0.0.0-20240508181413-e8d8b6e2de86/go.mod h1:2P0UgXMEa6TsToMSuFqKFQR+fZTO9CNGUNokkPatT/0=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260426004601-d5e63ff0b9ca h1:/tGUqs2h/DoQZztzFFPDABBOg/UAbfWoJ46JWUazNDs=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260426004601-d5e63ff0b9ca/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260503005035-c113ba3d2310 h1:rByFKh9JgQScu7oy0+TlUbC2e93woW/QNZmNXbbbw/E=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260503005035-c113ba3d2310/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f h1:pk6gmGpCE7F3FcjaOEKYriCvpmIN4+6OS/RD0vm4uIA=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f/go.mod h1:IfZAMTHB6XkZSeXUqriemErjAWCCzT0LwjKFYCZyw0I=
 github.com/charmbracelet/x/exp/ordered v0.1.0 h1:55/qLwjIh0gL0Vni+QAWk7T/qRVP6sBf+2agPBgnOFE=
 github.com/charmbracelet/x/exp/ordered v0.1.0/go.mod h1:5UHwmG+is5THxMyCJHNPCn2/ecI07aKNrW+LcResjJ8=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260426004601-d5e63ff0b9ca h1:zXzgHLj/t+jXwKwaFhNVhW+6bq7S646wXdHyMDo1uDQ=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260426004601-d5e63ff0b9ca/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260503005035-c113ba3d2310 h1:PMjHdSo8Vpq9psUw9BoHo9JLPMkm9Hqb+Whk64n3AQQ=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260503005035-c113ba3d2310/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
 github.com/charmbracelet/x/exp/strings v0.1.0 h1:i69S2XI7uG1u4NLGeJPSYU++Nmjvpo9nwd6aoEm7gkA=
 github.com/charmbracelet/x/exp/strings v0.1.0/go.mod h1:/ehtMPNh9K4odGFkqYJKpIYyePhdp1hLBRvyY4bWkH8=
 github.com/charmbracelet/x/json v0.2.0 h1:DqB+ZGx2h+Z+1s98HOuOyli+i97wsFQIxP2ZQANTPrQ=
@@ -124,8 +124,8 @@ github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJ
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os8IaYg++6uMOdKK83QtkkvJik=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=
-github.com/coder/acp-go-sdk v0.12.0 h1:GoIC6RrkPMBIVQ3ckSkl+bO/ERV/IRK6clBdZmx4Uf4=
-github.com/coder/acp-go-sdk v0.12.0/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
+github.com/coder/acp-go-sdk v0.12.2 h1:fpRJ8Z5HMSr5cZ5IywzFlFZcIxZOsto+laNVu7XelFA=
+github.com/coder/acp-go-sdk v0.12.2/go.mod h1:yKzM/3R9uELp4+nBAwwtkS0aN1FOFjo11CNPy37yFko=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
 github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
@@ -146,10 +146,10 @@ github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2
 github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
-github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
-github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
+github.com/go-json-experiment/json v0.0.0-20260430182902-b6187a392ed4 h1:2WmHkJINIjgXXYDGik8d3oJvFA3DAwPy00csDJ3vo+o=
+github.com/go-json-experiment/json v0.0.0-20260430182902-b6187a392ed4/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
 github.com/go-logfmt/logfmt v0.6.1 h1:4hvbpePJKnIzH1B+8OR/JPbTx37NktoI9LE2QZBBkvE=
 github.com/go-logfmt/logfmt v0.6.1/go.mod h1:EV2pOAQoZaT1ZXZbqDl5hrymndi4SY9ED9/z6CO0XAk=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -167,8 +167,8 @@ github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
-github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
-github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
 github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -187,14 +187,14 @@ github.com/indaco/herald v0.13.0 h1:+xVG9Fx5NpuWhwku/9IlRL6I009NnX4VUGKvlZHTRxU=
 github.com/indaco/herald v0.13.0/go.mod h1:T5g1+XLYvpjouhzAGHnAHDCKizhESkoV6+QPZ3DhgWA=
 github.com/indaco/herald-md v0.3.0 h1:hN1cKyrexPPM9PeHBsKuaWvIizSi/iYvM9yzRgtdb8M=
 github.com/indaco/herald-md v0.3.0/go.mod h1:RUHVaDSG45ymJjKyxpDwBocLXrZo93FB4OeYMsw9B9s=
-github.com/kaptinlin/go-i18n v0.4.4 h1:3XrUYyLOykcd1K3gm4j7ndrF8YLIYrJjtbKGr/nF2Kw=
-github.com/kaptinlin/go-i18n v0.4.4/go.mod h1:mU/7BH4molY5lGZYBwBRKAaiJ70dWRHuqmQ0/pFLGno=
-github.com/kaptinlin/jsonpointer v0.4.19 h1:dEkwEnvn9jJCofrwKGxfKaPNbDOQEf3UEbEumn4xZBg=
-github.com/kaptinlin/jsonpointer v0.4.19/go.mod h1:Mo7+DX8RlQTFqS4dnYJl0izSP4ob+Rl5xO/mGDETgaU=
-github.com/kaptinlin/jsonschema v0.7.11 h1:h63Lb3Q4FBSWeWiAGefNPEVPNsOvgn91ATmf25X0yRs=
-github.com/kaptinlin/jsonschema v0.7.11/go.mod h1:cJ8QIhwq3V/Yyh3sXRNt8w3sM943bNIbwnPTpBTXn3s=
-github.com/kaptinlin/messageformat-go v0.6.0 h1:D6jiXFsKW4/JG2CMddv/F6Rev9KVbCRKEzzV5QOAcpc=
-github.com/kaptinlin/messageformat-go v0.6.0/go.mod h1:NKjwS6e9u7DRhAK+vydjDDwJ7UbdHhYjk/yk2WPuZPs=
+github.com/kaptinlin/go-i18n v0.4.7 h1:apjIIZHnGRyrkiX3vHj07F1BF6D0JLmV+VGSr1781Jc=
+github.com/kaptinlin/go-i18n v0.4.7/go.mod h1:+i1J0pFq/9i9ESC5qRMVkKwC+mdQTABhhBExpYOlbeM=
+github.com/kaptinlin/jsonpointer v0.4.21 h1:WVkwQbeerbHFcoXG7Yo/mlQhhZjWiTnagECEfwDXXa0=
+github.com/kaptinlin/jsonpointer v0.4.21/go.mod h1:Mo7+DX8RlQTFqS4dnYJl0izSP4ob+Rl5xO/mGDETgaU=
+github.com/kaptinlin/jsonschema v0.7.13 h1:kahVXTy/rURL0XJjyQ9WELm59wEmXi6IY0TWswQEFvU=
+github.com/kaptinlin/jsonschema v0.7.13/go.mod h1:Uh0aUBusnhXDCEXJ2oimL/hx7YTo7F+sKniE+tM0ERc=
+github.com/kaptinlin/messageformat-go v0.6.3 h1:m9ZE/fCjnsk8bdkv7Qs56L/ZoHbmQqhz9mRZSAQLU5g=
+github.com/kaptinlin/messageformat-go v0.6.3/go.mod h1:2KOZ/hgo/SveZ+uyi7vPUpUXieX65Mppzbc3VpGyqKs=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
@@ -203,8 +203,8 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
 github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/mark3labs/mcp-go v0.49.0 h1:7Ssx4d7/T86qnWoJIdye7wEEvUzv39UIbnZb/FqUZMY=
-github.com/mark3labs/mcp-go v0.49.0/go.mod h1:BflTAZAzXlrTpiO44gmjMu89n2FO56rJ9m31fp4zd5k=
+github.com/mark3labs/mcp-go v0.51.0 h1:e8AhEfxzcYt7XqYzwT7uzWNhnqpu3H1Tn7dEJB9Ygj8=
+github.com/mark3labs/mcp-go v0.51.0/go.mod h1:Zg9cB2HdwdMMVgY0xtTzq3KvYIOJQDsaut+jWjwDaQY=
 github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
 github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
 github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
@@ -223,8 +223,8 @@ github.com/muesli/roff v0.1.0 h1:YD0lalCotmYuF5HhZliKWlIx7IEhiXeSfq7hNjFqGF8=
 github.com/muesli/roff v0.1.0/go.mod h1:pjAHQM9hdUUwm/krAfrLGgJkXJ+YuhtsfZ42kieB2Ig=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
-github.com/pelletier/go-toml/v2 v2.3.0 h1:k59bC/lIZREW0/iVaQR8nDHxVq8OVlIzYCOJf421CaM=
-github.com/pelletier/go-toml/v2 v2.3.0/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pelletier/go-toml/v2 v2.3.1 h1:MYEvvGnQjeNkRF1qUuGolNtNExTDwct51yp7olPtrEc=
+github.com/pelletier/go-toml/v2 v2.3.1/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ=
 github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo=
@@ -238,6 +238,8 @@ github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sagikazarmark/locafero v0.12.0 h1:/NQhBAkUb4+fH1jivKHWusDYFjMOOKU88eegjfxfHb4=
 github.com/sagikazarmark/locafero v0.12.0/go.mod h1:sZh36u/YSZ918v0Io+U9ogLYQJ9tLLBmM4eneO6WwsI=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
@@ -310,18 +312,18 @@ golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
-google.golang.org/api v0.276.0 h1:nVArUtfLEihtW+b0DdcqRGK1xoEm2+ltAihyztq7MKY=
-google.golang.org/api v0.276.0/go.mod h1:Fnag/EWUPIcJXuIkP1pjoTgS5vdxlk3eeemL7Do6bvw=
-google.golang.org/genai v1.54.0 h1:ZQCa70WMTJDI11FdqWCzGvZ5PanpcpfoO6jl/lrSnGU=
-google.golang.org/genai v1.54.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
-google.golang.org/genproto v0.0.0-20260414002931-afd174a4e478 h1:aLsVTW0lZ8+IY5u/ERjZSCvAmhuR7slKzyha3YikDNA=
-google.golang.org/genproto v0.0.0-20260414002931-afd174a4e478/go.mod h1:YJAzKjfHIUHb9T+bfu8L7mthAp7VVXQBUs1PLdBWS7M=
-google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478 h1:yQugLulqltosq0B/f8l4w9VryjV+N/5gcW0jQ3N8Qec=
-google.golang.org/genproto/googleapis/api v0.0.0-20260414002931-afd174a4e478/go.mod h1:C6ADNqOxbgdUUeRTU+LCHDPB9ttAMCTff6auwCVa4uc=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529 h1:XF8+t6QQiS0o9ArVan/HW8Q7cycNPGsJf6GA2nXxYAg=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260420184626-e10c466a9529/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
-google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
+google.golang.org/api v0.277.0 h1:HJfyJUiNeBBUMai7ez8u14wkp/gH/I4wpGbbO9o+cSk=
+google.golang.org/api v0.277.0/go.mod h1:B9TqLBwJqVjp1mtt7WeoQwWRwvu/400y5lETOql+giQ=
+google.golang.org/genai v1.55.0 h1:iLHGk4Bj/IZ/GNNZb7hYqwSJMRBvqLeu2Hb6YQ+rYGw=
+google.golang.org/genai v1.55.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
+google.golang.org/genproto v0.0.0-20260427160629-7cedc36a6bc4 h1:2iMJZntwvmfgtse+s744JY7v7PgEdSBuFYXucvpOHNM=
+google.golang.org/genproto v0.0.0-20260427160629-7cedc36a6bc4/go.mod h1:v14kaaboYyXQ1Gsu489Q+Hg/oN4B33mWtuOhF1HCeXA=
+google.golang.org/genproto/googleapis/api v0.0.0-20260427160629-7cedc36a6bc4 h1:yOzSCGPx+cp5VO7IxvZ9SBFF7j1tZVcNtlHR2iYKtVo=
+google.golang.org/genproto/googleapis/api v0.0.0-20260427160629-7cedc36a6bc4/go.mod h1:Q9HWtNeE7tM9npdIsEvqXj1QJIvVoeAV3rtXtS715Cw=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260427160629-7cedc36a6bc4 h1:tEkOQcXgF6dH1G+MVKZrfpYvozGrzb91k6ha7jireSM=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260427160629-7cedc36a6bc4/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.81.0 h1:W3G9N3KQf3BU+YuCtGKJk0CmxQNbAISICD/9AORxLIw=
+google.golang.org/grpc v1.81.0/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -185,6 +185,26 @@ func (a *Agent) ListSessions(_ context.Context, _ acp.ListSessionsRequest) (acp.
 	}, nil
 }

+// CloseSession cancels any ongoing work for the session and frees its resources.
+func (a *Agent) CloseSession(_ context.Context, params acp.CloseSessionRequest) (acp.CloseSessionResponse, error) {
+	sessionID := string(params.SessionId)
+	sess, ok := a.registry.get(sessionID)
+	if !ok {
+		return acp.CloseSessionResponse{}, nil
+	}
+
+	log.Debug("acp: close session", "session", sessionID)
+	sess.cancelPrompt()
+	a.registry.remove(sessionID)
+	return acp.CloseSessionResponse{}, nil
+}
+
+// ResumeSession is not supported — Kit doesn't persist sessions across
+// restarts in ACP mode. Clients should use NewSession instead.
+func (a *Agent) ResumeSession(_ context.Context, _ acp.ResumeSessionRequest) (acp.ResumeSessionResponse, error) {
+	return acp.ResumeSessionResponse{}, fmt.Errorf("resume session not supported")
+}
+
 // SetSessionConfigOption handles session configuration changes. Currently
 // supports the "model" config option to change the active model for a session.
 func (a *Agent) SetSessionConfigOption(ctx context.Context, params acp.SetSessionConfigOptionRequest) (acp.SetSessionConfigOptionResponse, error) {
@@ -232,6 +232,20 @@ func (r *sessionRegistry) closeAll() {
 	}
 }

+// remove closes and removes a single session by ID.
+func (r *sessionRegistry) remove(sessionID string) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	sess, ok := r.sessions[sessionID]
+	if !ok {
+		return
+	}
+	if sess.kit != nil {
+		_ = sess.kit.Close()
+	}
+	delete(r.sessions, sessionID)
+}
+
 // cancelPrompt cancels the current prompt for a session, if any.
 func (s *acpSession) cancelPrompt() {
 	s.cancelMu.Lock()
@@ -59,6 +59,11 @@ type AgentConfig struct {
 	// loading (successfully or with error). The callback receives the server
 	// name, tool count, and any error. Called from the background goroutine.
 	OnMCPServerLoaded func(serverName string, toolCount int, err error)
+
+	// MCPTaskConfig configures task-augmented tools/call execution. The
+	// zero value preserves historical synchronous-only behaviour for any
+	// server that didn't advertise task support during initialize.
+	MCPTaskConfig tools.MCPTaskConfig
 }

 // ToolCallHandler is a function type for handling tool calls as they happen.
@@ -231,6 +236,10 @@ type Agent struct {
 	authHandler       tools.MCPAuthHandler
 	tokenStoreFactory tools.TokenStoreFactory

+	// mcpTaskConfig is stored from AgentConfig so AddMCPServer() can
+	// propagate it to a lazily-created MCPToolManager.
+	mcpTaskConfig tools.MCPTaskConfig
+
 	// mcpReady is closed when background MCP tool loading completes (success
 	// or failure). nil when no MCP servers are configured.
 	mcpReady chan struct{}
@@ -329,6 +338,7 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 		modelConfig:         agentConfig.ModelConfig,
 		authHandler:         agentConfig.AuthHandler,
 		tokenStoreFactory:   agentConfig.TokenStoreFactory,
+		mcpTaskConfig:       agentConfig.MCPTaskConfig,
 	}

 	// Start MCP tool loading in the background if servers are configured.
@@ -348,6 +358,8 @@ func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error) {
 		if agentConfig.OnMCPServerLoaded != nil {
 			toolManager.SetOnServerLoaded(agentConfig.OnMCPServerLoaded)
 		}
+		// Apply task-augmented tool execution config (zero value = no-op).
+		toolManager.SetTaskConfig(agentConfig.MCPTaskConfig)
 		a.toolManager = toolManager
 		a.mcpReady = make(chan struct{})

@@ -1134,6 +1146,7 @@ func (a *Agent) AddMCPServer(ctx context.Context, name string, cfg config.MCPSer
 		if a.tokenStoreFactory != nil {
 			a.toolManager.SetTokenStoreFactory(a.tokenStoreFactory)
 		}
+		a.toolManager.SetTaskConfig(a.mcpTaskConfig)
 		a.toolManager.SetOnToolsChanged(func() {
 			a.rebuildFantasyAgent()
 		})
@@ -56,6 +56,8 @@ type AgentCreationOptions struct {
 	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
 	// loading (successfully or with error). Called from the background goroutine.
 	OnMCPServerLoaded func(serverName string, toolCount int, err error)
+	// MCPTaskConfig configures task-augmented tools/call execution.
+	MCPTaskConfig tools.MCPTaskConfig
 }

 // CreateAgent creates an agent with optional spinner for Ollama models.
@@ -76,6 +78,7 @@ func CreateAgent(ctx context.Context, opts *AgentCreationOptions) (*Agent, error
 		ToolWrapper:       opts.ToolWrapper,
 		ExtraTools:        opts.ExtraTools,
 		OnMCPServerLoaded: opts.OnMCPServerLoaded,
+		MCPTaskConfig:     opts.MCPTaskConfig,
 	}

 	var agent *Agent
@@ -38,6 +38,23 @@ type MCPServerConfig struct {
 	// servers that don't support it.
 	NoOAuth bool `json:"noOAuth,omitempty" yaml:"noOAuth,omitempty"`

+	// TasksMode controls when this server's tools/call requests are augmented
+	// with MCP task metadata (turning a synchronous call into an asynchronous,
+	// pollable job — see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks).
+	//
+	// Valid values:
+	//   - "" or "auto": (default) augment requests with task metadata only
+	//     when the server advertises tasks/toolCalls capability during initialize.
+	//   - "never":      never augment — every tool call is synchronous, regardless
+	//     of server capability.
+	//   - "always":     always augment, even when the server didn't advertise
+	//     task support. The server may still respond synchronously; this just
+	//     opts in unconditionally on the client side.
+	//
+	// In all modes, when the server returns a CreateTaskResult the client polls
+	// tasks/get / tasks/result until the task reaches a terminal state.
+	TasksMode string `json:"tasksMode,omitempty" yaml:"tasksMode,omitempty"`
+
 	// InProcessServer holds a live *server.MCPServer for in-process transport.
 	// When set (and Type is "inprocess"), the connection pool creates an
 	// in-process client instead of spawning a subprocess or making HTTP calls.
@@ -68,6 +85,7 @@ func (s *MCPServerConfig) UnmarshalJSON(data []byte) error {
 		OAuthClientSecret string            `json:"oauthClientSecret,omitempty" yaml:"oauthClientSecret,omitempty"`
 		OAuthScopes       []string          `json:"oauthScopes,omitempty" yaml:"oauthScopes,omitempty"`
 		NoOAuth           bool              `json:"noOAuth,omitempty" yaml:"noOAuth,omitempty"`
+		TasksMode         string            `json:"tasksMode,omitempty" yaml:"tasksMode,omitempty"`
 	}

 	// Also try legacy format
@@ -80,6 +98,7 @@ func (s *MCPServerConfig) UnmarshalJSON(data []byte) error {
 		Headers       []string       `json:"headers,omitempty"`
 		AllowedTools  []string       `json:"allowedTools,omitempty" yaml:"allowedTools,omitempty"`
 		ExcludedTools []string       `json:"excludedTools,omitempty" yaml:"excludedTools,omitempty"`
+		TasksMode     string         `json:"tasksMode,omitempty" yaml:"tasksMode,omitempty"`
 	}

 	// Try new format first
@@ -96,6 +115,7 @@ func (s *MCPServerConfig) UnmarshalJSON(data []byte) error {
 		s.OAuthClientSecret = newConfig.OAuthClientSecret
 		s.OAuthScopes = newConfig.OAuthScopes
 		s.NoOAuth = newConfig.NoOAuth
+		s.TasksMode = newConfig.TasksMode
 		return nil
 	}

@@ -116,6 +136,7 @@ func (s *MCPServerConfig) UnmarshalJSON(data []byte) error {
 	s.Headers = legacyConfig.Headers
 	s.AllowedTools = legacyConfig.AllowedTools
 	s.ExcludedTools = legacyConfig.ExcludedTools
+	s.TasksMode = legacyConfig.TasksMode

 	// Infer type from legacy format for better compatibility
 	// Only set Type when it doesn't change existing transport behavior
@@ -324,6 +345,17 @@ func (c *Config) Validate() error {
 			return fmt.Errorf("server %s: allowedTools and excludedTools are mutually exclusive", serverName)
 		}

+		// Reject unknown tasksMode values up front so a typo (e.g. "alwasy")
+		// fails loud here instead of being silently downgraded to "auto" by
+		// the runtime parser. Comparison is case-insensitive to match
+		// tools.ParseTaskMode.
+		switch strings.ToLower(strings.TrimSpace(serverConfig.TasksMode)) {
+		case "", "auto", "never", "always":
+			// ok
+		default:
+			return fmt.Errorf("server %s: invalid tasksMode %q (expected one of: auto, never, always)", serverName, serverConfig.TasksMode)
+		}
+
 		transport := serverConfig.GetTransportType()
 		switch transport {
 		case "stdio":
@@ -627,3 +627,92 @@ func TestMCPServerConfig_OAuthFields_Omitted(t *testing.T) {
 		t.Errorf("Expected empty OAuthScopes, got %v", cfg.OAuthScopes)
 	}
 }
+
+func TestMCPServerConfig_TasksMode_NewFormat(t *testing.T) {
+	jsonData := `{
+		"type": "remote",
+		"url": "https://my-mcp-server.com",
+		"tasksMode": "always"
+	}`
+	var cfg MCPServerConfig
+	if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+	if cfg.TasksMode != "always" {
+		t.Errorf("expected TasksMode 'always', got %q", cfg.TasksMode)
+	}
+}
+
+func TestMCPServerConfig_TasksMode_LegacyFormat(t *testing.T) {
+	// tasksMode also recognised in the legacy unmarshal path so users on
+	// the older command/args shape can opt in without migrating.
+	jsonData := `{
+		"command": "npx",
+		"args": ["@modelcontextprotocol/server-filesystem", "/path"],
+		"tasksMode": "never"
+	}`
+	var cfg MCPServerConfig
+	if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+	if cfg.TasksMode != "never" {
+		t.Errorf("expected TasksMode 'never', got %q", cfg.TasksMode)
+	}
+}
+
+func TestMCPServerConfig_TasksMode_DefaultEmpty(t *testing.T) {
+	// When tasksMode is not set the field stays empty, which downstream
+	// resolves to "auto" via tools.ParseTaskMode.
+	jsonData := `{"type":"remote","url":"https://x.example"}`
+	var cfg MCPServerConfig
+	if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+	if cfg.TasksMode != "" {
+		t.Errorf("expected default TasksMode to be empty, got %q", cfg.TasksMode)
+	}
+}
+
+func TestConfig_Validate_TasksMode(t *testing.T) {
+	t.Run("empty is valid", func(t *testing.T) {
+		cfg := &Config{
+			MCPServers: map[string]MCPServerConfig{
+				"a": {Type: "remote", URL: "https://x.example"},
+			},
+		}
+		if err := cfg.Validate(); err != nil {
+			t.Errorf("empty TasksMode should validate, got %v", err)
+		}
+	})
+
+	t.Run("known values are valid", func(t *testing.T) {
+		for _, mode := range []string{"auto", "never", "always", "AUTO", " always "} {
+			cfg := &Config{
+				MCPServers: map[string]MCPServerConfig{
+					"a": {Type: "remote", URL: "https://x.example", TasksMode: mode},
+				},
+			}
+			if err := cfg.Validate(); err != nil {
+				t.Errorf("TasksMode=%q should validate, got %v", mode, err)
+			}
+		}
+	})
+
+	t.Run("typo is rejected with a clear error", func(t *testing.T) {
+		cfg := &Config{
+			MCPServers: map[string]MCPServerConfig{
+				"buildbot": {Type: "remote", URL: "https://x.example", TasksMode: "alwasy"},
+			},
+		}
+		err := cfg.Validate()
+		if err == nil {
+			t.Fatal("expected validation error for invalid TasksMode")
+		}
+		// Error must mention the server name AND the bad value so the
+		// user knows where to look.
+		msg := err.Error()
+		if !strings.Contains(msg, "buildbot") || !strings.Contains(msg, `"alwasy"`) {
+			t.Errorf("error %q should mention both server name and bad value", msg)
+		}
+	})
+}
@@ -72,6 +72,9 @@ type AgentSetupOptions struct {
 	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
 	// loading (successfully or with error). Called from the background goroutine.
 	OnMCPServerLoaded func(serverName string, toolCount int, err error)
+	// MCPTaskConfig configures task-augmented tools/call execution. The
+	// zero value preserves historical synchronous-only behaviour.
+	MCPTaskConfig tools.MCPTaskConfig
 }

 // AgentSetupResult bundles the created agent and any debug logger so the caller
@@ -229,6 +232,7 @@ func SetupAgent(ctx context.Context, opts AgentSetupOptions) (*AgentSetupResult,
 		ToolWrapper:       toolWrapper,
 		ExtraTools:        extraTools,
 		OnMCPServerLoaded: opts.OnMCPServerLoaded,
+		MCPTaskConfig:     opts.MCPTaskConfig,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to create agent: %w", err)
@@ -0,0 +1,70 @@
+package session
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestEncodeCwdForDir verifies the working-directory → session-directory
+// name encoding strips characters that are illegal on Windows (notably the
+// drive-letter colon, see issue #18) while preserving the previous output
+// for the typical Unix paths.
+func TestEncodeCwdForDir(t *testing.T) {
+	tests := []struct {
+		name string
+		cwd  string
+		want string
+	}{
+		{
+			name: "unix absolute path",
+			cwd:  "/home/user/proj",
+			want: "home--user--proj",
+		},
+		{
+			name: "unix relative path",
+			cwd:  "proj/sub",
+			want: "proj--sub",
+		},
+		{
+			name: "windows drive root",
+			cwd:  `C:\test`,
+			want: "C--test",
+		},
+		{
+			name: "windows nested path",
+			cwd:  `C:\Users\User\code`,
+			want: "C--Users--User--code",
+		},
+		{
+			name: "windows secondary drive",
+			cwd:  `S:\work\repo`,
+			want: "S--work--repo",
+		},
+		{
+			name: "windows mixed separators",
+			cwd:  `C:\Users/User\code`,
+			want: "C--Users--User--code",
+		},
+		{
+			name: "windows other illegal chars stripped",
+			cwd:  `C:\a<b>c|d?e*f"g`,
+			want: "C--abcdefg",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := encodeCwdForDir(tc.cwd)
+			if got != tc.want {
+				t.Errorf("encodeCwdForDir(%q) = %q, want %q", tc.cwd, got, tc.want)
+			}
+			// Encoded directory must never contain characters that are
+			// illegal in Windows directory names.
+			for _, bad := range []string{":", "<", ">", "\"", "|", "?", "*", "\\", "/"} {
+				if strings.Contains(got, bad) {
+					t.Errorf("encodeCwdForDir(%q) = %q contains illegal char %q", tc.cwd, got, bad)
+				}
+			}
+		})
+	}
+}
@@ -1350,15 +1350,44 @@ func (tm *TreeManager) buildTreeNodeDepth(id string, depth int, visited map[stri
 // --- Path conventions ---

 // DefaultSessionDir returns the default session storage directory for a cwd.
-// Convention: ~/.kit/sessions/--<cwd-path>--/
+// Convention: ~/.kit/sessions/<encoded-cwd>, where path separators are
+// encoded as "--" with no leading or trailing dashes — e.g.
+// /home/user/proj becomes home--user--proj. See encodeCwdForDir for the
+// full encoding rules (including Windows path handling).
 func DefaultSessionDir(cwd string) string {
 	home, err := os.UserHomeDir()
 	if err != nil {
 		home = "."
 	}
-	// Convert path separators to double dashes.
-	safeCwd := strings.ReplaceAll(cwd, string(filepath.Separator), "--")
+	return filepath.Join(home, ".kit", "sessions", encodeCwdForDir(cwd))
+}
+
+// encodeCwdForDir converts a working-directory path into a single, filesystem-
+// safe directory name. Path separators are replaced with double dashes and
+// characters that are illegal in Windows directory names — most importantly
+// the colon that follows the drive letter (e.g. `C:\foo` → `C--foo`) — are
+// stripped. The result is identical to the previous Unix-only encoding for
+// paths that do not contain such characters, so existing session directories
+// are preserved.
+func encodeCwdForDir(cwd string) string {
+	// Convert both `/` and `\` to double dashes so encoding is stable across
+	// platforms and remains correct on Windows where `filepath.Separator`
+	// would otherwise miss forward-slash style paths.
+	safeCwd := strings.ReplaceAll(cwd, "\\", "--")
+	safeCwd = strings.ReplaceAll(safeCwd, "/", "--")
 	// Remove leading separator replacement.
 	safeCwd = strings.TrimPrefix(safeCwd, "--")
-	return filepath.Join(home, ".kit", "sessions", safeCwd)
+	// Strip characters that are illegal in directory names on Windows
+	// (`< > : " | ? *`). On Unix these characters are legal but rare in
+	// practice; stripping them keeps the encoding portable.
+	replacer := strings.NewReplacer(
+		":", "",
+		"<", "",
+		">", "",
+		"\"", "",
+		"|", "",
+		"?", "",
+		"*", "",
+	)
+	return replacer.Replace(safeCwd)
 }
@@ -47,6 +47,7 @@ type MCPConnection struct {
 	client       client.MCPClient
 	serverName   string
 	serverConfig config.MCPServerConfig
+	initResult   *mcp.InitializeResult // captured at handshake; nil before initialize
 	lastUsed     time.Time
 	isHealthy    bool
 	errorCount   int
@@ -262,7 +263,9 @@ func (p *MCPConnectionPool) createConnection(ctx context.Context, serverName str
 		}
 	}

-	if err := p.initializeClient(ctx, mcpClient); err != nil {
+	conn := &MCPConnection{}
+
+	if err := p.initializeClient(ctx, mcpClient, conn); err != nil {
 		// Streamable HTTP transport returns OAuth error during Initialize()
 		if oauthEnabled && IsOAuthError(err) {
 			if flowErr := p.oauthFlow.RunAuthFlow(ctx, serverName, err); flowErr != nil {
@@ -270,7 +273,7 @@ func (p *MCPConnectionPool) createConnection(ctx context.Context, serverName str
 				return nil, fmt.Errorf("OAuth authorization failed: %w", flowErr)
 			}
 			// Retry initialization after successful auth
-			if err := p.initializeClient(ctx, mcpClient); err != nil {
+			if err := p.initializeClient(ctx, mcpClient, conn); err != nil {
 				_ = mcpClient.Close()
 				return nil, err
 			}
@@ -280,15 +283,11 @@ func (p *MCPConnectionPool) createConnection(ctx context.Context, serverName str
 		}
 	}

-	conn := &MCPConnection{
-		client:       mcpClient,
-		serverName:   serverName,
-		serverConfig: serverConfig,
-		lastUsed:     time.Now(),
-		isHealthy:    true,
-		errorCount:   0,
-		lastError:    nil,
-	}
+	conn.client = mcpClient
+	conn.serverName = serverName
+	conn.serverConfig = serverConfig
+	conn.lastUsed = time.Now()
+	conn.isHealthy = true

 	if p.debugLogger != nil && p.debugLogger.IsDebugEnabled() {
 		p.debugLogger.LogDebug(fmt.Sprintf("[POOL] Created connection for %s", serverName))
@@ -484,8 +483,10 @@ func (p *MCPConnectionPool) createTokenStore(serverURL string) (transport.TokenS
 	return NewFileTokenStore(serverURL)
 }

-// initializeClient initializes the client
-func (p *MCPConnectionPool) initializeClient(ctx context.Context, client client.MCPClient) error {
+// initializeClient initializes the client and captures the server's
+// initialize result on the supplied connection so callers can later
+// inspect advertised capabilities (e.g. task support).
+func (p *MCPConnectionPool) initializeClient(ctx context.Context, c client.MCPClient, conn *MCPConnection) error {
 	initCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
 	defer cancel()

@@ -495,12 +496,21 @@ func (p *MCPConnectionPool) initializeClient(ctx context.Context, client client.
 		Name:    "kit",
 		Version: "1.0.0",
 	}
-	initRequest.Params.Capabilities = mcp.ClientCapabilities{}
+	// Advertise task support so servers may return CreateTaskResult for
+	// long-running tools/call requests instead of blocking the connection
+	// until completion. The client is responsible for polling tasks/get and
+	// tasks/result until the task reaches a terminal state.
+	initRequest.Params.Capabilities = mcp.ClientCapabilities{
+		Tasks: mcp.NewTasksCapability(),
+	}

-	_, err := client.Initialize(initCtx, initRequest)
+	initResult, err := c.Initialize(initCtx, initRequest)
 	if err != nil {
 		return fmt.Errorf("initialization timeout or failed: %w", err)
 	}
+	if conn != nil {
+		conn.initResult = initResult
+	}

 	if p.debugLogger != nil && p.debugLogger.IsDebugEnabled() {
 		p.debugLogger.LogDebug("[POOL] Initialized MCP client")
@@ -615,6 +625,54 @@ func (c *MCPConnection) ServerName() string {
 	return c.serverName
 }

+// InitializeResult returns the result captured from the server's initialize
+// response, or nil if the connection was created before initialize completed.
+// Callers can inspect ServerCapabilities.Tasks to discover task-related
+// capability advertisements.
+func (c *MCPConnection) InitializeResult() *mcp.InitializeResult {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.initResult
+}
+
+// SupportsToolTasks reports whether the server advertised support for
+// task-augmented tools/call requests. Returns false when the connection has
+// not yet completed initialization or when the server omitted task
+// capabilities.
+func (c *MCPConnection) SupportsToolTasks() bool {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return supportsToolTasksFromInit(c.initResult)
+}
+
+// supportsToolTasksFromInit reports whether the supplied InitializeResult
+// advertises task-augmented tools/call support. Extracted to a free function
+// for unit testing without standing up a connection.
+func supportsToolTasksFromInit(init *mcp.InitializeResult) bool {
+	if init == nil || init.Capabilities.Tasks == nil {
+		return false
+	}
+	req := init.Capabilities.Tasks.Requests
+	if req == nil || req.Tools == nil {
+		return false
+	}
+	return req.Tools.Call != nil
+}
+
+// ServerSupportsToolTasks reports whether the named server's connection
+// advertises task-augmented tools/call support. Returns false when no
+// connection exists for the server or when the server didn't advertise the
+// capability.
+func (p *MCPConnectionPool) ServerSupportsToolTasks(serverName string) bool {
+	p.mu.RLock()
+	conn, ok := p.connections[serverName]
+	p.mu.RUnlock()
+	if !ok {
+		return false
+	}
+	return conn.SupportsToolTasks()
+}
+
 // GetClients returns a map of all MCP clients currently in the pool.
 // The map keys are server names and values are the corresponding MCP client instances.
 // The returned map is a copy and modifications won't affect the pool.
@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/base64"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"maps"
 	"slices"
@@ -13,6 +14,7 @@ import (
 	log "github.com/charmbracelet/log"

 	"github.com/mark3labs/kit/internal/config"
+	"github.com/mark3labs/mcp-go/client"
 	"github.com/mark3labs/mcp-go/mcp"
 )

@@ -141,6 +143,11 @@ type MCPToolManager struct {
 	debug             bool
 	debugLogger       DebugLogger

+	// taskCfg controls task-augmented tools/call execution. The zero value
+	// means: auto-detect server capability, no progress callback, default
+	// poll/timeout.
+	taskCfg MCPTaskConfig
+
 	// onServerLoaded, if non-nil, is called when each server finishes loading.
 	// Called with server name, tool count, and error (nil on success).
 	onServerLoaded func(serverName string, toolCount int, err error)
@@ -220,6 +227,21 @@ func (m *MCPToolManager) SetOnToolsChanged(cb func()) {
 	m.onToolsChanged = cb
 }

+// SetTaskConfig sets the task-augmented tools/call configuration. Call
+// this before LoadTools / AddServer if you want the per-server mode
+// override and progress handler to take effect for the very first call.
+// Subsequent calls replace the previous configuration wholesale.
+func (m *MCPToolManager) SetTaskConfig(cfg MCPTaskConfig) {
+	m.taskCfg = cfg
+}
+
+// TaskConfig returns the manager's current task-augmented tools/call
+// configuration. The zero value means: defer to per-server config and
+// auto-detected capability, with no progress callback and default polling.
+func (m *MCPToolManager) TaskConfig() MCPTaskConfig {
+	return m.taskCfg
+}
+
 // AddServer connects to a new MCP server at runtime and loads its tools.
 // The server's tools are immediately available to the agent after this call.
 // Returns the number of tools loaded from the server.
@@ -551,6 +573,14 @@ func (m *MCPToolManager) loadServerTools(ctx context.Context, serverName string,
 // checks, OAuth re-authorization, and connection error tracking.
 // The inputJSON parameter is the raw JSON arguments from the LLM.
 // Returns the result content, error flag, and any execution error.
+//
+// When the per-server TasksMode resolves to "always", or to "auto" and the
+// server advertised tasks/toolCalls capability during initialize, the call
+// is augmented with TaskParams. If the server elects to respond with a
+// CreateTaskResult the manager polls tasks/get / tasks/result until the
+// task reaches a terminal state, transparently presenting the final
+// CallToolResult-equivalent content to the agent layer. Context
+// cancellation triggers a best-effort tasks/cancel.
 func (m *MCPToolManager) ExecuteTool(ctx context.Context, prefixedName, inputJSON string) (*MCPToolResult, error) {
 	m.mu.Lock()
 	mapping, ok := m.toolMap[prefixedName]
@@ -582,49 +612,221 @@ func (m *MCPToolManager) ExecuteTool(ctx context.Context, prefixedName, inputJSO
 		return nil, fmt.Errorf("failed to get healthy connection from pool: %w", err)
 	}

-	callRequest := mcp.CallToolRequest{
-		Request: mcp.Request{
-			Method: "tools/call",
-		},
-		Params: mcp.CallToolParams{
-			Name:      mapping.originalName,
-			Arguments: arguments,
-		},
+	callParams := mcp.CallToolParams{
+		Name:      mapping.originalName,
+		Arguments: arguments,
 	}

-	// Call the MCP tool using the original (unprefixed) name
-	result, err := conn.client.CallTool(ctx, callRequest)
-	if err != nil {
-		// Handle OAuth re-authorization: token may have expired mid-session.
-		if m.connectionPool.oauthFlow != nil && IsOAuthError(err) {
-			if flowErr := m.connectionPool.oauthFlow.RunAuthFlow(ctx, mapping.serverName, err); flowErr != nil {
+	// Decide whether to augment the request with TaskParams. Modes:
+	//   never  — never augment (synchronous-only).
+	//   always — always augment, even without server capability.
+	//   auto   — augment only when the server advertised tasks/toolCalls.
+	mode := m.resolveTaskMode(mapping.serverName, mapping.serverConfig)
+	useTask := mode == MCPTaskModeAlways ||
+		(mode == MCPTaskModeAuto && conn.SupportsToolTasks())
+	if useTask {
+		var ttl *int64
+		if m.taskCfg.DefaultTTL > 0 {
+			ms := m.taskCfg.DefaultTTL.Milliseconds()
+			ttl = &ms
+		}
+		callParams.Task = &mcp.TaskParams{TTL: ttl}
+	}
+
+	// Synchronous fast path: no task augmentation. Use the upstream client
+	// helper which keeps content-block typing identical to historical
+	// behaviour.
+	if !useTask {
+		callRequest := mcp.CallToolRequest{
+			Request: mcp.Request{Method: "tools/call"},
+			Params:  callParams,
+		}
+		result, callErr := conn.client.CallTool(ctx, callRequest)
+		if callErr != nil {
+			if m.connectionPool.oauthFlow != nil && IsOAuthError(callErr) {
+				if flowErr := m.connectionPool.oauthFlow.RunAuthFlow(ctx, mapping.serverName, callErr); flowErr != nil {
+					return nil, fmt.Errorf("OAuth re-authorization failed for tool %s: %w", mapping.originalName, flowErr)
+				}
+				result, callErr = conn.client.CallTool(ctx, callRequest)
+				if callErr != nil {
+					m.connectionPool.HandleConnectionError(mapping.serverName, callErr)
+					return nil, fmt.Errorf("failed to call mcp tool after re-auth: %w", callErr)
+				}
+			} else {
+				m.connectionPool.HandleConnectionError(mapping.serverName, callErr)
+				return nil, fmt.Errorf("failed to call mcp tool: %w", callErr)
+			}
+		}
+		marshaledResult, mErr := json.Marshal(result)
+		if mErr != nil {
+			return nil, fmt.Errorf("failed to marshal mcp tool result: %w", mErr)
+		}
+		return &MCPToolResult{
+			Content: string(marshaledResult),
+			IsError: result.IsError,
+		}, nil
+	}
+
+	// Task-augmented path. Bypass the upstream CallTool helper because its
+	// ParseCallToolResult requires a "content" field that is absent from a
+	// CreateTaskResult.
+	rawClient, ok := conn.client.(*client.Client)
+	if !ok {
+		// Older client implementations — fall back to the synchronous shape.
+		callParams.Task = nil
+		callRequest := mcp.CallToolRequest{
+			Request: mcp.Request{Method: "tools/call"},
+			Params:  callParams,
+		}
+		result, callErr := conn.client.CallTool(ctx, callRequest)
+		if callErr != nil {
+			m.connectionPool.HandleConnectionError(mapping.serverName, callErr)
+			return nil, fmt.Errorf("failed to call mcp tool: %w", callErr)
+		}
+		marshaledResult, mErr := json.Marshal(result)
+		if mErr != nil {
+			return nil, fmt.Errorf("failed to marshal mcp tool result: %w", mErr)
+		}
+		return &MCPToolResult{Content: string(marshaledResult), IsError: result.IsError}, nil
+	}
+
+	callResult, taskResult, callErr := callToolWithTask(ctx, rawClient, callParams)
+	if callErr != nil {
+		if m.connectionPool.oauthFlow != nil && IsOAuthError(callErr) {
+			if flowErr := m.connectionPool.oauthFlow.RunAuthFlow(ctx, mapping.serverName, callErr); flowErr != nil {
 				return nil, fmt.Errorf("OAuth re-authorization failed for tool %s: %w", mapping.originalName, flowErr)
 			}
-			// Retry the tool call after successful re-auth.
-			result, err = conn.client.CallTool(ctx, callRequest)
-			if err != nil {
-				m.connectionPool.HandleConnectionError(mapping.serverName, err)
-				return nil, fmt.Errorf("failed to call mcp tool after re-auth: %w", err)
+			callResult, taskResult, callErr = callToolWithTask(ctx, rawClient, callParams)
+			if callErr != nil {
+				m.connectionPool.HandleConnectionError(mapping.serverName, callErr)
+				return nil, fmt.Errorf("failed to call mcp tool after re-auth: %w", callErr)
 			}
 		} else {
-			// Mark connection as unhealthy for automatic recovery
-			m.connectionPool.HandleConnectionError(mapping.serverName, err)
-			return nil, fmt.Errorf("failed to call mcp tool: %w", err)
+			m.connectionPool.HandleConnectionError(mapping.serverName, callErr)
+			return nil, fmt.Errorf("failed to call mcp tool: %w", callErr)
 		}
 	}

-	// Marshal the MCP result to JSON string
-	marshaledResult, err := json.Marshal(result)
-	if err != nil {
-		return nil, fmt.Errorf("failed to marshal mcp tool result: %w", err)
+	// Server chose to answer synchronously — same shape as the no-task path.
+	if callResult != nil {
+		marshaledResult, mErr := json.Marshal(callResult)
+		if mErr != nil {
+			return nil, fmt.Errorf("failed to marshal mcp tool result: %w", mErr)
+		}
+		return &MCPToolResult{
+			Content: string(marshaledResult),
+			IsError: callResult.IsError,
+		}, nil
 	}

+	// Asynchronous task path: poll until terminal, then return the result.
+	if taskResult == nil {
+		return nil, errors.New("mcp tools/call returned neither result nor task")
+	}
+	final, pollErr := pollTaskUntilTerminal(
+		ctx, rawClient, mapping.serverName, taskResult.Task,
+		m.taskCfg, m.taskCfg.Progress,
+	)
+	if pollErr != nil {
+		return nil, fmt.Errorf("task execution failed: %w", pollErr)
+	}
+
+	// Adapt TaskResultResult → CallToolResult for downstream JSON shape parity.
+	adapted := &mcp.CallToolResult{
+		Content:           final.Content,
+		StructuredContent: final.StructuredContent,
+		IsError:           final.IsError,
+	}
+	marshaledResult, mErr := json.Marshal(adapted)
+	if mErr != nil {
+		return nil, fmt.Errorf("failed to marshal mcp tool result: %w", mErr)
+	}
 	return &MCPToolResult{
 		Content: string(marshaledResult),
-		IsError: result.IsError,
+		IsError: final.IsError,
 	}, nil
 }

+// resolveTaskMode resolves the effective task mode for a given server.
+// Programmatic overrides via SetTaskConfig take precedence over the
+// per-server TasksMode in MCPServerConfig. Empty / unknown values map to
+// MCPTaskModeAuto.
+func (m *MCPToolManager) resolveTaskMode(name string, cfg config.MCPServerConfig) MCPTaskMode {
+	if m.taskCfg.PerServerMode != nil {
+		if v, ok := m.taskCfg.PerServerMode[name]; ok {
+			return v
+		}
+	}
+	return ParseTaskMode(cfg.TasksMode)
+}
+
+// ListServerTasks queries tasks/list on the named server and returns the
+// active and recent tasks the server is willing to disclose. Errors are
+// returned untouched (callers commonly ignore METHOD_NOT_FOUND when the
+// server didn't advertise tasks/list capability).
+func (m *MCPToolManager) ListServerTasks(ctx context.Context, serverName string) ([]MCPTaskInfo, error) {
+	c, err := m.taskClient(serverName)
+	if err != nil {
+		return nil, err
+	}
+	res, err := c.ListTasks(ctx, mcp.ListTasksRequest{})
+	if err != nil {
+		return nil, fmt.Errorf("tasks/list on %s: %w", serverName, err)
+	}
+	out := make([]MCPTaskInfo, 0, len(res.Tasks))
+	for _, t := range res.Tasks {
+		out = append(out, taskFromMCP(serverName, t))
+	}
+	return out, nil
+}
+
+// GetServerTask queries tasks/get for a single task on the named server.
+func (m *MCPToolManager) GetServerTask(ctx context.Context, serverName, taskID string) (MCPTaskInfo, error) {
+	c, err := m.taskClient(serverName)
+	if err != nil {
+		return MCPTaskInfo{}, err
+	}
+	res, err := c.GetTask(ctx, mcp.GetTaskRequest{Params: mcp.GetTaskParams{TaskId: taskID}})
+	if err != nil {
+		return MCPTaskInfo{}, fmt.Errorf("tasks/get on %s: %w", serverName, err)
+	}
+	return taskFromMCP(serverName, res.Task), nil
+}
+
+// CancelServerTask issues tasks/cancel for a task on the named server.
+// Returns the post-cancel task state when the server responded with one.
+func (m *MCPToolManager) CancelServerTask(ctx context.Context, serverName, taskID string) (MCPTaskInfo, error) {
+	c, err := m.taskClient(serverName)
+	if err != nil {
+		return MCPTaskInfo{}, err
+	}
+	res, err := c.CancelTask(ctx, mcp.CancelTaskRequest{Params: mcp.CancelTaskParams{TaskId: taskID}})
+	if err != nil {
+		return MCPTaskInfo{}, fmt.Errorf("tasks/cancel on %s: %w", serverName, err)
+	}
+	return taskFromMCP(serverName, res.Task), nil
+}
+
+// taskClient returns the *client.Client for a server. Tasks endpoints are
+// not part of the upstream MCPClient interface so callers must work with
+// the concrete client. Returns an error when the connection is missing
+// or backed by a non-standard client type.
+func (m *MCPToolManager) taskClient(serverName string) (*client.Client, error) {
+	if m.connectionPool == nil {
+		return nil, fmt.Errorf("no connection pool available")
+	}
+	clients := m.connectionPool.GetClients()
+	raw, ok := clients[serverName]
+	if !ok {
+		return nil, fmt.Errorf("MCP server %q not loaded", serverName)
+	}
+	c, ok := raw.(*client.Client)
+	if !ok {
+		return nil, fmt.Errorf("MCP server %q does not support task RPCs", serverName)
+	}
+	return c, nil
+}
+
 // GetTools returns all loaded MCP tools from all configured MCP servers.
 // Tools are returned with their prefixed names (serverName__toolName) to ensure uniqueness.
 func (m *MCPToolManager) GetTools() []MCPTool {
@@ -0,0 +1,404 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"github.com/mark3labs/mcp-go/client"
+	"github.com/mark3labs/mcp-go/client/transport"
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+// MCPTaskMode controls when the connection pool augments tools/call requests
+// with MCP task metadata. See https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks.
+type MCPTaskMode string
+
+const (
+	// MCPTaskModeAuto augments tools/call with task metadata only when the
+	// server advertises tasks/toolCalls capability during initialize.
+	MCPTaskModeAuto MCPTaskMode = "auto"
+	// MCPTaskModeNever forces every tools/call to be issued synchronously
+	// (no Task field in the request), regardless of server capability.
+	MCPTaskModeNever MCPTaskMode = "never"
+	// MCPTaskModeAlways always sets a Task field on the tools/call request,
+	// even when the server didn't advertise task support. The server may
+	// still respond synchronously; this just opts in unconditionally on
+	// the client side.
+	MCPTaskModeAlways MCPTaskMode = "always"
+)
+
+// ParseTaskMode normalises a per-server tasks-mode string from
+// configuration. Empty input maps to MCPTaskModeAuto. Unknown values are
+// also treated as MCPTaskModeAuto so a stray config typo never breaks
+// existing flows.
+func ParseTaskMode(s string) MCPTaskMode {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "", "auto":
+		return MCPTaskModeAuto
+	case "never", "off", "disabled":
+		return MCPTaskModeNever
+	case "always", "force":
+		return MCPTaskModeAlways
+	default:
+		return MCPTaskModeAuto
+	}
+}
+
+// MCPTaskInfo is the connection-layer view of an MCP Task. It mirrors the
+// upstream mcp.Task but exposes Go-native types and includes the originating
+// server name. SDK-level wrappers re-export this under public-facing names.
+type MCPTaskInfo struct {
+	// Server is the configured MCP server name this task lives on.
+	Server string
+	// TaskID is the server-assigned identifier for the task.
+	TaskID string
+	// Status is the current task lifecycle state.
+	Status mcp.TaskStatus
+	// StatusMessage is an optional human-readable description.
+	StatusMessage string
+	// CreatedAt is the wall-clock time the task was created (best-effort
+	// parsed from the server's ISO-8601 timestamp; zero on parse failure).
+	CreatedAt time.Time
+	// UpdatedAt is the wall-clock time the task was last updated (best-
+	// effort parsed; zero on parse failure).
+	UpdatedAt time.Time
+	// TTL is the time-to-live the server intends to retain the task after
+	// creation. Zero means the server did not advertise a TTL.
+	TTL time.Duration
+	// PollInterval is the suggested polling interval. Zero means use the
+	// client's default.
+	PollInterval time.Duration
+}
+
+// MCPTaskProgress is emitted while the connection pool is waiting on a
+// task-augmented tool call. It provides minimal feedback for SDK consumers
+// that want to render progress widgets without subscribing to the full
+// notifications/tasks/status channel (Phase 2).
+type MCPTaskProgress struct {
+	Server  string
+	TaskID  string
+	Status  mcp.TaskStatus
+	Message string
+}
+
+// MCPTaskProgressHandler is invoked once after a task is accepted and on
+// every status transition observed by the polling loop. The final
+// invocation always carries a terminal status. Implementations must not
+// block; long work should be queued on a goroutine.
+type MCPTaskProgressHandler func(MCPTaskProgress)
+
+// MCPTaskConfig configures task-aware tool execution on the manager.
+// All fields are optional; the zero value disables progress callbacks and
+// applies sensible defaults.
+type MCPTaskConfig struct {
+	// PerServerMode overrides the per-server TasksMode resolved from
+	// MCPServerConfig. Keys are server names. Missing entries fall back
+	// to the value from config. Used by SDK consumers that want to set
+	// modes programmatically.
+	PerServerMode map[string]MCPTaskMode
+
+	// DefaultTTL is the TTL hint sent in TaskParams when augmenting a
+	// tools/call. Zero means omit the TTL — let the server pick its own.
+	DefaultTTL time.Duration
+
+	// PollInterval is the fallback interval between tasks/get requests
+	// when the server does not suggest one. Zero defaults to 1 second.
+	PollInterval time.Duration
+
+	// MaxPollInterval caps the polling interval. Zero defaults to 5 seconds.
+	MaxPollInterval time.Duration
+
+	// Timeout is the maximum wall-clock duration to wait for a task to
+	// reach a terminal state. Zero defaults to 15 minutes. Independent
+	// of the per-call context deadline; whichever fires first wins.
+	Timeout time.Duration
+
+	// Progress, if non-nil, receives every status transition observed by
+	// the polling loop.
+	Progress MCPTaskProgressHandler
+}
+
+func (c MCPTaskConfig) resolved() MCPTaskConfig {
+	if c.PollInterval <= 0 {
+		c.PollInterval = 1 * time.Second
+	}
+	if c.MaxPollInterval <= 0 {
+		c.MaxPollInterval = 5 * time.Second
+	}
+	if c.Timeout <= 0 {
+		c.Timeout = 15 * time.Minute
+	}
+	return c
+}
+
+// requestIDCounter generates monotonically increasing JSON-RPC request IDs
+// for low-level tools/call invocations that bypass the upstream client's
+// ParseCallToolResult helper (necessary because that helper rejects task
+// responses for lacking a "content" field).
+//
+// The counter is process-wide rather than per-manager so multiple managers
+// or repeated calls within the same connection produce unique IDs.
+var requestIDCounter atomic.Int64
+
+func nextRequestID() mcp.RequestId {
+	return mcp.NewRequestId(requestIDCounter.Add(1))
+}
+
+// callToolWithTask issues tools/call directly on the transport so we can
+// observe both response shapes:
+//
+//   - {"content": [...], ...}  — synchronous CallToolResult.
+//   - {"task": {...}, ...}     — asynchronous CreateTaskResult.
+//
+// On success exactly one of (callResult, taskResult) is non-nil. The
+// upstream client.CallTool helper parses the response with
+// mcp.ParseCallToolResult which requires a "content" field, so it cannot
+// be used for task-augmented calls.
+func callToolWithTask(
+	ctx context.Context,
+	c *client.Client,
+	params mcp.CallToolParams,
+) (callResult *mcp.CallToolResult, taskResult *mcp.CreateTaskResult, err error) {
+	tr := c.GetTransport()
+	if tr == nil {
+		return nil, nil, errors.New("mcp client has no transport")
+	}
+
+	req := transport.JSONRPCRequest{
+		JSONRPC: mcp.JSONRPC_VERSION,
+		ID:      nextRequestID(),
+		Method:  string(mcp.MethodToolsCall),
+		Params:  params,
+	}
+
+	resp, sendErr := tr.SendRequest(ctx, req)
+	if sendErr != nil {
+		return nil, nil, sendErr
+	}
+	if resp.Error != nil {
+		return nil, nil, resp.Error.AsError()
+	}
+
+	// Peek at the raw result to decide which shape we got.
+	var probe struct {
+		Task    json.RawMessage `json:"task"`
+		Content json.RawMessage `json:"content"`
+	}
+	raw := resp.Result
+	if len(raw) == 0 {
+		return nil, nil, errors.New("empty tools/call result")
+	}
+	if uErr := json.Unmarshal(raw, &probe); uErr != nil {
+		return nil, nil, fmt.Errorf("decode tools/call result: %w", uErr)
+	}
+
+	if len(probe.Task) > 0 && string(probe.Task) != "null" {
+		// Task-augmented response.
+		var ct mcp.CreateTaskResult
+		if uErr := json.Unmarshal(raw, &ct); uErr != nil {
+			return nil, nil, fmt.Errorf("decode CreateTaskResult: %w", uErr)
+		}
+		return nil, &ct, nil
+	}
+
+	// Synchronous response — defer to the upstream parser so content blocks
+	// are typed correctly (TextContent, ImageContent, ResourceLink, etc.).
+	cr, pErr := mcp.ParseCallToolResult(&raw)
+	if pErr != nil {
+		return nil, nil, fmt.Errorf("parse CallToolResult: %w", pErr)
+	}
+	return cr, nil, nil
+}
+
+// pollTaskUntilTerminal blocks until the task reaches a terminal status,
+// the context is cancelled, or the configured timeout elapses. On
+// cancellation it best-effort issues tasks/cancel before returning.
+func pollTaskUntilTerminal(
+	ctx context.Context,
+	c *client.Client,
+	serverName string,
+	task mcp.Task,
+	cfg MCPTaskConfig,
+	progress MCPTaskProgressHandler,
+) (*mcp.TaskResultResult, error) {
+	cfg = cfg.resolved()
+	deadline := time.Now().Add(cfg.Timeout)
+
+	emit := func(status mcp.TaskStatus, msg string) {
+		if progress != nil {
+			progress(MCPTaskProgress{Server: serverName, TaskID: task.TaskId, Status: status, Message: msg})
+		}
+	}
+
+	emit(task.Status, task.StatusMessage)
+
+	current := task
+	interval := cfg.PollInterval
+	if current.PollInterval != nil && *current.PollInterval > 0 {
+		interval = time.Duration(*current.PollInterval) * time.Millisecond
+	}
+	if interval > cfg.MaxPollInterval {
+		interval = cfg.MaxPollInterval
+	}
+
+	for !current.Status.IsTerminal() {
+		if time.Now().After(deadline) {
+			cancelTaskBestEffort(c, current.TaskId)
+			return nil, fmt.Errorf("task %s timed out after %s", current.TaskId, cfg.Timeout)
+		}
+
+		// Wait between polls or abort early on context cancellation.
+		select {
+		case <-ctx.Done():
+			cancelTaskBestEffort(c, current.TaskId)
+			return nil, ctx.Err()
+		case <-time.After(interval):
+		}
+
+		got, err := c.GetTask(ctx, mcp.GetTaskRequest{
+			Params: mcp.GetTaskParams{TaskId: current.TaskId},
+		})
+		if err != nil {
+			// Transient transport hiccup — propagate immediately. The
+			// upstream agent layer treats this like any other tool error.
+			return nil, fmt.Errorf("tasks/get failed: %w", err)
+		}
+		current = got.Task
+		if current.Status != task.Status || current.StatusMessage != task.StatusMessage {
+			emit(current.Status, current.StatusMessage)
+			task = current
+		}
+
+		// Honour any updated suggested poll interval, capped at the limit.
+		if current.PollInterval != nil && *current.PollInterval > 0 {
+			interval = min(time.Duration(*current.PollInterval)*time.Millisecond, cfg.MaxPollInterval)
+		}
+	}
+
+	// Terminal state reached. Emit one last progress event and fetch the
+	// definitive tool result.
+	emit(current.Status, current.StatusMessage)
+
+	if current.Status == mcp.TaskStatusCancelled {
+		return nil, fmt.Errorf("task %s was cancelled", current.TaskId)
+	}
+
+	res, err := fetchTaskResult(ctx, c, current.TaskId)
+	if err != nil {
+		return nil, fmt.Errorf("tasks/result failed: %w", err)
+	}
+	if current.Status == mcp.TaskStatusFailed && res != nil && !res.IsError {
+		// The server flagged the task as failed but didn't decorate the
+		// result. Surface the status message so the caller still sees a
+		// useful tool-error.
+		return nil, fmt.Errorf("task %s failed: %s", current.TaskId, current.StatusMessage)
+	}
+	return res, nil
+}
+
+// fetchTaskResult issues tasks/result on the transport and parses the raw
+// response. The upstream client.TaskResult helper delegates to
+// mcp.ParseTaskResultResult which (as of mcp-go v0.51.0) looks for the
+// content array under a nested "result" key that never exists in the
+// wire format — leading to systematically empty Content. Doing the
+// parse here keeps the polling path working until that is fixed upstream.
+func fetchTaskResult(ctx context.Context, c *client.Client, taskID string) (*mcp.TaskResultResult, error) {
+	tr := c.GetTransport()
+	if tr == nil {
+		return nil, errors.New("mcp client has no transport")
+	}
+	req := transport.JSONRPCRequest{
+		JSONRPC: mcp.JSONRPC_VERSION,
+		ID:      nextRequestID(),
+		Method:  string(mcp.MethodTasksResult),
+		Params:  mcp.TaskResultParams{TaskId: taskID},
+	}
+	resp, err := tr.SendRequest(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	if resp.Error != nil {
+		return nil, resp.Error.AsError()
+	}
+
+	// Manually decode the wire shape: {"_meta": {...}, "content": [...],
+	// "structuredContent": ..., "isError": bool}.
+	var shape struct {
+		Meta              json.RawMessage   `json:"_meta"`
+		Content           []json.RawMessage `json:"content"`
+		StructuredContent any               `json:"structuredContent"`
+		IsError           bool              `json:"isError"`
+	}
+	if err := json.Unmarshal(resp.Result, &shape); err != nil {
+		return nil, fmt.Errorf("decode tasks/result: %w", err)
+	}
+
+	out := &mcp.TaskResultResult{
+		StructuredContent: shape.StructuredContent,
+		IsError:           shape.IsError,
+	}
+	if len(shape.Meta) > 0 && string(shape.Meta) != "null" {
+		var metaMap map[string]any
+		if err := json.Unmarshal(shape.Meta, &metaMap); err == nil {
+			out.Meta = mcp.NewMetaFromMap(metaMap)
+		}
+	}
+	for _, raw := range shape.Content {
+		var contentMap map[string]any
+		if err := json.Unmarshal(raw, &contentMap); err != nil {
+			return nil, fmt.Errorf("decode content block: %w", err)
+		}
+		parsed, err := mcp.ParseContent(contentMap)
+		if err != nil {
+			return nil, fmt.Errorf("parse content block: %w", err)
+		}
+		out.Content = append(out.Content, parsed)
+	}
+	return out, nil
+}
+
+// cancelTaskBestEffort issues tasks/cancel and ignores any error. Used on
+// context cancellation paths where the connection is already going away.
+func cancelTaskBestEffort(c *client.Client, taskID string) {
+	if c == nil || taskID == "" {
+		return
+	}
+	cancelCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	_, _ = c.CancelTask(cancelCtx, mcp.CancelTaskRequest{
+		Params: mcp.CancelTaskParams{TaskId: taskID},
+	})
+}
+
+// taskFromMCP converts a wire-format mcp.Task to our richer connection-
+// layer view. Unparseable timestamps surface as the zero time.
+func taskFromMCP(serverName string, t mcp.Task) MCPTaskInfo {
+	out := MCPTaskInfo{
+		Server:        serverName,
+		TaskID:        t.TaskId,
+		Status:        t.Status,
+		StatusMessage: t.StatusMessage,
+	}
+	if t.CreatedAt != "" {
+		if v, err := time.Parse(time.RFC3339, t.CreatedAt); err == nil {
+			out.CreatedAt = v
+		}
+	}
+	if t.LastUpdatedAt != "" {
+		if v, err := time.Parse(time.RFC3339, t.LastUpdatedAt); err == nil {
+			out.UpdatedAt = v
+		}
+	}
+	if t.TTL != nil {
+		out.TTL = time.Duration(*t.TTL) * time.Millisecond
+	}
+	if t.PollInterval != nil {
+		out.PollInterval = time.Duration(*t.PollInterval) * time.Millisecond
+	}
+	return out
+}
@@ -0,0 +1,294 @@
+package tools
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/mark3labs/kit/internal/config"
+	"github.com/mark3labs/mcp-go/mcp"
+	"github.com/mark3labs/mcp-go/server"
+)
+
+// newTaskTestInProcessServer builds an in-process MCP server with a
+// task-augmented tool. The handler simulates work by sleeping briefly
+// before completing.
+//
+// Important: the upstream mcp-go server cancels the request context as
+// soon as the synchronous part of the tools/call returns (see
+// request_handler.go:85, `defer cancel()`). Task goroutines spawned by
+// AddTaskTool inherit that context and therefore see context.Canceled
+// the instant they start. Real-world transports (stdio, SSE, streamable
+// HTTP) don't trip this because they keep the connection — and a
+// background context — alive across the async work, but the in-process
+// transport runs entirely on the request goroutine. To test the polling
+// path realistically we detach from the request context here.
+func newTaskTestInProcessServer(t *testing.T, workDuration time.Duration) *server.MCPServer {
+	t.Helper()
+	srv := server.NewMCPServer("task-test", "1.0.0",
+		server.WithToolCapabilities(true),
+		// list=true, cancel=true, toolCallTasks=true so capability detection,
+		// cancellation, and tool augmentation all flow through.
+		server.WithTaskCapabilities(true, true, true),
+	)
+	srv.AddTaskTool(
+		mcp.Tool{
+			Name:        "long_running",
+			Description: "Sleep, then echo the input string.",
+			InputSchema: mcp.ToolInputSchema{
+				Type: "object",
+				Properties: map[string]any{
+					"msg": map[string]any{"type": "string"},
+				},
+			},
+			Execution: &mcp.ToolExecution{
+				TaskSupport: mcp.TaskSupportRequired,
+			},
+		},
+		func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CreateTaskResult, error) {
+			msg, _ := req.GetArguments()["msg"].(string)
+			// Detach from the request context so the task handler can
+			// outlive the synchronous request — see comment above.
+			time.Sleep(workDuration)
+			_ = ctx
+			return &mcp.CreateTaskResult{
+				Content: []mcp.Content{
+					mcp.TextContent{Type: "text", Text: "echo:" + msg},
+				},
+			}, nil
+		},
+	)
+	return srv
+}
+
+// newSyncOnlyServer is a server that does NOT advertise task capability.
+// Used to verify the auto-detect path keeps the sync semantics.
+func newSyncOnlyServer() *server.MCPServer {
+	srv := server.NewMCPServer("sync-only", "1.0.0",
+		server.WithToolCapabilities(true),
+	)
+	srv.AddTool(
+		mcp.NewTool("greet",
+			mcp.WithDescription("Say hello"),
+			mcp.WithString("name", mcp.Required()),
+		),
+		func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			name, _ := req.GetArguments()["name"].(string)
+			return mcp.NewToolResultText("hi " + name), nil
+		},
+	)
+	return srv
+}
+
+func TestConnectionPoolAdvertisesTaskCapability(t *testing.T) {
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	defer func() { _ = pool.Close() }()
+
+	srv := newTaskTestInProcessServer(t, 0)
+	cfg := config.MCPServerConfig{Type: "inprocess", InProcessServer: srv}
+
+	conn, err := pool.GetConnection(context.Background(), "tasks", cfg)
+	if err != nil {
+		t.Fatalf("GetConnection: %v", err)
+	}
+
+	init := conn.InitializeResult()
+	if init == nil {
+		t.Fatal("InitializeResult is nil after GetConnection")
+	}
+	if init.Capabilities.Tasks == nil {
+		t.Fatal("server did not advertise Tasks capability — initialize handshake regressed")
+	}
+	if !conn.SupportsToolTasks() {
+		t.Error("SupportsToolTasks should be true for a server with toolCallTasks=true")
+	}
+	if !pool.ServerSupportsToolTasks("tasks") {
+		t.Error("ServerSupportsToolTasks should mirror the connection's value")
+	}
+}
+
+func TestConnectionPoolDetectsAbsentTaskCapability(t *testing.T) {
+	pool := NewMCPConnectionPool(DefaultConnectionPoolConfig(), false, nil, nil)
+	defer func() { _ = pool.Close() }()
+
+	cfg := config.MCPServerConfig{Type: "inprocess", InProcessServer: newSyncOnlyServer()}
+	conn, err := pool.GetConnection(context.Background(), "sync", cfg)
+	if err != nil {
+		t.Fatalf("GetConnection: %v", err)
+	}
+	if conn.SupportsToolTasks() {
+		t.Error("SupportsToolTasks should be false for a server that didn't advertise the capability")
+	}
+}
+
+func TestSupportsToolTasksFromInit(t *testing.T) {
+	cases := []struct {
+		name string
+		in   *mcp.InitializeResult
+		want bool
+	}{
+		{"nil", nil, false},
+		{"no tasks", &mcp.InitializeResult{}, false},
+		{"tasks no requests", &mcp.InitializeResult{
+			Capabilities: mcp.ServerCapabilities{Tasks: &mcp.TasksCapability{}},
+		}, false},
+		{"tasks with toolCalls", &mcp.InitializeResult{
+			Capabilities: mcp.ServerCapabilities{Tasks: mcp.NewTasksCapability()},
+		}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := supportsToolTasksFromInit(tc.in); got != tc.want {
+				t.Errorf("supportsToolTasksFromInit() = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestParseTaskMode(t *testing.T) {
+	cases := []struct {
+		in   string
+		want MCPTaskMode
+	}{
+		{"", MCPTaskModeAuto},
+		{"auto", MCPTaskModeAuto},
+		{"AUTO", MCPTaskModeAuto},
+		{"never", MCPTaskModeNever},
+		{"off", MCPTaskModeNever},
+		{"always", MCPTaskModeAlways},
+		{"force", MCPTaskModeAlways},
+		{"bogus", MCPTaskModeAuto},
+	}
+	for _, tc := range cases {
+		if got := ParseTaskMode(tc.in); got != tc.want {
+			t.Errorf("ParseTaskMode(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}
+
+func TestExecuteToolPollsTaskToCompletion(t *testing.T) {
+	mgr := NewMCPToolManager()
+	mgr.SetTaskConfig(MCPTaskConfig{
+		PollInterval:    20 * time.Millisecond,
+		MaxPollInterval: 50 * time.Millisecond,
+		Timeout:         10 * time.Second,
+	})
+
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: newTaskTestInProcessServer(t, 50*time.Millisecond),
+	}
+
+	if _, err := mgr.AddServer(context.Background(), "tasks", cfg); err != nil {
+		t.Fatalf("AddServer: %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	res, err := mgr.ExecuteTool(ctx, "tasks__long_running", `{"msg":"hello"}`)
+	if err != nil {
+		t.Fatalf("ExecuteTool: %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("expected non-error result, got %s", res.Content)
+	}
+	if !strings.Contains(res.Content, "echo:hello") {
+		t.Errorf("expected result to contain 'echo:hello', got %s", res.Content)
+	}
+}
+
+func TestExecuteToolHonorsNeverMode(t *testing.T) {
+	// Even though the server advertises tasks/toolCalls, "never" should
+	// keep the call synchronous. Since the tool is TaskSupportRequired,
+	// the server returns an error rather than running it sync — we just
+	// verify the error surfaces (not a poll-loop hang).
+	mgr := NewMCPToolManager()
+	mgr.SetTaskConfig(MCPTaskConfig{
+		PerServerMode: map[string]MCPTaskMode{"tasks": MCPTaskModeNever},
+		Timeout:       2 * time.Second,
+	})
+
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: newTaskTestInProcessServer(t, 0),
+	}
+
+	if _, err := mgr.AddServer(context.Background(), "tasks", cfg); err != nil {
+		t.Fatalf("AddServer: %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	// We don't care which way the server fails the sync call; we just want
+	// to confirm we didn't hang in the polling loop and didn't panic.
+	_, err := mgr.ExecuteTool(ctx, "tasks__long_running", `{"msg":"x"}`)
+	if err == nil {
+		t.Fatal("expected an error when forcing sync execution of a task-required tool")
+	}
+}
+
+func TestExecuteToolEmitsProgress(t *testing.T) {
+	var statuses []mcp.TaskStatus
+	mgr := NewMCPToolManager()
+	mgr.SetTaskConfig(MCPTaskConfig{
+		PollInterval:    10 * time.Millisecond,
+		MaxPollInterval: 25 * time.Millisecond,
+		Timeout:         5 * time.Second,
+		Progress: func(p MCPTaskProgress) {
+			statuses = append(statuses, p.Status)
+		},
+	})
+
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: newTaskTestInProcessServer(t, 30*time.Millisecond),
+	}
+	if _, err := mgr.AddServer(context.Background(), "tasks", cfg); err != nil {
+		t.Fatalf("AddServer: %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if _, err := mgr.ExecuteTool(ctx, "tasks__long_running", `{"msg":"hi"}`); err != nil {
+		t.Fatalf("ExecuteTool: %v", err)
+	}
+	if len(statuses) == 0 {
+		t.Fatal("expected at least one progress event")
+	}
+	last := statuses[len(statuses)-1]
+	if !last.IsTerminal() {
+		t.Errorf("last progress event should be terminal, got %q", last)
+	}
+}
+
+func TestListGetCancelMCPTasksOnLoadedServer(t *testing.T) {
+	mgr := NewMCPToolManager()
+	cfg := config.MCPServerConfig{
+		Type:            "inprocess",
+		InProcessServer: newTaskTestInProcessServer(t, 0),
+	}
+	if _, err := mgr.AddServer(context.Background(), "tasks", cfg); err != nil {
+		t.Fatalf("AddServer: %v", err)
+	}
+
+	ctx := context.Background()
+
+	// tasks/list — no in-flight tasks yet, so we just verify the call
+	// succeeds and returns an empty slice (or any slice; the exact length
+	// depends on server retention policy).
+	if _, err := mgr.ListServerTasks(ctx, "tasks"); err != nil {
+		t.Errorf("ListServerTasks: %v", err)
+	}
+
+	// Unknown server should error cleanly without panicking.
+	if _, err := mgr.GetServerTask(ctx, "unknown", "abc"); err == nil {
+		t.Error("GetServerTask on unknown server should error")
+	}
+	if _, err := mgr.CancelServerTask(ctx, "unknown", "abc"); err == nil {
+		t.Error("CancelServerTask on unknown server should error")
+	}
+}
@@ -190,6 +190,41 @@ msg, err := host.GetMCPPrompt(ctx, "server-name", "prompt-name", map[string]stri
 })
 ```

+### MCP Tasks (long-running tools)
+
+Kit advertises [MCP task support](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
+during `initialize`. Cooperating servers can respond to `tools/call` with a
+`taskId` immediately; Kit then polls `tasks/get` / `tasks/result` until the
+task reaches a terminal state, and best-effort `tasks/cancel`s on context
+cancellation. Servers that don't advertise the capability keep their previous
+synchronous behaviour.
+
+```go
+host, _ := kit.New(ctx, &kit.Options{
+    // Per-server mode: auto (default), never, or always.
+    MCPTaskMode: map[string]kit.MCPTaskMode{
+        "build-server": kit.MCPTaskModeAlways,
+    },
+    MCPTaskTimeout:  15 * time.Minute, // total wall-clock cap
+    MCPTaskProgress: func(p kit.MCPTaskProgress) {
+        log.Printf("%s/%s: %s", p.Server, p.TaskID, p.Status)
+    },
+})
+
+// Inspect / cancel in-flight tasks
+tasks, _ := host.ListMCPTasks(ctx, "build-server")
+t, _    := host.GetMCPTask(ctx, "build-server", tasks[0].TaskID)
+if !t.Status.IsTerminal() {
+    _, _ = host.CancelMCPTask(ctx, "build-server", t.TaskID)
+}
+```
+
+The progress handler fires once when a task is accepted and again on every
+observed status transition; the final invocation always carries a terminal
+status (`MCPTaskStatusCompleted`, `MCPTaskStatusFailed`, or
+`MCPTaskStatusCancelled`). Don't block in the handler — dispatch long work on
+a goroutine.
+
 ### Session Management

 Maintain conversation context:
@@ -1035,6 +1035,41 @@ type Options struct {
 	// real-time progress in the TUI.
 	OnMCPServerLoaded func(serverName string, toolCount int, err error)

+	// MCPTaskMode overrides the per-server [MCPTaskMode] for task-augmented
+	// tools/call execution. Keys are MCP server names. Servers not present
+	// in the map fall back to the TasksMode field of MCPServerConfig (or
+	// MCPTaskModeAuto when that is empty). See the MCP Tasks spec for the
+	// underlying semantics:
+	// https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks
+	MCPTaskMode map[string]MCPTaskMode
+
+	// MCPTaskTimeout is the maximum wall-clock duration to wait for a
+	// task-augmented tool call to reach a terminal state. Independent of
+	// any per-call context deadline; whichever fires first wins. Zero
+	// means use the default (15 minutes).
+	MCPTaskTimeout time.Duration
+
+	// MCPTaskTTL is the TTL hint sent in TaskParams for every
+	// task-augmented tools/call. Zero omits the TTL and lets the server
+	// pick its own retention policy.
+	MCPTaskTTL time.Duration
+
+	// MCPTaskPollInterval is the fallback interval between tasks/get
+	// requests when the server does not suggest one. Zero means use the
+	// default (1 second).
+	MCPTaskPollInterval time.Duration
+
+	// MCPTaskMaxPollInterval caps the polling interval (a server-supplied
+	// pollInterval can otherwise grow without bound). Zero means use the
+	// default (5 seconds).
+	MCPTaskMaxPollInterval time.Duration
+
+	// MCPTaskProgress, if non-nil, is invoked once when a task is accepted
+	// and on every status transition observed by the polling loop. The
+	// final invocation always carries a terminal status. Implementations
+	// must not block; long work should run on a goroutine.
+	MCPTaskProgress MCPTaskProgressHandler
+
 	// CLI is optional CLI-specific configuration. SDK users leave this nil.
 	CLI *CLIOptions

@@ -1387,6 +1422,14 @@ func New(ctx context.Context, opts *Options) (*Kit, error) {
 		MaxSteps:          maxSteps,
 		StreamingEnabled:  streaming,
 		OnMCPServerLoaded: opts.OnMCPServerLoaded,
+		MCPTaskConfig: mcpTaskOptions{
+			perServer:       opts.MCPTaskMode,
+			defaultTTL:      opts.MCPTaskTTL,
+			pollInterval:    opts.MCPTaskPollInterval,
+			maxPollInterval: opts.MCPTaskMaxPollInterval,
+			timeout:         opts.MCPTaskTimeout,
+			progress:        opts.MCPTaskProgress,
+		}.toToolsConfig(),
 	}

 	// Set up OAuth handler for remote MCP servers. The SDK does not create
@@ -1799,6 +1842,13 @@ func (m *Kit) Subagent(ctx context.Context, cfg SubagentConfig) (*SubagentResult
 		Streaming:    true,
 		MCPConfig:    m.mcpConfig,
 	}
+	// Propagate the parent's MCP task configuration so a child subagent
+	// invoking long-running MCP tools observes the same per-server modes,
+	// timeouts, and progress callback as the parent. Without this, child
+	// agents would silently fall back to MCPTaskModeAuto with default
+	// polling and no progress feedback even when the parent had configured
+	// custom values.
+	inheritMCPTaskOptions(childOpts, m.opts)
 	child, err := New(ctx, childOpts)
 	if err != nil {
 		return &SubagentResult{Elapsed: time.Since(start)}, fmt.Errorf("failed to create subagent: %w", err)
@@ -0,0 +1,236 @@
+package kit
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/mark3labs/kit/internal/tools"
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+// MCPTaskStatus represents the lifecycle state of a task-augmented MCP
+// tool call. See https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks
+// for the underlying spec.
+type MCPTaskStatus string
+
+const (
+	// MCPTaskStatusWorking indicates the task is currently being processed.
+	MCPTaskStatusWorking MCPTaskStatus = MCPTaskStatus(mcp.TaskStatusWorking)
+	// MCPTaskStatusInputRequired indicates the server is waiting for client
+	// input before it can proceed (rare; typically surfaced via elicitation).
+	MCPTaskStatusInputRequired MCPTaskStatus = MCPTaskStatus(mcp.TaskStatusInputRequired)
+	// MCPTaskStatusCompleted indicates the task finished successfully.
+	MCPTaskStatusCompleted MCPTaskStatus = MCPTaskStatus(mcp.TaskStatusCompleted)
+	// MCPTaskStatusFailed indicates the task ended in error.
+	MCPTaskStatusFailed MCPTaskStatus = MCPTaskStatus(mcp.TaskStatusFailed)
+	// MCPTaskStatusCancelled indicates the task was cancelled before completion.
+	MCPTaskStatusCancelled MCPTaskStatus = MCPTaskStatus(mcp.TaskStatusCancelled)
+)
+
+// IsTerminal reports whether the status represents a final state — that is,
+// the task will not change again. Terminal states are completed, failed,
+// and cancelled.
+func (s MCPTaskStatus) IsTerminal() bool {
+	return mcp.TaskStatus(s).IsTerminal()
+}
+
+// MCPTaskMode controls when Kit augments tools/call requests with MCP task
+// metadata for a specific server.
+type MCPTaskMode string
+
+const (
+	// MCPTaskModeAuto augments tools/call with task metadata only when the
+	// server advertises tasks/toolCalls capability during initialize.
+	// This is the default and is safe to leave unconfigured for any
+	// existing MCP server.
+	MCPTaskModeAuto MCPTaskMode = MCPTaskMode(tools.MCPTaskModeAuto)
+	// MCPTaskModeNever forces every tools/call to be issued synchronously
+	// (no Task field), regardless of server capability.
+	MCPTaskModeNever MCPTaskMode = MCPTaskMode(tools.MCPTaskModeNever)
+	// MCPTaskModeAlways always opts into task augmentation, even when the
+	// server didn't advertise the capability. The server may still respond
+	// synchronously; this just expresses client intent unconditionally.
+	MCPTaskModeAlways MCPTaskMode = MCPTaskMode(tools.MCPTaskModeAlways)
+)
+
+// MCPTask is the SDK-level view of an MCP Task. Timestamps are best-effort
+// parsed from the server's ISO-8601 strings; they may be the zero time when
+// the server omitted them or used a non-RFC3339 format.
+type MCPTask struct {
+	// Server is the configured MCP server name this task lives on.
+	Server string
+	// TaskID is the server-assigned identifier for the task.
+	TaskID string
+	// Status is the current task lifecycle state.
+	Status MCPTaskStatus
+	// StatusMessage is an optional human-readable description provided by
+	// the server.
+	StatusMessage string
+	// CreatedAt is when the task was created on the server.
+	CreatedAt time.Time
+	// UpdatedAt is when the task was last updated on the server.
+	UpdatedAt time.Time
+	// TTL is how long the server intends to retain this task after creation.
+	// Zero means the server did not advertise a TTL.
+	TTL time.Duration
+	// PollInterval is the suggested time between status checks. Zero means
+	// the client should use its own default.
+	PollInterval time.Duration
+}
+
+// MCPTaskProgress is a single status update emitted while Kit is waiting
+// on a task-augmented tool call.
+type MCPTaskProgress struct {
+	// Server is the configured MCP server name.
+	Server string
+	// TaskID is the server-assigned identifier for the in-flight task.
+	TaskID string
+	// Status is the most recent task status observed.
+	Status MCPTaskStatus
+	// Message is the optional human-readable status message from the server.
+	Message string
+}
+
+// MCPTaskProgressHandler is called once when a task is accepted and again
+// on every observed status transition. The final invocation always carries
+// a terminal status. Implementations must not block; long work should be
+// dispatched on a goroutine.
+type MCPTaskProgressHandler func(MCPTaskProgress)
+
+// mcpTaskOptions carries SDK consumer configuration into the agent setup.
+// Stored on Options as a single value so the public surface stays compact;
+// individual fields are exposed via WithMCP* builder functions.
+type mcpTaskOptions struct {
+	perServer       map[string]MCPTaskMode
+	defaultTTL      time.Duration
+	pollInterval    time.Duration
+	maxPollInterval time.Duration
+	timeout         time.Duration
+	progress        MCPTaskProgressHandler
+}
+
+// toToolsConfig converts the SDK-level config to the internal tools-package
+// representation. Keeps the dependency arrow internal-only.
+func (o mcpTaskOptions) toToolsConfig() tools.MCPTaskConfig {
+	cfg := tools.MCPTaskConfig{
+		DefaultTTL:      o.defaultTTL,
+		PollInterval:    o.pollInterval,
+		MaxPollInterval: o.maxPollInterval,
+		Timeout:         o.timeout,
+	}
+	if len(o.perServer) > 0 {
+		cfg.PerServerMode = make(map[string]tools.MCPTaskMode, len(o.perServer))
+		for k, v := range o.perServer {
+			cfg.PerServerMode[k] = tools.MCPTaskMode(v)
+		}
+	}
+	if o.progress != nil {
+		h := o.progress
+		cfg.Progress = func(p tools.MCPTaskProgress) {
+			h(MCPTaskProgress{
+				Server:  p.Server,
+				TaskID:  p.TaskID,
+				Status:  MCPTaskStatus(p.Status),
+				Message: p.Message,
+			})
+		}
+	}
+	return cfg
+}
+
+// ListMCPTasks queries tasks/list on the named MCP server and returns the
+// active and recent tasks the server is willing to disclose. Returns an
+// error when the server isn't loaded, doesn't expose tasks/list, or the
+// underlying transport fails.
+func (m *Kit) ListMCPTasks(ctx context.Context, serverName string) ([]MCPTask, error) {
+	mgr, err := m.mcpToolManager()
+	if err != nil {
+		return nil, err
+	}
+	infos, err := mgr.ListServerTasks(ctx, serverName)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]MCPTask, len(infos))
+	for i, t := range infos {
+		out[i] = mcpTaskFromInternal(t)
+	}
+	return out, nil
+}
+
+// GetMCPTask queries tasks/get for a single in-flight task on the named
+// server. The returned MCPTask reflects the server's current view of the
+// task.
+func (m *Kit) GetMCPTask(ctx context.Context, serverName, taskID string) (MCPTask, error) {
+	mgr, err := m.mcpToolManager()
+	if err != nil {
+		return MCPTask{}, err
+	}
+	info, err := mgr.GetServerTask(ctx, serverName, taskID)
+	if err != nil {
+		return MCPTask{}, err
+	}
+	return mcpTaskFromInternal(info), nil
+}
+
+// CancelMCPTask issues tasks/cancel for an in-flight task on the named
+// server. Returns the post-cancel task state when the server responded
+// with one. Cancelling an already-terminal task is a no-op on most
+// servers.
+func (m *Kit) CancelMCPTask(ctx context.Context, serverName, taskID string) (MCPTask, error) {
+	mgr, err := m.mcpToolManager()
+	if err != nil {
+		return MCPTask{}, err
+	}
+	info, err := mgr.CancelServerTask(ctx, serverName, taskID)
+	if err != nil {
+		return MCPTask{}, err
+	}
+	return mcpTaskFromInternal(info), nil
+}
+
+// mcpToolManager returns the underlying MCP tool manager or an error when
+// no MCP servers are configured.
+func (m *Kit) mcpToolManager() (*tools.MCPToolManager, error) {
+	if m == nil || m.agent == nil {
+		return nil, fmt.Errorf("kit instance has no agent")
+	}
+	mgr := m.agent.GetMCPToolManager()
+	if mgr == nil {
+		return nil, fmt.Errorf("no MCP servers configured")
+	}
+	return mgr, nil
+}
+
+// mcpTaskFromInternal adapts the internal tools.MCPTaskInfo to the
+// SDK-level MCPTask type. Keeps the public surface independent of
+// internal package types.
+func mcpTaskFromInternal(t tools.MCPTaskInfo) MCPTask {
+	return MCPTask{
+		Server:        t.Server,
+		TaskID:        t.TaskID,
+		Status:        MCPTaskStatus(t.Status),
+		StatusMessage: t.StatusMessage,
+		CreatedAt:     t.CreatedAt,
+		UpdatedAt:     t.UpdatedAt,
+		TTL:           t.TTL,
+		PollInterval:  t.PollInterval,
+	}
+}
+
+// inheritMCPTaskOptions copies every MCP task-related field from parent
+// onto child. Used by Kit.Subagent so child instances observe the same
+// per-server modes, timeouts, and progress callback as their parent.
+// A nil parent is a no-op so callers don't have to guard at the call site.
+func inheritMCPTaskOptions(child, parent *Options) {
+	if child == nil || parent == nil {
+		return
+	}
+	child.MCPTaskMode = parent.MCPTaskMode
+	child.MCPTaskTimeout = parent.MCPTaskTimeout
+	child.MCPTaskTTL = parent.MCPTaskTTL
+	child.MCPTaskPollInterval = parent.MCPTaskPollInterval
+	child.MCPTaskMaxPollInterval = parent.MCPTaskMaxPollInterval
+	child.MCPTaskProgress = parent.MCPTaskProgress
+}
@@ -0,0 +1,165 @@
+package kit
+
+import (
+	"testing"
+	"time"
+
+	"github.com/mark3labs/kit/internal/tools"
+)
+
+func TestMCPTaskStatusIsTerminal(t *testing.T) {
+	cases := []struct {
+		s    MCPTaskStatus
+		want bool
+	}{
+		{MCPTaskStatusWorking, false},
+		{MCPTaskStatusInputRequired, false},
+		{MCPTaskStatusCompleted, true},
+		{MCPTaskStatusFailed, true},
+		{MCPTaskStatusCancelled, true},
+		{MCPTaskStatus("unknown"), false},
+	}
+	for _, tc := range cases {
+		if got := tc.s.IsTerminal(); got != tc.want {
+			t.Errorf("MCPTaskStatus(%q).IsTerminal() = %v, want %v", tc.s, got, tc.want)
+		}
+	}
+}
+
+func TestMCPTaskOptionsToToolsConfig(t *testing.T) {
+	called := 0
+	o := mcpTaskOptions{
+		perServer: map[string]MCPTaskMode{
+			"alpha": MCPTaskModeAlways,
+			"beta":  MCPTaskModeNever,
+		},
+		defaultTTL:      30 * time.Second,
+		pollInterval:    250 * time.Millisecond,
+		maxPollInterval: 2 * time.Second,
+		timeout:         5 * time.Minute,
+		progress:        func(p MCPTaskProgress) { called++ },
+	}
+	cfg := o.toToolsConfig()
+
+	if cfg.DefaultTTL != 30*time.Second {
+		t.Errorf("DefaultTTL = %v, want 30s", cfg.DefaultTTL)
+	}
+	if cfg.PollInterval != 250*time.Millisecond {
+		t.Errorf("PollInterval = %v, want 250ms", cfg.PollInterval)
+	}
+	if cfg.MaxPollInterval != 2*time.Second {
+		t.Errorf("MaxPollInterval = %v, want 2s", cfg.MaxPollInterval)
+	}
+	if cfg.Timeout != 5*time.Minute {
+		t.Errorf("Timeout = %v, want 5m", cfg.Timeout)
+	}
+	if cfg.PerServerMode["alpha"] != tools.MCPTaskModeAlways {
+		t.Errorf("PerServerMode[alpha] = %q, want always", cfg.PerServerMode["alpha"])
+	}
+	if cfg.PerServerMode["beta"] != tools.MCPTaskModeNever {
+		t.Errorf("PerServerMode[beta] = %q, want never", cfg.PerServerMode["beta"])
+	}
+
+	// Progress conversion: invoking the internal handler must call our
+	// SDK-level callback with the converted struct.
+	if cfg.Progress == nil {
+		t.Fatal("Progress callback was lost in conversion")
+	}
+	cfg.Progress(tools.MCPTaskProgress{
+		Server: "alpha",
+		TaskID: "t1",
+		Status: "working",
+	})
+	if called != 1 {
+		t.Errorf("expected SDK progress handler to be invoked once, got %d", called)
+	}
+}
+
+func TestMCPTaskFromInternal(t *testing.T) {
+	in := tools.MCPTaskInfo{
+		Server:        "srv",
+		TaskID:        "t-1",
+		Status:        "working",
+		StatusMessage: "phase 1",
+		CreatedAt:     time.Date(2026, 5, 4, 12, 0, 0, 0, time.UTC),
+		UpdatedAt:     time.Date(2026, 5, 4, 12, 0, 1, 0, time.UTC),
+		TTL:           5 * time.Minute,
+		PollInterval:  500 * time.Millisecond,
+	}
+	out := mcpTaskFromInternal(in)
+
+	if out.Server != "srv" || out.TaskID != "t-1" {
+		t.Errorf("identity fields not copied: %+v", out)
+	}
+	if out.Status != MCPTaskStatusWorking {
+		t.Errorf("Status = %q, want working", out.Status)
+	}
+	if out.StatusMessage != "phase 1" {
+		t.Errorf("StatusMessage = %q, want phase 1", out.StatusMessage)
+	}
+	if out.TTL != 5*time.Minute || out.PollInterval != 500*time.Millisecond {
+		t.Errorf("durations not copied: %+v", out)
+	}
+}
+
+func TestKitMCPTasksWithoutAgentReturnsError(t *testing.T) {
+	// A nil/zero Kit must not panic — task RPCs should surface a clear
+	// error instead. Useful for SDK consumers that try task ops on a Kit
+	// constructed without MCP servers.
+	var k *Kit
+	ctx := t.Context()
+	if _, err := k.ListMCPTasks(ctx, "any"); err == nil {
+		t.Error("ListMCPTasks on nil Kit should error")
+	}
+	if _, err := k.GetMCPTask(ctx, "any", "id"); err == nil {
+		t.Error("GetMCPTask on nil Kit should error")
+	}
+	if _, err := k.CancelMCPTask(ctx, "any", "id"); err == nil {
+		t.Error("CancelMCPTask on nil Kit should error")
+	}
+}
+
+func TestSubagentPropagatesMCPTaskOptions(t *testing.T) {
+	// Exercises the helper Kit.Subagent uses to copy MCP task options
+	// onto child Options. Calling the real helper (rather than
+	// duplicating its body in the test) means any new field added to
+	// the propagation list is picked up automatically by the
+	// equivalence assertion below.
+	parent := &Options{
+		MCPTaskMode: map[string]MCPTaskMode{
+			"build": MCPTaskModeAlways,
+			"chat":  MCPTaskModeNever,
+		},
+		MCPTaskTimeout:         30 * time.Minute,
+		MCPTaskTTL:             45 * time.Minute,
+		MCPTaskPollInterval:    750 * time.Millisecond,
+		MCPTaskMaxPollInterval: 4 * time.Second,
+		MCPTaskProgress:        func(MCPTaskProgress) {},
+	}
+
+	child := &Options{}
+	inheritMCPTaskOptions(child, parent)
+
+	if child.MCPTaskMode["build"] != MCPTaskModeAlways || child.MCPTaskMode["chat"] != MCPTaskModeNever {
+		t.Errorf("MCPTaskMode not propagated: got %+v", child.MCPTaskMode)
+	}
+	if child.MCPTaskTimeout != 30*time.Minute {
+		t.Errorf("MCPTaskTimeout = %v, want 30m", child.MCPTaskTimeout)
+	}
+	if child.MCPTaskTTL != 45*time.Minute {
+		t.Errorf("MCPTaskTTL = %v, want 45m", child.MCPTaskTTL)
+	}
+	if child.MCPTaskPollInterval != 750*time.Millisecond {
+		t.Errorf("MCPTaskPollInterval = %v, want 750ms", child.MCPTaskPollInterval)
+	}
+	if child.MCPTaskMaxPollInterval != 4*time.Second {
+		t.Errorf("MCPTaskMaxPollInterval = %v, want 4s", child.MCPTaskMaxPollInterval)
+	}
+	if child.MCPTaskProgress == nil {
+		t.Error("MCPTaskProgress not propagated")
+	}
+
+	// Nil parent is a no-op rather than a panic.
+	inheritMCPTaskOptions(&Options{}, nil)
+	inheritMCPTaskOptions(nil, parent)
+}
@@ -88,6 +88,11 @@ mcpServers:
    type: remote
    url: "https://pubmed.mcp.example.com"
    noOAuth: true  # skip OAuth for public servers
+
+  builds:
+    type: remote
+    url: "https://builds.mcp.example.com"
+    tasksMode: always  # always run tools/call as async tasks (Phase 1 MVP)
 ```

 ### MCP server fields
@@ -101,9 +106,34 @@ mcpServers:
 | `allowedTools` | list | Whitelist of tool names to expose |
 | `excludedTools` | list | Blacklist of tool names to hide |
 | `noOAuth` | bool | Skip OAuth for this server (for public servers that don't require auth) |
+| `tasksMode` | string | When to augment `tools/call` with MCP task metadata: `auto` (default — only when the server advertises task support), `never`, or `always`. See [MCP tasks](#mcp-tasks-long-running-tools). |

 A legacy format with `transport`, `args`, `env`, and `headers` fields is also supported.

+### MCP tasks (long-running tools)
+
+Kit advertises [MCP task support](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
+during `initialize` so servers can respond to `tools/call` with a
+`CreateTaskResult` (a task ID + `working` status) instead of blocking until
+the operation finishes. Kit then polls `tasks/get` / `tasks/result` until the
+task reaches a terminal state, and best-effort `tasks/cancel`s on context
+cancellation.
+
+This avoids HTTP/SSE proxy timeouts on long builds, deploys, and batch jobs,
+and lets the user/agent abort cleanly with Ctrl-C.
+
+**Per-server `tasksMode`:**
+
+| Value | Behaviour |
+|-------|-----------|
+| `auto` (default) | Augment `tools/call` with task metadata only when the server advertised `tasks/toolCalls` capability. Servers that don't advertise it run synchronously, exactly as before. |
+| `never` | Always issue `tools/call` synchronously, regardless of server capability. |
+| `always` | Always opt into task augmentation, even when the server didn't advertise the capability. The server may still respond synchronously — this just expresses client intent unconditionally. |
+
+Defaults are safe: any existing MCP server keeps its previous behaviour
+bit-for-bit. SDK consumers can also override the mode programmatically and
+plug in a progress callback — see [SDK options](/sdk/options#mcp-tasks).
+
 ## Custom models

 Define custom models in your `.kit.yml` for use with the `custom` provider. This is useful for self-hosted models or API endpoints not in the built-in database:
@@ -169,6 +169,12 @@ when embedding Kit as a library.
 | `MCPAuthHandler` | `MCPAuthHandler` | — | OAuth handler for remote MCP servers. `nil` disables OAuth (servers returning 401 fail with the authorization-required error). See [MCP OAuth](#mcp-oauth-authorization) below. |
 | `MCPTokenStoreFactory` | `func` | — | Custom OAuth token storage for MCP servers (default: JSON file in `$XDG_CONFIG_HOME/.kit/mcp_tokens.json`). |
 | `InProcessMCPServers` | `map[string]*MCPServer` | — | In-process mcp-go servers (no subprocess) |
+| `MCPTaskMode` | `map[string]MCPTaskMode` | — | Per-server override for task-augmented `tools/call`. Keys are server names; missing entries fall back to the `tasksMode` field of the matching `MCPServerConfig`. See [MCP Tasks](#mcp-tasks). |
+| `MCPTaskTimeout` | `time.Duration` | `15m` | Maximum wall-clock to wait for a task to reach a terminal state. Independent of any per-call context deadline. |
+| `MCPTaskTTL` | `time.Duration` | — | TTL hint sent in `TaskParams` for every task-augmented call. Zero omits the field and lets the server pick. |
+| `MCPTaskPollInterval` | `time.Duration` | `1s` | Fallback interval between `tasks/get` requests when the server does not suggest one. |
+| `MCPTaskMaxPollInterval` | `time.Duration` | `5s` | Cap on the polling interval (a server-supplied `pollInterval` can otherwise grow without bound). |
+| `MCPTaskProgress` | `MCPTaskProgressHandler` | — | Optional callback invoked once when a task is accepted and on every observed status transition. The final invocation always carries a terminal status. |

 ## MCP OAuth Authorization

@@ -248,6 +254,79 @@ authorization URL and hang until the 2-minute callback timeout fires. Always
 set `OnAuthURL`, or use a higher-level wrapper like `CLIMCPAuthHandler`.
 :::

+## MCP Tasks
+
+The [MCP Tasks utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
+turns a synchronous `tools/call` into a pollable async job: the server
+returns a `taskId` with status `working` immediately, and the client polls
+`tasks/get` / `tasks/result` until the task reaches a terminal state.
+
+Kit advertises task support during `initialize` and, by default, augments
+`tools/call` with task metadata only when the server advertises
+`tasks/toolCalls` capability — so any existing MCP server keeps its previous
+synchronous behaviour bit-for-bit. Long-running tools (builds, deployments,
+batch jobs, sub-agent runs) get HTTP/SSE timeout-resistance and clean
+cancellation "for free" once both sides opt in.
+
+### Per-server mode
+
+```go
+import "time"
+
+host, _ := kit.New(ctx, &kit.Options{
+    MCPTaskMode: map[string]kit.MCPTaskMode{
+        "build-server": kit.MCPTaskModeAlways, // force task-augmented calls
+        "chat-server":  kit.MCPTaskModeNever,  // force synchronous calls
+        // any server not in the map honours its `tasksMode` config field
+        // (default "auto")
+    },
+})
+```
+
+| Mode | Behaviour |
+|---|---|
+| `MCPTaskModeAuto` (default) | Augment `tools/call` with `TaskParams` only when the server advertised `tasks/toolCalls`. |
+| `MCPTaskModeNever` | Always issue `tools/call` synchronously, ignoring server capability. |
+| `MCPTaskModeAlways` | Always opt in, even when the server didn't advertise the capability. The server may still respond synchronously. |
+
+### Progress callbacks
+
+```go
+host, _ := kit.New(ctx, &kit.Options{
+    MCPTaskTimeout:  15 * time.Minute,        // total wall-clock cap
+    MCPTaskTTL:      30 * time.Minute,        // server retention hint
+    MCPTaskProgress: func(p kit.MCPTaskProgress) {
+        log.Printf("%s/%s: %s %s", p.Server, p.TaskID, p.Status, p.Message)
+    },
+})
+```
+
+The handler fires once when a task is accepted and again on every observed
+status transition. The final call always carries a terminal status
+(`MCPTaskStatusCompleted`, `MCPTaskStatusFailed`, or `MCPTaskStatusCancelled`).
+Do not block in the handler — dispatch long work on a goroutine.
+
+### Inspecting and cancelling tasks
+
+```go
+tasks, _ := host.ListMCPTasks(ctx, "build-server")
+for _, t := range tasks {
+    fmt.Printf("%s: %s (%s)\n", t.TaskID, t.Status, t.StatusMessage)
+}
+
+t, _ := host.GetMCPTask(ctx, "build-server", taskID)
+if !t.Status.IsTerminal() {
+    _, _ = host.CancelMCPTask(ctx, "build-server", taskID)
+}
+```
+
+`Kit.ListMCPTasks`, `Kit.GetMCPTask`, and `Kit.CancelMCPTask` work against any
+loaded MCP server that advertises the corresponding capability.
+`MCPTaskStatus.IsTerminal()` is the canonical check for completion.
+
+Context cancellation also works end-to-end: cancelling the `ctx` passed to a
+tool execution triggers a best-effort `tasks/cancel` before the call returns.
+
 ## Precedence

 For any given generation or provider field, the effective value is resolved
@@ -215,6 +215,33 @@ resources := host.ListMCPResources()
 content, _ := host.ReadMCPResource(ctx, "server", "file:///path")
 ```

+## MCP tasks (long-running tools)
+
+Kit advertises [MCP task support](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
+during `initialize`, so cooperating servers can return a `taskId` immediately
+and let Kit poll `tasks/get` / `tasks/result` until the operation completes.
+This avoids HTTP/SSE proxy timeouts on long tools and gives you clean
+cancellation via context.
+
+```go
+host, _ := kit.New(ctx, &kit.Options{
+    MCPTaskMode: map[string]kit.MCPTaskMode{
+        "build-server": kit.MCPTaskModeAlways,
+    },
+    MCPTaskProgress: func(p kit.MCPTaskProgress) {
+        log.Printf("%s: %s", p.TaskID, p.Status)
+    },
+})
+
+// Inspect / cancel in-flight tasks
+tasks, _ := host.ListMCPTasks(ctx, "build-server")
+_, _    = host.CancelMCPTask(ctx, "build-server", tasks[0].TaskID)
+```
+
+Defaults to `MCPTaskModeAuto` per server, so any existing MCP server keeps
+its previous synchronous behaviour. See [SDK options → MCP Tasks](/sdk/options#mcp-tasks)
+for the full surface.
+
 ## Context and compaction

 Monitor and manage context usage:
Author	SHA1	Message	Date
Ed Zynda	4ef57eec4e	docs(session): correct DefaultSessionDir convention comment - Stale comment showed ~/.kit/sessions/--<cwd-path>--/ which does not match the actual encoding (no leading/trailing dashes) - Update to reflect the real format and point to encodeCwdForDir for full rules	2026-05-05 14:54:20 +03:00
Ed Zynda	cbd828e190	fix(session): strip illegal characters from windows session dir (#18 ) - Encode cwd via new encodeCwdForDir helper that handles both `/` and `\` separators and strips characters illegal in Windows directory names (`: < > " \| ? *`) - Fixes session creation on Windows where the drive-letter colon produced names like `C:--test` and caused mkdir to fail - Add regression tests covering Unix paths, Windows drive roots, secondary drives, mixed separators, and other illegal chars Fixes #18	2026-05-05 14:46:36 +03:00
Ed Zynda	d304805106	Merge pull request #22 from mark3labs/feat/21-mcp-tasks-mvp feat(mcp): add MCP Tasks support at the SDK level (#21)	2026-05-04 19:30:15 +03:00
Ed Zynda	6e36053856	fix(mcp): validate tasksMode and inherit task options in Subagent (#21 ) Address two review findings on the MCP Tasks PR. - Config.Validate() now rejects unknown tasksMode values with a clear error naming the server and bad value. Without this a typo (e.g. "alwasy") was silently downgraded to "auto" by the runtime parser. - Kit.Subagent() now propagates the parent's six MCP task options (mode map, timeout, TTL, poll interval, max poll interval, progress callback) onto the child via a new inheritMCPTaskOptions helper. Without this, child subagents always saw default polling and no progress feedback regardless of parent configuration. The propagation logic lives in a helper so the test exercises the real code path instead of duplicating it; future task fields only need to be added in one place.	2026-05-04 17:06:11 +03:00
Ed Zynda	92eaaf6a59	docs(mcp): document MCP Tasks support (#21 ) - README: add tasksMode YAML example and MCP Tasks subsection with SDK opt-in snippet - pkg/kit/README: add MCP Tasks subsection covering MCPTaskMode, progress callbacks, and List/Get/Cancel methods - www/configuration: document the tasksMode server field plus a per-mode behaviour table - www/sdk/options: extend the Compaction & MCP table with the six new Options fields and add a top-level MCP Tasks section - www/sdk/overview: add a brief MCP Tasks section between MCP prompts/resources and Context & compaction All examples verified against the public symbols in pkg/kit/mcp_tasks.go; docs site builds cleanly via npx tome build.	2026-05-04 17:01:47 +03:00
Ed Zynda	e6084b7bd0	feat(mcp): add MCP Tasks support at the SDK level (#21 ) Implement Phase 1 of the MCP Tasks spec so long-running tools/call requests can run asynchronously, survive proxy timeouts, and be cancelled mid-flight. - connection pool now advertises mcp.NewTasksCapability() during initialize and captures the InitializeResult so callers can detect per-server task support - new MCPServerConfig.TasksMode (auto\|never\|always, default auto) parsed from both new and legacy mcp.json shapes - ExecuteTool augments tools/call with TaskParams when policy and capability allow, polls tasks/get / tasks/result until terminal, and best-effort tasks/cancel on context cancellation - new MCPToolManager methods: SetTaskConfig, ListServerTasks, GetServerTask, CancelServerTask - public SDK surface in pkg/kit: MCPTask, MCPTaskStatus, MCPTaskMode, MCPTaskProgress, MCPTaskProgressHandler, plus Options fields (MCPTaskMode, MCPTaskTimeout, MCPTaskTTL, MCPTaskPollInterval, MCPTaskMaxPollInterval, MCPTaskProgress) and Kit.{List,Get,Cancel} MCPTask methods - works around two upstream mcp-go v0.51.0 parser bugs (ParseCallToolResult rejects task responses; ParseTaskResultResult looks for content under a non-existent nested key) by decoding the wire shape directly via the transport - defaults to MCPTaskModeAuto so servers that don't advertise task support behave exactly as before Fixes #21	2026-05-04 16:51:09 +03:00
Ed Zynda	34d5abff9c	build(deps): update dependencies and implement new acp.Agent methods - Bump fantasy v0.21.0 -> v0.23.0, mcp-go v0.49.0 -> v0.51.0, acp-go-sdk v0.12.0 -> v0.12.2, chroma v2.23.1 -> v2.24.1, fsnotify v1.9.0 -> v1.10.1, ultraviolet, AWS SDK, Google API - Implement CloseSession and ResumeSession on acpserver.Agent to satisfy the expanded acp.Agent interface in acp-go-sdk v0.12.2 - Add sessionRegistry.remove helper to support session close	2026-05-04 16:23:12 +03:00
Ed Zynda	fc0ddd5f4f	update	2026-05-04 15:51:00 +03:00
Ed Zynda	7aa6160c75	updates	2026-05-04 12:10:46 +03:00