kanibako-cli 1.5.1__tar.gz → 1.6.0.dev23__tar.gz

{kanibako_cli-1.5.1/src/kanibako_cli.egg-info → kanibako_cli-1.6.0.dev23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanibako-cli
-Version: 1.5.1
+Version: 1.6.0.dev23
 Summary: Run AI coding agents in rootless containers with per-project isolation
 Requires-Python: >=3.11
 License-File: LICENSE.md

{kanibako_cli-1.5.1 → kanibako_cli-1.6.0.dev23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kanibako-cli"
-version = "1.5.1"
+version = "1.6.0.dev23"
 description = "Run AI coding agents in rootless containers with per-project isolation"
 requires-python = ">=3.11"
 dependencies = ["argcomplete>=3.0", "PyYAML>=6.0"]
@@ -22,6 +22,7 @@ dev = ["pytest>=7.0", "pytest-cov", "mypy", "ruff", "bump2version"]
 where = ["src"]
 
 [tool.setuptools.package-data]
+"kanibako" = ["py.typed"]
 "kanibako.containers" = ["Containerfile.*", "tmux.conf"]
 "kanibako.scripts" = ["*.sh", "kanibako-entry"]
 "kanibako.data" = ["*.yaml"]
@@ -33,6 +34,17 @@ line-length = 99
 [tool.ruff.lint.per-file-ignores]
 "tests/conftest.py" = ["E402"]
 
+[tool.mypy]
+# kanibako is a namespace package split across distributions: the core ships
+# kanibako/ (regular package) while each plugin contributes
+# kanibako/plugins/<agent>/ with no __init__.py in kanibako/plugins/. To let
+# `mypy packages/agent-<agent>/src` assign the full dotted module name (and
+# thus resolve sibling imports like kanibako.plugins.claude.target), point
+# mypy at every src base and enable explicit package bases.
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = "$MYPY_CONFIG_FILE_DIR/src:$MYPY_CONFIG_FILE_DIR/packages/agent-claude/src:$MYPY_CONFIG_FILE_DIR/packages/agent-goose/src:$MYPY_CONFIG_FILE_DIR/packages/agent-codex/src"
+
 [[tool.mypy.overrides]]
 module = ["yaml"]
 ignore_missing_imports = true

{kanibako_cli-1.5.1 → kanibako_cli-1.6.0.dev23}/src/kanibako/__init__.py

@@ -1,3 +1,3 @@
 """kanibako: Run AI coding agents in rootless containers with per-project isolation."""
 
-__version__ = "1.5.1"
+__version__ = "1.6.0.dev23"

{kanibako_cli-1.5.1 → kanibako_cli-1.6.0.dev23}/src/kanibako/commands/start.py

@@ -24,7 +24,8 @@ from kanibako.paths import (
     load_std_paths,
     resolve_any_project,
 )
-from kanibako.targets import resolve_target
+from kanibako.targets import assembly, credsync, resolve_target
+from kanibako.targets.assembly import BindingSourceError, descriptor_mounts
 from kanibako.utils import container_name_for, short_hash
 
 
@@ -192,6 +193,7 @@ def run_start(args: argparse.Namespace) -> int:
     # Map -A/-S to safe_mode: -A means autonomous (safe_mode=False),
     # -S means secure (safe_mode=True). Neither means autonomous (default).
     safe_mode = secure
+    autonomous = getattr(args, "autonomous", False)
 
     # Check for agent before launching container.
     # If no agent is detected, show a helpful message instead of silently
@@ -215,6 +217,7 @@ def run_start(args: argparse.Namespace) -> int:
         image_override=image_override,
         new_session=new_session,
         safe_mode=safe_mode,
+        autonomous=autonomous,
         resume_mode=resume_session,
         extra_args=agent_args,
         no_helpers=no_helpers,
@@ -268,6 +271,7 @@ def run_shell(args: argparse.Namespace) -> int:
         image_override=image_override,
         new_session=False,
         safe_mode=False,
+        autonomous=False,
         resume_mode=False,
         extra_args=shell_args,
         no_helpers=no_helpers,
@@ -543,6 +547,7 @@ def _run_container(
     image_override: str | None,
     new_session: bool,
     safe_mode: bool,
+    autonomous: bool = False,
     resume_mode: bool,
     extra_args: list[str],
     no_helpers: bool = False,
@@ -719,12 +724,25 @@ def _run_container(
     logger.debug("Image: %s", image)
     logger.debug("Container: %s", container_name)
 
+    # Plugin descriptor (None for legacy/no_agent targets).  Hoisted here so the
+    # credential lifecycle sites below (init / refresh / writeback) and the
+    # launch-assembly block all branch off a single value: descriptor-bearing
+    # targets route their cred lifecycle through the credsync engine, legacy
+    # targets keep the per-plugin init_home/refresh/writeback hooks.
+    desc = target.descriptor if target else None
+
     # Persistent mode: reattach if already running, clean up stale containers
     if persistent:
         if runtime.is_running(container_name):
             # Refresh credentials before reattaching
             if target and proj.group_auth:
-                target.refresh_credentials(proj.shell_path)
+                if desc is not None:
+                    credsync.refresh_cred_files(
+                        desc, target, host_home=Path.home(),
+                        project_home=proj.shell_path, group_auth=proj.group_auth,
+                    )
+                else:
+                    target.refresh_credentials(proj.shell_path)
             return runtime.exec(
                 container_name, _bootstrap_attach(bootstrap_program)
             )
@@ -804,7 +822,13 @@ def _run_container(
             # Ensure the agent-specific template variant directory exists.
             (templates_base / target.name / crab_cfg.shell).mkdir(parents=True, exist_ok=True)
             apply_shell_template(proj.shell_path, templates_base, target.name, crab_cfg.shell)
-            target.init_home(proj.shell_path, group_auth=proj.group_auth)
+            if desc is not None:
+                credsync.seed_cred_files(
+                    desc, target, host_home=Path.home(),
+                    project_home=proj.shell_path, group_auth=proj.group_auth,
+                )
+            else:
+                target.init_home(proj.shell_path, group_auth=proj.group_auth)
 
             # Merge layered instruction files (base + template + user).
             instr_files = target.instruction_files()
@@ -898,7 +922,13 @@ def _run_container(
 
         # Credential refresh via target (skip for distinct auth)
         if target and proj.group_auth:
-            target.refresh_credentials(proj.shell_path)
+            if desc is not None:
+                credsync.refresh_cred_files(
+                    desc, target, host_home=Path.home(),
+                    project_home=proj.shell_path, group_auth=proj.group_auth,
+                )
+            else:
+                target.refresh_credentials(proj.shell_path)
 
         # tweakcc: patch agent binary if enabled
         tweakcc_entry = None
@@ -922,16 +952,61 @@ def _run_container(
             # Apply model override from -M/--model flag
             if model_override:
                 effective_state["model"] = model_override
-            state_args, state_env = target.apply_state(effective_state)
             all_extra = list(crab_cfg.run_args) + list(extra_args)
-            cli_args = target.build_cli_args(
-                safe_mode=safe_mode,
-                resume_mode=resume_mode,
-                new_session=new_session,
-                is_new_project=proj.is_new,
-                extra_args=all_extra,
-            )
-            cli_args.extend(state_args)
+            if desc is not None:
+                # Descriptor path: assemble argv + container-env overlay
+                # declaratively from the plugin descriptor (replaces the legacy
+                # apply_state / build_cli_args hooks for descriptor-bearing
+                # targets).
+                #
+                # safe_off redeems the persisted `access` setting (claude:
+                # safe_bypass.setting_key="access", default "permissive") while
+                # the per-launch -A/-S flags still win (safe_mode IS the -S
+                # `secure` bool; autonomous IS -A).  An agent whose descriptor
+                # declares no safe_bypass.setting_key (goose/codex) falls back to
+                # default-autonomous via effective_safe_mode_off.
+                sb = desc.safe_bypass
+                persisted_access = (
+                    effective_state.get(sb.setting_key, "")
+                    if sb is not None and sb.setting_key
+                    else ""
+                )
+                safe_off = assembly.effective_safe_mode_off(
+                    secure=safe_mode,
+                    autonomous=autonomous,
+                    persisted_access=persisted_access,
+                )
+                mode_key = assembly.resolve_mode(
+                    resume_mode=resume_mode,
+                    new_session=new_session,
+                    is_new_project=proj.is_new,
+                    extra_args=all_extra,
+                    available_modes=desc.mode.keys(),
+                )
+                cli_args = assembly.assemble_argv(
+                    desc,
+                    mode_key=mode_key,
+                    safe_mode_off=safe_off,
+                    setting_values=effective_state,
+                    op=None,
+                    extra_args=all_extra,
+                )
+                state_env = assembly.assemble_env(
+                    desc,
+                    safe_mode_off=safe_off,
+                    setting_values=effective_state,
+                )
+            else:
+                # Legacy path (unchanged): apply_state + build_cli_args.
+                state_args, state_env = target.apply_state(effective_state)
+                cli_args = target.build_cli_args(
+                    safe_mode=safe_mode,
+                    resume_mode=resume_mode,
+                    new_session=new_session,
+                    is_new_project=proj.is_new,
+                    extra_args=all_extra,
+                )
+                cli_args.extend(state_args)
         else:
             state_env = {}
             cli_args = list(extra_args)
@@ -944,38 +1019,99 @@ def _run_container(
             # non-executable file fails fast with an actionable message before
             # anything execs it.  Here we only guard against missing mount
             # sources.
-            binary_mnts = target.binary_mounts(install)
-            if not binary_mnts:
-                print(
-                    f"Error: {target.display_name} binary detected at "
-                    f"{install.binary} but mount sources are missing.\n"
-                    f"  binary:      {install.binary} "
-                    f"({'exists' if install.binary.exists() else 'MISSING'})\n"
-                    f"  install_dir: {install.install_dir} "
-                    f"({'exists' if install.install_dir.exists() else 'MISSING'})\n"
-                    f"The container would launch without the agent binary.",
-                    file=sys.stderr,
+            if desc is not None:
+                # Descriptor path: the AGENT_CRITICAL delivery binds (binary +
+                # launcher) come from the descriptor.  A missing/unresolvable
+                # source raises BindingSourceError -> clean safe-fail (replaces
+                # the legacy "mount source disappeared" check), not a crun crash.
+                #
+                # SHARED_STORE bindings (e.g. claude's AGENT-scope `plugins`
+                # share) resolve under the agent-namespaced global shared store
+                # `global_shared/<agent_id>/<src_rel>`, unifying with SHARED
+                # resources.  When the project has NO global shared store,
+                # shared_store_root stays None and descriptor_mounts SKIPS those
+                # bindings (the no-shared-store case, unchanged).
+                shared_store_root = (
+                    proj.global_shared_path / agent_id
+                    if proj.global_shared_path
+                    else None
                 )
-                return 1
-            # Safe-fail: every agent bind source must still exist at mount
-            # time.  If the host churned (prune/repoint mid-flight) between
-            # detection and here, fail with a clean, actionable kanibako error
-            # instead of letting crun crash on a dangling bind source.
-            missing = [m for m in binary_mnts if not m.source.exists()]
-            if missing:
-                detail = "\n".join(
-                    f"  {m.source} → {m.destination}" for m in missing
+                # Per-agent binding host-source overrides (crab.<name>.binding.<key>
+                # layered over crab.default.binding) resolved across the config
+                # cascade; an override redirects (and always wins for) a binding's
+                # host source.
+                binding_overrides = _build_binding_overrides(
+                    project_toml=project_toml,
+                    workset_config_path=workset_path,
+                    crab_config_path=crab_cfg_path,
+                    global_config_path=config_file,
+                    agent_name=agent_id,
                 )
-                print(
-                    f"Error: {target.display_name} mount source disappeared "
-                    f"before launch:\n{detail}\n"
-                    f"The host agent install changed while starting (e.g. an "
-                    f"update pruned a version). Retry the launch.\n"
-                    f"Run 'kanibako system diagnose' for a full health check.",
-                    file=sys.stderr,
-                )
-                return 1
-            extra_mounts.extend(binary_mnts)
+                # The `plugins` binding is rw (ro=False) AGENT scope, and
+                # descriptor_mounts SKIPS a MISSING agent source.  Pre-create the
+                # resolved host source dir best-effort (mirrors the legacy
+                # rw-share behavior) so podman binds a real, PERSISTENT dir
+                # instead of stubbing it.  A bad source must never crash launch.
+                plugins_src = binding_overrides.get("plugins")
+                if not plugins_src and shared_store_root is not None:
+                    plugins_src = str(shared_store_root / "plugins")
+                if plugins_src:
+                    try:
+                        Path(plugins_src).mkdir(parents=True, exist_ok=True)
+                    except OSError:
+                        pass
+                try:
+                    binary_mnts = descriptor_mounts(
+                        desc, install,
+                        shared_store_root=shared_store_root,
+                        overrides=binding_overrides,
+                    )
+                except BindingSourceError as exc:
+                    logger.error("Agent delivery binding unusable: %s", exc)
+                    print(
+                        f"Error: {target.display_name} mount source "
+                        f"disappeared before launch: {exc}\n"
+                        f"The host agent install changed while starting (e.g. "
+                        f"an update pruned a version). Retry the launch.\n"
+                        f"Run 'kanibako system diagnose' for a full health "
+                        f"check.",
+                        file=sys.stderr,
+                    )
+                    return 1
+                extra_mounts.extend(binary_mnts)
+            else:
+                binary_mnts = target.binary_mounts(install)
+                if not binary_mnts:
+                    print(
+                        f"Error: {target.display_name} binary detected at "
+                        f"{install.binary} but mount sources are missing.\n"
+                        f"  binary:      {install.binary} "
+                        f"({'exists' if install.binary.exists() else 'MISSING'})\n"
+                        f"  install_dir: {install.install_dir} "
+                        f"({'exists' if install.install_dir.exists() else 'MISSING'})\n"
+                        f"The container would launch without the agent binary.",
+                        file=sys.stderr,
+                    )
+                    return 1
+                # Safe-fail: every agent bind source must still exist at mount
+                # time.  If the host churned (prune/repoint mid-flight) between
+                # detection and here, fail with a clean, actionable kanibako
+                # error instead of letting crun crash on a dangling bind source.
+                missing = [m for m in binary_mnts if not m.source.exists()]
+                if missing:
+                    detail = "\n".join(
+                        f"  {m.source} → {m.destination}" for m in missing
+                    )
+                    print(
+                        f"Error: {target.display_name} mount source disappeared "
+                        f"before launch:\n{detail}\n"
+                        f"The host agent install changed while starting (e.g. an "
+                        f"update pruned a version). Retry the launch.\n"
+                        f"Run 'kanibako system diagnose' for a full health check.",
+                        file=sys.stderr,
+                    )
+                    return 1
+                extra_mounts.extend(binary_mnts)
 
         # kanibako CLI bind-mount (package + entry script)
         kanibako_mnts = _kanibako_mounts()
@@ -1077,11 +1213,10 @@ def _run_container(
         # Merge per-run -e/--env KEY=VALUE vars (highest priority).
         container_env.update(_parse_cli_env(cli_env))
 
-        # Disable Claude Code telemetry inside containers.
-        if target and target.name == "claude":
-            container_env.setdefault(
-                "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1",
-            )
+        # NOTE: Claude Code telemetry (CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC)
+        # and the auto-updater disable (DISABLE_AUTOUPDATER) are now carried by
+        # claude's descriptor.container_env, merged via state_env above.  The
+        # former core `target.name == "claude"` special-case has been removed.
 
         # Inject instance identity for peer communication.
         if proj.name:
@@ -1306,6 +1441,7 @@ def _run_container(
                         image_override=image_override,
                         new_session=True,
                         safe_mode=safe_mode,
+                        autonomous=autonomous,
                         resume_mode=False,
                         extra_args=extra_args,
                         no_helpers=no_helpers,
@@ -1372,6 +1508,7 @@ def _run_container(
                             image_override=image_override,
                             new_session=True,
                             safe_mode=safe_mode,
+                            autonomous=autonomous,
                             resume_mode=False,
                             extra_args=extra_args,
                             no_helpers=no_helpers,
@@ -1386,7 +1523,13 @@ def _run_container(
         else:
             # Write back refreshed credentials via target (skip for distinct auth)
             if target and proj.group_auth:
-                target.writeback_credentials(proj.shell_path)
+                if desc is not None:
+                    credsync.writeback_cred_files(
+                        desc, target, host_home=Path.home(),
+                        project_home=proj.shell_path, group_auth=proj.group_auth,
+                    )
+                else:
+                    target.writeback_credentials(proj.shell_path)
 
             # Hint when agent exits non-zero and --continue/--resume was used
             if rc != 0 and is_agent_mode and not new_session:
@@ -1445,12 +1588,17 @@ def _build_effective_state(
     with the target's declared defaults as a FLOOR (the system level's declared
     defaults).  Sources for each level's ``[crab]`` table:
 
-      * **box**     — ``[crab]`` in project.yaml
-      * **workset** — ``[crab]`` in the workset's config.yaml (if any)
-      * **crab**    — the crab config's own state dict
-      * **system**  — ``[crab]`` in the global kanibako.yaml
+      * **box**     — ``crab.<name>`` (over ``crab.default``) in project.yaml
+      * **workset** — ``crab.<name>`` in the workset's config.yaml (if any)
+      * **crab**    — the crab config's own state dict (already per-agent)
+      * **system**  — ``crab.<name>`` in the global kanibako.yaml
       * **floor**   — target ``setting_descriptors()`` defaults
 
+    The box/workset/system/machine override sections are keyed per agent
+    (``crab.<target.name>`` layered over the any-agent ``crab.default`` tier) so
+    an override never bleeds across an agent switch; ``crab_cfg.state`` is
+    already per-agent (loaded from ``crabs/<name>.yaml``).
+
     Explicit set values beat all declared defaults; the most-specific level
     wins; an explicit ``""`` is terminal (no fall-through to the floor).
     Undeclared keys set anywhere (e.g. ``start_mode``) are passed through.
@@ -1480,7 +1628,9 @@ def _build_effective_state(
         try:
             if not path.exists():
                 return {}
-            return read_crab_settings(path)
+            # Agent-keyed: read crab.<agent>.* layered over crab.default.* so an
+            # override set for one agent never bleeds onto another after a switch.
+            return read_crab_settings(path, target.name)
         except Exception:
             return {}
 
@@ -1531,6 +1681,42 @@ def _build_effective_state(
     return effective
 
 
+def _build_binding_overrides(
+    *,
+    project_toml,
+    workset_config_path,
+    crab_config_path,
+    global_config_path,
+    agent_name: str,
+) -> dict[str, str]:
+    """Resolve descriptor binding host-source overrides across the config cascade.
+
+    Reads each config level's ``crab.<agent_name>.binding`` sub-table (layered
+    over ``crab.default.binding`` within each file) via
+    :func:`~kanibako.config.read_binding_overrides`, mirroring B3's agent-keying,
+    then overlays the levels MOST-SPECIFIC-WINS:
+
+        box (project.yaml) > workset > crab (crabs/<name>.yaml) > system > machine
+
+    Returns ``{binding_key: host_src}`` (empty when nothing is configured, the
+    common case).  A bad/unreadable level contributes nothing (the reader
+    swallows its own errors).
+    """
+    from kanibako.config import machine_config_path, read_binding_overrides
+
+    overrides: dict[str, str] = {}
+    # Least-specific first so each more-specific level's .update() wins.
+    for path in (
+        machine_config_path(),
+        global_config_path,
+        crab_config_path,
+        workset_config_path,
+        project_toml,
+    ):
+        overrides.update(read_binding_overrides(path, agent_name))
+    return overrides
+
+
 def _apply_init_seeds(
     *,
     std,

{kanibako_cli-1.5.1 → kanibako_cli-1.6.0.dev23}/src/kanibako/config.py

@@ -442,48 +442,134 @@ def load_project_overrides(path: Path) -> dict[str, str]:
 # Target settings overrides (per-project)
 # ---------------------------------------------------------------------------
 
-def read_crab_settings(path: Path) -> dict[str, str]:
-    """Read crab-state overrides from a project.yaml ``crab`` section.
-
-    project.yaml's ``crab`` holds box-level crab-state overrides (e.g.
-    ``{"model": "sonnet"}``); identity keys live in ``box.crab``, not here.
-    Returns an empty dict when the file or section is absent.
+def read_crab_settings(path: Path, agent_name: str) -> dict[str, str]:
+    """Read agent-keyed crab-state overrides from a config file's ``crab`` table.
+
+    Override sections are keyed per agent under ``crab.<agent_name>``, layered
+    over the reserved any-agent ``crab.default`` tier (the agent-specific value
+    wins within a single file). This stops an override set while a box is on one
+    agent (e.g. ``model`` under ``crab.claude``) from bleeding onto another
+    agent after the box is switched (e.g. to ``goose``); identity keys live in
+    ``box.crab``, not here.
+
+    ``crab.default`` is RESERVED as the any-agent default tier; no real agent
+    may be named ``default``.
+
+    **No pass-1 migration.** A legacy FLAT ``[crab]`` table (scalar values
+    written directly under ``crab``, e.g. ``crab.model``) is treated as UNSET —
+    only nested per-agent dicts (``crab.default`` / ``crab.<agent_name>``) are
+    honored. Configs are hand-edited to the new shape. The common no-config case
+    (absent file, or absent/empty ``crab`` table) still returns ``{}`` unchanged.
     """
     if not path.exists():
         return {}
     data = load_doc(path)
-    return {k: str(v) for k, v in data.get("crab", {}).items()}
+    crab = data.get("crab", {})
+    if not isinstance(crab, dict):
+        return {}
+    out: dict[str, str] = {}
+    default_sec = crab.get("default")
+    if isinstance(default_sec, dict):
+        out.update({k: str(v) for k, v in default_sec.items()})
+    agent_sec = crab.get(agent_name)
+    if isinstance(agent_sec, dict):
+        out.update({k: str(v) for k, v in agent_sec.items()})
+    return out
 
 
-def write_crab_setting(path: Path, key: str, value: str) -> None:
-    """Write a single crab-state override to ``crab`` in project.yaml.
+def write_crab_setting(path: Path, key: str, value: str, agent_name: str) -> None:
+    """Write a single crab-state override under ``crab.<agent_name>``.
 
-    Preserves all other sections.
+    Preserves all other sections and other agents' crab subsections. Pass the
+    reserved ``"default"`` agent name to target the any-agent default tier.
     """
     existing = load_doc(path)
-    existing.setdefault("crab", {})
-    existing["crab"][key] = value
+    crab = existing.get("crab")
+    if not isinstance(crab, dict):
+        crab = {}
+        existing["crab"] = crab
+    agent_sec = crab.get(agent_name)
+    if not isinstance(agent_sec, dict):
+        agent_sec = {}
+        crab[agent_name] = agent_sec
+    agent_sec[key] = value
     dump_doc(path, existing)
 
 
-def remove_crab_setting(path: Path, key: str) -> bool:
-    """Remove a single crab-state override from ``crab`` in project.yaml.
+def remove_crab_setting(path: Path, key: str, agent_name: str) -> bool:
+    """Remove a single crab-state override from ``crab.<agent_name>``.
 
-    Returns True if the setting was found and removed, False otherwise.
+    Returns True if the setting was found and removed, False otherwise. Prunes a
+    now-empty agent subsection and a now-empty ``crab`` table.
     """
     if not path.exists():
         return False
     existing = load_doc(path)
-    settings = existing.get("crab", {})
-    if key not in settings:
+    crab = existing.get("crab")
+    if not isinstance(crab, dict):
         return False
-    del settings[key]
-    if not settings:
+    agent_sec = crab.get(agent_name)
+    if not isinstance(agent_sec, dict) or key not in agent_sec:
+        return False
+    del agent_sec[key]
+    if not agent_sec:
+        del crab[agent_name]
+    if not crab:
         existing.pop("crab", None)
     dump_doc(path, existing)
     return True
 
 
+def read_binding_overrides(path: Path | None, agent_name: str) -> dict[str, str]:
+    """Read agent-keyed binding host-source overrides from a config ``crab`` table.
+
+    Reads the ``binding`` sub-table under ``crab.<agent_name>`` layered over the
+    reserved any-agent ``crab.default.binding`` tier (the agent-specific value
+    wins within a single file) — the SAME agent-keying as
+    :func:`read_crab_settings`. These redirect the HOST SOURCE of a descriptor
+    :class:`~kanibako.targets.base.Binding` (e.g. ``crab.claude.binding.plugins``
+    points the claude ``plugins`` share at a custom host directory).
+
+    Returns ``{binding_key: host_src}``. Each binding VALUE may be either:
+
+    * a bare string ``host_src`` (``crab.claude.binding.plugins = "/path"``), or
+    * a sub-table carrying a ``host_src`` key
+      (``crab.claude.binding.plugins.host_src = "/path"``).
+
+    A sub-table without a string ``host_src`` (and any other non-string value)
+    is skipped. As with :func:`read_crab_settings`, a legacy FLAT ``[crab]``
+    table is treated as UNSET (no pass-1 migration); the common no-config case
+    (absent/None/unreadable path, or absent ``crab``/``binding`` table) returns
+    ``{}``.
+    """
+    if path is None or not path.exists():
+        return {}
+    try:
+        data = load_doc(path)
+    except Exception:
+        return {}
+    crab = data.get("crab", {})
+    if not isinstance(crab, dict):
+        return {}
+    out: dict[str, str] = {}
+    # Least-specific (default tier) first so the agent-specific tier wins.
+    for tier in ("default", agent_name):
+        section = crab.get(tier)
+        if not isinstance(section, dict):
+            continue
+        binding = section.get("binding")
+        if not isinstance(binding, dict):
+            continue
+        for key, val in binding.items():
+            if isinstance(val, str):
+                out[key] = val
+            elif isinstance(val, dict):
+                host_src = val.get("host_src")
+                if isinstance(host_src, str):
+                    out[key] = host_src
+    return out
+
+
 # ---------------------------------------------------------------------------
 # Scoped shares (settings-framework {scope}.path.share_{ro,rw}.*)
 # ---------------------------------------------------------------------------