fix: apply external review findings across recent checkpoints

- CRITICAL: GIT_CONTEXT_AGENT_TYPES used underscored reviewer names while
  registered type names are dashed (code-reviewer/security-reviewer), so
  reviewer agents silently missed the git-context injection; names fixed
  and a pin added asserting every gate name is a real profile key.
- Foreground isolation requests now fail fast on Agent AND RunAgents
  instead of warning-and-proceeding unisolated (degraded behavior was
  presented as authoritative); warning pin updated to the new contract.
- Unknown-config-key diagnostics now also run for explicit loads
  (--config-file / --config text) via single-source provenance.
- Failure/timeout/cancel paths name the retained isolation worktree in
  the task output (retention is deliberate for resume, never silent).
- Best-effort prune in overflow recovery logs its failure instead of
  contextlib.suppress.
- supports_parallel flags annotated (: bool); test helpers cleaned
  (fail-fast _git asserts, unused _ListingClient params dropped).

Author: elkaix

src/pythinker_code/background/agent_runner.py

@@ -137,11 +137,13 @@ async def run(self) -> None:
                 output.error(
                     _timeout_recovery_message(timeout_s=self._timeout_s, agent_id=self._agent_id)
                 )
+                self._note_retained_worktree(output)
             else:
                 # Internal timeout (e.g. aiohttp request) — treat as generic failure
                 logger.exception("Background agent runner failed")
                 self._finalize_safely(outcome="failed", reason=str(exc))
                 output.error(_failure_recovery_message(reason=str(exc), agent_id=self._agent_id))
+                self._note_retained_worktree(output)
         except asyncio.CancelledError:
             self._finalize_safely(outcome="killed", reason="Stopped by TaskStop")
             output.stage("cancelled")
@@ -156,6 +158,7 @@ async def run(self) -> None:
             logger.exception("Background agent runner failed")
             self._finalize_safely(outcome="failed", reason=str(exc))
             output.error(_failure_recovery_message(reason=str(exc), agent_id=self._agent_id))
+            self._note_retained_worktree(output)
         finally:
             # Whatever happens in approval cleanup below, the dict pop must
             # run — it is the *only* place that removes this task from
@@ -272,6 +275,19 @@ async def _prepare_isolation_worktree(self, output: SubagentOutputWriter) -> Hos
         output.stage(f"worktree_created: {worktree}")
         return HostPath.unsafe_from_local_path(worktree)
 
+    def _note_retained_worktree(self, output: SubagentOutputWriter) -> None:
+        """Name the retained worktree on failure/timeout paths.
+
+        Retention on failure is deliberate — resume reuses the worktree and a
+        post-mortem may need its state — but it must never be silent.
+        """
+        if self._worktree_path is None:
+            return
+        output.stage(
+            f"worktree_retained: {self._worktree_path} (resume reuses it; remove with "
+            f"`git worktree remove {self._worktree_path}`)"
+        )
+
     async def _append_worktree_report(self, final_response: str) -> str:
         """Tell the orchestrator where the isolated changes live.
 

src/pythinker_code/config.py

@@ -185,6 +185,21 @@ def _sole_non_none_type(annotation: Any) -> Any:
     return annotation
 
 
+def _report_unknown_keys_single_source(data: Any, source: str) -> None:
+    """Unknown-key diagnostics for single-source loads (--config/--config-file).
+
+    The scoped pipeline reports through its merge provenance; explicit loads
+    bypass the merge, so build a one-source provenance here. Non-dict payloads
+    are left for Config.model_validate to reject with its own error.
+    """
+    if not isinstance(data, dict):
+        return
+    plain = {str(key): value for key, value in cast(dict[Any, Any], data).items()}
+    provenance: dict[str, Any] = {}
+    merged = _type_based_merge({}, plain, provenance, source)
+    _report_unknown_config_keys(merged, provenance)
+
+
 def _report_unknown_config_keys(merged: dict[str, Any], provenance: dict[str, Any]) -> None:
     """Warn (or raise under PYTHINKER_STRICT_CONFIG) for unconsumed keys."""
     unknown_paths = unknown_config_key_paths(Config, merged)
@@ -1217,6 +1232,7 @@ def load_config(config_file: Path | None = None) -> Config:
             data = json.loads(config_text)
         else:
             data = tomlkit.loads(config_text)
+        _report_unknown_keys_single_source(data, str(config_file))
         config = Config.model_validate(data)
     except json.JSONDecodeError as e:
         raise ConfigError(f"Invalid JSON in configuration file {config_file}: {e}") from e
@@ -1260,6 +1276,7 @@ def load_config_from_string(config_string: str) -> Config:
                 f"Invalid configuration text: {json_error}; {toml_error}"
             ) from toml_error
 
+    _report_unknown_keys_single_source(data, "--config text")
     try:
         config = Config.model_validate(data)
     except ValidationError as e:

src/pythinker_code/soul/pythinkersoul.py

@@ -1979,8 +1979,13 @@ async def _recover_from_context_overflow(self, step_no: int) -> bool:
             step_no=step_no,
         )
         try:
-            with contextlib.suppress(Exception):
+            try:
                 await self.prune_context()
+            except Exception as prune_err:
+                logger.debug(
+                    "Best-effort prune during overflow recovery failed: {error}",
+                    error=prune_err,
+                )
             await self.compact_context()
         except Exception as compact_err:
             from pythinker_code.telemetry.errors import report_handled_error

src/pythinker_code/subagents/core.py

@@ -25,7 +25,9 @@
 from pythinker_code.subagents.store import SubagentStore
 from pythinker_code.wire.types import TextPart, ThinkPart
 
-GIT_CONTEXT_AGENT_TYPES = frozenset({"explore", "review", "code_reviewer", "security_reviewer"})
+# NOTE: these must match the registered type names in agents/default/agent.yaml
+# (dashed), which _SUBAGENT_PROFILES also keys on — not the yaml file stems.
+GIT_CONTEXT_AGENT_TYPES = frozenset({"explore", "review", "code-reviewer", "security-reviewer"})
 """Read-oriented agent types whose first prompt gets a git-context prefix.
 
 Exploration and review both orient on repo state (branch, dirty files,

src/pythinker_code/tools/agent/__init__.py

@@ -297,14 +297,18 @@ async def __call__(self, params: Params) -> ToolReturnValue:
                 ),
                 brief="Invalid fork_context",
             )
+        if not params.run_in_background and params.isolation != "none":
+            # Proceeding unisolated after an isolation request would present
+            # degraded behavior as authoritative; fail fast instead.
+            return ToolError(
+                message=(
+                    "isolation='worktree' is only supported for background agents; "
+                    "set run_in_background=true or drop isolation."
+                ),
+                brief="Invalid isolation",
+            )
         if params.run_in_background:
             return await self._run_in_background(params)
-        if params.isolation != "none":
-            logger.warning(
-                "isolation={isolation!r} has no effect on foreground agents; "
-                "use run_in_background=True to enable isolation.",
-                isolation=params.isolation,
-            )
         await self._journal_foreground_agent_start(params, requested_type)
         timeout = params.effective_timeout
         try:
@@ -667,6 +671,16 @@ async def __call__(self, params: RunAgentsParams) -> ToolReturnValue:
                 message="Subagents cannot launch other subagents.",
                 brief="RunAgents unavailable",
             )
+        if not params.run_in_background and params.isolation != "none":
+            # Foreground children would share one tree despite the isolation
+            # request; fail fast rather than proceed unisolated.
+            return ToolError(
+                message=(
+                    "isolation='worktree' is only supported for background child "
+                    "agents; set run_in_background=true or drop isolation."
+                ),
+                brief="Invalid isolation",
+            )
         if params.model is not None and params.model not in self._runtime.config.models:
             return ToolError(
                 message=f"Unknown model alias: {params.model}",

src/pythinker_code/tools/file/glob.py

@@ -31,7 +31,7 @@ class Params(BaseModel):
 
 class Glob(CallableTool2[Params]):
     name: str = "Glob"
-    supports_parallel = True
+    supports_parallel: bool = True
     description: str = load_desc(
         Path(__file__).parent / "glob.md",
         {

src/pythinker_code/tools/file/grep_local.py

@@ -719,7 +719,7 @@ def _smart_search_patterns(query: str) -> list[tuple[str, str]]:
 
 class SmartSearch(CallableTool2[SmartSearchParams]):
     name: str = "SmartSearch"
-    supports_parallel = True
+    supports_parallel: bool = True
     description: str = (
         "Plan and run a small set of bounded local grep passes for a symbol or concept. "
         "Returns cited file/line spans and truncation guidance; use for exploration before "
@@ -789,7 +789,7 @@ async def __call__(self, params: SmartSearchParams) -> ToolReturnValue:
 
 class Grep(CallableTool2[Params]):
     name: str = "Grep"
-    supports_parallel = True
+    supports_parallel: bool = True
     description: str = load_desc(Path(__file__).parent / "grep.md")
     params: type[Params] = Params
 

src/pythinker_code/tools/file/read.py

@@ -63,7 +63,7 @@ def _validate_line_offset(self) -> "Params":
 
 class ReadFile(CallableTool2[Params]):
     name: str = "ReadFile"
-    supports_parallel = True
+    supports_parallel: bool = True
     params: type[Params] = Params
 
     def __init__(self, runtime: Runtime) -> None:

src/pythinker_code/tools/file/read_media.py

@@ -49,7 +49,7 @@ class Params(BaseModel):
 
 class ReadMediaFile(CallableTool2[Params]):
     name: str = "ReadMediaFile"
-    supports_parallel = True
+    supports_parallel: bool = True
     params: type[Params] = Params
 
     def __init__(self, runtime: Runtime) -> None:

src/pythinker_code/tools/mcp_resource/__init__.py

@@ -26,7 +26,7 @@ class ListParams(BaseModel):
 
 class ListMcpResources(CallableTool2[ListParams]):
     name: str = "ListMcpResources"
-    supports_parallel = True
+    supports_parallel: bool = True
     params: type[ListParams] = ListParams
 
     def __init__(self, toolset: PythinkerToolset) -> None:
@@ -75,7 +75,7 @@ class ReadParams(BaseModel):
 
 class ReadMcpResource(CallableTool2[ReadParams]):
     name: str = "ReadMcpResource"
-    supports_parallel = True
+    supports_parallel: bool = True
     params: type[ReadParams] = ReadParams
 
     def __init__(self, toolset: PythinkerToolset) -> None: