agentpool-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.1.4 - 2026-05-31
+
+- Add Markdown delegation preferences at `~/.agentpool/preferences.md`, surfaced
+  through the CLI, MCP tools, MCP resources, inventory, usage summaries, model
+  listings, and spawn responses so agents can read one user-owned preference
+  source before choosing whether and how to use AgentPool.
+- Bound live MCP usage refreshes so slow provider probes return partial data
+  instead of hanging the host session.
+- Remove deprecated `gemini-cli` from the default provider set after Google's
+  transition to Antigravity CLI.
+
 ## 0.1.3 - 2026-05-29
 
 - Reposition docs and descriptions around the primary value: making full use of

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentpool-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom.
 Author: AgentPool contributors
 License-Expression: MIT
@@ -23,8 +23,8 @@ Description-Content-Type: text/markdown
 <!-- mcp-name: io.github.sidduHERE/agentpool -->
 
 You pay for several coding-agent subscriptions — Codex, Claude Code, Cursor,
-Copilot, Gemini — but you work in one at a time. The rest sit idle until your
-active provider hits its 5-hour or weekly limit, and then you stall.
+Copilot, Devin, Droid — but you work in one at a time. The rest sit idle until
+your active provider hits its 5-hour or weekly limit, and then you stall.
 
 AgentPool is a local Python CLI and MCP server that reads the live usage limits
 of every coding-agent subscription you have and lets you — or your primary
@@ -178,6 +178,9 @@ and the opt-in `get_usage_summary` tool.
 The default buffer is `policy.min_remaining_percent = 10`. If any reported
 quota window is below that buffer, the provider row is marked unusable for the
 summary. AgentPool still does not pick an alternative provider for you.
+MCP usage refreshes are intentionally bounded and may return `partial=true`;
+use the CLI commands above when a shell-capable agent needs a complete live
+refresh.
 
 ## Provider Matrix
 
@@ -289,11 +292,15 @@ MCP-connected agents should read these once on connect:
 
 - `agentpool://onboarding`
 - `agentpool://skill.md`
-
-Then use tools for live operations. The default MCP toolset is deliberately
-small: inventory, usage snapshot, provider models, spawn, observe, send,
-interrupt, collect, artifact manifest, transcript paging, and terminate. Add
-opt-in toolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.
+- `agentpool://preferences.md`
+
+Then use tools for live operations. The user-owned preferences file also shows
+up through `agentpool preferences` and `get_delegation_preferences()`. It may
+say to use your native subagent system instead of AgentPool for some tasks. The
+default MCP toolset is deliberately small: inventory, usage snapshot, usage
+summary, provider models, preferences, spawn, observe, send, interrupt,
+collect, artifact manifest, transcript paging, and terminate. Add opt-in
+toolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.
 
 Coding agents with shell access should prefer the CLI path. It is more
 token-efficient because large worker output stays in artifact files and

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/README.md

@@ -3,8 +3,8 @@
 <!-- mcp-name: io.github.sidduHERE/agentpool -->
 
 You pay for several coding-agent subscriptions — Codex, Claude Code, Cursor,
-Copilot, Gemini — but you work in one at a time. The rest sit idle until your
-active provider hits its 5-hour or weekly limit, and then you stall.
+Copilot, Devin, Droid — but you work in one at a time. The rest sit idle until
+your active provider hits its 5-hour or weekly limit, and then you stall.
 
 AgentPool is a local Python CLI and MCP server that reads the live usage limits
 of every coding-agent subscription you have and lets you — or your primary
@@ -158,6 +158,9 @@ and the opt-in `get_usage_summary` tool.
 The default buffer is `policy.min_remaining_percent = 10`. If any reported
 quota window is below that buffer, the provider row is marked unusable for the
 summary. AgentPool still does not pick an alternative provider for you.
+MCP usage refreshes are intentionally bounded and may return `partial=true`;
+use the CLI commands above when a shell-capable agent needs a complete live
+refresh.
 
 ## Provider Matrix
 
@@ -269,11 +272,15 @@ MCP-connected agents should read these once on connect:
 
 - `agentpool://onboarding`
 - `agentpool://skill.md`
-
-Then use tools for live operations. The default MCP toolset is deliberately
-small: inventory, usage snapshot, provider models, spawn, observe, send,
-interrupt, collect, artifact manifest, transcript paging, and terminate. Add
-opt-in toolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.
+- `agentpool://preferences.md`
+
+Then use tools for live operations. The user-owned preferences file also shows
+up through `agentpool preferences` and `get_delegation_preferences()`. It may
+say to use your native subagent system instead of AgentPool for some tasks. The
+default MCP toolset is deliberately small: inventory, usage snapshot, usage
+summary, provider models, preferences, spawn, observe, send, interrupt,
+collect, artifact manifest, transcript paging, and terminate. Add opt-in
+toolsets with `agentpool mcp --toolsets default,stats,sessions,leases,worktrees`.
 
 Coding agents with shell access should prefer the CLI path. It is more
 token-efficient because large worker output stays in artifact files and

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/agent-cli-and-mcp.md

@@ -48,15 +48,18 @@ The default MCP surface is narrow:
 agentpool mcp
 ```
 
-It exposes inventory, cached/live usage snapshots, provider models, spawn,
-observe, send, interrupt, artifact manifest, transcript paging, collect, and
-terminate.
+It exposes inventory, compact usage summaries, cached raw usage snapshots,
+provider models, spawn, observe, send, interrupt, artifact manifest, transcript
+paging, collect, and terminate.
+Explicit MCP refreshes avoid interactive provider TUI probes so a host like
+Claude Code does not accidentally launch a nested Claude `/usage` UI inside
+itself.
 
 Opt into more:
 
 ```bash
 agentpool mcp --toolsets default,stats,sessions,leases,worktrees
-agentpool mcp --tools get_usage_summary
+agentpool mcp --tools validate_model_catalog
 AGENTPOOL_MCP_LOCKDOWN=1 agentpool mcp
 ```
 

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/agentpool-skill.md

@@ -11,12 +11,21 @@ need to delegate coding-agent work.
 ## Rules
 
 - AgentPool is a control plane, not an auto-router.
+- Read the user's AgentPool preferences before deciding whether to delegate:
+  - CLI: `agentpool preferences`
+  - MCP: `get_delegation_preferences()` or `agentpool://preferences.md`
+  - These preferences may tell you to use your own native subagent system
+    instead of AgentPool for some tasks.
 - Choose provider and model explicitly. Never use `provider=auto`.
 - Prefer the CLI when you have shell access; use MCP for MCP-native/no-shell hosts.
 - Run or read usage before delegation:
   - CLI: `agentpool usage-summary --refresh --json`
-  - MCP: `get_usage_snapshot(refresh=false)` for cached state, or
-    `get_usage_snapshot(refresh=true)` for a live refresh.
+  - MCP: `get_usage_summary(refresh=false)` for compact cached state. Use
+    `get_usage_snapshot` only when you need raw snapshots. Avoid asking MCP to
+    run interactive provider TUI probes from inside that same provider's host
+    session; run a CLI refresh from a normal shell when you need a complete
+    live refresh. MCP `refresh=true` is bounded and can return `partial=true`
+    with unknown rows for slow providers.
 - Treat usage rows as a provider-id map. They are not ordered and not ranked.
 - Inspect provider models before spawning when the model is not already chosen:
   - CLI: `agentpool models --provider <provider-id>`
@@ -34,6 +43,7 @@ need to delegate coding-agent work.
 
 ```bash
 agentpool usage-summary --refresh --json
+agentpool preferences
 agentpool models --provider <provider-id> --json
 agentpool spawn --provider <provider-id> --model <model-id> --repo . --task "<narrow task>" --isolation read_only --json
 agentpool observe <session-id> --wait-for completed,error,question,approval_prompt --timeout 120 --json
@@ -58,15 +68,16 @@ without dumping the whole file into context.
 
 ## Typical MCP Flow
 
-1. `get_usage_snapshot(provider_id=..., refresh=false)`
-2. `get_provider_models(provider_id=...)`
-3. `spawn_worker(provider_id=..., model=..., repo_path=..., task=..., isolation="read_only")`
-4. `observe_worker(session_id=..., wait_for=["completed","error","question","approval_prompt"], timeout_seconds=120)`
-5. `send_worker_message(...)` or `interrupt_worker(...)`
-6. `get_artifact_manifest(...)`
-7. `read_worker_transcript(...)` for bounded transcript pages, only if needed
-8. `collect_worker_artifacts(...)`
-9. `terminate_worker(...)`
+1. `get_delegation_preferences()`
+2. `get_usage_summary(provider_id=..., refresh=false)`
+3. `get_provider_models(provider_id=...)`
+4. `spawn_worker(provider_id=..., model=..., repo_path=..., task=..., isolation="read_only")`
+5. `observe_worker(session_id=..., wait_for=["completed","error","question","approval_prompt"], timeout_seconds=120)`
+6. `send_worker_message(...)` or `interrupt_worker(...)`
+7. `get_artifact_manifest(...)`
+8. `read_worker_transcript(...)` for bounded transcript pages, only if needed
+9. `collect_worker_artifacts(...)`
+10. `terminate_worker(...)`
 
 Use opt-in MCP toolsets for extra surfaces:
 

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/mcp-clients.md

@@ -10,7 +10,7 @@ Most users should not run that command by hand. Add it to your MCP host config,
 then let the host start AgentPool when needed.
 
 After setup, ask the agent to read `agentpool://skill.md`, then call
-`get_usage_snapshot(refresh=false)` and `get_provider_models()` before
+`get_usage_summary(refresh=false)` and `get_provider_models()` before
 delegating work. Coding agents with shell access should usually prefer the
 `agentpool` CLI because it keeps large worker output in artifact files.
 
@@ -257,8 +257,9 @@ Restart Claude Desktop after editing the file.
 Once connected, a good first prompt is:
 
 ```text
-Read agentpool://skill.md. Then call
-get_usage_snapshot(refresh=false), get_provider_models(), and get_inventory() before
+Read agentpool://skill.md and agentpool://preferences.md. Then call
+get_delegation_preferences(), get_usage_summary(refresh=false),
+get_provider_models(), and get_inventory() before
 spawning any workers. After spawn_worker, use observe_worker for the worker
 control loop; do not poll get_session/list_sessions as a substitute. Use
 read_worker_transcript with offset/limit only when you need bounded transcript

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/mcp-tools.md

@@ -31,8 +31,10 @@ Unknown toolsets or tool names fail at server startup.
 The default toolset is the smallest worker lifecycle surface:
 
 - `get_inventory`
+- `get_usage_summary`
 - `get_usage_snapshot`
 - `get_provider_models`
+- `get_delegation_preferences`
 - `spawn_worker`
 - `observe_worker`
 - `send_worker_message`
@@ -48,13 +50,19 @@ Removed MCP aliases:
 - `get_capacity_summary`
 - `get_cached_usage_snapshot`
 
-Use `get_usage_snapshot(refresh=false)` for cached snapshots. Use the `usage`
-toolset if you need `get_usage_summary`, `validate_model_catalog`, or
+Use `get_usage_summary(refresh=false)` for the compact provider-capacity view.
+Use `get_usage_snapshot(refresh=false)` only when you need raw snapshots; cached
+mode is the default for both. MCP refreshes intentionally avoid interactive
+provider TUI probes that could interfere with the host agent session. Live MCP
+refreshes are also time bounded; a slow provider returns an unknown row and the
+response sets `partial=true` instead of letting the MCP connection sit open.
+Use the CLI for a complete live refresh from shell-capable coding agents. Use
+the `usage` toolset if you need `validate_model_catalog` or
 `filter_candidates`.
 
 ## Opt-In Toolsets
 
-- `usage`: `get_usage_summary`, `validate_model_catalog`, `filter_candidates`
+- `usage`: `validate_model_catalog`, `filter_candidates`
 - `stats`: `get_stats`, `get_stats_card`
 - `sessions`: `list_sessions`, `get_session`, `attach_info`, `send_worker_keys`
 - `leases`: `acquire_file_lease`, `list_file_leases`, `release_file_lease`
@@ -73,7 +81,7 @@ metadata lookups, not substitutes for observation.
 
 Recommended loop:
 
-1. `get_usage_snapshot(provider_id=..., refresh=false)`
+1. `get_usage_summary(provider_id=..., refresh=false)`
 2. `get_provider_models(provider_id=...)`
 3. `spawn_worker(provider_id=..., model=..., repo_path=..., task=..., isolation="read_only")`
 4. `observe_worker(session_id=..., wait_for=["completed","error","question","approval_prompt"], timeout_seconds=120)`
@@ -123,6 +131,7 @@ The default resource set is non-duplicative:
 
 - `agentpool://onboarding`
 - `agentpool://skill.md`
+- `agentpool://preferences.md`
 - `agentpool://sessions/{session_id}/transcript`
 - `agentpool://sessions/{session_id}/events`
 - `agentpool://artifacts/{session_id}`

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/onboarding.md

@@ -2,8 +2,9 @@
 
 AgentPool helps you use every coding-agent subscription you pay for. It reads
 the live usage limits of each provider you have (Codex, Claude Code, Cursor,
-Copilot, Gemini, ...) so you can offload work to whichever still has headroom
-instead of stalling when your active subscription hits its 5-hour or weekly cap.
+Copilot, Devin, Droid, ...) so you can offload work to whichever still has
+headroom instead of stalling when your active subscription hits its 5-hour or
+weekly cap.
 It is a control plane for explicitly selected coding-agent CLIs: it does not
 route automatically and it does not choose a provider for you.
 
@@ -20,6 +21,7 @@ uv pip install -e ".[dev]"
 
 ```bash
 agentpool init
+agentpool preferences
 agentpool setup cursor
 agentpool config validate
 agentpool doctor --deep --privacy
@@ -146,6 +148,7 @@ resource is missing from their context:
 
 - `agentpool://onboarding`
 - `agentpool://skill.md`
+- `agentpool://preferences.md`
 - `agentpool://sessions/{session_id}/transcript`
 - `agentpool://sessions/{session_id}/events`
 - `agentpool://artifacts/{session_id}`
@@ -156,18 +159,20 @@ the CLI because it keeps transcripts and artifacts on disk until explicitly read
 
 ## Agent Operating Loop
 
-1. Read usage and model state (`agentpool usage-summary --json`, `agentpool models --json`, or the matching MCP tools).
-2. Pick the provider explicitly.
-3. Use `read_only` for exploration and choose `worktree` explicitly only when
+1. Read the user's preferences (`agentpool preferences`, `get_delegation_preferences()`, or `agentpool://preferences.md`).
+2. Read usage and model state (`agentpool usage-summary --json`, `agentpool models --json`, or the matching MCP tools).
+3. Decide whether AgentPool is appropriate, or whether your own native subagent system is better for this task.
+4. Pick the provider explicitly.
+5. Use `read_only` for exploration and choose `worktree` explicitly only when
    AgentPool should create an isolated worktree.
-4. Spawn one narrow worker.
-5. Observe until question, approval, completion, error, or timeout.
-6. Send steering or interrupt deliberately.
-7. Use advisory file leases when multiple workers may touch the same files.
-8. Read bounded transcript pages only when the manifest/summary is not enough.
-9. Use paginated `sessions` / `list_sessions` reads for fleet metadata.
-10. Read the artifact manifest, then collect artifacts.
-11. Terminate sessions when done.
+6. Spawn one narrow worker.
+7. Observe until question, approval, completion, error, or timeout.
+8. Send steering or interrupt deliberately.
+9. Use advisory file leases when multiple workers may touch the same files.
+10. Read bounded transcript pages only when the manifest/summary is not enough.
+11. Use paginated `sessions` / `list_sessions` reads for fleet metadata.
+12. Read the artifact manifest, then collect artifacts.
+13. Terminate sessions when done.
 
 AgentPool never merges, pushes, silently accepts overage, stores provider
 credentials, scrapes browser pages, or ranks providers.

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/quickstart.md

@@ -54,4 +54,5 @@ Use `--isolation worktree` instead of `read_only` for tasks that edit files.
 
 - Full agent guidance: `agentpool://skill.md`
 - Setup and privacy detail: `agentpool://onboarding`
+- User delegation preferences: `agentpool://preferences.md`
 - MCP host config: `agentpool mcp-config --client <host> --absolute-command --install`

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/setup-codex.md

@@ -98,7 +98,7 @@ Then ask Codex:
 
 ```text
 Read agentpool://skill.md. Then call
-get_usage_snapshot(provider_id="codex-cli", refresh=false),
+get_usage_summary(provider_id="codex-cli", refresh=false),
 get_provider_models(provider_id="codex-cli"), and get_inventory before spawning
 any workers. After spawn_worker, use
 observe_worker for the worker control loop. If Codex shows an update prompt,

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/setup-cursor.md

@@ -47,5 +47,5 @@ See [docs/mcp-clients.md](mcp-clients.md) for other hosts.
 ## After Connect
 
 Ask Cursor to read `agentpool://skill.md`, then call
-`get_usage_snapshot(refresh=false)` and `get_provider_models()` before spawning
+`get_usage_summary(refresh=false)` and `get_provider_models()` before spawning
 workers.

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/docs/usage-detection.md

@@ -4,7 +4,7 @@ Usage is best effort and confidence-tagged. Unknown is valid.
 
 Allowed confidence values include `official`, `local_cli`, `local_config`, `provider_warning`, `observed`, `user_configured`, and `unknown`. AgentPool does not fabricate exact quotas and does not scrape browser sessions in v0.1.
 
-Live probes are only run by explicit usage requests. Inventory remains non-invasive and reports whether a provider supports an explicit usage probe. Successful explicit probes are persisted to SQLite; `agentpool usage --cached` and `get_usage_snapshot(refresh=false)` read the latest persisted snapshots without refreshing providers.
+Live probes are only run by explicit usage requests. Inventory remains non-invasive and reports whether a provider supports an explicit usage probe. Successful explicit probes are persisted to SQLite; `agentpool usage --cached`, `get_usage_summary(refresh=false)`, and `get_usage_snapshot(refresh=false)` read the latest persisted snapshots without refreshing providers. MCP refreshes do not run interactive provider TUI probes, because those can interfere with the host agent that is calling AgentPool. MCP refreshes are also bounded by a short server-side budget; if a provider is slow, AgentPool returns a partial response with an unknown row instead of holding the MCP connection open.
 
 `agentpool usage-summary` returns a `providers` map keyed by provider id. The
 CLI `capacity-summary` command is a human convenience alias; MCP does not expose

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentpool-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "Make full use of every coding-agent subscription you pay for: a local CLI + MCP server that surfaces live usage limits and offloads work to providers with headroom."
 readme = "README.md"
 requires-python = ">=3.11"

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.sidduHERE/agentpool",
   "title": "AgentPool",
-  "description": "See live usage limits across your coding-agent subscriptions and offload work to a provider with headroom. Local-first, explicit selection, no auto-routing.",
-  "version": "0.1.3",
+  "description": "See each coding-agent subscription's live limits and offload work to one with headroom.",
+  "version": "0.1.4",
   "repository": {
     "url": "https://github.com/sidduHERE/agentpool",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "pypi",
       "identifier": "agentpool-cli",
-      "version": "0.1.3",
+      "version": "0.1.4",
       "transport": {
         "type": "stdio"
       },

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/src/agentpool/__init__.py

@@ -1,3 +1,3 @@
 """AgentPool local agent control plane."""
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/src/agentpool/cli.py

@@ -36,6 +36,7 @@ from agentpool.onboarding import (
     setup_all_providers,
     setup_provider,
 )
+from agentpool.preferences import PREFERENCES_PATH, ensure_preferences_file, preferences_payload
 from agentpool.mcp import tools as mcp_tools
 from agentpool.session_manager import SessionManager
 from agentpool.stats.card import render_stats_card
@@ -191,6 +192,10 @@ def init_command(
         return
     status = "wrote" if data["changed"] else "exists"
     console.print(f"config {status}: {data['config_path']}")
+    preferences = data.get("preferences") or {}
+    if preferences:
+        preferences_status = "wrote" if preferences.get("changed") else "exists"
+        console.print(f"preferences {preferences_status}: {preferences['path']}")
     if data.get("backup_path"):
         console.print(f"backup: {data['backup_path']}")
     console.print("next:")
@@ -264,6 +269,7 @@ def inventory(json_output: Annotated[bool, typer.Option("--json", help="Emit JSO
                 provider["usage"]["status"] if provider.get("usage") else "unknown",
             )
         console.print(table)
+        console.print(f"preferences: {data['preferences']['path']}")
 
 
 @app.command(help="Show a provider usage snapshot (cached or freshly probed).")
@@ -316,6 +322,7 @@ def usage_summary(
             )
         console.print(f"source: {data['source']}")
         console.print(table)
+        console.print(f"preferences: {data['preferences']['path']}")
     except ToolError as exc:
         handle_tool_error(exc, json_output)
 
@@ -441,6 +448,7 @@ def onboard(json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.
         "config_path": str(DEFAULT_CONFIG_PATH),
         "db_path": str(mgr.config.storage.db),
         "artifact_root": str(mgr.config.storage.artifacts),
+        "preferences": preferences_payload(include_text=False),
         "usage_backends": {
             "default": "combined",
             "available": ["native", "codexbar", "ccusage", "combined"],
@@ -459,6 +467,7 @@ def onboard(json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.
         "mcp_resources": [
             "agentpool://onboarding",
             "agentpool://skill.md",
+            "agentpool://preferences.md",
             "agentpool://sessions/{session_id}/transcript",
             "agentpool://sessions/{session_id}/events",
             "agentpool://artifacts/{session_id}",
@@ -480,6 +489,7 @@ def onboard(json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.
     console.print(f"config: {data['config_path']}")
     console.print(f"db: {data['db_path']}")
     console.print(f"artifacts: {data['artifact_root']}")
+    console.print(f"preferences: {data['preferences']['path']}")
     codexbar = data["usage_backends"]["codexbar"]
     console.print(f"codexbar: {'installed' if codexbar['installed'] else 'not installed'}")
     console.print("\nFirst commands:")
@@ -492,6 +502,61 @@ def onboard(json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.
     console.print_json(json.dumps(data["mcp_host_config"]))
 
 
+@app.command("preferences", help="Show or initialize the user-owned AgentPool preferences file.")
+def preferences_command(
+    action: Annotated[
+        str,
+        typer.Argument(help="Action: show, init, or path."),
+    ] = "show",
+    path: Annotated[
+        Path,
+        typer.Option("--path", help="Preferences path. Defaults to ~/.agentpool/preferences.md."),
+    ] = PREFERENCES_PATH,
+    force: Annotated[bool, typer.Option("--force", help="Back up and overwrite during init.")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+) -> None:
+    """Show or create the Markdown preferences agents should read before delegation.
+
+    Examples:
+      agentpool preferences
+      agentpool preferences init
+      agentpool preferences --json
+      agentpool preferences path
+    """
+    action = action.strip().lower()
+    if action == "path":
+        data = {"path": str(path.expanduser()), "resource_uri": "agentpool://preferences.md"}
+        if json_output:
+            console.print_json(json.dumps(data, default=str))
+        else:
+            console.print(data["path"])
+        return
+    if action == "init":
+        data = ensure_preferences_file(path, force=force)
+    elif action == "show":
+        data = preferences_payload(path, include_text=True)
+    else:
+        handle_tool_error(
+            ToolError(
+                "INVALID_REQUEST",
+                "Preferences action must be one of: show, init, path.",
+                {"example": "agentpool preferences init"},
+            ),
+            json_output,
+        )
+        return
+    if json_output:
+        console.print_json(json.dumps(data, default=str))
+        return
+    if action == "init":
+        status = "wrote" if data["changed"] else "exists"
+        console.print(f"preferences {status}: {data['path']}")
+        if data.get("backup_path"):
+            console.print(f"backup: {data['backup_path']}")
+        return
+    console.print(data["text"], end="" if str(data["text"]).endswith("\n") else "\n")
+
+
 @app.command()
 def smoke(
     provider: Annotated[str, typer.Option("--provider", help="Provider id to smoke test.")] = "fake-question",
@@ -542,10 +607,16 @@ def smoke(
 def providers(json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False) -> None:
     data = manager().inventory(include_usage=False)
     if json_output:
-        console.print_json(json.dumps({"providers": data["providers"]}, default=str))
+        console.print_json(
+            json.dumps(
+                {"providers": data["providers"], "preferences": data["preferences"]},
+                default=str,
+            )
+        )
     else:
         for provider in data["providers"]:
             console.print(provider["id"])
+        console.print(f"preferences: {data['preferences']['path']}")
 
 
 @app.command("models", help="List the model catalog, or validate it with 'models validate'.")
@@ -580,9 +651,10 @@ def models_command(
         if not data["ok"]:
             raise typer.Exit(1)
         return
-    rows = mgr.provider_models(provider)["providers"]
+    data = mgr.provider_models(provider)
+    rows = data["providers"]
     if json_output:
-        console.print_json(json.dumps({"providers": rows}, default=str))
+        console.print_json(json.dumps(data, default=str))
         return
     if provider:
         row = rows[0]
@@ -609,6 +681,7 @@ def models_command(
                 reasoning_text,
             )
         console.print(table)
+        console.print(f"preferences: {data['preferences']['path']}")
         return
     table = Table("Provider", "Default", "Smoke", "Selection", "Models", "Catalog")
     for row in rows:
@@ -621,6 +694,7 @@ def models_command(
             str(row["catalog_completeness"] or ""),
         )
     console.print(table)
+    console.print(f"preferences: {data['preferences']['path']}")
 
 
 @app.command()
@@ -853,6 +927,7 @@ def spawn(
         else:
             console.print(data["session"]["id"])
             console.print(data["attach_command"])
+            console.print(f"preferences: {data['preferences']['path']}")
     except ToolError as exc:
         handle_tool_error(exc, json_output)
 

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/src/agentpool/config.py

@@ -16,6 +16,12 @@ from agentpool.utils import expand_user_path
 DEFAULT_CONFIG_PATH = Path("~/.agentpool/config.yaml").expanduser()
 DEFAULT_MODEL_CATALOG_PATH = Path(__file__).with_name("provider_model_catalog.json")
 FAKE_AGENT_DIR = Path(__file__).with_name("fixtures") / "fake_agents"
+DEPRECATED_PROVIDER_IDS = {
+    "gemini-cli": (
+        "Gemini CLI has transitioned to Antigravity CLI; "
+        "AgentPool no longer exposes it as a supported provider."
+    ),
+}
 FAKE_PROVIDER_SCRIPTS = {
     "fake-question": "fake_question_agent.py",
     "fake-approval": "fake_approval_agent.py",
@@ -299,6 +305,7 @@ def load_config(path: Path | None = None) -> AgentPoolConfig:
     _refresh_provider_models_from_catalog(merged_config.providers, load_model_catalog(model_catalog_paths))
     merged = merged_config.model_dump(mode="json")
     _repair_packaged_fake_provider_paths(merged)
+    _drop_deprecated_providers(merged)
     return AgentPoolConfig.model_validate(merged)
 
 
@@ -321,6 +328,9 @@ def validate_config(config: AgentPoolConfig) -> dict[str, Any]:
         errors.append("providers.auto is not allowed")
     if "factory-droid" in config.providers:
         warnings.append("factory-droid is a PRD compatibility name; use droid-cli for the droid binary")
+    for provider_id, reason in DEPRECATED_PROVIDER_IDS.items():
+        if provider_id in config.providers:
+            warnings.append(f"{provider_id} is deprecated and ignored by load_config: {reason}")
     for provider_id, provider in config.providers.items():
         if provider.command is not None and not provider.command:
             errors.append(f"providers.{provider_id}.command must not be empty")
@@ -371,3 +381,11 @@ def _repair_packaged_fake_provider_paths(config: dict[str, Any]) -> None:
             continue
         provider["binary_candidates"] = [sys.executable]
         provider["command"] = [sys.executable, str(FAKE_AGENT_DIR / script)]
+
+
+def _drop_deprecated_providers(config: dict[str, Any]) -> None:
+    providers = config.get("providers")
+    if not isinstance(providers, dict):
+        return
+    for provider_id in DEPRECATED_PROVIDER_IDS:
+        providers.pop(provider_id, None)

{agentpool_cli-0.1.3 → agentpool_cli-0.1.4}/src/agentpool/mcp/resources.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Any
 
 from agentpool.agent_io import compact_artifact_manifest, lockdown_resource, omitted_worker_output, wrap_untrusted
+from agentpool.preferences import read_preferences_text
 from agentpool.session_manager import SessionManager
 
 PROJECT_ROOT = Path(__file__).resolve().parents[3]
@@ -18,6 +19,8 @@ def read_resource(manager: SessionManager, uri: str, lockdown: bool = False) ->
         return _text_resource("onboarding.md")
     if uri == "agentpool://skill.md":
         return _text_resource("agentpool-skill.md")
+    if uri == "agentpool://preferences.md":
+        return read_preferences_text()
     prefix = "agentpool://sessions/"
     if uri.startswith(prefix):
         tail = uri[len(prefix) :]