agent-config-kit 0.1.0__py3-none-any.whl

agent_config_kit/__init__.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from .diff import Drift, diff
+from .jsonio import load_json_object, write_json
+from .manifest import Manifest, ManifestError, ManifestOptions, load_manifest
+from .models import (
+    AgentPlatform,
+    ApprovalMode,
+    ApprovalPolicy,
+    CapabilityScope,
+    DeclarativeHook,
+    FrontmatterRule,
+    Hook,
+    HookEvent,
+    InstructionsConfig,
+    LspServer,
+    McpServer,
+    MergeStrategy,
+    PluginRegistration,
+    RemoteServer,
+    Scope,
+    ScopeTarget,
+    SearchStrategy,
+    SkillSource,
+    StdioServer,
+)
+from .plan import InstallResult, RegistrationBundle, apply, apply_all
+from .prune import (
+    PlatformState,
+    apply_with_prune,
+    default_state_path,
+    hook_identity,
+    load_state,
+    write_state,
+)
+from .registry import detect_installed_platforms, get_platform, known_platforms
+
+__all__ = [
+    "AgentPlatform",
+    "ApprovalMode",
+    "ApprovalPolicy",
+    "CapabilityScope",
+    "DeclarativeHook",
+    "Drift",
+    "FrontmatterRule",
+    "Hook",
+    "HookEvent",
+    "InstallResult",
+    "InstructionsConfig",
+    "LspServer",
+    "Manifest",
+    "ManifestError",
+    "ManifestOptions",
+    "McpServer",
+    "MergeStrategy",
+    "PlatformState",
+    "PluginRegistration",
+    "RegistrationBundle",
+    "RemoteServer",
+    "Scope",
+    "ScopeTarget",
+    "SearchStrategy",
+    "SkillSource",
+    "StdioServer",
+    "apply",
+    "apply_all",
+    "apply_with_prune",
+    "default_state_path",
+    "detect_installed_platforms",
+    "diff",
+    "get_platform",
+    "hook_identity",
+    "known_platforms",
+    "load_json_object",
+    "load_manifest",
+    "load_state",
+    "write_json",
+    "write_state",
+]

agent_config_kit/adapters/__init__.py

@@ -0,0 +1 @@
+"""Per-platform wire-format adapters — quirks live here, never in the canonical models."""

agent_config_kit/adapters/_wire/__init__.py

@@ -0,0 +1,14 @@
+"""Vendored, codegen'd wire-format models — adapter-internal, not public API.
+
+Generated with ``datamodel-code-generator`` (per spec D6) from real published
+JSON Schemas (Claude Code's ``settings.json`` hooks section, OpenCode's
+``config.json``) or, where no upstream schema exists (Pi, GitHub Copilot/VS
+Code), a minimal hand-authored one. Regenerate on demand when upstream
+schemas change — deliberately not enforced by CI, since roughly half the
+v1 platforms have no live schema to diff against automatically.
+
+Not imported by ``agent_config_kit``'s adapters at runtime; used only to
+validate adapter output against real schema shape (see
+``tests/test_wire_validation.py``) and as a reference for future adapter
+work.
+"""

agent_config_kit/adapters/_wire/claude_settings.py

@@ -0,0 +1,313 @@
+# generated by datamodel-codegen:
+#   filename:  claude-hooks.schema.json
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, PositiveFloat, RootModel, constr
+
+
+class Shell(StrEnum):
+    bash = "bash"
+    powershell = "powershell"
+
+
+class HookCommand1(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Literal["command"] = Field(..., description="Hook type")
+    command: constr(min_length=1) = Field(..., description="Shell command to execute")
+    timeout: PositiveFloat | None = Field(
+        None, description="Optional timeout in seconds"
+    )
+    async_: bool | None = Field(
+        None,
+        alias="async",
+        description="Run this hook asynchronously without blocking Claude Code",
+    )
+    asyncRewake: bool | None = Field(
+        None,
+        description="When true, the hook runs in the background and wakes the model when it exits with code 2. Implies async.",
+    )
+    shell: Shell | None = Field(
+        None,
+        description='Shell interpreter for the command. "bash" uses the login shell (bash/zsh/sh); "powershell" uses pwsh. Defaults to bash.',
+    )
+    if_: str | None = Field(
+        None,
+        alias="if",
+        description='Optional permission-rule-syntax filter (e.g., "Bash(git *)"). Evaluated only on tool-related events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied); on other events a hook with `if` set never runs. See https://code.claude.com/docs/en/hooks-guide#filter-hooks-with-matchers',
+    )
+    statusMessage: str | None = Field(
+        None, description="Custom spinner message displayed while the hook runs"
+    )
+    args: list[str] | None = Field(
+        None,
+        description="Argument list for exec form. When present, spawns the command directly without shell interpretation — each element is passed as-is, so path placeholders never need quoting. See https://code.claude.com/docs/en/hooks#command-hook-fields",
+    )
+
+
+class HookCommand2(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Literal["prompt"] = Field(..., description="Hook type")
+    prompt: constr(min_length=1) = Field(
+        ...,
+        description="Prompt to evaluate with LLM. Use $ARGUMENTS placeholder for hook input JSON.",
+    )
+    model: str | None = Field(
+        None, description="Model to use for evaluation. Defaults to a fast model"
+    )
+    timeout: PositiveFloat | None = Field(
+        None, description="Optional timeout in seconds (default: 30)"
+    )
+    if_: str | None = Field(
+        None,
+        alias="if",
+        description="Optional permission-rule-syntax filter. Evaluated only on tool-related events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied); on other events a hook with `if` set never runs. See https://code.claude.com/docs/en/hooks-guide#filter-hooks-with-matchers",
+    )
+    statusMessage: str | None = Field(
+        None, description="Custom spinner message displayed while the hook runs"
+    )
+    continueOnBlock: bool | None = Field(
+        False,
+        description='When the prompt returns ok: false, feed the reason back to Claude and continue the turn instead of stopping. Implemented as continue: true on the resulting decision: "block". See https://code.claude.com/docs/en/hooks#prompt-hook-configuration',
+    )
+
+
+class HookCommand3(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Literal["agent"] = Field(..., description="Hook type")
+    prompt: constr(min_length=1) = Field(
+        ...,
+        description="Prompt describing what to verify. Use $ARGUMENTS placeholder for hook input JSON.",
+    )
+    model: str | None = Field(
+        None, description="Model to use for evaluation. Defaults to a fast model"
+    )
+    timeout: PositiveFloat | None = Field(
+        None, description="Optional timeout in seconds (default: 60)"
+    )
+    if_: str | None = Field(
+        None,
+        alias="if",
+        description="Optional permission-rule-syntax filter. Evaluated only on tool-related events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied); on other events a hook with `if` set never runs. See https://code.claude.com/docs/en/hooks-guide#filter-hooks-with-matchers",
+    )
+    statusMessage: str | None = Field(
+        None, description="Custom spinner message displayed while the hook runs"
+    )
+
+
+class HookCommand4(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Literal["http"] = Field(..., description="Hook type")
+    url: constr(min_length=1) = Field(
+        ...,
+        description="URL to POST hook input JSON to. Endpoint must accept POST requests and return JSON.",
+    )
+    headers: dict[str, str] | None = Field(
+        None,
+        description="Custom HTTP headers (e.g., Authorization: Bearer token). Values support $VAR_NAME or ${VAR_NAME} interpolation.",
+    )
+    allowedEnvVars: list[constr(min_length=1)] | None = Field(
+        None,
+        description="List of environment variable names permitted for interpolation in headers. If not set, no env var interpolation is allowed.",
+    )
+    timeout: PositiveFloat | None = Field(
+        None, description="Optional timeout in seconds (default: 30)"
+    )
+    if_: str | None = Field(
+        None,
+        alias="if",
+        description="Optional permission-rule-syntax filter. Evaluated only on tool-related events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied); on other events a hook with `if` set never runs. See https://code.claude.com/docs/en/hooks-guide#filter-hooks-with-matchers",
+    )
+    statusMessage: str | None = Field(
+        None, description="Custom spinner message displayed while the hook runs"
+    )
+
+
+class HookCommand5(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Literal["mcp_tool"] = Field(..., description="Hook type")
+    server: constr(min_length=1) = Field(
+        ..., description="Name of a configured MCP server (must already be connected)"
+    )
+    tool: constr(min_length=1) = Field(
+        ..., description="Name of the tool to call on that server"
+    )
+    input: dict[str, Any] | None = Field(
+        None,
+        description="Arguments passed to the tool. String values support ${path} substitution from hook JSON input (e.g., ${tool_input.file_path}, ${cwd})",
+    )
+    timeout: PositiveFloat | None = Field(
+        None, description="Optional timeout in seconds (default: 60)"
+    )
+    if_: str | None = Field(
+        None,
+        alias="if",
+        description="Optional permission-rule-syntax filter. Evaluated only on tool-related events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied); on other events a hook with `if` set never runs. See https://code.claude.com/docs/en/hooks-guide#filter-hooks-with-matchers",
+    )
+    statusMessage: str | None = Field(
+        None, description="Custom spinner message displayed while the hook runs"
+    )
+
+
+class HookCommand(
+    RootModel[HookCommand1 | HookCommand2 | HookCommand3 | HookCommand4 | HookCommand5]
+):
+    root: HookCommand1 | HookCommand2 | HookCommand3 | HookCommand4 | HookCommand5
+
+
+class HookMatcher(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    matcher: str | None = Field(
+        None,
+        description="Optional pattern to match event contexts, case-sensitive. Behavior depends on event type. See https://code.claude.com/docs/en/hooks#matcher-patterns for event-specific details and examples",
+    )
+    hooks: list[HookCommand] = Field(..., description="Array of hooks to execute")
+
+
+class Hooks(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    PreToolUse: list[HookMatcher] | None = Field(
+        None, description="Hooks that run before tool calls"
+    )
+    PostToolUse: list[HookMatcher] | None = Field(
+        None, description="Hooks that run after tool completion"
+    )
+    PostToolUseFailure: list[HookMatcher] | None = Field(
+        None, description="Hooks that run after a tool fails"
+    )
+    PermissionRequest: list[HookMatcher] | None = Field(
+        None, description="Hooks that run when a permission dialog appears"
+    )
+    Notification: list[HookMatcher] | None = Field(
+        None, description="Hooks that trigger on notifications"
+    )
+    UserPromptSubmit: list[HookMatcher] | None = Field(
+        None, description="Hooks that run when a user submits a prompt"
+    )
+    Stop: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when agents finish responding. Does not run on user interrupt",
+    )
+    StopFailure: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a turn ends due to an API error (e.g., rate_limit, authentication_failed, billing_error, invalid_request, server_error, max_output_tokens, unknown). Matcher can scope to specific error types. Hook output and exit code are ignored. See https://code.claude.com/docs/en/hooks",
+    )
+    SubagentStart: list[HookMatcher] | None = Field(
+        None, description="Hooks that run when a subagent is spawned"
+    )
+    SubagentStop: list[HookMatcher] | None = Field(
+        None, description="Hooks that run when subagents finish responding"
+    )
+    PreCompact: list[HookMatcher] | None = Field(
+        None, description="Hooks that run before the context is compacted"
+    )
+    PostCompact: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run after the context is compacted. See https://code.claude.com/docs/en/hooks",
+    )
+    Elicitation: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when an MCP server requests user input during a tool call. See https://code.claude.com/docs/en/hooks",
+    )
+    ElicitationResult: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run after a user responds to an MCP elicitation, before the response is sent back to the server. See https://code.claude.com/docs/en/hooks",
+    )
+    TeammateIdle: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when an agent team teammate is about to go idle. Exit code 2 sends feedback and keeps the teammate working. Does not support matchers. Agent teams are experimental. See https://code.claude.com/docs/en/hooks#teammateidle",
+    )
+    TaskCompleted: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a task is being marked as completed. Exit code 2 prevents completion and sends feedback. Does not support matchers. See https://code.claude.com/docs/en/hooks#taskcompleted",
+    )
+    Setup: list[HookMatcher] | None = Field(
+        None,
+        description="UNDOCUMENTED. Hooks that run during repository initialization (--init, --init-only) or maintenance (--maintenance)",
+    )
+    InstructionsLoaded: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a CLAUDE.md or .claude/rules/*.md file is loaded into context. Fires at session start and when files are lazily loaded (e.g., nested traversal, path glob match). No decision control; used for audit logging and observability. Does not support matchers. See https://code.claude.com/docs/en/hooks#instructionsloaded",
+    )
+    CwdChanged: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when the working directory changes. Provides cwd (new directory) and previous_cwd. Matchers are ignored; fires on every directory change. See https://code.claude.com/docs/en/hooks#cwdchanged",
+    )
+    FileChanged: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a watched file is created, modified, or deleted. Supports filename matchers. Provides file_path and file_event_type (created, modified, deleted). See https://code.claude.com/docs/en/hooks#filechanged",
+    )
+    ConfigChange: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when settings, managed settings, or skill files change during a session. Supports matchers: user_settings, project_settings, local_settings, policy_settings, skills. Command handlers only. Exit code 2 blocks the change (except policy_settings which is audit-only). See https://code.claude.com/docs/en/hooks#configchange",
+    )
+    WorktreeCreate: list[HookMatcher] | None = Field(
+        None,
+        description='Hooks that run when a worktree is created via --worktree or isolation: "worktree" in subagents. Command handlers only, no matchers. Hook must print absolute path to created worktree on stdout; non-zero exit fails creation. See https://code.claude.com/docs/en/hooks#worktreecreate',
+    )
+    WorktreeRemove: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a worktree is being removed at session exit or when a subagent finishes. Command handlers only, no matchers. Used for cleanup tasks; cannot block removal. See https://code.claude.com/docs/en/hooks#worktreeremove",
+    )
+    SessionStart: list[HookMatcher] | None = Field(
+        None, description="Hooks that run when a new session starts"
+    )
+    SessionEnd: list[HookMatcher] | None = Field(
+        None, description="Hooks that run when a session ends"
+    )
+    PostToolBatch: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run after a full batch of parallel tool calls resolves, before the next model call. Exit code 2 blocks the agentic loop. Does not support matchers. See https://code.claude.com/docs/en/hooks",
+    )
+    TaskCreated: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a task is being created via TaskCreate. Exit code 2 rolls back task creation. Does not support matchers. See https://code.claude.com/docs/en/hooks#taskcreated",
+    )
+    PermissionDenied: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a tool call is denied by the auto mode classifier. Supports matchers on tool name. See https://code.claude.com/docs/en/hooks",
+    )
+    UserPromptExpansion: list[HookMatcher] | None = Field(
+        None,
+        description="Hooks that run when a user-typed command expands into a prompt, before it reaches Claude. Exit code 2 blocks the expansion. Supports matchers on command name. See https://code.claude.com/docs/en/hooks",
+    )
+
+
+class ClaudeCodeHooksConfig(BaseModel):
+    hooks: Hooks | None = Field(
+        None,
+        description="Custom commands to run before/after tool executions. See https://code.claude.com/docs/en/hooks",
+        examples=[
+            {
+                "PostToolUse": [
+                    {
+                        "matcher": "Edit|Write",
+                        "hooks": [
+                            {
+                                "type": "command",
+                                "command": "prettier --write",
+                                "timeout": 5,
+                            }
+                        ],
+                    }
+                ]
+            }
+        ],
+    )

agent_config_kit/adapters/_wire/copilot_mcp.py

@@ -0,0 +1,34 @@
+# generated by datamodel-codegen:
+#   filename:  copilot-mcp.schema.json
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Type(StrEnum):
+    stdio = "stdio"
+    sse = "sse"
+    http = "http"
+
+
+class CopilotMcpServer(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Type
+    command: str | None = None
+    args: list[str] | None = None
+    url: str | None = None
+    inputs: list[dict[str, Any]] | None = None
+    env: dict[str, str] | None = None
+
+
+class CopilotMcpConfig(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    servers: dict[str, CopilotMcpServer] | None = None

agent_config_kit/adapters/_wire/opencode_config.py

@@ -0,0 +1,120 @@
+# generated by datamodel-codegen:
+#   filename:  opencode-mcp.schema.json
+
+from __future__ import annotations
+
+from enum import Enum, StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, conint
+
+
+class Mcp(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    enabled: bool
+
+
+class Skills(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    paths: list[str] | None = Field(
+        None, description="Additional paths to skill folders"
+    )
+    urls: list[str] | None = Field(
+        None,
+        description="URLs to fetch skills from (e.g., https://example.com/.well-known/skills/)",
+    )
+
+
+class Type(StrEnum):
+    local = "local"
+
+
+class McpLocalConfig(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Type = Field(..., description="Type of MCP server connection")
+    command: list[str] = Field(
+        ..., description="Command and arguments to run the MCP server"
+    )
+    cwd: str | None = Field(
+        None,
+        description="Working directory for the MCP server process. Relative paths resolve from the workspace directory.",
+    )
+    environment: dict[str, str] | None = Field(
+        None, description="Environment variables to set when running the MCP server"
+    )
+    enabled: bool | None = Field(
+        None, description="Enable or disable the MCP server on startup"
+    )
+    timeout: conint(le=9007199254740991, gt=0) | None = Field(
+        None,
+        description="Timeout in ms for MCP server requests. Defaults to 5000 (5 seconds) if not specified.",
+    )
+
+
+class McpOAuthConfig(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    clientId: str | None = Field(
+        None,
+        description="OAuth client ID. If not provided, dynamic client registration (RFC 7591) will be attempted.",
+    )
+    clientSecret: str | None = Field(
+        None,
+        description="OAuth client secret (if required by the authorization server)",
+    )
+    scope: str | None = Field(
+        None, description="OAuth scopes to request during authorization"
+    )
+    callbackPort: conint(ge=1, le=65535) | None = Field(
+        None,
+        description="Port for the local OAuth callback server (default: 19876). Shorthand for redirectUri when only the port needs changing. Ignored if redirectUri is set.",
+    )
+    redirectUri: str | None = Field(
+        None,
+        description="OAuth redirect URI (default: http://127.0.0.1:19876/mcp/oauth/callback).",
+    )
+
+
+class Type1(StrEnum):
+    remote = "remote"
+
+
+class Oauth(Enum):
+    boolean_False = False
+
+
+class McpRemoteConfig(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    type: Type1 = Field(..., description="Type of MCP server connection")
+    url: str = Field(..., description="URL of the remote MCP server")
+    enabled: bool | None = Field(
+        None, description="Enable or disable the MCP server on startup"
+    )
+    headers: dict[str, str] | None = Field(
+        None, description="Headers to send with the request"
+    )
+    oauth: McpOAuthConfig | Oauth | None = Field(
+        None,
+        description="OAuth authentication configuration for the MCP server. Set to false to disable OAuth auto-detection.",
+    )
+    timeout: conint(le=9007199254740991, gt=0) | None = Field(
+        None,
+        description="Timeout in ms for MCP server requests. Defaults to 5000 (5 seconds) if not specified.",
+    )
+
+
+class OpenCodeMcpConfig(BaseModel):
+    mcp: dict[str, McpLocalConfig | McpRemoteConfig | Mcp] | None = Field(
+        None, description="MCP (Model Context Protocol) server configurations"
+    )
+    plugin: list[str | tuple[str, dict[str, Any]]] | None = None
+    skills: Skills | None = Field(None, description="Additional skill folder paths")

agent_config_kit/adapters/_wire/pi_mcp.py

@@ -0,0 +1,36 @@
+# generated by datamodel-codegen:
+#   filename:  pi-mcp.schema.json
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class Settings(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    toolPrefix: str | None = None
+    idleTimeout: int | None = None
+
+
+class PiMcpServer(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    command: str | None = None
+    args: list[str] | None = None
+    url: str | None = None
+    lifecycle: str | None = None
+    idleTimeout: int | None = None
+    directTools: list[str] | None = None
+    debug: bool | None = None
+    env: dict[str, str] | None = None
+
+
+class PiMcpConfig(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    settings: Settings | None = None
+    mcpServers: dict[str, PiMcpServer] | None = None