fix(config): per-agent parallel_tool_calls defaults; fix lint & skill regressions

The earlier refactor on this branch collapsed three agent builders' distinct
historical parallel_tool_calls defaults onto one shared value, changing
behavior for two of them:

- lint agent: never sent parallel_tool_calls before; the refactor made it
  send `false` by default, re-triggering the Bedrock #175 malformed-tool_choice
  bug for `openkb lint` (LiteLLM's Bedrock transform breaks on ANY value).
- skill-create agent: kept a hardcoded `parallel_tool_calls=True` that ignored
  config entirely, so `openkb skill new` stayed broken on Bedrock even with the
  `parallel_tool_calls: null` escape hatch set.

Make resolution tri-state — resolve_parallel_tool_calls now returns
(value, was_explicit):
- key absent  -> each agent applies its OWN historical default via
  resolve_model_settings(default_parallel_tool_calls=...): query/chat False,
  lint None (omit), skill-create True.
- true/false/null -> applies uniformly to every agent (the escape hatch works
  regardless of which agent runs).
- invalid value -> omit (the one value that never breaks a provider), instead
  of the old fall-back to False that could silently re-break Bedrock.

parallel_tool_calls is dropped from DEFAULT_CONFIG so load_config's merge can't
mask "not configured"; the runtime stash carries the was_explicit flag.

Tool-less eval agents (skill/evaluator.py) deliberately stay unmigrated and
always omit the setting — the SDK forwards an explicit `false` even with no
tools, which strict OpenAI endpoints reject. Guarded by tests.

Docs: the setting now scopes to all LLM agents (query/chat/lint/skill),
documents the unset-per-agent-default semantics and the bare-`null` requirement.

Adds regression tests across config/query/linter/skill-creator/skill-evaluator.

Author: KylinMountain

config.yaml.example

@@ -2,12 +2,14 @@ model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 
-# Optional: whether query/chat agents may call tools in parallel.
-#   false (default) force sequential tool calls
-#   true            allow parallel tool calls
-#   null            don't send the setting (use the provider default) — set this
-#                   for Amazon Bedrock Claude, which rejects the request when
-#                   parallel_tool_calls is sent at all (any value). See #175.
+# Optional: whether the LLM agents (query, chat, lint, skill) may call tools
+# in parallel. Leave it UNSET (commented out) to keep OpenKB's per-agent
+# defaults. Setting it applies the SAME value to every agent:
+#   true    allow parallel tool calls
+#   false   force sequential tool calls
+#   null    don't send the setting at all (use the provider default) — REQUIRED
+#           for Amazon Bedrock Claude, which rejects the request when
+#           parallel_tool_calls is sent at all (any value). See #175.
 # parallel_tool_calls: null
 
 # Optional: override the entity-type vocabulary used for entity pages.

examples/configuration/README.md

@@ -70,12 +70,14 @@ model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 
-# Optional: whether query/chat agents may call tools in parallel.
-#   false (default) force sequential tool calls
-#   true            allow parallel tool calls
-#   null            don't send the setting (use the provider default) — set this
-#                   for Amazon Bedrock Claude, which rejects the request when
-#                   parallel_tool_calls is sent at all (any value). See #175.
+# Optional: whether the LLM agents (query, chat, lint, skill) may call tools
+# in parallel. Leave it UNSET (commented out) to keep OpenKB's per-agent
+# defaults. Setting it applies the SAME value to every agent:
+#   true    allow parallel tool calls
+#   false   force sequential tool calls
+#   null    don't send the setting at all (use the provider default) — REQUIRED
+#           for Amazon Bedrock Claude, which rejects the request when
+#           parallel_tool_calls is sent at all (any value). See #175.
 # parallel_tool_calls: null
 
 # Optional: override the entity-type vocabulary used for entity pages.
@@ -103,7 +105,7 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 | `model` | `gpt-5.4` | LLM used for all compile/query/chat work. |
 | `language` | `en` | Language the wiki is written in. |
 | `pageindex_threshold` | `20` | PDFs with this many pages **or more** take the long-doc (PageIndex) path; shorter ones go through the short-doc path. See [`pageindex-cloud/`](../pageindex-cloud/). |
-| `parallel_tool_calls` | `false` | Whether query/chat agents may call tools in parallel. `false` (default) forces sequential; `true` allows parallel; `null` omits the setting (provider default). **Amazon Bedrock needs `null`** (see below). |
+| `parallel_tool_calls` | unset | Whether the LLM agents (query, chat, lint, skill) may call tools in parallel. Unset keeps OpenKB's per-agent defaults; `true`/`false` force allow/sequential for every agent; `null` omits the setting (provider default). **Amazon Bedrock needs `null`** (see below). |
 | `entity_types` | 7 defaults | Custom vocabulary for entity pages. `other` is always kept. |
 | `litellm:` | – | A pass-through block for LiteLLM. See below. |
 
@@ -200,10 +202,11 @@ LLM_API_KEY=your-key-here
   ```yaml
   # <kb>/.openkb/config.yaml
   model: bedrock/eu.anthropic.claude-sonnet-4-6
-  parallel_tool_calls: null   # REQUIRED for Bedrock Claude: the default (false)
-                              # — and any explicit value — makes LiteLLM send a
-                              # malformed tool_choice that Bedrock rejects (#175).
-                              # null tells OpenKB not to send the setting at all.
+  parallel_tool_calls: null   # REQUIRED for Bedrock Claude: sending
+                              # parallel_tool_calls at all (any value) makes
+                              # LiteLLM send a malformed tool_choice that Bedrock
+                              # rejects (#175). null tells OpenKB to omit it.
+                              # Write it as bare `null` — not `None` or "null".
   ```
 
 **Where keys are read from** (first match wins, existing env always respected):

openkb/agent/linter.py

@@ -82,7 +82,7 @@ def read_file(path: str) -> str:
         instructions=instructions,
         tools=[list_files, read_file],
         model=f"litellm/{model}",
-        model_settings=ModelSettings(**resolve_model_settings()),
+        model_settings=ModelSettings(**resolve_model_settings(default_parallel_tool_calls=None)),
     )
 
 

openkb/cli.py

@@ -176,7 +176,8 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
     provider: str | None = None
     extra_headers: dict[str, str] = {}
     timeout: float | None = None
-    parallel_tool_calls: bool | None = DEFAULT_CONFIG["parallel_tool_calls"]
+    parallel_tool_calls: bool | None = None
+    parallel_tool_calls_explicit = False
     litellm_settings: dict = {}
     if kb_dir is not None:
         config_path = kb_dir / ".openkb" / "config.yaml"
@@ -186,7 +187,7 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
             provider = _extract_provider(str(model))
             extra_headers = resolve_extra_headers(config)
             timeout = resolve_timeout(config)
-            parallel_tool_calls = resolve_parallel_tool_calls(config)
+            parallel_tool_calls, parallel_tool_calls_explicit = resolve_parallel_tool_calls(config)
             litellm_settings = resolve_litellm_settings(config)
             # `timeout` / `extra_headers` in the block route to the per-call
             # stashes (replacing the legacy top-level keys); the rest are globals.
@@ -198,7 +199,7 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
                 timeout = resolve_timeout({"timeout": litellm_settings.pop("timeout")})
     set_extra_headers(extra_headers)
     set_timeout(timeout)
-    set_parallel_tool_calls(parallel_tool_calls)
+    set_parallel_tool_calls(parallel_tool_calls, parallel_tool_calls_explicit)
     _apply_litellm_settings(litellm_settings)
 
     if not api_key:

openkb/config.py

@@ -17,13 +17,6 @@
     "model": "gpt-5.4",
     "language": "en",
     "pageindex_threshold": 20,
-    # Whether query/chat agents may call tools in parallel. Default false =
-    # force sequential tool calls (historical behavior). true = allow parallel.
-    # null = don't send the setting at all (use the provider default) — the
-    # escape hatch for Amazon Bedrock Claude, where sending parallel_tool_calls
-    # (any value) makes LiteLLM emit a malformed tool_choice missing `type`, so
-    # every query/chat fails (issue #175).
-    "parallel_tool_calls": False,
 }
 
 # Default entity-type vocabulary. Overridable per-KB via the optional
@@ -151,36 +144,48 @@ def resolve_extra_headers(config: dict) -> dict[str, str]:
     return headers
 
 
-def resolve_parallel_tool_calls(config: dict) -> bool | None:
+def resolve_parallel_tool_calls(config: dict) -> tuple[bool | None, bool]:
     """Resolve the optional ``parallel_tool_calls:`` key.
 
-    Tri-state:
-      * key absent → the default (``False`` — force sequential tool calls).
-      * ``true`` / ``false`` → that bool.
-      * explicit ``null`` → ``None``, meaning "don't send the setting" so the
-        provider's own default applies. This is the escape hatch for Amazon
-        Bedrock Claude, which rejects the request when the param is sent at all.
-
-    A non-bool, non-null value is invalid → falls back to the default with a
-    warning. An explicit ``null`` is a valid choice and warns silently.
-
-    Note this relies on the config being merged with ``DEFAULT_CONFIG`` (as
-    ``load_config`` does), so an omitted key reads back as ``False`` while an
-    explicit ``null`` reads back as ``None`` — the two are distinguishable.
+    Returns ``(value, was_explicit)``:
+      * key absent → ``(None, False)`` — "not configured". Different agent
+        builders had different HISTORICAL defaults before this setting existed
+        (query/chat forced sequential; the semantic linter and skill-creation
+        agents never forced a value at all), so there's no single systemwide
+        default to fall back to here — ``resolve_model_settings()`` lets each
+        caller supply its own, applied only when ``was_explicit`` is ``False``.
+      * ``true`` / ``false`` → ``(that bool, True)`` — an explicit choice that
+        overrides every agent's own default uniformly.
+      * explicit ``null`` → ``(None, True)`` — "don't send the setting at all"
+        (the provider decides). This is the escape hatch for Amazon Bedrock
+        Claude, which rejects the request when the param is sent at all —
+        distinct from "absent" even though both currently carry a value of
+        ``None``; ``was_explicit`` is what tells them apart.
+      * anything else (invalid) → ``(None, True)``, with a warning. Omitting
+        is the one value known to never break any provider, so a malformed
+        config value degrades to the safest behavior rather than to a fixed
+        bool that could reproduce the exact failure (e.g. Bedrock's) the user
+        may have set this key specifically to avoid.
+
+    This function does not depend on ``config`` being pre-merged with
+    ``DEFAULT_CONFIG`` — ``parallel_tool_calls`` is intentionally absent from
+    ``DEFAULT_CONFIG`` so ``load_config``'s merge can't mask "the user's
+    config.yaml doesn't mention this key" as if it had been set to a value.
     """
-    default = DEFAULT_CONFIG["parallel_tool_calls"]
-    value = config.get("parallel_tool_calls", default)
+    if "parallel_tool_calls" not in config:
+        return None, False
+    value = config["parallel_tool_calls"]
     if value is None:
-        return None
-    if not isinstance(value, bool):
-        logger.warning(
-            "config: 'parallel_tool_calls' must be true, false, or null, got %r "
-            "— using default (%r).",
-            value,
-            default,
-        )
-        return default
-    return value
+        return None, True
+    if isinstance(value, bool):
+        return value, True
+    logger.warning(
+        "config: 'parallel_tool_calls' must be true, false, or null, got %r "
+        "— omitting the setting (the safest fallback; it never breaks a "
+        "provider, unlike a fixed true/false might).",
+        value,
+    )
+    return None, True
 
 
 def resolve_timeout(config: dict) -> float | None:
@@ -283,37 +288,64 @@ def get_timeout_extra_args() -> dict[str, float] | None:
 
 
 # Process-wide agent ``parallel_tool_calls`` setting, resolved from config by
-# the CLI (cli._setup_llm_key) and read when building query/chat agents. None =
-# omit the setting (provider default) — see the DEFAULT_CONFIG note on why
-# Bedrock needs this.
-_runtime_parallel_tool_calls: bool | None = None
+# the CLI (cli._setup_llm_key) and read when building agents. ``(None, False)``
+# — the module's own raw default — means "not configured", matching what
+# ``resolve_parallel_tool_calls({})`` returns for an absent key, so an agent
+# built before ``_setup_llm_key`` has ever run defers to its own default via
+# ``resolve_model_settings()`` instead of landing on an arbitrary fixed value.
+_runtime_parallel_tool_calls: tuple[bool | None, bool] = (None, False)
 
 
-def set_parallel_tool_calls(value: bool | None) -> None:
-    """Set the process-wide agent ``parallel_tool_calls`` setting."""
+def set_parallel_tool_calls(value: bool | None, was_explicit: bool) -> None:
+    """Set the process-wide agent ``parallel_tool_calls`` setting.
+
+    ``was_explicit`` distinguishes "the KB's config.yaml has no
+    ``parallel_tool_calls`` key" (``False``) from "the user explicitly chose
+    this value, including an explicit ``null``" (``True``) — see
+    :func:`resolve_parallel_tool_calls`.
+    """
     global _runtime_parallel_tool_calls
-    _runtime_parallel_tool_calls = value
+    _runtime_parallel_tool_calls = (value, was_explicit)
 
 
-def get_parallel_tool_calls() -> bool | None:
-    """Return the process-wide agent ``parallel_tool_calls`` setting (or None)."""
+def get_parallel_tool_calls() -> tuple[bool | None, bool]:
+    """Return the process-wide agent ``parallel_tool_calls`` setting as
+    ``(value, was_explicit)`` — see :func:`resolve_parallel_tool_calls`."""
     return _runtime_parallel_tool_calls
 
 
-def resolve_model_settings() -> dict[str, Any]:
+def resolve_model_settings(*, default_parallel_tool_calls: bool | None = False) -> dict[str, Any]:
     """Assemble the agents-SDK ``ModelSettings`` kwargs from the process-wide LLM
     runtime settings (populated by ``cli._setup_llm_key``).
 
     This is the single place that maps runtime LLM config onto agent model
-    settings: every agent builder does ``ModelSettings(**resolve_model_settings())``
-    rather than enumerating the individual getters, so a new agent-facing knob
-    is wired in here once and can't be silently forgotten by one builder.
-    ``None`` values are what the agents SDK treats as "unset / provider default".
+    settings: TOOL-USING agent builders (query, chat, lint, skill-create) do
+    ``ModelSettings(**resolve_model_settings(...))`` rather than enumerating
+    the individual getters, so a new agent-facing knob is wired in here once
+    and can't be silently forgotten by one of them. ``None`` values are what
+    the agents SDK treats as "unset / provider default".
+
+    Tool-LESS agents (e.g. the skill-eval graders) deliberately do NOT use
+    this — ``parallel_tool_calls`` is meaningless without tools, and the
+    agents SDK forwards an explicit ``False`` even to a tool-less request,
+    which strict OpenAI-compatible endpoints reject. They build
+    ``ModelSettings`` directly and omit ``parallel_tool_calls`` entirely.
+
+    ``default_parallel_tool_calls`` is applied ONLY when the KB's config.yaml
+    doesn't configure ``parallel_tool_calls`` at all — pass your agent
+    builder's own historical default here (``query``/``chat`` force
+    sequential → ``False``, the module default; other builders pass their
+    own). An explicit config value (``true``/``false``/``null``) always
+    overrides every builder's default uniformly — that's what lets Amazon
+    Bedrock users escape issue #175 with one setting, regardless of which
+    agent they're running.
     """
+    value, was_explicit = get_parallel_tool_calls()
+    parallel_tool_calls = value if was_explicit else default_parallel_tool_calls
     return {
         "extra_headers": get_extra_headers() or None,
         "extra_args": get_timeout_extra_args(),
-        "parallel_tool_calls": get_parallel_tool_calls(),
+        "parallel_tool_calls": parallel_tool_calls,
     }
 
 

openkb/skill/creator.py

@@ -20,7 +20,7 @@
 from agents import Agent, Runner, ToolOutputImage, ToolOutputText, function_tool
 from agents.model_settings import ModelSettings
 
-from openkb.config import get_extra_headers, get_timeout_extra_args
+from openkb.config import resolve_model_settings
 from openkb.prompts import load_prompt
 from openkb.schema import get_agents_md
 from openkb.skill import skill_dir
@@ -154,18 +154,15 @@ def done(summary: str) -> str:
             done,
         ],
         model=f"litellm/{model}",
-        # Allow the model to issue multiple read tool calls in one turn —
-        # the compile's early phase is a fan-out (list dir -> read N
-        # summaries -> read N source page-ranges), and serialising each
-        # read into its own turn costs roughly 5-10 extra round-trips per
-        # compile. Writes serialise naturally because each
-        # `write_skill_file` depends on accumulated reads; the model has
-        # no reason to issue parallel writes to the same path.
-        model_settings=ModelSettings(
-            parallel_tool_calls=True,
-            extra_headers=get_extra_headers() or None,
-            extra_args=get_timeout_extra_args(),
-        ),
+        # Default to allowing parallel read tool calls — the compile's early
+        # phase is a fan-out (list dir -> read N summaries -> read N source
+        # page-ranges), and serialising each read into its own turn costs
+        # roughly 5-10 extra round-trips per compile. Writes serialise
+        # naturally because each `write_skill_file` depends on accumulated
+        # reads; the model has no reason to issue parallel writes to the
+        # same path. An explicit `parallel_tool_calls:` in config.yaml (e.g.
+        # `null` for Amazon Bedrock, issue #175) overrides this uniformly.
+        model_settings=ModelSettings(**resolve_model_settings(default_parallel_tool_calls=True)),
     )
 
 

tests/conftest.py

@@ -12,7 +12,7 @@ def _reset_extra_headers():
     yield
     set_extra_headers({})
     set_timeout(None)
-    set_parallel_tool_calls(None)
+    set_parallel_tool_calls(None, False)
 
 
 @pytest.fixture