fix(python): mirror Factory Droid 0.175 hooks

sdks/python/elydora/plugins/droid.py

@@ -2,183 +2,113 @@
 
 from __future__ import annotations
 
-import json
-import os
-from typing import List, Optional
+from typing import Dict, List
 
-from ._transaction import FileChange, file_change, require_runtime, write_changes
 from .base import AgentPlugin, InstallConfig, PluginStatus
 from .droid_config import (
-    additions_for,
-    installation_targets,
+    DroidSources,
+    RenderedDocument,
+    active_document,
+    additions_for_target,
+    effective_hooks,
+    hook_block,
+    installation_documents,
     render_document,
-    unique_documents,
+    source_documents,
 )
 from .droid_contract import (
     AGENT_KEY,
-    AUDIT_SCRIPT,
-    GUARD_SCRIPT,
-    TOOL_EVENTS,
+    JsonObject,
     build_group,
-    elydora_dir,
-    merge_hook_settings,
     runtime_contracts,
-    validate_javascript_regexes,
 )
-from .droid_io import (
-    display_config_path,
-    read_sources,
-    rendered_change,
-    runtime_files_exist,
+from .droid_installation import (
+    commit_droid_installation,
+    commit_droid_uninstall,
+    preflight_droid_installation,
+    prepare_droid_installation,
+    prepare_droid_uninstall,
 )
-from .hook_template import generate_hook_script
+from .droid_io import display_config_path, read_sources, runtime_files_exist
 
 
-def _agent_directory(agent_id: str) -> str:
-    if (
-        not agent_id
-        or agent_id in {".", ".."}
-        or os.path.basename(agent_id) != agent_id
-        or os.path.isabs(agent_id)
-    ):
-        raise ValueError("agent_id must be a single non-empty path segment")
-    return os.path.join(elydora_dir(), agent_id)
+def _render_installation(
+    sources: DroidSources,
+    guard_path: str,
+    audit_path: str,
+) -> List[RenderedDocument]:
+    target = active_document(sources)
+    groups: Dict[str, JsonObject] = {
+        "PreToolUse": build_group(guard_path),
+        "PostToolUse": build_group(audit_path),
+    }
+    return [
+        render_document(
+            document,
+            None,
+            additions_for_target(document, target, groups),
+        )
+        for document in installation_documents(sources)
+    ]
 
 
-def _same_path(left: str, right: str) -> bool:
-    return os.path.normcase(os.path.abspath(left)) == os.path.normcase(
-        os.path.abspath(right)
-    )
-
-
-def _append_change(changes: List[FileChange], change: Optional[FileChange]) -> None:
-    if change is not None:
-        changes.append(change)
+def _render_uninstall(
+    sources: DroidSources,
+    agent_id: str,
+) -> List[RenderedDocument]:
+    return [
+        render_document(document, agent_id or None, {})
+        for document in source_documents(sources)
+    ]
 
 
 class DroidPlugin(AgentPlugin):
     """Install Elydora into Factory Droid's user-level hook sources."""
 
-    def install(self, config: InstallConfig) -> None:
-        agent_id = config.get("agent_id", "")
-        agent_directory = _agent_directory(agent_id)
+    manages_guard_runtime = True
+
+    def preflight_install(self, config: InstallConfig) -> None:
         sources = read_sources()
-        validate_javascript_regexes([
-            sources.primary.hooks if sources.primary is not None else {},
-            sources.settings.hooks,
-        ])
+        preflight_droid_installation(config, sources)
 
-        guard_path = config.get("guard_script_path", "")
-        expected_guard_path = os.path.join(agent_directory, GUARD_SCRIPT)
-        if not _same_path(guard_path, expected_guard_path):
-            raise ValueError(
-                "Elydora guard runtime must use the managed agent directory: "
-                f"{expected_guard_path}"
-            )
-        require_runtime(guard_path, "Elydora guard runtime")
-        audit_path = os.path.join(agent_directory, AUDIT_SCRIPT)
-
-        selected = installation_targets(sources)
-        groups = {
-            "PreToolUse": build_group(guard_path),
-            "PostToolUse": build_group(audit_path),
-        }
-        documents = unique_documents([
-            sources.primary,
-            sources.settings if sources.settings.has_hooks_container else None,
-            *(selected.targets[event] for event in TOOL_EVENTS),
-        ])
-        rendered = [
-            render_document(
-                document,
-                None,
-                additions_for(document, selected.targets, groups),
-            )
-            for document in documents
-        ]
-
-        runtime_config = {
-            "org_id": config.get("org_id", ""),
-            "agent_id": agent_id,
-            "kid": config.get("kid", ""),
-            "base_url": config.get("base_url", "https://api.elydora.com"),
-            "token": config.get("token", ""),
-            "agent_name": AGENT_KEY,
-        }
-        audit_script = generate_hook_script(
-            org_id=config.get("org_id", ""),
-            agent_id=agent_id,
-            kid=config.get("kid", ""),
-            base_url=config.get("base_url", "https://api.elydora.com"),
+    def install(self, config: InstallConfig) -> None:
+        sources = read_sources()
+        paths = preflight_droid_installation(config, sources)
+        rendered = _render_installation(
+            sources,
+            paths.guard_path,
+            paths.audit_path,
         )
-        changes: List[FileChange] = []
-        _append_change(changes, file_change(
-            os.path.join(agent_directory, "config.json"),
-            "Elydora runtime config",
-            json.dumps(runtime_config, indent=2) + "\n",
-            0o600,
-        ))
-        _append_change(changes, file_change(
-            os.path.join(agent_directory, "private.key"),
-            "Elydora private key",
-            config.get("private_key", ""),
-            0o600,
-        ))
-        _append_change(changes, file_change(
-            audit_path,
-            "Elydora audit runtime",
-            audit_script,
-            0o700,
-        ))
-        for item in rendered:
-            _append_change(changes, rendered_change(item))
-        write_changes(changes, "Write Factory Droid installation")
-
-        locations = ", ".join(
-            f"{event}: {selected.targets[event].file_path}"
-            for event in TOOL_EVENTS
-        )
-        print(f"Factory Droid: {locations}")
+        prepared = prepare_droid_installation(config, sources, rendered)
+        commit_droid_installation(prepared)
+        print(f"Factory Droid hooks: {active_document(sources).file_path}")
         print("Factory Droid: run /hooks to review the Elydora hook changes.")
 
     def uninstall(self, agent_id: str = "") -> None:
         sources = read_sources()
-        documents = unique_documents([
-            sources.primary,
-            sources.settings if sources.settings.has_hooks_container else None,
-        ])
-        changes: List[FileChange] = []
-        for document in documents:
-            rendered = render_document(document, agent_id or None, {})
-            _append_change(changes, rendered_change(rendered))
-        write_changes(changes, "Write Factory Droid hook sources")
+        rendered = _render_uninstall(sources, agent_id)
+        commit_droid_uninstall(prepare_droid_uninstall(rendered))
 
     def status(self) -> PluginStatus:
         sources = read_sources()
-        effective = merge_hook_settings(
-            sources.primary.hooks if sources.primary is not None else None,
-            sources.settings.hooks,
-        )
-        contracts = runtime_contracts(effective)
+        contracts = runtime_contracts(effective_hooks(sources))
+        blocked = hook_block(sources)
+        configured = blocked is None and bool(contracts)
+        installed = configured and runtime_files_exist(contracts)
         config_path = display_config_path(sources)
-        if effective.get("hooksDisabled") is True:
-            return PluginStatus(
-                installed=False,
-                agent=AGENT_KEY,
-                details=f"Configured hooks are disabled: {config_path}",
+        if blocked is not None:
+            details = (
+                f"Configured hooks are disabled by {blocked.field}: "
+                f"{blocked.file_path}"
             )
-        if not contracts:
-            return PluginStatus(
-                installed=False,
-                agent=AGENT_KEY,
-                details="Not installed",
+        elif not contracts:
+            details = "Not installed"
+        elif installed:
+            details = f"Config: {config_path}"
+        else:
+            details = (
+                f"Configured at {config_path}; managed contract incomplete"
             )
-        installed = runtime_files_exist(contracts)
-        details = (
-            f"Config: {config_path}"
-            if installed
-            else f"Configured at {config_path}; runtime scripts missing"
-        )
         return PluginStatus(
             installed=installed,
             agent=AGENT_KEY,

sdks/python/elydora/plugins/droid_config.py

@@ -3,17 +3,20 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Dict, List, Optional, Sequence, Tuple
+import os
+from typing import Dict, List, Optional, Tuple
 
+from ._jsonc import JsonPathPart, JsoncEditor
+from ._managed_files import FileSnapshot
 from .droid_contract import (
     TOOL_EVENTS,
-    DroidHookSettings,
+    DroidHookMap,
     JsonObject,
-    has_own,
     managed_removals,
-    read_hook_settings,
+    read_hook_map,
+    same_path,
 )
-from ._jsonc import JsonPathPart, JsoncEditor
+from .droid_policy import DroidPolicyState
 
 
 OWNED_FILE_MARKER = "// Managed by Elydora"
@@ -25,24 +28,23 @@ class DroidDocument:
     file_path: str
     exists: bool
     raw: str
+    snapshot: Optional[FileSnapshot]
     root: JsonObject
-    hooks: DroidHookSettings
+    hooks: DroidHookMap
     base_path: Tuple[JsonPathPart, ...]
     has_hooks_container: bool
+    hooks_disabled: Optional[bool]
+    show_hook_output: Optional[bool]
     owned_file: bool
 
 
 @dataclass(frozen=True)
 class DroidSources:
-    root_path: str
-    primary: Optional[DroidDocument]
+    root: DroidDocument
+    legacy: DroidDocument
     settings: DroidDocument
-
-
-@dataclass(frozen=True)
-class InstallationTargets:
-    targets: Dict[str, DroidDocument]
-    created_root: Optional[DroidDocument]
+    local_settings: DroidDocument
+    policy: DroidPolicyState
 
 
 @dataclass(frozen=True)
@@ -52,30 +54,65 @@ class RenderedDocument:
     next_source: Optional[str]
 
 
+@dataclass(frozen=True)
+class DroidHookBlock:
+    field: str
+    file_path: str
+    label: str
+
+
 def _label(kind: str, file_path: str) -> str:
     if kind == "settings":
         return f"Factory Droid settings at {file_path}"
+    if kind == "local-settings":
+        return f"Factory Droid local settings at {file_path}"
     if kind == "legacy":
         return f"Factory Droid legacy hooks at {file_path}"
     return f"Factory Droid hooks at {file_path}"
 
 
+def _optional_boolean(root: JsonObject, field: str, label: str) -> Optional[bool]:
+    value = root.get(field)
+    if field in root and not isinstance(value, bool):
+        raise ValueError(f'{label} field "{field}" must be a boolean')
+    return value
+
+
+def _legacy_direct_hooks(
+    root: JsonObject,
+    label: str,
+) -> Tuple[DroidHookMap, Optional[bool], Optional[bool]]:
+    hooks_disabled = _optional_boolean(root, "hooksDisabled", label)
+    show_hook_output = _optional_boolean(root, "showHookOutput", label)
+    entries = {
+        key: value
+        for key, value in root.items()
+        if key not in {"hooksDisabled", "showHookOutput"}
+    }
+    return (
+        read_hook_map(entries, label),
+        hooks_disabled,
+        show_hook_output,
+    )
+
+
 def parse_document(
     *,
     exists: bool,
     file_path: str,
     kind: str,
     raw: str,
+    snapshot: Optional[FileSnapshot] = None,
 ) -> DroidDocument:
     label = _label(kind, file_path)
     editor = JsoncEditor(raw, label)
     if not isinstance(editor.value, dict):
         raise ValueError(f"{label} must contain a JSON object")
     root = editor.value
-    if kind == "settings":
-        has_container = has_own(root, "hooks")
+    if kind in {"settings", "local-settings"}:
+        has_container = "hooks" in root
         hooks = (
-            read_hook_settings(root["hooks"], f'{label} field "hooks"')
+            read_hook_map(root["hooks"], f'{label} field "hooks"')
             if has_container
             else {}
         )
@@ -84,30 +121,65 @@ def parse_document(
             file_path,
             exists,
             raw,
+            snapshot,
             root,
             hooks,
             ("hooks",),
             has_container,
+            _optional_boolean(root, "hooksDisabled", label),
+            _optional_boolean(root, "showHookOutput", label),
             False,
         )
+    if "hooks" in root:
+        hooks = read_hook_map(root["hooks"], f'{label} field "hooks"')
+        return DroidDocument(
+            kind,
+            file_path,
+            exists,
+            raw,
+            snapshot,
+            root,
+            hooks,
+            ("hooks",),
+            True,
+            None,
+            None,
+            raw.startswith(OWNED_FILE_MARKER),
+        )
+    hooks, hooks_disabled, show_hook_output = _legacy_direct_hooks(root, label)
     return DroidDocument(
         kind,
         file_path,
         exists,
         raw,
+        snapshot,
         root,
-        read_hook_settings(root, label),
+        hooks,
         (),
-        True,
+        False,
+        hooks_disabled,
+        show_hook_output,
         raw.startswith(OWNED_FILE_MARKER),
     )
 
 
-def create_settings_document(file_path: str) -> DroidDocument:
+def create_settings_document(
+    file_path: str,
+    kind: str = "settings",
+) -> DroidDocument:
     return parse_document(
         exists=False,
         file_path=file_path,
-        kind="settings",
+        kind=kind,
+        raw="{}\n",
+    )
+
+
+def create_legacy_hook_document(file_path: str) -> DroidDocument:
+    return parse_document(
+        exists=False,
+        file_path=file_path,
+        kind="legacy",
         raw="{}\n",
     )
 
@@ -117,30 +189,40 @@ def create_owned_hook_document(file_path: str) -> DroidDocument:
         exists=False,
         file_path=file_path,
         kind="hooks",
-        raw=f"{OWNED_FILE_MARKER}\n{{}}\n",
+        raw=f'{OWNED_FILE_MARKER}\n{{\n  "hooks": {{}}\n}}\n',
     )
 
 
 def _hooks_from_editor(
     editor: JsoncEditor,
     document: DroidDocument,
-) -> DroidHookSettings:
+) -> DroidHookMap:
     root = editor.value
+    label = _label(document.kind, document.file_path)
     if not isinstance(root, dict):
-        raise ValueError(f"{_label(document.kind, document.file_path)} must be an object")
-    if document.kind == "settings":
-        hooks = root.get("hooks")
-        return read_hook_settings(
-            hooks,
-            f'{_label(document.kind, document.file_path)} field "hooks"',
-        )
-    return read_hook_settings(root, _label(document.kind, document.file_path))
+        raise ValueError(f"{label} must contain a JSON object")
+    if document.kind in {"settings", "local-settings"} or "hooks" in root:
+        return read_hook_map(root.get("hooks"), f'{label} field "hooks"')
+    return _legacy_direct_hooks(root, label)[0]
 
 
 def _event_path(document: DroidDocument, event: str) -> Tuple[JsonPathPart, ...]:
     return (*document.base_path, event)
 
 
+def _current_document(
+    document: DroidDocument,
+    raw: str,
+) -> DroidDocument:
+    return parse_document(
+        exists=document.exists,
+        file_path=document.file_path,
+        kind=document.kind,
+        raw=raw,
+        snapshot=document.snapshot,
+    )
+
+
 def _remove_managed(
     editor: JsoncEditor,
     document: DroidDocument,
@@ -160,9 +242,53 @@ def _remove_managed(
                 continue
             for handler_index in sorted(removal.handler_indexes, reverse=True):
                 editor.delete((*group_path, "hooks", handler_index))
-        current = _hooks_from_editor(editor, document)
-        if document.owned_file and event in current and not current[event]:
-            editor.delete(_event_path(document, event))
+        if event_removals:
+            current = _hooks_from_editor(editor, document)
+            if not current.get(event):
+                editor.delete(_event_path(document, event))
+
+
+def _append_group(
+    editor: JsoncEditor,
+    document: DroidDocument,
+    event: str,
+    group: JsonObject,
+) -> None:
+    current = _hooks_from_editor(editor, document)
+    if event in current:
+        editor.append(_event_path(document, event), group)
+    else:
+        editor.add_property(document.base_path, event, [group])
+
+
+def _hook_file_is_empty(
+    document: DroidDocument,
+    raw: str,
+) -> bool:
+    if document.kind in {"settings", "local-settings"}:
+        return False
+    current = _current_document(document, raw)
+    remaining_root_fields = [key for key in current.root if key != "hooks"]
+    return not current.hooks and not remaining_root_fields
+
+
+def _has_exact_installation(
+    document: DroidDocument,
+    additions: Dict[str, JsonObject],
+) -> bool:
+    if set(additions) != set(TOOL_EVENTS):
+        return False
+    removals = managed_removals(document.hooks)
+    if len(removals) != len(TOOL_EVENTS):
+        return False
+    for event in TOOL_EVENTS:
+        matches = [item for item in removals if item.event == event]
+        if len(matches) != 1 or not matches[0].remove_group:
+            return False
+        group = document.hooks[event][matches[0].group_index]
+        if group != additions[event]:
+            return False
+    return True
 
 
 def render_document(
@@ -170,93 +296,112 @@ def render_document(
     agent_id: Optional[str],
     additions: Dict[str, JsonObject],
 ) -> RenderedDocument:
-    editor = JsoncEditor(
-        document.raw,
-        _label(document.kind, document.file_path),
-    )
+    if additions and _has_exact_installation(document, additions):
+        return RenderedDocument(document, False, document.raw)
+    editor = JsoncEditor(document.raw, _label(document.kind, document.file_path))
     _remove_managed(editor, document, agent_id)
     for event in TOOL_EVENTS:
         group = additions.get(event)
-        if group is None:
-            continue
-        current = _hooks_from_editor(editor, document)
-        if event in current:
-            editor.append(_event_path(document, event), group)
-        else:
-            editor.add_property(document.base_path, event, [group])
-    next_document = parse_document(
-        exists=document.exists,
-        file_path=document.file_path,
-        kind=document.kind,
-        raw=editor.raw,
-    )
+        if group is not None:
+            _append_group(editor, document, event, group)
+    _current_document(document, editor.raw)
     if (
         not additions
+        and document.exists
         and document.owned_file
-        and document.kind != "settings"
-        and not next_document.hooks
+        and _hook_file_is_empty(document, editor.raw)
     ):
         return RenderedDocument(document, True, None)
-    return RenderedDocument(
-        document,
-        editor.raw != document.raw,
-        editor.raw,
-    )
+    return RenderedDocument(document, editor.raw != document.raw, editor.raw)
 
 
-def _event_target(
-    event: str,
-    sources: DroidSources,
-    create_root: "_RootFactory",
-) -> DroidDocument:
-    if sources.primary is not None and event in sources.primary.hooks:
-        return sources.primary
-    if sources.settings.has_hooks_container and event in sources.settings.hooks:
-        return sources.settings
-    if sources.primary is not None:
-        return sources.primary
+def active_document(sources: DroidSources) -> DroidDocument:
+    if sources.root.exists:
+        return sources.root
+    if sources.legacy.exists:
+        return sources.legacy
+    if sources.local_settings.has_hooks_container:
+        return sources.local_settings
     if sources.settings.has_hooks_container:
         return sources.settings
-    return create_root.get()
+    return sources.root
 
 
-class _RootFactory:
-    def __init__(self, file_path: str) -> None:
-        self.file_path = file_path
-        self.document: Optional[DroidDocument] = None
-
-    def get(self) -> DroidDocument:
-        if self.document is None:
-            self.document = create_owned_hook_document(self.file_path)
-        return self.document
+def effective_hooks(sources: DroidSources) -> DroidHookMap:
+    return active_document(sources).hooks
 
 
-def installation_targets(sources: DroidSources) -> InstallationTargets:
-    root = _RootFactory(sources.root_path)
-    targets = {
-        event: _event_target(event, sources, root)
-        for event in TOOL_EVENTS
-    }
-    return InstallationTargets(targets, root.document)
+def hook_block(sources: DroidSources) -> Optional[DroidHookBlock]:
+    managed = sources.policy.allow_managed_hooks_only_by
+    if managed is not None:
+        return DroidHookBlock(
+            "allowManagedHooksOnly",
+            managed.file_path,
+            managed.label,
+        )
+    if sources.policy.hooks_disabled is not None:
+        if sources.policy.hooks_disabled:
+            origin = sources.policy.hooks_disabled_by
+            if origin is None:
+                raise RuntimeError("Factory Droid policy origin is missing")
+            return DroidHookBlock(
+                "hooksDisabled",
+                origin.file_path,
+                origin.label,
+            )
+        return None
+    selected = (
+        sources.local_settings
+        if sources.local_settings.hooks_disabled is not None
+        else sources.settings
+    )
+    if selected.hooks_disabled is True:
+        return DroidHookBlock(
+            "hooksDisabled",
+            selected.file_path,
+            _label(selected.kind, selected.file_path),
+        )
+    active = active_document(sources)
+    if active.hooks_disabled is True:
+        return DroidHookBlock(
+            "hooksDisabled",
+            active.file_path,
+            _label(active.kind, active.file_path),
+        )
+    return None
 
 
-def additions_for(
+def source_documents(sources: DroidSources) -> List[DroidDocument]:
+    return [
+        sources.root,
+        sources.legacy,
+        sources.settings,
+        sources.local_settings,
+    ]
+
+
+def installation_documents(sources: DroidSources) -> List[DroidDocument]:
+    target = active_document(sources)
+    candidates = [
+        sources.root if sources.root.exists or target is sources.root else None,
+        sources.legacy if sources.legacy.exists else None,
+        sources.settings if sources.settings.has_hooks_container else None,
+        (
+            sources.local_settings
+            if sources.local_settings.has_hooks_container
+            else None
+        ),
+    ]
+    unique: Dict[str, DroidDocument] = {}
+    for document in candidates:
+        if document is not None:
+            unique[os.path.normcase(os.path.abspath(document.file_path))] = document
+    return list(unique.values())
+
+
+def additions_for_target(
     document: DroidDocument,
-    targets: Dict[str, DroidDocument],
+    target: DroidDocument,
     groups: Dict[str, JsonObject],
 ) -> Dict[str, JsonObject]:
-    return {
-        event: groups[event]
-        for event in TOOL_EVENTS
-        if targets[event].file_path == document.file_path
-    }
-
-
-def unique_documents(
-    documents: Sequence[Optional[DroidDocument]],
-) -> List[DroidDocument]:
-    unique: Dict[str, DroidDocument] = {}
-    for document in documents:
-        if document is not None:
-            unique[document.file_path] = document
-    return list(unique.values())
+    return groups if same_path(document.file_path, target.file_path) else {}

sdks/python/elydora/plugins/droid_contract.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 import json
 import math
 import os
+import re
 import shutil
 import subprocess  # nosec B404
 import sys
@@ -18,21 +19,10 @@ AUDIT_SCRIPT = "hook.py"
 HOOK_TIMEOUT_SECONDS = 10
 TOOL_EVENTS = ("PreToolUse", "PostToolUse")
 
-_EVENT_NAMES = {
-    "PreToolUse",
-    "PostToolUse",
-    "Notification",
-    "UserPromptSubmit",
-    "Stop",
-    "SubagentStop",
-    "PreCompact",
-    "SessionStart",
-    "SessionEnd",
-}
-_FLAG_NAMES = {"hooksDisabled", "showHookOutput"}
 _HANDLER_KEYS = {"command", "timeout", "type"}
 _GROUP_KEYS = {"hooks", "matcher"}
 _REGEX_TIMEOUT_SECONDS = 10
+_WINDOWS_EXIT_SUFFIX = "; exit $LASTEXITCODE"
 _REGEX_VALIDATOR = """import fs from 'node:fs';
 const entries = JSON.parse(fs.readFileSync(0, 'utf8'));
 for (const entry of entries) {
@@ -47,7 +37,7 @@ for (const entry of entries) {
 """
 
 JsonObject = Dict[str, Any]
-DroidHookSettings = Dict[str, Any]
+DroidHookMap = Dict[str, Any]
 
 
 @dataclass(frozen=True)
@@ -65,20 +55,22 @@ class ManagedRemoval:
     remove_group: bool
 
 
-def is_object(value: Any) -> bool:
-    return isinstance(value, dict)
-
-
-def has_own(value: JsonObject, key: str) -> bool:
-    return key in value
-
-
 def elydora_dir() -> str:
     return os.path.join(os.path.expanduser("~"), ".elydora")
 
 
-def _quote_windows(value: str) -> str:
-    return '"' + value.replace('"', '\\"') + '"'
+def same_path(left: str, right: str) -> bool:
+    return os.path.normcase(os.path.abspath(left)) == os.path.normcase(
+        os.path.abspath(right)
+    )
+
+
+def same_agent_id(left: str, right: str) -> bool:
+    return os.path.normcase(left) == os.path.normcase(right)
+
+
+def _quote_power_shell(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
 
 
 def _quote_posix(value: str) -> str:
@@ -86,8 +78,16 @@ def _quote_posix(value: str) -> str:
 
 
 def build_command(script_path: str) -> str:
-    quote = _quote_windows if os.name == "nt" else _quote_posix
-    return f"{quote(sys.executable)} {quote(script_path)}"
+    if not os.path.isabs(sys.executable) or not os.path.isabs(script_path):
+        raise ValueError(
+            "Factory Droid hook commands require absolute executable and script paths"
+        )
+    if os.name == "nt":
+        return (
+            f"& {_quote_power_shell(sys.executable)} "
+            f"{_quote_power_shell(script_path)}{_WINDOWS_EXIT_SUFFIX}"
+        )
+    return f"{_quote_posix(sys.executable)} {_quote_posix(script_path)}"
 
 
 def build_group(script_path: str) -> JsonObject:
@@ -102,25 +102,27 @@ def build_group(script_path: str) -> JsonObject:
 
 
 def _validate_handler(value: Any, label: str) -> JsonObject:
-    if not is_object(value):
+    if not isinstance(value, dict):
         raise ValueError(f"{label} must be an object")
     handler = dict(value)
     if handler.get("type") != "command":
         raise ValueError(f'{label} type must be "command"')
-    if not isinstance(handler.get("command"), str):
-        raise ValueError(f"{label} command must be a string")
+    command = handler.get("command")
+    if not isinstance(command, str) or not command.strip():
+        raise ValueError(f"{label} command must be a non-empty string")
     timeout = handler.get("timeout")
     if timeout is not None and (
         isinstance(timeout, bool)
         or not isinstance(timeout, (int, float))
         or not math.isfinite(timeout)
+        or timeout <= 0
     ):
-        raise ValueError(f"{label} timeout must be a finite number")
+        raise ValueError(f"{label} timeout must be a positive finite number")
     return handler
 
 
 def _validate_group(value: Any, label: str) -> JsonObject:
-    if not is_object(value):
+    if not isinstance(value, dict):
         raise ValueError(f"{label} must be an object")
     group = dict(value)
     matcher = group.get("matcher")
@@ -139,31 +141,23 @@ def _validate_group(value: Any, label: str) -> JsonObject:
     return group
 
 
-def read_hook_settings(value: Any, label: str) -> DroidHookSettings:
-    if not is_object(value):
+def read_hook_map(value: Any, label: str) -> DroidHookMap:
+    if not isinstance(value, dict):
         raise ValueError(f"{label} must contain a JSON object")
-    settings: DroidHookSettings = dict(value)
-    for key, item in value.items():
-        if key in _FLAG_NAMES:
-            if not isinstance(item, bool):
-                raise ValueError(f'{label} field "{key}" must be a boolean')
-            continue
-        if key not in _EVENT_NAMES:
-            raise ValueError(f'{label} contains unsupported field "{key}"')
-        if not isinstance(item, list):
-            raise ValueError(f'{label} field "{key}" must be an array')
-        settings[key] = [
-            _validate_group(group, f'{label} field "{key}"[{index}]')
-            for index, group in enumerate(item)
+    hooks: DroidHookMap = {}
+    for event, groups in value.items():
+        if not isinstance(groups, list):
+            raise ValueError(f'{label} field "{event}" must be an array')
+        hooks[event] = [
+            _validate_group(group, f'{label} field "{event}"[{index}]')
+            for index, group in enumerate(groups)
         ]
-    return settings
+    return hooks
 
 
-def _regex_entries(settings: DroidHookSettings) -> List[JsonObject]:
+def _regex_entries(hooks: DroidHookMap) -> List[JsonObject]:
     entries: List[JsonObject] = []
-    for event, groups in settings.items():
-        if event in _FLAG_NAMES:
-            continue
+    for event, groups in hooks.items():
         for index, group in enumerate(groups):
             matcher = group.get("matcher")
             if isinstance(matcher, str) and matcher not in {"", "*"}:
@@ -182,8 +176,8 @@ def _regex_entries(settings: DroidHookSettings) -> List[JsonObject]:
     return entries
 
 
-def validate_javascript_regexes(settings: Sequence[DroidHookSettings]) -> None:
-    entries = [entry for source in settings for entry in _regex_entries(source)]
+def validate_javascript_regexes(sources: Sequence[DroidHookMap]) -> None:
+    entries = [entry for source in sources for entry in _regex_entries(source)]
     if not entries:
         return
     node_path = shutil.which("node")
@@ -220,20 +214,24 @@ def validate_javascript_regexes(settings: Sequence[DroidHookSettings]) -> None:
     )
 
 
-def _read_windows_argument(command: str, start: int) -> Optional[Tuple[str, int]]:
-    if start >= len(command) or command[start] != '"':
+def _read_power_shell_argument(
+    command: str,
+    start: int,
+) -> Optional[Tuple[str, int]]:
+    if start >= len(command) or command[start] != "'":
         return None
     value = ""
     index = start + 1
     while index < len(command):
-        if command[index:index + 2] == '\\"':
-            value += '"'
+        if command[index] != "'":
+            value += command[index]
+            index += 1
+            continue
+        if index + 1 < len(command) and command[index + 1] == "'":
+            value += "'"
             index += 2
             continue
-        if command[index] == '"':
-            return value, index + 1
-        value += command[index]
-        index += 1
+        return value, index + 1
     return None
 
 
@@ -257,14 +255,16 @@ def _read_posix_argument(command: str, start: int) -> Optional[Tuple[str, int]]:
     return None
 
 
-def _parse_generated_command(command: str) -> Optional[Tuple[str, str]]:
-    reader = _read_windows_argument if os.name == "nt" else _read_posix_argument
-    executable = reader(command, 0)
+def _parse_two_arguments(
+    command: str,
+    start: int,
+) -> Optional[Tuple[str, str]]:
+    executable = _read_posix_argument(command, start)
     if executable is None or executable[1] >= len(command):
         return None
     if command[executable[1]] != " ":
         return None
-    script = reader(command, executable[1] + 1)
+    script = _read_posix_argument(command, executable[1] + 1)
     if script is None or script[1] != len(command):
         return None
     if not executable[0] or not script[0]:
@@ -272,32 +272,65 @@ def _parse_generated_command(command: str) -> Optional[Tuple[str, str]]:
     return executable[0], script[0]
 
 
-def _same_path(left: str, right: str) -> bool:
-    return os.path.normcase(os.path.abspath(left)) == os.path.normcase(
-        os.path.abspath(right)
+def _parse_power_shell_command(command: str) -> Optional[Tuple[str, str]]:
+    if not command.startswith("& "):
+        return None
+    executable = _read_power_shell_argument(command, 2)
+    if executable is None or executable[1] >= len(command):
+        return None
+    if command[executable[1]] != " ":
+        return None
+    script = _read_power_shell_argument(command, executable[1] + 1)
+    if (
+        script is None
+        or command[script[1]:] != _WINDOWS_EXIT_SUFFIX
+        or not executable[0]
+        or not script[0]
+    ):
+        return None
+    return executable[0], script[0]
+
+
+def _parse_legacy_windows_command(command: str) -> Optional[Tuple[str, str]]:
+    match = re.fullmatch(r'"([^"\r\n]+)" "([^"\r\n]+)"', command)
+    return (match.group(1), match.group(2)) if match else None
+
+
+def _parse_generated_command(
+    command: str,
+    include_legacy: bool,
+) -> Optional[Tuple[str, str]]:
+    if os.name != "nt":
+        return _parse_two_arguments(command, 0)
+    current = _parse_power_shell_command(command)
+    return current or (
+        _parse_legacy_windows_command(command) if include_legacy else None
     )
 
 
-def same_agent_id(left: str, right: str) -> bool:
-    return os.path.normcase(left) == os.path.normcase(right)
-
-
-def managed_agent_id(handler: JsonObject, script_name: str) -> Optional[str]:
+def managed_agent_id(
+    handler: JsonObject,
+    script_name: str,
+    include_legacy: bool = False,
+) -> Optional[str]:
     if set(handler) != _HANDLER_KEYS:
         return None
-    if handler.get("type") != "command" or handler.get("timeout") != 10:
+    if (
+        handler.get("type") != "command"
+        or handler.get("timeout") != HOOK_TIMEOUT_SECONDS
+    ):
         return None
     command = handler.get("command")
     if not isinstance(command, str):
         return None
-    parsed = _parse_generated_command(command)
-    if parsed is None or not _same_path(parsed[0], sys.executable):
+    parsed = _parse_generated_command(command, include_legacy)
+    if parsed is None or not same_path(parsed[0], sys.executable):
         return None
     script_path = parsed[1]
     if os.path.basename(script_path) != script_name:
         return None
     agent_directory = os.path.dirname(script_path)
-    if not _same_path(os.path.dirname(agent_directory), elydora_dir()):
+    if not same_path(os.path.dirname(agent_directory), elydora_dir()):
         return None
     agent_id = os.path.basename(agent_directory)
     return agent_id if agent_id not in {"", ".", ".."} else None
@@ -314,7 +347,7 @@ def _exact_owned_group(group: JsonObject, indexes: Tuple[int, ...]) -> bool:
 
 
 def managed_removals(
-    settings: DroidHookSettings,
+    hooks: DroidHookMap,
     agent_id: Optional[str] = None,
 ) -> List[ManagedRemoval]:
     removals: List[ManagedRemoval] = []
@@ -322,12 +355,19 @@ def managed_removals(
         ("PreToolUse", GUARD_SCRIPT),
         ("PostToolUse", AUDIT_SCRIPT),
     ):
-        for group_index, group in enumerate(settings.get(event, [])):
+        for group_index, group in enumerate(hooks.get(event, [])):
             indexes = tuple(
                 index
                 for index, handler in enumerate(group["hooks"])
                 if (
-                    (managed_id := managed_agent_id(handler, script_name)) is not None
+                    (
+                        managed_id := managed_agent_id(
+                            handler,
+                            script_name,
+                            include_legacy=True,
+                        )
+                    )
+                    is not None
                     and (agent_id is None or same_agent_id(managed_id, agent_id))
                 )
             )
@@ -350,9 +390,9 @@ def _managed_ids(groups: List[JsonObject], script_name: str) -> Set[str]:
     }
 
 
-def runtime_contracts(settings: DroidHookSettings) -> List[RuntimeContract]:
-    guards = _managed_ids(settings.get("PreToolUse", []), GUARD_SCRIPT)
-    audits = _managed_ids(settings.get("PostToolUse", []), AUDIT_SCRIPT)
+def runtime_contracts(hooks: DroidHookMap) -> List[RuntimeContract]:
+    guards = _managed_ids(hooks.get("PreToolUse", []), GUARD_SCRIPT)
+    audits = _managed_ids(hooks.get("PostToolUse", []), AUDIT_SCRIPT)
     contracts = []
     for agent_id in sorted(guards):
         if not any(same_agent_id(agent_id, audit_id) for audit_id in audits):
@@ -364,10 +404,3 @@ def runtime_contracts(settings: DroidHookSettings) -> List[RuntimeContract]:
             os.path.join(root, AUDIT_SCRIPT),
         ))
     return contracts
-
-
-def merge_hook_settings(
-    primary: Optional[DroidHookSettings],
-    fallback: Optional[DroidHookSettings],
-) -> DroidHookSettings:
-    return {**(fallback or {}), **(primary or {})}

sdks/python/elydora/plugins/droid_installation.py

@@ -0,0 +1,312 @@
+"""Transactional Factory Droid hook installation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+import sys
+from typing import Optional, Sequence, Tuple
+
+from elydora._runtime_paths import resolve_agent_directory
+
+from ._managed_files import MAX_CONFIG_BYTES, MAX_SECRET_BYTES, MAX_SOURCE_BYTES
+from ._transaction import (
+    FileChange,
+    FilePrecondition,
+    file_change,
+    source_change,
+    write_changes,
+)
+from .base import InstallConfig
+from .droid_config import (
+    DroidDocument,
+    DroidSources,
+    RenderedDocument,
+    installation_documents,
+    source_documents,
+)
+from .droid_contract import (
+    AGENT_KEY,
+    AUDIT_SCRIPT,
+    GUARD_SCRIPT,
+    elydora_dir,
+    same_path,
+    validate_javascript_regexes,
+)
+from .droid_io import (
+    require_hooks_enabled,
+    validate_api_origin,
+    validate_private_key,
+    validate_runtime_tree,
+)
+from .guard_template import generate_guard_script
+from .hook_template import generate_hook_script
+
+
+@dataclass(frozen=True)
+class DroidRuntimePaths:
+    agent_id: str
+    agent_directory: str
+    guard_path: str
+    audit_path: str
+
+
+@dataclass(frozen=True)
+class PreparedDroidInstallation:
+    changes: Tuple[FileChange, ...]
+    preconditions: Tuple[FilePrecondition, ...]
+
+
+@dataclass(frozen=True)
+class PreparedDroidUninstall:
+    changes: Tuple[FileChange, ...]
+    preconditions: Tuple[FilePrecondition, ...]
+
+
+def _source_label(document: DroidDocument) -> str:
+    if document.kind == "settings":
+        return "Factory Droid user settings"
+    if document.kind == "local-settings":
+        return "Factory Droid local settings"
+    if document.kind == "legacy":
+        return "Factory Droid legacy hooks"
+    return "Factory Droid user hooks"
+
+
+def _runtime_config(config: InstallConfig, agent_id: str) -> dict:
+    value = {
+        "org_id": config.get("org_id", ""),
+        "agent_id": agent_id,
+        "kid": config.get("kid", ""),
+        "base_url": config.get("base_url", "https://api.elydora.com"),
+        "agent_name": AGENT_KEY,
+    }
+    token = config.get("token")
+    if token:
+        value["token"] = token
+    return value
+
+
+def _json_source(value: dict) -> str:
+    return json.dumps(value, indent=2) + "\n"
+
+
+def _agent_paths(config: InstallConfig) -> DroidRuntimePaths:
+    agent_id = config.get("agent_id", "")
+    if not agent_id:
+        raise ValueError("agent_id is required")
+    agent_directory = resolve_agent_directory(elydora_dir(), agent_id)
+    guard_path = os.path.join(agent_directory, GUARD_SCRIPT)
+    audit_path = os.path.join(agent_directory, AUDIT_SCRIPT)
+    if not same_path(config.get("guard_script_path", ""), guard_path):
+        raise ValueError(
+            "Elydora guard runtime must use the managed agent directory: "
+            f"{guard_path}"
+        )
+    return DroidRuntimePaths(
+        agent_id,
+        agent_directory,
+        guard_path,
+        audit_path,
+    )
+
+
+def _validate_install_config(config: InstallConfig) -> None:
+    for field in ("org_id", "agent_id", "kid", "private_key", "base_url"):
+        value = config.get(field)
+        if not isinstance(value, str) or not value:
+            raise ValueError(f"{field} is required")
+    if config.get("agent_name") != AGENT_KEY:
+        raise ValueError(
+            f"Factory Droid installation requires agent_name {AGENT_KEY}"
+        )
+    if not os.path.isabs(sys.executable):
+        raise RuntimeError(
+            "Factory Droid requires an absolute Python executable path"
+        )
+    validate_private_key(config["private_key"])
+    validate_api_origin(config["base_url"])
+    if "token" in config:
+        token = config["token"]
+        if not isinstance(token, str) or not token:
+            raise ValueError("token must be a non-empty string when provided")
+    _agent_paths(config)
+
+
+def preflight_droid_installation(
+    config: InstallConfig,
+    sources: DroidSources,
+) -> DroidRuntimePaths:
+    require_hooks_enabled(sources)
+    validate_javascript_regexes([
+        document.hooks for document in source_documents(sources)
+    ])
+    _validate_install_config(config)
+    paths = _agent_paths(config)
+    validate_runtime_tree(paths.agent_directory, paths.agent_id)
+    return paths
+
+
+def _runtime_change(
+    file_path: str,
+    label: str,
+    next_source: str,
+    mode: int,
+    maximum_bytes: int = MAX_SOURCE_BYTES,
+) -> Optional[FileChange]:
+    return file_change(file_path, label, next_source, mode, maximum_bytes)
+
+
+def _document_change(rendered: RenderedDocument) -> Optional[FileChange]:
+    if not rendered.changed:
+        return None
+    document = rendered.document
+    return source_change(
+        document.file_path,
+        _source_label(document),
+        document.raw if document.exists else None,
+        rendered.next_source,
+        0o600,
+        MAX_SOURCE_BYTES,
+        document.snapshot,
+    )
+
+
+def _present(
+    changes: Sequence[Optional[FileChange]],
+) -> Tuple[FileChange, ...]:
+    return tuple(change for change in changes if change is not None)
+
+
+def _validate_rendered_documents(
+    sources: DroidSources,
+    rendered: Sequence[RenderedDocument],
+) -> None:
+    expected = installation_documents(sources)
+    if len(rendered) != len(expected):
+        raise ValueError("Factory Droid rendered source set is incomplete")
+    for document in expected:
+        matches = [
+            item
+            for item in rendered
+            if same_path(item.document.file_path, document.file_path)
+        ]
+        if len(matches) != 1:
+            raise ValueError(
+                "Factory Droid rendered source set contains unexpected paths"
+            )
+
+
+def _source_preconditions(
+    sources: DroidSources,
+    changed_paths: Sequence[str],
+) -> Tuple[FilePrecondition, ...]:
+    return tuple(
+        FilePrecondition(
+            document.file_path,
+            _source_label(document),
+            document.snapshot,
+            MAX_SOURCE_BYTES,
+        )
+        for document in source_documents(sources)
+        if not any(
+            same_path(document.file_path, changed)
+            for changed in changed_paths
+        )
+    )
+
+
+def prepare_droid_installation(
+    config: InstallConfig,
+    sources: DroidSources,
+    rendered: Sequence[RenderedDocument],
+) -> PreparedDroidInstallation:
+    paths = preflight_droid_installation(config, sources)
+    _validate_rendered_documents(sources, rendered)
+    guard_script = generate_guard_script(AGENT_KEY, paths.agent_id)
+    audit_script = generate_hook_script(
+        org_id=config.get("org_id", ""),
+        agent_id=paths.agent_id,
+        kid=config.get("kid", ""),
+        base_url=config.get("base_url", "https://api.elydora.com"),
+        native_payload=True,
+        agent_name=AGENT_KEY,
+    )
+    document_changes = _present(tuple(
+        _document_change(item) for item in rendered
+    ))
+    changes = _present((
+        _runtime_change(
+            paths.guard_path,
+            "Elydora guard runtime",
+            guard_script,
+            0o700,
+        ),
+        _runtime_change(
+            os.path.join(paths.agent_directory, "config.json"),
+            "Elydora runtime config",
+            _json_source(_runtime_config(config, paths.agent_id)),
+            0o600,
+            MAX_CONFIG_BYTES,
+        ),
+        _runtime_change(
+            os.path.join(paths.agent_directory, "private.key"),
+            "Elydora private key",
+            config.get("private_key", ""),
+            0o600,
+            MAX_SECRET_BYTES,
+        ),
+        _runtime_change(
+            paths.audit_path,
+            "Elydora audit runtime",
+            audit_script,
+            0o700,
+        ),
+        *document_changes,
+    ))
+    changed_paths = [change.file_path for change in document_changes]
+    preconditions = (
+        *_source_preconditions(sources, changed_paths),
+        *sources.policy.preconditions,
+    )
+    return PreparedDroidInstallation(changes, tuple(preconditions))
+
+
+def commit_droid_installation(
+    prepared: PreparedDroidInstallation,
+) -> None:
+    write_changes(
+        prepared.changes,
+        "Install Factory Droid hooks",
+        prepared.preconditions,
+    )
+
+
+def prepare_droid_uninstall(
+    rendered: Sequence[RenderedDocument],
+) -> PreparedDroidUninstall:
+    changes = _present(tuple(_document_change(item) for item in rendered))
+    changed_paths = [change.file_path for change in changes]
+    preconditions = tuple(
+        FilePrecondition(
+            item.document.file_path,
+            _source_label(item.document),
+            item.document.snapshot,
+            MAX_SOURCE_BYTES,
+        )
+        for item in rendered
+        if not any(
+            same_path(item.document.file_path, changed)
+            for changed in changed_paths
+        )
+    )
+    return PreparedDroidUninstall(changes, preconditions)
+
+
+def commit_droid_uninstall(prepared: PreparedDroidUninstall) -> None:
+    write_changes(
+        prepared.changes,
+        "Uninstall Factory Droid hooks",
+        prepared.preconditions,
+    )

sdks/python/elydora/plugins/droid_io.py

@@ -1,126 +1,324 @@
-"""Factory Droid source discovery and runtime inspection."""
+"""Factory Droid source discovery and managed runtime validation."""
 
 from __future__ import annotations
 
-import json
+import base64
+from dataclasses import dataclass
 import os
-from typing import Optional
+from typing import Any, Optional
+import urllib.parse
 
-from ._transaction import (
-    FileChange,
-    read_optional,
-    regular_file_exists,
-    source_change,
+from ._managed_files import (
+    MAX_CONFIG_BYTES,
+    MAX_SECRET_BYTES,
+    MAX_SOURCE_BYTES,
+    physical_directory_exists,
+    physical_file_exists,
+    read_physical_file,
 )
+from ._strict_json import JsonObject, parse_json_object
 from .droid_config import (
+    DroidDocument,
     DroidSources,
-    RenderedDocument,
+    active_document,
+    create_legacy_hook_document,
+    create_owned_hook_document,
     create_settings_document,
+    hook_block,
     parse_document,
 )
-from .droid_contract import AGENT_KEY, JsonObject, RuntimeContract, same_agent_id
+from .droid_contract import (
+    AGENT_KEY,
+    AUDIT_SCRIPT,
+    GUARD_SCRIPT,
+    RuntimeContract,
+    elydora_dir,
+    same_agent_id,
+    same_path,
+)
+from .droid_policy import read_droid_policy
+from .guard_template import generate_guard_script
+from .hook_template import generate_hook_script
 
 
-def _factory_paths() -> tuple[str, str, str]:
+@dataclass(frozen=True)
+class FactoryPaths:
+    directory: str
+    root: str
+    legacy_directory: str
+    legacy: str
+    settings: str
+    local_settings: str
+
+
+def _factory_paths() -> FactoryPaths:
     directory = os.path.join(os.path.expanduser("~"), ".factory")
-    return (
+    legacy_directory = os.path.join(directory, "hooks")
+    return FactoryPaths(
+        directory,
         os.path.join(directory, "hooks.json"),
-        os.path.join(directory, "hooks", "hooks.json"),
+        legacy_directory,
+        os.path.join(legacy_directory, "hooks.json"),
         os.path.join(directory, "settings.json"),
+        os.path.join(directory, "settings.local.json"),
+    )
+
+
+def _read_document(
+    file_path: str,
+    kind: str,
+    label: str,
+) -> Optional[DroidDocument]:
+    snapshot = read_physical_file(file_path, label, MAX_SOURCE_BYTES)
+    if snapshot is None:
+        return None
+    return parse_document(
+        exists=True,
+        file_path=file_path,
+        kind=kind,
+        raw=snapshot.contents,
+        snapshot=snapshot,
     )
 
 
 def read_sources() -> DroidSources:
-    root_path, legacy_path, settings_path = _factory_paths()
-    root_raw = read_optional(root_path, "Factory Droid hooks")
-    settings_raw = read_optional(settings_path, "Factory Droid settings")
-    primary = None
-    if root_raw is not None:
-        primary = parse_document(
-            exists=True,
-            file_path=root_path,
-            kind="hooks",
-            raw=root_raw,
-        )
-    else:
-        legacy_raw = read_optional(legacy_path, "Factory Droid legacy hooks")
-        if legacy_raw is not None:
-            primary = parse_document(
-                exists=True,
-                file_path=legacy_path,
-                kind="legacy",
-                raw=legacy_raw,
-            )
-    settings = (
-        create_settings_document(settings_path)
-        if settings_raw is None
-        else parse_document(
-            exists=True,
-            file_path=settings_path,
-            kind="settings",
-            raw=settings_raw,
-        )
+    paths = _factory_paths()
+    physical_directory_exists(
+        paths.directory,
+        "Factory Droid user configuration directory",
     )
-    return DroidSources(root_path, primary, settings)
-
-
-def rendered_change(rendered: RenderedDocument) -> Optional[FileChange]:
-    if not rendered.changed:
-        return None
-    if rendered.document.kind == "settings":
-        label = "Factory Droid settings"
-    elif rendered.document.kind == "legacy":
-        label = "Factory Droid legacy hooks"
-    else:
-        label = "Factory Droid hooks"
-    return source_change(
-        rendered.document.file_path,
-        label,
-        rendered.document.raw if rendered.document.exists else None,
-        rendered.next_source,
-        0o600,
+    physical_directory_exists(
+        paths.legacy_directory,
+        "Factory Droid legacy hooks directory",
+    )
+    root = _read_document(paths.root, "hooks", "Factory Droid user hooks")
+    legacy = _read_document(
+        paths.legacy,
+        "legacy",
+        "Factory Droid legacy hooks",
+    )
+    settings = _read_document(
+        paths.settings,
+        "settings",
+        "Factory Droid user settings",
+    )
+    local_settings = _read_document(
+        paths.local_settings,
+        "local-settings",
+        "Factory Droid local settings",
+    )
+    return DroidSources(
+        root or create_owned_hook_document(paths.root),
+        legacy or create_legacy_hook_document(paths.legacy),
+        settings or create_settings_document(paths.settings),
+        local_settings or create_settings_document(
+            paths.local_settings,
+            "local-settings",
+        ),
+        read_droid_policy(),
     )
 
 
-def _read_runtime_config(file_path: str) -> Optional[JsonObject]:
-    raw = read_optional(file_path, "Elydora runtime config")
-    if raw is None:
-        return None
+def require_hooks_enabled(sources: DroidSources) -> None:
+    blocked = hook_block(sources)
+    if blocked is not None:
+        raise ValueError(
+            "Factory Droid user hooks are disabled by "
+            f"{blocked.field} in {blocked.label} at {blocked.file_path}"
+        )
+
+
+def validate_api_origin(value: str, label: str = "base_url") -> None:
     try:
-        value = json.loads(raw)
-    except json.JSONDecodeError as error:
+        parsed = urllib.parse.urlsplit(value)
+        hostname = parsed.hostname
+        parsed.port
+    except ValueError as error:
         raise ValueError(
-            f"Failed to parse Elydora runtime config at {file_path}: {error}"
+            f"{label} must be an absolute HTTP or HTTPS URL"
         ) from error
-    if not isinstance(value, dict):
+    invalid_character = "\\" in value or any(
+        character.isspace() or ord(character) < 32 for character in value
+    )
+    if (
+        parsed.scheme not in ("http", "https")
+        or not parsed.netloc
+        or hostname is None
+        or invalid_character
+    ):
+        raise ValueError(f"{label} must be an absolute HTTP or HTTPS URL")
+    if (
+        parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
         raise ValueError(
-            f"Elydora runtime config at {file_path} must contain a JSON object"
+            f"{label} must exclude credentials, query parameters, and fragments"
+        )
+
+
+def validate_private_key(value: str, label: str = "private_key") -> None:
+    try:
+        padded = value + "=" * ((4 - len(value) % 4) % 4)
+        seed = base64.b64decode(
+            padded.replace("-", "+").replace("_", "/"),
+            validate=True,
+        )
+        canonical = base64.urlsafe_b64encode(seed).rstrip(b"=").decode("ascii")
+    except (ValueError, UnicodeEncodeError) as error:
+        raise ValueError(
+            f"{label} must be a canonical 32-byte base64url value"
+        ) from error
+    if len(seed) != 32 or canonical != value:
+        raise ValueError(f"{label} must be a canonical 32-byte base64url value")
+
+
+def _require_string(value: Any, field: str, config_path: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(
+            f"Elydora runtime config {field} is invalid: {config_path}"
         )
     return value
 
 
+def _validate_runtime_config(
+    config: JsonObject,
+    contract: RuntimeContract,
+    config_path: str,
+) -> None:
+    supported = {"org_id", "agent_id", "kid", "base_url", "token", "agent_name"}
+    extra = next((key for key in config if key not in supported), None)
+    if extra is not None:
+        raise ValueError(
+            f'Elydora runtime config has unsupported field "{extra}": '
+            f"{config_path}"
+        )
+    _require_string(config.get("org_id"), "org_id", config_path)
+    _require_string(config.get("kid"), "kid", config_path)
+    agent_id = _require_string(config.get("agent_id"), "agent_id", config_path)
+    if (
+        not same_agent_id(agent_id, contract.agent_id)
+        or config.get("agent_name") != AGENT_KEY
+    ):
+        raise ValueError(
+            "Elydora runtime identity does not match Factory Droid hooks: "
+            f"{config_path}"
+        )
+    if "token" in config:
+        _require_string(config.get("token"), "token", config_path)
+    base_url = _require_string(config.get("base_url"), "base_url", config_path)
+    validate_api_origin(base_url, "Elydora runtime config base_url")
+
+
+def _read_runtime_config(file_path: str) -> Optional[JsonObject]:
+    snapshot = read_physical_file(
+        file_path,
+        "Elydora runtime config",
+        MAX_CONFIG_BYTES,
+    )
+    if snapshot is None:
+        return None
+    return parse_json_object(
+        snapshot.contents,
+        f"Elydora runtime config at {file_path}",
+    )
+
+
+def validate_runtime_tree(agent_directory: str, agent_id: str) -> None:
+    root = elydora_dir()
+    if not physical_directory_exists(root, "Elydora runtime directory"):
+        return
+    if not physical_directory_exists(
+        agent_directory,
+        "Elydora agent runtime directory",
+    ):
+        return
+    config_path = os.path.join(agent_directory, "config.json")
+    config = _read_runtime_config(config_path)
+    artifacts = (
+        ("private.key", "Elydora private key"),
+        (GUARD_SCRIPT, "Elydora guard runtime"),
+        (AUDIT_SCRIPT, "Elydora audit runtime"),
+        ("chain-state.json", "Elydora chain state"),
+        ("status-cache.json", "Elydora status cache"),
+        ("error.log", "Elydora error log"),
+    )
+    artifact_exists = any(
+        physical_file_exists(os.path.join(agent_directory, name), label)
+        for name, label in artifacts
+    )
+    if config is None:
+        if artifact_exists:
+            raise ValueError(
+                "Elydora runtime identity cannot be verified without config.json: "
+                f"{agent_directory}"
+            )
+        return
+    configured_id = config.get("agent_id")
+    if (
+        not isinstance(configured_id, str)
+        or not same_agent_id(configured_id, agent_id)
+        or config.get("agent_name") != AGENT_KEY
+    ):
+        raise ValueError(
+            "Elydora runtime config identity does not match Factory Droid agent "
+            f"{agent_id}: {config_path}"
+        )
+
+
+def _valid_contract_paths(contract: RuntimeContract) -> bool:
+    agent_directory = os.path.dirname(contract.guard_path)
+    return (
+        same_path(os.path.dirname(agent_directory), elydora_dir())
+        and same_path(
+            contract.guard_path,
+            os.path.join(agent_directory, GUARD_SCRIPT),
+        )
+        and same_path(
+            contract.audit_path,
+            os.path.join(agent_directory, AUDIT_SCRIPT),
+        )
+    )
+
+
+def _runtime_contract_exists(contract: RuntimeContract) -> bool:
+    if not _valid_contract_paths(contract):
+        return False
+    root = elydora_dir()
+    agent_directory = os.path.dirname(contract.guard_path)
+    if not physical_directory_exists(root, "Elydora runtime directory"):
+        return False
+    if not physical_directory_exists(
+        agent_directory,
+        "Elydora agent runtime directory",
+    ):
+        return False
+    config_path = os.path.join(agent_directory, "config.json")
+    key_path = os.path.join(agent_directory, "private.key")
+    config = _read_runtime_config(config_path)
+    key = read_physical_file(key_path, "Elydora private key", MAX_SECRET_BYTES)
+    guard = read_physical_file(contract.guard_path, "Elydora guard runtime")
+    audit = read_physical_file(contract.audit_path, "Elydora audit runtime")
+    if config is None or key is None or guard is None or audit is None:
+        return False
+    _validate_runtime_config(config, contract, config_path)
+    validate_private_key(key.contents, "Elydora private key")
+    expected_guard = generate_guard_script(AGENT_KEY, contract.agent_id)
+    expected_audit = generate_hook_script(
+        org_id="",
+        agent_id=contract.agent_id,
+        kid="",
+        base_url="",
+        native_payload=True,
+        agent_name=AGENT_KEY,
+    )
+    return guard.contents == expected_guard and audit.contents == expected_audit
+
+
 def runtime_files_exist(contracts: list[RuntimeContract]) -> bool:
-    for contract in contracts:
-        agent_directory = os.path.dirname(contract.guard_path)
-        config = _read_runtime_config(os.path.join(agent_directory, "config.json"))
-        config_agent_id = config.get("agent_id") if config else None
-        if (
-            config is None
-            or config.get("agent_name") != AGENT_KEY
-            or not isinstance(config_agent_id, str)
-            or not same_agent_id(config_agent_id, contract.agent_id)
-        ):
-            continue
-        if regular_file_exists(
-            contract.guard_path, "Elydora guard runtime"
-        ) and regular_file_exists(contract.audit_path, "Elydora audit runtime"):
-            return True
-    return False
+    return any(_runtime_contract_exists(contract) for contract in contracts)
 
 
 def display_config_path(sources: DroidSources) -> str:
-    if sources.primary is not None:
-        return sources.primary.file_path
-    if sources.settings.exists and sources.settings.has_hooks_container:
-        return sources.settings.file_path
-    return sources.root_path
+    return active_document(sources).file_path

sdks/python/elydora/plugins/droid_policy.py

@@ -0,0 +1,225 @@
+"""Factory Droid read-only hierarchy and organization policy resolution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+import stat
+import sys
+from typing import List, Optional, Tuple
+
+from ._jsonc import JsoncEditor
+from ._managed_files import (
+    FileSnapshot,
+    MAX_SOURCE_BYTES,
+    physical_directory_exists,
+    read_physical_file,
+)
+from ._transaction import FilePrecondition
+
+
+@dataclass(frozen=True)
+class PolicyLocation:
+    file_path: str
+    label: str
+
+
+@dataclass(frozen=True)
+class PolicyLayer:
+    file_path: str
+    label: str
+    snapshot: Optional[FileSnapshot]
+    hooks_disabled: Optional[bool]
+    allow_managed_hooks_only: Optional[bool]
+    show_hook_output: Optional[bool]
+
+
+@dataclass(frozen=True)
+class PolicyOrigin:
+    file_path: str
+    label: str
+
+
+@dataclass(frozen=True)
+class DroidPolicyState:
+    allow_managed_hooks_only_by: Optional[PolicyOrigin]
+    hooks_disabled: Optional[bool]
+    hooks_disabled_by: Optional[PolicyOrigin]
+    preconditions: Tuple[FilePrecondition, ...]
+
+
+def _optional_boolean(root: dict, field: str, label: str) -> Optional[bool]:
+    value = root.get(field)
+    if field in root and not isinstance(value, bool):
+        raise ValueError(f'{label} field "{field}" must be a boolean')
+    return value
+
+
+def _managed_settings_path() -> str:
+    if sys.platform == "darwin":
+        return "/Library/Application Support/Factory/settings.json"
+    if os.name == "nt":
+        program_files = os.environ.get("ProgramFiles") or r"C:\Program Files"
+        return os.path.join(program_files, "Factory", "settings.json")
+    return "/etc/factory/settings.json"
+
+
+def _read_layer(location: PolicyLocation) -> PolicyLayer:
+    physical_directory_exists(
+        os.path.dirname(location.file_path),
+        f"{location.label} directory",
+    )
+    snapshot = read_physical_file(
+        location.file_path,
+        location.label,
+        MAX_SOURCE_BYTES,
+    )
+    if snapshot is None:
+        return PolicyLayer(
+            location.file_path,
+            location.label,
+            None,
+            None,
+            None,
+            None,
+        )
+    editor = JsoncEditor(
+        snapshot.contents,
+        f"{location.label} at {location.file_path}",
+    )
+    root = editor.value
+    if not isinstance(root, dict):
+        raise ValueError(
+            f"{location.label} at {location.file_path} "
+            "must contain a JSON object"
+        )
+    return PolicyLayer(
+        location.file_path,
+        location.label,
+        snapshot,
+        _optional_boolean(root, "hooksDisabled", location.label),
+        _optional_boolean(root, "allowManagedHooksOnly", location.label),
+        _optional_boolean(root, "showHookOutput", location.label),
+    )
+
+
+def _git_root(start: str) -> Optional[str]:
+    current = os.path.abspath(start)
+    while True:
+        marker = os.path.join(current, ".git")
+        try:
+            metadata = os.lstat(marker)
+        except (FileNotFoundError, NotADirectoryError):
+            pass
+        except OSError as error:
+            raise OSError(
+                f"Inspect Factory Droid project marker at {marker}: {error}"
+            ) from error
+        else:
+            if stat.S_ISLNK(metadata.st_mode) or not (
+                stat.S_ISDIR(metadata.st_mode) or stat.S_ISREG(metadata.st_mode)
+            ):
+                raise OSError(
+                    f"Factory Droid project marker is not physical: {marker}"
+                )
+            return current
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def _project_directories(root: str, current: str) -> List[str]:
+    directories = [root]
+    try:
+        relative = os.path.relpath(current, root)
+    except ValueError:
+        return directories
+    if relative in {"", "."} or relative == os.pardir:
+        return directories
+    if relative.startswith(os.pardir + os.sep) or os.path.isabs(relative):
+        return directories
+    directory = root
+    for segment in relative.split(os.sep):
+        if not segment:
+            continue
+        directory = os.path.join(directory, segment)
+        directories.append(directory)
+    return directories
+
+
+def _project_locations() -> List[Tuple[PolicyLocation, PolicyLocation]]:
+    current = os.path.abspath(os.getcwd())
+    root = _git_root(current) or current
+    locations = []
+    for index, directory in enumerate(_project_directories(root, current)):
+        factory = os.path.join(directory, ".factory")
+        scope = "project" if index == 0 else f"folder {directory}"
+        locations.append((
+            PolicyLocation(
+                os.path.join(factory, "settings.json"),
+                f"Factory Droid {scope} settings",
+            ),
+            PolicyLocation(
+                os.path.join(factory, "settings.local.json"),
+                f"Factory Droid {scope} local settings",
+            ),
+        ))
+    return locations
+
+
+def _scope_value(layers: Tuple[PolicyLayer, PolicyLayer]) -> Optional[PolicyLayer]:
+    settings, local = layers
+    if local.hooks_disabled is not None:
+        return local
+    if settings.hooks_disabled is not None:
+        return settings
+    return None
+
+
+def read_droid_policy() -> DroidPolicyState:
+    managed = _read_layer(PolicyLocation(
+        _managed_settings_path(),
+        "Factory Droid system-managed settings",
+    ))
+    project_layers = [
+        (_read_layer(scope[0]), _read_layer(scope[1]))
+        for scope in _project_locations()
+    ]
+    allow_managed = (
+        PolicyOrigin(managed.file_path, managed.label)
+        if managed.allow_managed_hooks_only is True
+        else None
+    )
+    selected = next(
+        (
+            layer
+            for layer in (
+                managed,
+                *(_scope_value(scope) for scope in project_layers),
+            )
+            if layer is not None and layer.hooks_disabled is not None
+        ),
+        None,
+    )
+    flattened = [managed]
+    for scope in project_layers:
+        flattened.extend(scope)
+    return DroidPolicyState(
+        allow_managed,
+        selected.hooks_disabled if selected is not None else None,
+        (
+            PolicyOrigin(selected.file_path, selected.label)
+            if selected is not None
+            else None
+        ),
+        tuple(
+            FilePrecondition(
+                layer.file_path,
+                layer.label,
+                layer.snapshot,
+                MAX_SOURCE_BYTES,
+            )
+            for layer in flattened
+        ),
+    )