Skip to main content
ClawQL
Getting started8.0 breaking
Major semver — read before upgrading. Generated from docs/getting-started/migrate-to-8.0.md on main. Status matrix: Vision & roadmap. Release checklist: v8.0.0 checklist.

title: Migrating to ClawQL 8.0.0

Migrating to ClawQL 8.0.0

Breaking release means breaking release. The Phase-2 Plugin / onRegister / beforeCallTool interface is removed. There is no compatibility bridge. Rewrite plugins against ProviderPlugin / StandaloneSkillPlugin. Defaults also change (empty catalog, enforcement off).

Breaking defaults (read first)

Before 8.0 After 8.0 What to set
Bundled OpenAPI pack often loaded Empty catalog until opted in CLAWQL_PROVIDER=default or CLAWQL_INSTANCE_SPEC='\{"providers":\{"pack":"default"\}\}' / Helm providers.pack=default
Panguard proxy composed by default Off until opted in CLAWQL_PANGUARD_PROXY_PLUGIN=1
In-process ATR gating opt-in Still opt-in (unchanged) CLAWQL_PANGUARD_IN_PROCESS=1 (+ block list / real policy as needed)
Silent ungated tools if Panguard passive SECURITY WARNING at boot Install any blocking enforcement provider, or set CLAWQL_ALLOW_NO_ENFORCEMENT=1 only if intentional
Plugin + beforeCallTool Deleted Author ProviderPlugin with tools / hooks / defineRegisteringProviderPlugin

Bare clawql-mcp after upgrade: search / execute / cache / audit / skills_list / skills_get — no GitHub/Slack/… ops and no tool-scope enforcement until you opt in.

Plugin interface (hard break)

  • Only ProviderPlugin and StandaloneSkillPlugin from clawql-core are installable.
  • Tool registration: declare tools on the plugin, or use defineRegisteringProviderPlugin(\{ register \}) for env-gated sets.
  • Enforcement: blocking tool / pre-execute hooks (not beforeCallTool). Awaited by McpProxyPipeline via fireHook (ATR never-loosen).
  • Horizontal tiers: production MCP boot uses dynamic import() via ensureClawqlApi() / createRegisteredMcpServerAsync(). Sync getClawqlApi() still static-composes for tests.

Rewrite sketch

  defineProviderPlugin,
  defineRegisteringProviderPlugin,
} from 'clawql-core'

// Tools
export const myPlugin = defineRegisteringProviderPlugin({
  id: 'my-plugin',
  version: '1.0.0',
  description: '…',
  register: (api) =>
    Effect.gen(function* () {
      yield* api.registerMcpTool({ name: 'my_tool', schema, handler })
    }),
})

// Enforcement (hooks-only is valid)
export const gate = defineProviderPlugin({
  id: 'my-gate',
  version: '1.0.0',
  description: '…',
  hooks: [
    {
      id: 'my-gate:pre-execute',
      scope: 'tool',
      event: 'pre-execute',
      toolPattern: '.*',
      blocking: true,
      handler: (ctx) => Effect.succeed({ allow: true }),
    },
  ],
})

Skills-over-MCP + unified search (8.0)

| Tool / path | Role | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | search | Ranks operations and skills together (kind: "operation" \\ | "skill") | | skills_list | Lightweight index (SkillIndexEntry) | | skills_get | Full skill body by skillId | | Standalone pack | handoff / session-handoff — default on (CLAWQL_ENABLE_HANDOFF_SKILL=0 to omit) | | WebMCP draft | webmcp_draft* — opt-in (CLAWQL_ENABLE_WEBMCP_DRAFT=1); see docs/specs/webmcp-draft/ |

WebMCP draft (opt-in):

export CLAWQL_ENABLE_WEBMCP_DRAFT=1
export CLAWQL_WEBMCP_DRAFT_DURABLE=1          # JSON store under .clawql/ (gateway default when enabled)
# export CLAWQL_WEBMCP_DRAFT_STORE_PATH=/path/to/store.json
# export CLAWQL_WEBMCP_BIND_URL=https://gateway.example/webmcp-draft/bound-execute

MCP tools: webmcp_draft, webmcp_draft_review, webmcp_draft_publish, webmcp_draft_execute, webmcp_draft_rollback. Published browser tools POST /webmcp-draft/bound-execute (OpenAPI/GraphQL → ExecuteService; forms → formAction submit).

Empty skill index until a ProviderPlugin / StandaloneSkillPlugin installs skills (handoff is composed by default).

ATR visibility: provider-bundled skills inherit tool ATR (SkillIndexEntry.source: "provider"). Standalone skills are not ATR-gated. Hosts bind tokens via bindProcessSearchAtrTokens / CLAWQL_SESSION_ATR, or pass atrScopeTokens on the search layer.

Session / model hooks: MCP HTTP fires session-start / session-end; inference callers pass modelHooks: \{ hookRegistry, worm \} into createInferenceGateway (helper: modelHooksFromClawqlApi / getHostInferenceGateway).

Cold-start scenarios (Agent Seer §9): synthesizeScenarios / synthesizeScenariosFromApi build graded scenarios from tool schemas + parameterNotes; map to harness tasks via clawql-harness/bench/scenario-synthesis.

Minimal upgrade checklist

# 1. Rewrite any out-of-tree plugins to ProviderPlugin (no bridge)
# 2. Restore curated APIs (if you relied on the old default pack)
export CLAWQL_PROVIDER=default

# 3. Restore enforcement (recommended for production)
export CLAWQL_PANGUARD_PROXY_PLUGIN=1
export CLAWQL_PANGUARD_IN_PROCESS=1

# 4. Or acknowledge ungated tools (dev only)
# export CLAWQL_ALLOW_NO_ENFORCEMENT=1

Docs