python-codex 0.2.7__py3-none-any.whl → 0.3.0__py3-none-any.whl

pycodex/context.py

@@ -1,16 +1,17 @@
-
-from dataclasses import dataclass
+import typing
+from dataclasses import dataclass, replace
 from datetime import datetime
 from pathlib import Path
-import typing
+from xml.sax.saxutils import escape
+
+import yaml
 
 try:
     import tomllib
 except ModuleNotFoundError:  # pragma: no cover - Python 3.10 path
     import tomli as tomllib
 
-from .collaboration import DEFAULT_COLLABORATION_MODE, CollaborationMode
-from .model_metadata import load_models_by_slug
+from .model_metadata import model_metadata
 from .protocol import ContextMessage, ConversationItem, JSONDict, Prompt, ToolSpec
 from .utils.get_env import (
     get_sandbox_tag,
@@ -22,12 +23,6 @@ from .utils.get_env import (
 DEFAULT_BASE_INSTRUCTIONS_PATH = (
     Path(__file__).resolve().parent / "prompts" / "default_base_instructions.md"
 )
-DEFAULT_COLLABORATION_INSTRUCTIONS_PATH = (
-    Path(__file__).resolve().parent / "prompts" / "collaboration_default.md"
-)
-PLAN_COLLABORATION_INSTRUCTIONS_PATH = (
-    Path(__file__).resolve().parent / "prompts" / "collaboration_plan.md"
-)
 DEFAULT_EFFECTIVE_CONTEXT_WINDOW_PERCENT = 95
 PERMISSIONS_SANDBOX_PROMPTS_PATH = (
     Path(__file__).resolve().parent / "prompts" / "permissions" / "sandbox_mode"
@@ -43,50 +38,56 @@ PERMISSIONS_OPEN_TAG = "<permissions instructions>"
 PERMISSIONS_CLOSE_TAG = "</permissions instructions>"
 SKILLS_OPEN_TAG = "<skills_instructions>"
 SKILLS_CLOSE_TAG = "</skills_instructions>"
-COLLABORATION_MODE_OPEN_TAG = "<collaboration_mode>"
-COLLABORATION_MODE_CLOSE_TAG = "</collaboration_mode>"
 PERSONALITY_PLACEHOLDER = "{{ personality }}"
-SKILLS_GUIDANCE = """- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
+SKILLS_GUIDANCE = """- Discovery: The list above is the skills available in this session (name + description + short path). Skill bodies live on disk at the listed paths after expanding the matching alias from `### Skill roots`.
 - Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
 - Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.
 - How to use a skill (progressive disclosure):
-  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.
-  2) When `SKILL.md` references relative paths (e.g., `scripts/foo.py`), resolve them relative to the skill directory listed above first, and only consider other paths if needed.
-  3) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.
+  1) After deciding to use a skill, the main agent must expand the listed short `path` with the matching alias from `### Skill roots`, then open and read its `SKILL.md` completely before taking task actions. If a read is truncated or paginated, continue until EOF.
+  2) When `SKILL.md` references relative paths (e.g., `scripts/foo.py`), resolve them relative to the directory containing that expanded `SKILL.md` first, and only consider other paths if needed.
+  3) If `SKILL.md` points to extra folders such as `references/`, use its routing instructions to identify the files required for the task. The main agent must read each required instruction or reference file itself before acting on it. Do not delegate reading, summarizing, or interpreting skill instructions to a subagent. Subagents may still perform task work when the selected skill allows it.
   4) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.
   5) If `assets/` or templates exist, reuse them instead of recreating from scratch.
 - Coordination and sequencing:
   - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.
   - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.
 - Context hygiene:
-  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
+  - Progressive disclosure applies to selecting relevant files, not partially reading a selected instruction file. Do not load unrelated references, scripts, or assets.
   - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.
   - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
 - Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue."""
 
 
-@dataclass(frozen=True, )
+@dataclass(
+    frozen=True,
+)
 class ContextConfig:
-    base_instructions: 'typing.Union[str, None]' = None
-    developer_instructions: 'typing.Union[str, None]' = None
-    user_instructions: 'typing.Union[str, None]' = None
-    codex_home_instructions: 'typing.Union[str, None]' = None
-    model_instructions_file: 'typing.Union[Path, None]' = None
-    codex_home: 'typing.Union[Path, None]' = None
-    project_doc_max_bytes: 'typing.Union[int, None]' = None
-    model: 'typing.Union[str, None]' = None
-    model_context_window: 'typing.Union[int, None]' = None
-    model_auto_compact_token_limit: 'typing.Union[int, None]' = None
-    personality: 'typing.Union[str, None]' = None
-    approval_policy: 'typing.Union[str, None]' = None
-    sandbox_mode: 'typing.Union[str, None]' = None
+    base_instructions: "typing.Union[str, None]" = None
+    developer_instructions: "typing.Union[str, None]" = None
+    user_instructions: "typing.Union[str, None]" = None
+    codex_home_instructions: "typing.Union[str, None]" = None
+    model_instructions_file: "typing.Union[Path, None]" = None
+    codex_home: "typing.Union[Path, None]" = None
+    project_doc_max_bytes: "typing.Union[int, None]" = None
+    model: "typing.Union[str, None]" = None
+    model_context_window: "typing.Union[int, None]" = None
+    model_auto_compact_token_limit: "typing.Union[int, None]" = None
+    personality: "typing.Union[str, None]" = None
+    approval_policy: "typing.Union[str, None]" = None
+    sandbox_mode: "typing.Union[str, None]" = None
+    base_instructions_override: "typing.Union[str, None]" = None
+    include_permissions_instructions: "bool" = True
+    include_skills_instructions: "bool" = True
+    network_access: "str" = "enabled"
+    extra_contextual_user_messages: "typing.Tuple[str, ...]" = ()
+    cwd: "typing.Union[str, Path, None]" = None
 
     @classmethod
     def from_codex_config(
         cls,
-        config_path: 'typing.Union[str, Path]',
-        profile: 'typing.Union[str, None]' = None,
-    ) -> 'ContextConfig':
+        config_path: "typing.Union[str, Path]",
+        profile: "typing.Union[str, None]" = None,
+    ) -> "ContextConfig":
         path = Path(config_path)
         data = tomllib.loads(path.read_text(encoding="utf-8"))
         selected = dict(data)
@@ -128,91 +129,46 @@ class ContextConfig:
         )
 
 
-@dataclass(frozen=True, )
+@dataclass(
+    frozen=True,
+)
 class SkillDescriptor:
-    name: 'str'
-    description: 'str'
-    path_to_skill_md: 'Path'
-    scope_rank: 'int'
+    name: "str"
+    description: "str"
+    path_to_skill_md: "Path"
+    scope_rank: "int"
+    root: "Path"
 
 
 class ContextManager:
-    def __init__(
-        self,
-        base_instructions_override: 'typing.Union[str, None]' = None,
-        config: 'typing.Union[ContextConfig, None]' = None,
-        collaboration_mode: 'CollaborationMode' = DEFAULT_COLLABORATION_MODE,
-        collaboration_instructions: 'typing.Union[str, None]' = None,
-        include_collaboration_instructions: 'bool' = False,
-        include_permissions_instructions: 'bool' = True,
-        include_skills_instructions: 'bool' = True,
-        network_access: 'str' = "enabled",
-        extra_contextual_user_messages: 'typing.Iterable[str]' = (),
-        cwd: 'typing.Union[str, Path, None]' = None,
-    ) -> 'None':
-        self.cwd = Path(cwd or Path.cwd()).resolve()
+    def __init__(self, config: "ContextConfig") -> "None":
+        self.cwd = Path(config.cwd or Path.cwd()).resolve()
         self._shell = get_shell_name()
         self._current_date = datetime.now().date().isoformat()
         self._timezone_name = get_timezone_name()
-        self._base_instructions_override = _normalize_text(base_instructions_override)
-        self._config = config or ContextConfig()
-        self._collaboration_mode = collaboration_mode
-        self._collaboration_instructions = (
-            collaboration_instructions
-            if collaboration_instructions is not None
-            else _default_collaboration_instructions(collaboration_mode)
+        self._base_instructions_override = _normalize_text(
+            config.base_instructions_override
         )
-        self._include_collaboration_instructions = include_collaboration_instructions
-        self._include_permissions_instructions = include_permissions_instructions
-        self._include_skills_instructions = include_skills_instructions
-        self._network_access = network_access
+        self._config = config
+        self._include_permissions_instructions = config.include_permissions_instructions
+        self._include_skills_instructions = config.include_skills_instructions
+        self._network_access = config.network_access
         self._extra_contextual_user_messages = tuple(
             text
             for text in (
                 _normalize_text(message)
-                for message in extra_contextual_user_messages
+                for message in config.extra_contextual_user_messages
             )
             if text is not None
         )
         self._default_base_instructions = DEFAULT_BASE_INSTRUCTIONS_PATH.read_text(
             encoding="utf-8"
         )
-        self._workspace_metadata_turn_id: 'typing.Union[str, None]' = None
-        self._workspace_metadata_cache: 'typing.Union[JSONDict, None]' = None
+        self._workspace_metadata_turn_id: "typing.Union[str, None]" = None
+        self._workspace_metadata_cache: "typing.Union[JSONDict, None]" = None
 
-    @classmethod
-    def from_codex_config(
-        cls,
-        config_path: 'typing.Union[str, Path]',
-        profile: 'typing.Union[str, None]' = None,
-        base_instructions_override: 'typing.Union[str, None]' = None,
-        collaboration_mode: 'CollaborationMode' = DEFAULT_COLLABORATION_MODE,
-        include_collaboration_instructions: 'bool' = False,
-        include_permissions_instructions: 'bool' = True,
-        include_skills_instructions: 'bool' = True,
-        network_access: 'str' = "enabled",
-        extra_contextual_user_messages: 'typing.Iterable[str]' = (),
-        cwd: 'typing.Union[str, Path, None]' = None,
-    ) -> 'ContextManager':
-        config = ContextConfig.from_codex_config(config_path, profile)
-        return cls(
-            base_instructions_override=base_instructions_override,
-            config=config,
-            collaboration_mode=collaboration_mode,
-            include_collaboration_instructions=include_collaboration_instructions,
-            include_permissions_instructions=include_permissions_instructions,
-            include_skills_instructions=include_skills_instructions,
-            network_access=network_access,
-            extra_contextual_user_messages=extra_contextual_user_messages,
-            cwd=cwd,
-        )
-
-    @property
-    def collaboration_mode(self) -> 'CollaborationMode':
-        return self._collaboration_mode
-
-    def get_turn_metadata(self, turn_id: 'str') -> 'JSONDict':
-        metadata: 'JSONDict' = {"turn_id": turn_id}
+    def get_turn_metadata(self, turn_id: "str") -> "JSONDict":
+        metadata: "JSONDict" = {"turn_id": turn_id}
         if self._workspace_metadata_turn_id is None:
             self._workspace_metadata_turn_id = turn_id
             self._workspace_metadata_cache = get_workspace_turn_metadata(self.cwd)
@@ -226,12 +182,12 @@ class ContextManager:
 
     def build_prompt(
         self,
-        history: 'typing.Union[typing.Tuple[ConversationItem, ...], typing.List[ConversationItem]]',
-        tools: 'typing.List[ToolSpec]',
-        parallel_tool_calls: 'bool',
-        turn_id: 'typing.Union[str, None]' = None,
-    ) -> 'Prompt':
-        input_items: 'typing.List[ConversationItem]' = []
+        history: "typing.Union[typing.Tuple[ConversationItem, ...], typing.List[ConversationItem]]",
+        tools: "typing.List[ToolSpec]",
+        parallel_tool_calls: "bool",
+        turn_id: "typing.Union[str, None]" = None,
+    ) -> "Prompt":
+        input_items: "typing.List[ConversationItem]" = []
         turn_metadata = self.get_turn_metadata(turn_id) if turn_id is not None else None
 
         developer_message = self._build_developer_message()
@@ -249,7 +205,7 @@ class ContextManager:
             turn_metadata=turn_metadata,
         )
 
-    def resolve_base_instructions(self) -> 'str':
+    def resolve_base_instructions(self) -> "str":
         if self._base_instructions_override is not None:
             return self._base_instructions_override
         if self._config.base_instructions is not None:
@@ -264,47 +220,51 @@ class ContextManager:
             return resolved
         return self._default_base_instructions
 
-    def resolve_model_context_window(self) -> 'typing.Union[int, None]':
-        model_metadata = None
-        model_slug = self._config.model
-        if model_slug is not None:
-            model_metadata = load_models_by_slug().get(model_slug)
-
+    def resolve_model_max_context_window(self) -> "typing.Union[int, None]":
+        metadata = model_metadata(self._config.model)
         context_window = self._config.model_context_window
-        if context_window is None and model_metadata is not None:
-            context_window = _normalize_int(model_metadata.get("context_window"))
+        if context_window is None and metadata is not None:
+            context_window = _normalize_int(metadata.get("context_window"))
+        return context_window
+
+    def resolve_model_context_window(self) -> "typing.Union[int, None]":
+        context_window = self.resolve_model_max_context_window()
         if context_window is None:
             return None
+        metadata = model_metadata(self._config.model)
         effective_percent = None
-        if model_metadata is not None:
+        if metadata is not None:
             effective_percent = _normalize_int(
-                model_metadata.get("effective_context_window_percent")
+                metadata.get("effective_context_window_percent")
             )
         if effective_percent is None:
             effective_percent = DEFAULT_EFFECTIVE_CONTEXT_WINDOW_PERCENT
         return context_window * max(effective_percent, 0) // 100
 
-    def resolve_auto_compact_token_limit(self) -> 'typing.Union[int, None]':
+    def set_model(self, model: "str") -> "None":
+        self._config = replace(self._config, model=model)
+
+    def resolve_auto_compact_token_limit(self) -> "typing.Union[int, None]":
         if self._config.model_auto_compact_token_limit is not None:
             return self._config.model_auto_compact_token_limit
 
         model_slug = self._config.model
         if model_slug is None:
             return None
-        model_metadata = load_models_by_slug().get(model_slug)
-        if model_metadata is None:
+        metadata = model_metadata(model_slug)
+        if metadata is None:
             return None
-        return _normalize_int(model_metadata.get("auto_compact_token_limit"))
+        return _normalize_int(metadata.get("auto_compact_token_limit"))
 
-    def _resolve_model_instructions(self) -> 'typing.Union[str, None]':
+    def _resolve_model_instructions(self) -> "typing.Union[str, None]":
         model_slug = self._config.model
         if model_slug is None:
             return None
-        model_metadata = load_models_by_slug().get(model_slug)
-        if model_metadata is None:
+        metadata = model_metadata(model_slug)
+        if metadata is None:
             return None
 
-        model_messages = model_metadata.get("model_messages")
+        model_messages = metadata.get("model_messages")
         if isinstance(model_messages, dict):
             template = model_messages.get("instructions_template")
             variables = model_messages.get("instructions_variables")
@@ -315,30 +275,23 @@ class ContextManager:
                 )
                 return template.replace(PERSONALITY_PLACEHOLDER, personality_message)
 
-        base_instructions = model_metadata.get("base_instructions")
+        base_instructions = metadata.get("base_instructions")
         if isinstance(base_instructions, str):
             return base_instructions
         return None
 
-    def _build_developer_message(self) -> 'typing.Union[ContextMessage, None]':
-        sections: 'typing.List[str]' = []
-        if self._include_permissions_instructions:
-            permissions = self._build_permissions_instructions()
-            if permissions is not None:
-                sections.append(permissions)
+    def _build_developer_message(self) -> "typing.Union[ContextMessage, None]":
+        sections: "typing.List[str]" = []
         if self._config.developer_instructions is not None:
             sections.append(self._config.developer_instructions)
-        if self._include_collaboration_instructions:
-            collaboration = self._collaboration_instructions.strip()
-            if collaboration:
-                sections.append(
-                    f"{COLLABORATION_MODE_OPEN_TAG}{collaboration}"
-                    f"\n{COLLABORATION_MODE_CLOSE_TAG}"
-                )
         if self._include_skills_instructions:
             skills = self._build_skills_instructions()
             if skills is not None:
                 sections.append(skills)
+        if self._include_permissions_instructions:
+            permissions = self._build_permissions_instructions()
+            if permissions is not None:
+                sections.append(permissions)
         if not sections:
             return None
         return ContextMessage(
@@ -346,7 +299,7 @@ class ContextManager:
             content_items=tuple(_input_text_item(section) for section in sections),
         )
 
-    def _build_permissions_instructions(self) -> 'typing.Union[str, None]':
+    def _build_permissions_instructions(self) -> "typing.Union[str, None]":
         sandbox_mode = self._config.sandbox_mode or "danger-full-access"
         approval_policy = self._config.approval_policy or "never"
         sandbox_prompt_name = sandbox_mode.replace("-", "_")
@@ -354,15 +307,16 @@ class ContextManager:
             PERMISSIONS_SANDBOX_PROMPTS_PATH / f"{sandbox_prompt_name}.md"
         )
         approval_prompt_path = (
-            PERMISSIONS_APPROVAL_PROMPTS_PATH / f"{approval_policy.replace('-', '_')}.md"
+            PERMISSIONS_APPROVAL_PROMPTS_PATH
+            / f"{approval_policy.replace('-', '_')}.md"
         )
         if not sandbox_prompt_path.exists() or not approval_prompt_path.exists():
             return None
 
         sandbox_text = (
-            sandbox_prompt_path.read_text(encoding="utf-8").strip().replace(
-                "{network_access}", self._network_access
-            )
+            sandbox_prompt_path.read_text(encoding="utf-8")
+            .strip()
+            .replace("{network_access}", self._network_access)
         )
         approval_text = approval_prompt_path.read_text(encoding="utf-8").strip()
         return "\n".join(
@@ -374,56 +328,68 @@ class ContextManager:
             ]
         )
 
-    def _build_skills_instructions(self) -> 'typing.Union[str, None]':
+    def _build_skills_instructions(self) -> "typing.Union[str, None]":
         skills = self._discover_skills()
         if not skills:
             return None
 
         lines = [
             "## Skills",
-            "A skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.",
-            "### Available skills",
+            "A skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and a short path that can be expanded into an absolute path using the skill roots table.",
+            "### Skill roots",
         ]
+        roots = {}
         for skill in skills:
-            path_str = skill.path_to_skill_md.as_posix()
-            lines.append(
-                f"- {skill.name}: {skill.description} (file: {path_str})"
+            if skill.root not in roots:
+                alias = "r{0}".format(len(roots))
+                roots[skill.root] = alias
+                lines.append("- `{0}` = `{1}`".format(alias, skill.root.as_posix()))
+        lines.append("### Available skills")
+        for skill in sorted(
+            skills, key=lambda item: (item.scope_rank, item.name, item.path_to_skill_md)
+        ):
+            path_str = "{0}/{1}".format(
+                roots[skill.root],
+                skill.path_to_skill_md.relative_to(skill.root).as_posix(),
             )
-        lines.append("### How to use skills")
-        lines.extend(SKILLS_GUIDANCE.splitlines())
+            lines.append(f"- {skill.name}: {skill.description} (file: {path_str})")
+        metadata = model_metadata(self._config.model)
+        if metadata is None or metadata.get("include_skills_usage_instructions", True):
+            lines.append("### How to use skills")
+            lines.extend(SKILLS_GUIDANCE.splitlines())
         body = "\n".join(lines)
         return f"{SKILLS_OPEN_TAG}\n{body}\n{SKILLS_CLOSE_TAG}"
 
-    def _discover_skills(self) -> 'typing.List[SkillDescriptor]':
+    def _discover_skills(self) -> "typing.List[SkillDescriptor]":
         codex_home = self._config.codex_home
         if codex_home is None:
             return []
 
         user_root = codex_home / "skills"
         system_root = user_root / ".system"
-        discovered: 'typing.List[SkillDescriptor]' = []
-        seen: 'typing.Set[Path]' = set()
+        discovered: "typing.List[SkillDescriptor]" = []
+        seen: "typing.Set[Path]" = set()
 
         user_paths = _discover_skill_files(user_root, excluded_root=system_root)
         system_paths = _discover_skill_files(system_root)
 
-        for scope_rank, paths in ((0, user_paths), (1, system_paths)):
+        for scope_rank, root, paths in (
+            (3, user_root, user_paths),
+            (0, system_root, system_paths),
+        ):
             for path in paths:
                 resolved = path.resolve()
                 if resolved in seen:
                     continue
                 seen.add(resolved)
-                descriptor = _parse_skill_descriptor(path, scope_rank)
+                descriptor = _parse_skill_descriptor(path, scope_rank, root)
                 if descriptor is not None:
                     discovered.append(descriptor)
 
-        return sorted(
-            discovered,
-            key=lambda skill: (skill.scope_rank, skill.name, skill.path_to_skill_md),
-        )
+        return discovered
 
-    def _build_contextual_user_messages(self) -> 'typing.List[ContextMessage]':
-        sections: 'typing.List[str]' = []
+    def _build_contextual_user_messages(self) -> "typing.List[ContextMessage]":
+        sections: "typing.List[str]" = []
         user_instructions = self._merged_user_instructions()
         if user_instructions is not None:
             sections.append(
@@ -443,8 +409,8 @@ class ContextManager:
             )
         ]
 
-    def _merged_user_instructions(self) -> 'typing.Union[str, None]':
-        parts: 'typing.List[str]' = []
+    def _merged_user_instructions(self) -> "typing.Union[str, None]":
+        parts: "typing.List[str]" = []
         if self._config.user_instructions is not None:
             parts.append(self._config.user_instructions)
         if self._config.codex_home_instructions is not None:
@@ -459,8 +425,8 @@ class ContextManager:
 
         return "\n\n".join(parts) or None
 
-    def _read_project_docs(self) -> 'typing.Union[str, None]':
-        docs: 'typing.List[str]' = []
+    def _read_project_docs(self) -> "typing.Union[str, None]":
+        docs: "typing.List[str]" = []
         remaining = self._config.project_doc_max_bytes
         for path in self._discover_project_doc_paths():
             text = path.read_text(encoding="utf-8", errors="replace")
@@ -478,13 +444,16 @@ class ContextManager:
             return None
         return "\n\n".join(docs)
 
-    def _discover_project_doc_paths(self) -> 'typing.List[Path]':
-        seen: 'typing.Set[Path]' = set()
-        discovered: 'typing.List[Path]' = []
+    def _discover_project_doc_paths(self) -> "typing.List[Path]":
+        seen: "typing.Set[Path]" = set()
+        discovered: "typing.List[Path]" = []
 
         search_dirs = self._project_search_dirs()
         for directory in search_dirs:
-            for candidate_name in (LOCAL_PROJECT_DOC_FILENAME, DEFAULT_PROJECT_DOC_FILENAME):
+            for candidate_name in (
+                LOCAL_PROJECT_DOC_FILENAME,
+                DEFAULT_PROJECT_DOC_FILENAME,
+            ):
                 candidate = (directory / candidate_name).resolve()
                 if candidate.exists() and candidate.is_file() and candidate not in seen:
                     discovered.append(candidate)
@@ -492,9 +461,9 @@ class ContextManager:
                     break
         return discovered
 
-    def _project_search_dirs(self) -> 'typing.List[Path]':
+    def _project_search_dirs(self) -> "typing.List[Path]":
         project_root = self._find_project_root()
-        directories: 'typing.List[Path]' = []
+        directories: "typing.List[Path]" = []
         current = self.cwd
         chain = [current]
         while current != project_root and current.parent != current:
@@ -504,48 +473,75 @@ class ContextManager:
         directories.extend(chain)
         return directories
 
-    def _find_project_root(self) -> 'Path':
+    def _find_project_root(self) -> "Path":
         for ancestor in [self.cwd, *self.cwd.parents]:
             if (ancestor / ".git").exists():
                 return ancestor
         return self.cwd
 
-    def _serialize_environment_context(self) -> 'str':
+    def _serialize_environment_context(self) -> "str":
+        cwd = escape(str(self.cwd), {'"': "&quot;", "'": "&apos;"})
         lines = [
             "<environment_context>",
-            f"  <cwd>{self.cwd}</cwd>",
+            f"  <cwd>{cwd}</cwd>",
             f"  <shell>{self._shell}</shell>",
             f"  <current_date>{self._current_date}</current_date>",
             f"  <timezone>{self._timezone_name}</timezone>",
-            "</environment_context>",
         ]
+        sandbox_mode = self._config.sandbox_mode or "danger-full-access"
+        if sandbox_mode == "danger-full-access":
+            permissions = (
+                '<permission_profile type="disabled"><file_system type="unrestricted" />'
+                "</permission_profile>"
+            )
+        elif sandbox_mode in {"read-only", "workspace-write"}:
+            entries = ['<entry access="read"><special>:root</special></entry>']
+            if sandbox_mode == "workspace-write":
+                entries.extend(
+                    [
+                        '<entry access="write"><path>{0}</path></entry>'.format(cwd),
+                        '<entry access="write"><special>:slash_tmp</special></entry>',
+                        '<entry access="write"><special>:tmpdir</special></entry>',
+                    ]
+                )
+                entries.extend(
+                    '<entry access="read"><path>{0}</path></entry>'.format(
+                        escape(str(self.cwd / name), {'"': "&quot;", "'": "&apos;"})
+                    )
+                    for name in (".git", ".agents", ".codex")
+                )
+            permissions = (
+                '<permission_profile type="managed"><file_system type="restricted">'
+                "{0}</file_system></permission_profile>".format("".join(entries))
+            )
+        else:
+            raise ValueError("unsupported sandbox mode: {0}".format(sandbox_mode))
+        lines.append(
+            "  <filesystem><workspace_roots><root>{0}</root></workspace_roots>"
+            "{1}</filesystem>".format(cwd, permissions)
+        )
+        lines.append("</environment_context>")
         return "\n".join(lines)
 
 
-def _input_text_item(text: 'str') -> 'JSONDict':
+def _input_text_item(text: "str") -> "JSONDict":
     return {"type": "input_text", "text": text}
 
 
-def _normalize_text(value) -> 'typing.Union[str, None]':
+def _normalize_text(value) -> "typing.Union[str, None]":
     if value is None:
         return None
     text = str(value).strip()
     return text or None
 
 
-def _normalize_int(value) -> 'typing.Union[int, None]':
+def _normalize_int(value) -> "typing.Union[int, None]":
     if value is None:
         return None
     return int(value)
 
 
-def _default_collaboration_instructions(mode: 'CollaborationMode') -> 'str':
-    if mode == "plan":
-        return PLAN_COLLABORATION_INSTRUCTIONS_PATH.read_text(encoding="utf-8")
-    return DEFAULT_COLLABORATION_INSTRUCTIONS_PATH.read_text(encoding="utf-8")
-
-
-def _read_first_instruction_file(base: 'Path') -> 'typing.Union[str, None]':
+def _read_first_instruction_file(base: "Path") -> "typing.Union[str, None]":
     for candidate_name in (LOCAL_PROJECT_DOC_FILENAME, DEFAULT_PROJECT_DOC_FILENAME):
         candidate = base / candidate_name
         try:
@@ -558,7 +554,9 @@ def _read_first_instruction_file(base: 'Path') -> 'typing.Union[str, None]':
     return None
 
 
-def _resolve_personality_message(variables, personality: 'typing.Union[str, None]') -> 'str':
+def _resolve_personality_message(
+    variables, personality: "typing.Union[str, None]"
+) -> "str":
     if not isinstance(variables, dict):
         return ""
     normalized = (personality or "").strip().lower()
@@ -577,22 +575,30 @@ def _resolve_personality_message(variables, personality: 'typing.Union[str, None
 
 
 def _discover_skill_files(
-    root: 'Path',
-    excluded_root: 'typing.Union[Path, None]' = None,
-) -> 'typing.List[Path]':
+    root: "Path",
+    excluded_root: "typing.Union[Path, None]" = None,
+) -> "typing.List[Path]":
     if not root.exists() or not root.is_dir():
         return []
-    excluded = excluded_root.resolve() if excluded_root is not None and excluded_root.exists() else None
-    paths: 'typing.List[Path]' = []
+    excluded = (
+        excluded_root.resolve()
+        if excluded_root is not None and excluded_root.exists()
+        else None
+    )
+    paths: "typing.List[Path]" = []
     for path in root.glob("**/SKILL.md"):
         resolved = path.resolve()
-        if excluded is not None and (resolved == excluded or excluded in resolved.parents):
+        if excluded is not None and (
+            resolved == excluded or excluded in resolved.parents
+        ):
             continue
         paths.append(path)
     return sorted(paths)
 
 
-def _parse_skill_descriptor(path: 'Path', scope_rank: 'int') -> 'typing.Union[SkillDescriptor, None]':
+def _parse_skill_descriptor(
+    path: "Path", scope_rank: "int", root: "Path"
+) -> "typing.Union[SkillDescriptor, None]":
     text = path.read_text(encoding="utf-8", errors="replace")
     if not text.startswith("---\n"):
         return None
@@ -601,25 +607,29 @@ def _parse_skill_descriptor(path: 'Path', scope_rank: 'int') -> 'typing.Union[Sk
     if end_index == -1:
         return None
     frontmatter = text[4:end_index]
-    fields: 'typing.Dict[str, str]' = {}
-    for line in frontmatter.splitlines():
-        if ":" not in line:
-            continue
-        key, _, raw_value = line.partition(":")
-        fields[key.strip()] = _strip_yaml_string(raw_value.strip())
+    fields = yaml.safe_load(frontmatter)
+    if not isinstance(fields, dict):
+        return None
     name = fields.get("name")
     description = fields.get("description")
-    if not name or not description:
+    if not isinstance(name, str) or not isinstance(description, str):
+        return None
+    if not name.strip() or not description.strip():
         return None
+    metadata_path = path.parent / "agents" / "openai.yaml"
+    if metadata_path.is_file():
+        metadata = yaml.safe_load(
+            metadata_path.read_text(encoding="utf-8", errors="replace")
+        )
+        if (
+            metadata is not None
+            and metadata.get("policy", {}).get("allow_implicit_invocation") is False
+        ):
+            return None
     return SkillDescriptor(
-        name=name,
-        description=description,
-        path_to_skill_md=path.resolve(),
+        name=name.strip(),
+        description=description.strip(),
+        path_to_skill_md=root.resolve() / path.relative_to(root),
         scope_rank=scope_rank,
+        root=root.resolve(),
     )
-
-
-def _strip_yaml_string(value: 'str') -> 'str':
-    if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
-        return value[1:-1]
-    return value