ouroboros-ai 0.26.5.dev7__tar.gz → 0.26.5.dev9__tar.gz

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.5.dev7
+Version: 0.26.5.dev9
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.26.5.dev7'
-__version_tuple__ = version_tuple = (0, 26, 5, 'dev7')
+__version__ = version = '0.26.5.dev9'
+__version_tuple__ = version_tuple = (0, 26, 5, 'dev9')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/bigbang/pm_completion.py

@@ -49,8 +49,7 @@ def build_pm_completion_summary(
         lines.append(f"Ambiguity score: {ambiguity_score:.2f}")
 
     lines.append("")
-    lines.append(f"Deferred items: {deferred_count}")
-    lines.append(f"Decide-later items: {decide_later_count}")
+    lines.append(f"Decide-later items: {deferred_count + decide_later_count}")
 
     if decide_later_summary:
         lines.append("")

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/bigbang/pm_document.py

@@ -130,8 +130,8 @@ def generate_pm_markdown(seed: PMSeed) -> str:
             lines.append(f"- {assumption}")
         lines.append("")
 
-    # Decide Later (merged: deferred + decide-later)
-    all_decide_later = list(seed.deferred_items or []) + list(seed.decide_later_items or [])
+    # Decide Later
+    all_decide_later = list(seed.decide_later_items or [])
     if all_decide_later:
         lines.append("## Decide Later")
         lines.append("")
@@ -439,7 +439,7 @@ class PMDocumentGenerator:
                 parts.append(f"- {a}")
             parts.append("")
 
-        all_decide_later = list(seed.deferred_items or []) + list(seed.decide_later_items or [])
+        all_decide_later = list(seed.decide_later_items or [])
         if all_decide_later:
             parts.append("**Decide Later:**")
             for item in all_decide_later:

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/bigbang/pm_interview.py

@@ -664,16 +664,20 @@ class PMInterviewEngine:
         return await self.inner.complete_interview(state)
 
     def get_decide_later_summary(self) -> list[str]:
-        """Return the list of decide-later items collected during the interview.
+        """Return the combined list of deferred + decide-later items.
 
-        These are the original question texts for questions classified as
-        DECIDE_LATER — premature or unknowable at the PM stage. Shown to
-        the PM at interview end so they have a clear record of open items.
+        Merges runtime ``deferred_items`` (technical questions deferred to
+        dev phase) with ``decide_later_items`` (premature/unknowable questions)
+        into one canonical list for display and artifact generation.
 
         Returns:
             List of original question text strings. Empty if none were deferred.
         """
-        return list(self.decide_later_items)
+        combined = list(self.decide_later_items)
+        for item in self.deferred_items:
+            if item not in combined:
+                combined.append(item)
+        return combined
 
     def format_decide_later_summary(self) -> str:
         """Format decide-later items as a human-readable summary string.
@@ -730,7 +734,7 @@ class PMInterviewEngine:
     def restore_meta(self, meta: dict[str, Any]) -> None:
         """Restore PM-specific metadata into this engine from a loaded dict.
 
-        Sets ``deferred_items``, ``decide_later_items``, ``codebase_context``,
+        Sets ``decide_later_items``, ``codebase_context``,
         ``pending_reframe`` (via ``_reframe_map``), and syncs the classifier's
         ``codebase_context`` so that subsequent classification calls use the
         brownfield context.
@@ -740,12 +744,19 @@ class PMInterviewEngine:
 
         Args:
             meta: Dictionary previously persisted as ``pm_meta_{session_id}.json``.
-                  Expected keys: ``deferred_items``, ``decide_later_items``,
+                  Expected keys: ``decide_later_items``,
                   ``codebase_context``, ``pending_reframe``.
+                  Legacy key ``deferred_items`` is merged into
+                  ``decide_later_items`` for backward compatibility.
         """
-        # Full state reset — clear all session-scoped fields before restoring
-        self.deferred_items = list(meta.get("deferred_items", []))
+        # Full state reset — clear all session-scoped fields before restoring.
+        # Legacy metadata may still have separate deferred_items; merge them
+        # into decide_later_items (canonical field since v0.25).
         self.decide_later_items = list(meta.get("decide_later_items", []))
+        for item in meta.get("deferred_items", []):
+            if item not in self.decide_later_items:
+                self.decide_later_items.append(item)
+        self.deferred_items = []
         self.codebase_context = meta.get("codebase_context", "") or ""
         self.classifications = []  # Reset before restoring
         self._reframe_map = {}  # Reset before restoring
@@ -803,8 +814,8 @@ class PMInterviewEngine:
         new items were added during classification.  Returns a dict with:
             new_deferred: list of newly deferred question texts
             new_decide_later: list of newly decide-later question texts
-            deferred_count: total deferred items
-            decide_later_count: total decide-later items
+            deferred_count: always 0 (deprecated; merged into decide_later_count)
+            decide_later_count: combined total of deferred + decide-later items
 
         Args:
             deferred_len_before: Length of deferred_items before the call.
@@ -819,8 +830,8 @@ class PMInterviewEngine:
         return {
             "new_deferred": list(new_deferred),
             "new_decide_later": list(new_decide_later),
-            "deferred_count": len(self.deferred_items),
-            "decide_later_count": len(self.decide_later_items),
+            "deferred_count": 0,
+            "decide_later_count": len(self.deferred_items) + len(self.decide_later_items),
         }
 
     def get_pending_reframe(self) -> dict[str, str] | None:
@@ -1009,7 +1020,7 @@ class PMInterviewEngine:
                 pm_id=seed.pm_id,
                 product_name=seed.product_name,
                 story_count=len(seed.user_stories),
-                deferred_count=len(seed.deferred_items),
+                decide_later_count=len(seed.decide_later_items),
             )
             return Result.ok(seed)
         except (ValueError, KeyError, json.JSONDecodeError) as e:
@@ -1115,22 +1126,21 @@ class PMInterviewEngine:
 ---
 """
 
-        if self.deferred_items:
-            deferred_text = "\n".join(f"- {item}" for item in self.deferred_items)
-            prompt += f"""
-
-The following technical questions were deferred during the interview.
-Include them in "deferred_items":
-{deferred_text}
-"""
+        # Combine deferred and decide-later items under one canonical key
+        # so the LLM output schema matches PMSeed (which only has
+        # decide_later_items).
+        all_decide_later: list[str] = list(self.deferred_items)
+        for item in self.decide_later_items:
+            if item not in all_decide_later:
+                all_decide_later.append(item)
 
-        if self.decide_later_items:
-            decide_later_text = "\n".join(f"- {item}" for item in self.decide_later_items)
+        if all_decide_later:
+            items_text = "\n".join(f"- {item}" for item in all_decide_later)
             prompt += f"""
 
-The following questions were identified as premature or unknowable at this stage.
+The following questions were deferred or identified as premature during the interview.
 Include them as original question text in "decide_later_items":
-{decide_later_text}
+{items_text}
 """
 
         # Note: brownfield codebase context is already included in
@@ -1185,11 +1195,15 @@ Include them as original question text in "decide_later_items":
         # The extraction prompt includes raw items as context so the LLM may
         # already emit them, but engine-tracked items are authoritative and
         # must survive even if the extractor omits them.
-        all_deferred = list(data.get("deferred_items", []))
-        for item in self.deferred_items:
-            if item not in all_deferred:
-                all_deferred.append(item)
+        # Both deferred_items (from LLM) and engine.deferred_items are merged
+        # into decide_later_items on the PMSeed.
         all_decide_later = list(data.get("decide_later_items", []))
+        for item in data.get("deferred_items", []):
+            if item not in all_decide_later:
+                all_decide_later.append(item)
+        for item in self.deferred_items:
+            if item not in all_decide_later:
+                all_decide_later.append(item)
         for item in self.decide_later_items:
             if item not in all_decide_later:
                 all_decide_later.append(item)
@@ -1204,7 +1218,6 @@ Include them as original question text in "decide_later_items":
             user_stories=stories,
             constraints=tuple(data.get("constraints", [])),
             success_criteria=tuple(data.get("success_criteria", [])),
-            deferred_items=tuple(all_deferred),
             decide_later_items=tuple(all_decide_later),
             assumptions=tuple(data.get("assumptions", [])),
             interview_id=interview_id,

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/bigbang/pm_seed.py

@@ -1,7 +1,7 @@
 """PM Seed — immutable specification for product requirements.
 
 A PMSeed captures PM-level product requirements: goals, user stories,
-constraints, success criteria, and deferred items. It is produced by the
+constraints, success criteria, and decide-later items. It is produced by the
 PM interview flow and can be serialized to YAML for handoff to a
 development interview via initial_context.
 """
@@ -10,12 +10,9 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING
+from typing import Any
 from uuid import uuid4
 
-if TYPE_CHECKING:
-    from ouroboros.core.seed import Seed
-
 
 @dataclass(frozen=True, slots=True)
 class UserStory:
@@ -49,16 +46,18 @@ class PMSeed:
         user_stories: Captured user stories.
         constraints: Product constraints (budget, timeline, compliance, etc.).
         success_criteria: Measurable success criteria.
-        deferred_items: Items explicitly deferred to later phases.
         assumptions: Assumptions made during the interview.
+        decide_later_items: Questions deferred or identified as premature.
         interview_id: Reference to the source PM interview.
         codebase_context: Shared codebase exploration context (brownfield).
         brownfield_repos: Registered brownfield repositories.
-        seed: Optional reference to the generated dev Seed.
-        deferred_decisions: Decisions deferred during PM interview
-            (architectural, technical, or strategic choices postponed).
-        referenced_repos: Repos referenced during PM interview for context.
         created_at: When this seed was generated.
+
+    Deprecated fields (kept for backward compatibility, merged on init):
+        deferred_items: Merged into decide_later_items.
+        deferred_decisions: Merged into decide_later_items.
+        seed: Preserved for legacy round-trip; not used by new code.
+        referenced_repos: Merged into brownfield_repos.
     """
 
     pm_id: str = field(default_factory=lambda: f"pm_seed_{uuid4().hex[:12]}")
@@ -67,45 +66,67 @@ class PMSeed:
     user_stories: tuple[UserStory, ...] = ()
     constraints: tuple[str, ...] = ()
     success_criteria: tuple[str, ...] = ()
-    deferred_items: tuple[str, ...] = ()
     decide_later_items: tuple[str, ...] = ()
-    """Original question text for items classified as decide-later.
+    """Items deferred or identified as premature during the PM interview.
 
-    These are questions that were premature or unknowable during the PM
-    interview. Stored as the original question text so they can be surfaced
-    later when enough context exists to answer them.
+    Includes both feature-level deferrals and questions that were premature
+    or unknowable. Stored as the original question/item text so they can be
+    surfaced later when enough context exists to address them.
     """
     assumptions: tuple[str, ...] = ()
     interview_id: str = ""
     codebase_context: str = ""
     brownfield_repos: tuple[dict[str, str], ...] = ()
-    seed: Seed | None = None
-    """Optional reference to the generated dev Seed.
+    created_at: str = field(
+        default_factory=lambda: datetime.now(UTC).isoformat(),
+    )
 
-    Populated after the dev interview produces a Seed from the PM
-    requirements. None while in the PM-only phase.
-    """
+    # ── Deprecated fields (backward compat, merged via __post_init__) ──
+    deferred_items: tuple[str, ...] = ()
     deferred_decisions: tuple[str, ...] = ()
-    """Decisions deferred during the PM interview.
+    seed: Any = ""
+    """Legacy dev seed reference. Accepts str, dict, or Seed-like objects.
 
-    These are architectural, technical, or strategic decisions that the PM
-    chose to postpone. Distinct from decide_later_items (which are questions
-    the classifier auto-deferred) and deferred_items (feature-level deferrals).
+    Preserved on round-trip: if the value has a ``to_dict()`` method it is
+    serialized via that; dicts and strings are passed through as-is.
     """
     referenced_repos: tuple[dict[str, str], ...] = ()
-    """Repos referenced during the PM interview for brownfield context.
 
-    Each entry is a dict with keys: path, name, desc. This captures which
-    repositories were consulted during codebase exploration, providing
-    traceability for the PM requirements.
-    """
-    created_at: str = field(
-        default_factory=lambda: datetime.now(UTC).isoformat(),
-    )
+    def __post_init__(self) -> None:
+        """Merge deprecated fields into their canonical counterparts."""
+        # Merge deferred_items and deferred_decisions → decide_later_items
+        if self.deferred_items or self.deferred_decisions:
+            combined = list(self.decide_later_items)
+            for item in self.deferred_items:
+                if item not in combined:
+                    combined.append(item)
+            for item in self.deferred_decisions:
+                if item not in combined:
+                    combined.append(item)
+            object.__setattr__(self, "decide_later_items", tuple(combined))
+            object.__setattr__(self, "deferred_items", ())
+            object.__setattr__(self, "deferred_decisions", ())
+
+        # Merge referenced_repos → brownfield_repos (additive, not replacement)
+        if self.referenced_repos:
+            if self.brownfield_repos:
+                merged = list(self.brownfield_repos)
+                existing_paths = {r.get("path") for r in merged}
+                for r in self.referenced_repos:
+                    if r.get("path") not in existing_paths:
+                        merged.append(r)
+                object.__setattr__(self, "brownfield_repos", tuple(merged))
+            else:
+                object.__setattr__(self, "brownfield_repos", self.referenced_repos)
+            object.__setattr__(self, "referenced_repos", ())
 
     def to_dict(self) -> dict:
-        """Convert to a plain dictionary for YAML serialization."""
-        return {
+        """Convert to a plain dictionary for YAML serialization.
+
+        Preserves legacy ``seed`` field when non-empty so that older
+        PM seed artifacts survive a load/save round-trip without data loss.
+        """
+        d: dict = {
             "pm_id": self.pm_id,
             "product_name": self.product_name,
             "goal": self.goal,
@@ -115,23 +136,32 @@ class PMSeed:
             ],
             "constraints": list(self.constraints),
             "success_criteria": list(self.success_criteria),
-            "deferred_items": list(self.deferred_items),
             "decide_later_items": list(self.decide_later_items),
             "assumptions": list(self.assumptions),
             "interview_id": self.interview_id,
             "codebase_context": self.codebase_context,
             "brownfield_repos": [dict(r) for r in self.brownfield_repos],
-            "seed": self.seed.to_dict() if self.seed is not None else None,
-            "deferred_decisions": list(self.deferred_decisions),
-            "referenced_repos": [dict(r) for r in self.referenced_repos],
             "created_at": self.created_at,
         }
+        # Preserve legacy seed for round-trip safety.
+        # Handles Seed objects (via to_dict()), raw dicts, and strings.
+        # Explicit None check: falsey-but-present values ({}, 0) are preserved.
+        if self.seed is not None and self.seed != "":
+            if hasattr(self.seed, "to_dict"):
+                d["seed"] = self.seed.to_dict()
+            else:
+                d["seed"] = self.seed
+        return d
 
     @classmethod
     def from_dict(cls, data: dict) -> PMSeed:
-        """Create a PMSeed from a dictionary (e.g., loaded from YAML)."""
-        from ouroboros.core.seed import Seed
+        """Create a PMSeed from a dictionary (e.g., loaded from YAML).
 
+        Handles backward compatibility: legacy fields ``deferred_items``,
+        ``deferred_decisions``, ``seed``, and ``referenced_repos`` are
+        accepted and migrated to their canonical counterparts via
+        ``__post_init__``.
+        """
         stories = tuple(
             UserStory(
                 persona=s.get("persona", ""),
@@ -141,9 +171,29 @@ class PMSeed:
             for s in data.get("user_stories", [])
         )
 
-        # Deserialize seed if present
-        seed_data = data.get("seed")
-        seed = Seed.from_dict(seed_data) if seed_data is not None else None
+        # Backward compat: merge legacy deferred_items / deferred_decisions
+        # into decide_later_items (canonical field since v0.25).
+        decide_later = list(data.get("decide_later_items", []))
+        for key in ("deferred_items", "deferred_decisions"):
+            for item in data.get(key, []):
+                if item not in decide_later:
+                    decide_later.append(item)
+
+        # Backward compat: merge referenced_repos into brownfield_repos (additive)
+        brownfield_raw = list(data.get("brownfield_repos", []))
+        for r in data.get("referenced_repos", []):
+            if r not in brownfield_raw:
+                brownfield_raw.append(r)
+
+        # Rehydrate legacy seed: dict → Seed object if possible
+        seed_raw = data.get("seed", "")
+        if isinstance(seed_raw, dict):
+            try:
+                from ouroboros.core.seed import Seed as DevSeed
+
+                seed_raw = DevSeed.from_dict(seed_raw)
+            except Exception:
+                pass  # Preserve as raw dict if Seed import/parse fails
 
         return cls(
             pm_id=data.get("pm_id", ""),
@@ -152,16 +202,13 @@ class PMSeed:
             user_stories=stories,
             constraints=tuple(data.get("constraints", [])),
             success_criteria=tuple(data.get("success_criteria", [])),
-            deferred_items=tuple(data.get("deferred_items", [])),
-            decide_later_items=tuple(data.get("decide_later_items", [])),
+            decide_later_items=tuple(decide_later),
             assumptions=tuple(data.get("assumptions", [])),
             interview_id=data.get("interview_id", ""),
             codebase_context=data.get("codebase_context", ""),
-            brownfield_repos=tuple(dict(r) for r in data.get("brownfield_repos", [])),
-            seed=seed,
-            deferred_decisions=tuple(data.get("deferred_decisions", [])),
-            referenced_repos=tuple(dict(r) for r in data.get("referenced_repos", [])),
+            brownfield_repos=tuple(dict(r) for r in brownfield_raw),
             created_at=data.get("created_at", ""),
+            seed=seed_raw,
         )
 
     def to_initial_context(self) -> str:

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/cli/commands/pm.py

@@ -355,9 +355,15 @@ def _save_cli_pm_meta(session_id: str, engine: Any) -> None:
             "original": engine._reframe_map[reframed],
         }
 
+    # Collapse deferred_items into decide_later_items (canonical schema)
+    combined_decide_later = list(engine.decide_later_items)
+    for item in engine.deferred_items:
+        if item not in combined_decide_later:
+            combined_decide_later.append(item)
+
     meta = {
-        "deferred_items": list(engine.deferred_items),
-        "decide_later_items": list(engine.decide_later_items),
+        "deferred_items": [],  # Deprecated: merged into decide_later_items
+        "decide_later_items": combined_decide_later,
         "codebase_context": engine.codebase_context,
         "pending_reframe": pending_reframe,
         "cwd": "",
@@ -589,8 +595,8 @@ async def _run_pm_interview(
                 session_id=state.interview_id,
                 completion=completion,
                 stored_ambiguity_score=state.ambiguity_score,
-                deferred_count=len(engine.deferred_items),
-                decide_later_count=len(engine.decide_later_items),
+                deferred_count=0,
+                decide_later_count=len(engine.deferred_items) + len(engine.decide_later_items),
                 decide_later_summary=decide_later_summary,
             )
             console.print(f"\n[bold green]{summary_text}[/]\n")
@@ -660,8 +666,8 @@ async def _run_pm_interview(
                 session_id=state.interview_id,
                 completion=completion,
                 stored_ambiguity_score=state.ambiguity_score,
-                deferred_count=len(engine.deferred_items),
-                decide_later_count=len(engine.decide_later_items),
+                deferred_count=0,
+                decide_later_count=len(engine.deferred_items) + len(engine.decide_later_items),
                 decide_later_summary=decide_later_summary,
             )
             console.print(f"\n[bold green]{summary_text}[/]\n")

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/mcp/tools/pm_handler.py

@@ -89,9 +89,16 @@ def _save_pm_meta(
     if engine is not None:
         pending_reframe = engine.get_pending_reframe()
 
+        # Collapse deferred_items into decide_later_items so the persisted
+        # metadata uses the same canonical schema as PMSeed.
+        combined_decide_later = list(engine.decide_later_items)
+        for item in engine.deferred_items:
+            if item not in combined_decide_later:
+                combined_decide_later.append(item)
+
         meta: dict[str, Any] = {
-            "deferred_items": list(engine.deferred_items),
-            "decide_later_items": list(engine.decide_later_items),
+            "deferred_items": [],  # Deprecated: merged into decide_later_items
+            "decide_later_items": combined_decide_later,
             "codebase_context": engine.codebase_context,
             "pending_reframe": pending_reframe,
             "cwd": cwd,
@@ -874,8 +881,9 @@ class PMInterviewHandler:
                         "pending_reframe": pending_reframe,
                         "new_deferred": [],
                         "new_decide_later": [],
-                        "deferred_count": len(engine.deferred_items),
-                        "decide_later_count": len(engine.decide_later_items),
+                        "deferred_count": 0,
+                        "decide_later_count": len(engine.deferred_items)
+                        + len(engine.decide_later_items),
                     },
                 )
             )
@@ -1028,8 +1036,8 @@ class PMInterviewHandler:
                 session_id=session_id,
                 completion=completion,
                 stored_ambiguity_score=getattr(state, "ambiguity_score", None),
-                deferred_count=len(engine.deferred_items),
-                decide_later_count=len(engine.decide_later_items),
+                deferred_count=0,
+                decide_later_count=len(engine.deferred_items) + len(engine.decide_later_items),
                 decide_later_summary=decide_later_summary,
             )
             summary_text += f"\n\nPM document: {pm_path}\nSeed: {seed_path}"
@@ -1042,8 +1050,8 @@ class PMInterviewHandler:
                 "deferred_this_round": [],
                 "decide_later_this_round": [],
                 **completion,
-                "deferred_count": len(engine.deferred_items),
-                "decide_later_count": len(engine.decide_later_items),
+                "deferred_count": 0,
+                "decide_later_count": len(engine.deferred_items) + len(engine.decide_later_items),
                 "seed_path": str(seed_path),
                 "pm_path": str(pm_path),
             }
@@ -1273,7 +1281,6 @@ class PMInterviewHandler:
                             f"PM document: {pm_path}\n\n"
                             "This PM seed is a handoff artifact for the dev interview, "
                             "not the runnable Seed.\n"
-                            f"Deferred items: {len(seed.deferred_items)}\n"
                             f"Decide-later items: {len(seed.decide_later_items)}\n"
                             f"Next: {next_step}"
                         ),

{ouroboros_ai-0.26.5.dev7 → ouroboros_ai-0.26.5.dev9}/src/ouroboros/providers/claude_code_adapter.py

@@ -89,9 +89,11 @@ class ClaudeCodeAdapter:
         self,
         permission_mode: str = "default",
         cli_path: str | Path | None = None,
+        cwd: str | Path | None = None,
         allowed_tools: list[str] | None = None,
         max_turns: int = 1,
         on_message: Callable[[str, str], None] | None = None,
+        timeout: float | None = None,
     ) -> None:
         """Initialize Claude Code adapter.
 
@@ -102,23 +104,34 @@ class ClaudeCodeAdapter:
             cli_path: Path to the Claude CLI binary. If not provided,
                 checks OUROBOROS_CLI_PATH env var, then falls back to
                 SDK's bundled CLI.
-            allowed_tools: List of tools to allow. None means no tools.
-                For interview mode with codebase access, use ["Read", "Glob", "Grep"].
+            cwd: Working directory passed to the Claude Agent SDK.
+            allowed_tools: Explicit allow-list for Claude tools. ``None`` keeps
+                the default permissive mode while still blocking dangerous tools.
+                Use ``[]`` to forbid all Claude tools.
             max_turns: Maximum turns for the conversation. Default 1 for
                 single-response completions (most MCP use cases).
             on_message: Callback for streaming messages. Called with (type, content):
                 - ("thinking", "content") for agent reasoning
                 - ("tool", "tool_name") for tool usage
+            timeout: Optional application-level timeout in seconds for a
+                single completion request. When set, aborts before outer
+                transport timeouts and returns a ProviderError.
         """
         self._permission_mode: str = permission_mode
         self._cli_path: Path | None = self._resolve_cli_path(cli_path)
-        self._allowed_tools: list[str] = allowed_tools or []
+        self._cwd: str = str(Path(cwd).expanduser()) if cwd is not None else os.getcwd()
+        self._allowed_tools: list[str] | None = (
+            list(allowed_tools) if allowed_tools is not None else None
+        )
         self._max_turns: int = max_turns
         self._on_message: Callable[[str, str], None] | None = on_message
+        self._timeout: float | None = timeout if timeout and timeout > 0 else None
         log.info(
             "claude_code_adapter.initialized",
             permission_mode=permission_mode,
             cli_path=str(self._cli_path) if self._cli_path else None,
+            cwd=self._cwd,
+            timeout_seconds=self._timeout,
         )
 
     def _resolve_cli_path(self, cli_path: str | Path | None) -> Path | None:
@@ -260,9 +273,15 @@ class ClaudeCodeAdapter:
 
         for attempt in range(_MAX_RETRIES):
             try:
-                result = await self._execute_single_request(
-                    prompt, config, system_prompt=system_prompt
-                )
+                if self._timeout is None:
+                    result = await self._execute_single_request(
+                        prompt, config, system_prompt=system_prompt
+                    )
+                else:
+                    async with asyncio.timeout(self._timeout):
+                        result = await self._execute_single_request(
+                            prompt, config, system_prompt=system_prompt
+                        )
 
                 if result.is_ok:
                     if attempt > 0:
@@ -290,6 +309,22 @@ class ClaudeCodeAdapter:
                 # Non-retryable error
                 return result
 
+            except TimeoutError:
+                log.warning(
+                    "claude_code_adapter.request_timed_out",
+                    timeout_seconds=self._timeout,
+                    attempt=attempt + 1,
+                )
+                return Result.err(
+                    ProviderError(
+                        message=f"Claude Code request timed out after {self._timeout:.1f}s",
+                        details={
+                            "timed_out": True,
+                            "timeout_seconds": self._timeout,
+                            "attempt": attempt + 1,
+                        },
+                    )
+                )
             except Exception as e:
                 error_str = str(e)
                 error_type = type(e).__name__
@@ -405,16 +440,17 @@ class ClaudeCodeAdapter:
             log.debug("claude_code_adapter.stderr", line=line[:200])
 
         options_kwargs: dict = {
-            "allowed_tools": self._allowed_tools if self._allowed_tools is not None else [],
             "disallowed_tools": disallowed,
             "max_turns": self._max_turns,
             # Allow MCP and other ~/.claude/ settings to be inherited
             "permission_mode": self._permission_mode,
-            "cwd": os.getcwd(),
+            "cwd": self._cwd,
             "cli_path": self._cli_path,
             "stderr": _stderr_callback,
             "env": env_overrides,
         }
+        if self._allowed_tools is not None:
+            options_kwargs["allowed_tools"] = self._allowed_tools
 
         # Pass model from CompletionConfig if specified
         # "default" is not a valid SDK model — treat it as None (use SDK default)