diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
new file mode 100644
index 00000000000..bb751970237
--- /dev/null
+++ b/.specify/memory/constitution.md
@@ -0,0 +1,51 @@
+# Roo Code Project Constitution
+
+We are building an **AI-Native IDE with Intent–Code Traceability**. All specs, plans, and implementation must align with these principles.
+
+---
+
+## I. Intent–Code Traceability (Non‑negotiable)
+
+- **All agent actions must be traceable to intent IDs.** Every action taken by the AI agent must be linkable to a specific user intent.
+- The **`.orchestration/` directory is the source of truth** for intent definitions, state machine definitions, and traceability metadata. Do not bypass or duplicate it.
+- We implement the **two-stage state machine**: **(1) intent selection** → **(2) execution**. Selection and execution are distinct phases; design and code must reflect this.
+
+---
+
+## II. Hook Middleware Pattern
+
+- We follow the **hook middleware pattern** from the challenge. Agent flows and state transitions go through this pattern; do not introduce ad-hoc or parallel patterns that skip it.
+
+---
+
+## III. TypeScript & Strictness
+
+- We use **TypeScript with strict mode** enabled. No disabling strict checks without documented justification and review.
+- Follow existing patterns in the repo (React in webview-ui, extension APIs in `src/`, shared types in `packages/types`). Prefer project tooling: ESLint, Prettier, pnpm, Turbo.
+
+---
+
+## IV. Settings View & State
+
+**Source:** [AGENTS.md](../AGENTS.md)
+
+- When working on **SettingsView** (or any settings UI that edits extension state), inputs **must** bind to the local **cachedState**, NOT the live `useExtensionState()`.
+- **cachedState** is the buffer for user edits until the user explicitly clicks **Save**. Wiring inputs directly to live state causes **race conditions**. Do not do it.
+
+---
+
+## V. Testing & Documentation
+
+- New or changed behavior should be covered by tests where practical. UI/state changes must respect the Settings View pattern (cachedState → Save) and the two-stage state machine.
+- Update AGENTS.md when introducing new patterns or constraints. Keep README and contributor docs accurate.
+
+---
+
+## VI. Scope & Simplicity
+
+- Prefer small, reviewable changes. Break large features into spec/plan/tasks with clear deliverables.
+- Avoid speculative features; tie work to concrete user or product needs.
+
+---
+
+_This constitution is the source of truth for how we build and maintain Roo Code. Specs and implementation plans must reference it and must not contradict it._
diff --git a/.specify/specs/001-intent-orchestration/spec.md b/.specify/specs/001-intent-orchestration/spec.md
new file mode 100644
index 00000000000..4b13c0ecf78
--- /dev/null
+++ b/.specify/specs/001-intent-orchestration/spec.md
@@ -0,0 +1,76 @@
+# Spec: Intent orchestration and intent–code traceability
+
+**Feature:** 001-intent-orchestration
+**Status:** Draft
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+
+---
+
+## 1. Overview
+
+Introduce an **orchestration layer** so that every AI agent action is tied to a specific user intent. The system uses a **two-stage state machine** (intent selection → execution) and treats **`.orchestration/`** as the source of truth for intents and traceability. This enables an AI-native IDE where “why” (intent) is always traceable to “what” (code/actions).
+
+---
+
+## 2. User stories
+
+| ID | As a… | I want… | So that… |
+| ---- | --------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
+| US-1 | Developer | every agent action to be tied to an intent ID | I can trace code and edits back to the user’s intent |
+| US-2 | Developer | intents and the state machine to live under `.orchestration/` | there is a single source of truth for intent definitions and flow |
+| US-3 | Developer | a clear separation between “choose intent” and “execute intent” | the system is predictable and testable |
+| US-4 | Developer | agent flows to go through the hook middleware pattern | behavior is consistent and extensible |
+
+---
+
+## 3. Functional requirements
+
+- **FR-1** Intent selection phase: the system resolves or selects the user’s intent and assigns an **intent ID** before any execution.
+- **FR-2** Execution phase: agent actions (e.g. edits, runs, tool calls) are executed only after intent selection and must carry the **intent ID** for traceability.
+- **FR-3** `.orchestration/` contains (at least):
+ - Intent definitions (e.g. IDs, names, metadata).
+ - State machine definition (states, transitions: selection → execution).
+ - Traceability metadata linking intent IDs to actions/artifacts where applicable.
+- **FR-4** All agent flows use the **hook middleware pattern**; no bypass paths that skip this pattern.
+- **FR-5** Traceability: given an intent ID, it must be possible to determine which actions or artifacts were produced for that intent (e.g. logs, state, or references).
+
+---
+
+## 4. Acceptance criteria
+
+- [ ] Intent selection and execution are implemented as distinct phases (two-stage state machine).
+- [ ] Every agent action that affects code or UX is associated with an intent ID.
+- [ ] `.orchestration/` exists and is the only source of truth for intent definitions and state machine definition.
+- [ ] Agent flows use the hook middleware pattern; no ad-hoc paths around it.
+- [ ] TypeScript strict mode remains enabled; new code follows existing repo patterns.
+- [ ] AGENTS.md (and constitution) are not violated (e.g. Settings View still uses cachedState).
+
+---
+
+## 5. Constraints (from constitution)
+
+- TypeScript strict mode required.
+- Hook middleware pattern required for agent flows.
+- `.orchestration/` is source of truth; do not duplicate or bypass.
+- Two-stage state machine: intent selection → execution only.
+
+---
+
+## 6. Out of scope for this spec
+
+- Detailed UI for “intent picker” or intent selection UX (can be a later spec).
+- Migration of all existing agent entry points in one go (can be incremental).
+- Specific storage format inside `.orchestration/` (e.g. JSON vs YAML) — to be decided in plan.
+
+---
+
+## 7. Review & acceptance checklist
+
+- [ ] No [NEEDS CLARIFICATION] markers remain.
+- [ ] Requirements are testable and unambiguous.
+- [ ] Success criteria are measurable.
+- [ ] Aligned with constitution (Articles I–VI).
+
+---
+
+_Next step: run `/speckit.clarify` to resolve ambiguities, or `/speckit.plan` to produce the technical implementation plan._
diff --git a/.specify/specs/001-intent-orchestration/tasks.md b/.specify/specs/001-intent-orchestration/tasks.md
new file mode 100644
index 00000000000..3dc7c03f927
--- /dev/null
+++ b/.specify/specs/001-intent-orchestration/tasks.md
@@ -0,0 +1,42 @@
+# Tasks: 001-intent-orchestration
+
+**Spec:** [spec.md](./spec.md)
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+
+Tasks derived from functional requirements and acceptance criteria. Implement in dependency order; 002-intent-system tasks implement the concrete tool and schema.
+
+---
+
+## 1. Orchestration foundation
+
+| ID | Task | Source | Status |
+| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ |
+| 001-1 | Create `.orchestration/` directory layout (e.g. `active_intents.yaml`, optional `state machine` or metadata file) and document as source of truth | FR-3, AC | ☐ |
+| 001-2 | Implement intent selection phase: resolve/select user intent and assign intent ID before any execution | FR-1 | ☐ |
+| 001-3 | Implement execution phase: allow agent actions only after intent selection; ensure actions carry intent ID for traceability | FR-2 | ☐ |
+| 001-4 | Define state machine (states, transitions: selection → execution) and store under `.orchestration/` | FR-3 | ☐ |
+| 001-5 | Ensure all agent flows use hook middleware; audit and remove any bypass paths | FR-4, AC | ☐ |
+| 001-6 | Implement traceability: given an intent ID, determine which actions/artifacts were produced (logs, state, or references) | FR-5 | ☐ |
+
+---
+
+## 2. Acceptance criteria verification
+
+| ID | Task | Source | Status |
+| ------ | ---------------------------------------------------------------------------------------------- | ------ | ------ |
+| 001-7 | Verify intent selection and execution are distinct phases (two-stage state machine) | AC | ☐ |
+| 001-8 | Verify every agent action that affects code or UX is associated with an intent ID | AC | ☐ |
+| 001-9 | Verify `.orchestration/` is the only source of truth for intent definitions and state machine | AC | ☐ |
+| 001-10 | Verify no ad-hoc paths around hook middleware | AC | ☐ |
+| 001-11 | Confirm TypeScript strict mode and AGENTS.md (e.g. Settings View cachedState) are not violated | AC | ☐ |
+
+---
+
+## 3. Dependencies
+
+- **002-intent-system** implements the `select_active_intent` tool, schema for `active_intents.yaml`, and gatekeeper; those tasks satisfy 001-2, 001-3, and feed 001-4, 001-5, 001-6.
+- Complete 001-1 and 002 schema/tool tasks first, then 001-2 through 001-6, then 001-7–001-11.
+
+---
+
+_Next: run tasks in 002-intent-system for concrete implementation; use this list to verify 001 acceptance criteria._
diff --git a/.specify/specs/002-intent-system/plan.md b/.specify/specs/002-intent-system/plan.md
new file mode 100644
index 00000000000..2fe003647a1
--- /dev/null
+++ b/.specify/specs/002-intent-system/plan.md
@@ -0,0 +1,201 @@
+# Implementation plan: select_active_intent tool
+
+**Feature:** 002-intent-system
+**Spec:** [spec.md](./spec.md)
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+
+This plan covers the **select_active_intent** tool: definition, system prompt change, pre-hook interception, loading intent context from `.orchestration/active_intents.yaml`, returning an XML context block to the LLM, and gatekeeper validation.
+
+---
+
+## Phase 0: Prerequisites and schema
+
+### 0.1 active_intents.yaml schema (minimal for this tool)
+
+Define a minimal schema so the tool and pre-hook can read intent context. Full schema may be extended in a later task.
+
+```yaml
+# .orchestration/active_intents.yaml
+version: 1
+current_intent_id: null | "INT-001" # null = none selected
+intents:
+ - id: "INT-001"
+ summary: string
+ scope:
+ allow_glob: string[] # e.g. ["src/**/*.ts"]
+ deny_glob: string[] # optional
+ constraints:
+ disallow_tools: string[]
+ disallow_patterns: string[]
+ acceptance_criteria:
+ - id: string
+ description: string
+ status: "pending" | "met" | "failed"
+```
+
+- **Location:** `.orchestration/active_intents.yaml` (workspace root relative).
+- **Reader:** Use existing YAML parsing (e.g. `yaml` in package.json); add a small typed loader in `src/orchestration/` or next to the tool.
+
+### 0.2 Tool name and types
+
+- Add **`select_active_intent`** to `ToolName` in `packages/types` (or `src/shared/tools.ts` if types live there).
+- Add param type: e.g. `{ intent_id: string }` (required). Optionally `{ intent_id?: string }` for “list available” when no ID given.
+- Add to native tool definitions so the model can call it.
+
+---
+
+## Phase 1: Tool definition — `src/hooks/tools/selectActiveIntent.ts`
+
+**Note:** The codebase currently uses `src/core/tools/` for native tools. Two options: (a) Put the new tool under **`src/hooks/tools/selectActiveIntent.ts`** as a dedicated orchestration/hook surface and wire it from there, or (b) Use **`src/core/tools/SelectActiveIntentTool.ts`** for consistency. This plan uses **`src/hooks/tools/`** as requested; if the project prefers a single tools dir, the same logic can live in `src/core/tools/SelectActiveIntentTool.ts`.
+
+### 1.1 Create the tool class
+
+- **File:** `src/hooks/tools/selectActiveIntent.ts`.
+- **Class:** `SelectActiveIntentTool extends BaseTool<"select_active_intent">`.
+- **Params:** `{ intent_id: string }` (required). Validate format `INT-XXX` (regex or simple prefix check).
+- **execute():**
+ - Resolve workspace root (e.g. from `task.cwd` or first workspace folder).
+ - Read `.orchestration/active_intents.yaml` (create directory/file if missing, with safe defaults).
+ - Find intent with `id === intent_id` in `intents`; if not found, pushToolResult with error and return.
+ - Build an **XML context block** string containing:
+ - `current_intent_id`
+ - Selected intent’s `scope`, `constraints`, `acceptance_criteria` (and optionally `summary`).
+ - **pushToolResult**(xmlContextBlock) so the LLM receives it as the tool result in the next turn.
+- **handlePartial:** Optional; no-op unless streaming UX is needed later.
+- Use **formatResponse** or a small helper to wrap the XML so it’s clearly delimited (e.g. `...`).
+
+### 1.2 Register the tool in the execution path
+
+- **presentAssistantMessage** (`src/core/assistant-message/presentAssistantMessage.ts`): In the `switch (block.name)` add:
+ - `case "select_active_intent":` → call `selectActiveIntentTool.handle(cline, block, { askApproval, handleError, pushToolResult })`.
+- Import the tool from `src/hooks/tools/selectActiveIntent` (or from core if moved). Ensure the tool is registered so it’s available in the same way as `execute_command` / `write_to_file`.
+
+### 1.3 Native tool definition (for the LLM)
+
+- **File:** `src/core/prompts/tools/native-tools/select_active_intent.ts` (same pattern as `execute_command.ts`).
+- **name:** `"select_active_intent"`.
+- **description:** State that the agent must select an active intent by ID (format INT-XXX) before performing file-modifying or constrained actions; the tool returns the intent’s scope, constraints, and acceptance criteria for the current turn.
+- **parameters:** `intent_id` (string, required).
+- Export and add to the native tools list in `src/core/prompts/tools/native-tools/index.ts` (and ensure **buildNativeToolsArrayWithRestrictions** / filter-tools-for-mode include it for the appropriate mode(s)).
+
+### 1.4 shared/tools.ts and types
+
+- In `src/shared/tools.ts` (and any central ToolName / param type definition):
+ - Add `select_active_intent` to the tool name union and to any param map (e.g. `select_active_intent: { intent_id: string }`).
+- Add a **ToolUse<"select_active_intent">** type if the codebase uses per-tool types.
+
+---
+
+## Phase 2: System prompt — require intent selection first
+
+### 2.1 Add “intent selection first” rule
+
+- **Option A (recommended):** Add a new section (e.g. **getIntentSelectionSection()**) in `src/core/prompts/sections/` that returns a short block of text:
+ - “You must call the **select_active_intent** tool with a valid intent ID (format INT-XXX) before performing any file-modifying or constrained actions. If no intent is selected, call select_active_intent first.”
+- **Option B:** Append the same text inside **getRulesSection** or **getObjectiveSection** in `src/core/prompts/sections/`.
+- Wire the new section into **generatePrompt** in `src/core/prompts/system.ts` (e.g. after rules or before capabilities).
+
+### 2.2 Placement
+
+- Insert the intent-selection requirement early in the prompt (e.g. after role/formatting, before or with tool-use guidelines) so the model sees it before tool descriptions.
+
+---
+
+## Phase 3: Pre-hook that intercepts select_active_intent calls
+
+### 3.1 Purpose of the pre-hook
+
+- **Intercept** every **select_active_intent** tool call before the actual tool executes.
+- Use this to: (1) ensure the call is valid, (2) optionally load context from YAML and attach to task state for downstream hooks, (3) optionally short-circuit (e.g. return cached XML) or delegate to the real tool.
+
+### 3.2 Implementation options
+
+- **Option A — In presentAssistantMessage, before the switch:** When `block.name === "select_active_intent"`, run a **pre-hook** function (e.g. `orchestrationPreHook.selectActiveIntent(task, block)`). The pre-hook can:
+ - Read `.orchestration/active_intents.yaml`.
+ - Validate `intent_id` and that the intent exists.
+ - Set on the task a “pending intent context” (e.g. `task.currentIntentContext`) so the tool’s execute() can use it, or the pre-hook can push the XML and skip the tool (if “intercept” means “handle here”).
+- **Option B — Wrapper around the tool:** A thin wrapper in presentAssistantMessage: when `block.name === "select_active_intent"`, call `selectActiveIntentPreHook(task, block, callbacks)` which may load YAML, run validation, then call `selectActiveIntentTool.handle(...)` (or push result and not call handle).
+
+Recommended: **Option A** — run a pre-hook before the switch; pre-hook loads YAML and sets task-level state (e.g. `task.currentIntentId`, `task.currentIntentContext`); then fall through to the tool’s handle(), which uses that state to build and push the XML (or the pre-hook pushes the XML and the tool no-ops if preferred). This keeps “load and validate” in one place and “format for LLM” in the tool.
+
+### 3.3 Where to define the pre-hook
+
+- **File:** e.g. `src/hooks/preHooks/selectActiveIntent.ts` or `src/orchestration/selectActiveIntentPreHook.ts`.
+- **Function:** `selectActiveIntentPreHook(task, block, callbacks): Promise` — returns `true` to continue to tool execution, `false` to skip (e.g. already pushed result). Read `.orchestration/active_intents.yaml`, validate, set `task.currentIntentId` and optionally `task.currentIntentContext` (parsed object). If validation fails, push error via `pushToolResult` and return `false`.
+
+---
+
+## Phase 4: Load intent context from YAML and return XML context block
+
+### 4.1 Loading
+
+- In the **pre-hook** (or inside the tool): Read `.orchestration/active_intents.yaml` from workspace root (path: `path.join(task.cwd, ".orchestration", "active_intents.yaml")` or via `vscode.workspace.workspaceFolders[0].uri.fsPath`).
+- Parse YAML; find the intent with `id === block.params.intent_id` (or `block.nativeArgs?.intent_id`).
+- If file missing or intent not found: pushToolResult with a clear error message and return.
+
+### 4.2 XML context block
+
+- Build a string, e.g.:
+ - ``
+ - `...` (allow_glob, deny_glob)
+ - `...`
+ - `...`
+ - ``
+- **pushToolResult**(xmlString) so the next API request receives this as the tool result content. The LLM can then use scope/constraints/criteria for the rest of the turn.
+
+### 4.3 Update current intent on task
+
+- After a successful select_active_intent: set `task.currentIntentId = intent_id` and optionally `task.currentIntentContext = parsedIntent` so the **gatekeeper** (Phase 6) and scope-enforcement hooks can use it.
+
+---
+
+## Phase 5: Gatekeeper validation
+
+### 5.1 Purpose
+
+- Ensure that **before** any tool other than **select_active_intent** is executed, an intent has been selected (i.e. `task.currentIntentId != null` or equivalent).
+
+### 5.2 Placement
+
+- In **presentAssistantMessage**, inside the `block.type === "tool_use"` path, **before** the `switch (block.name)`:
+ - If `block.name !== "select_active_intent"` and there is no current intent (e.g. `!cline.currentIntentId`):
+ - pushToolResult with a message like: “No active intent selected. You must call select_active_intent with a valid intent ID (INT-XXX) before using other tools.”
+ - **break** (do not execute the tool).
+ - Optionally: allow a small allowlist of “always allowed” tools (e.g. `read_file`, `list_files`) without an intent; document the allowlist in the plan or spec.
+
+### 5.3 Edge cases
+
+- First user message: no intent selected yet. The system prompt (Phase 2) tells the model to call select_active_intent first; the gatekeeper enforces it if the model tries another tool.
+- After select_active_intent succeeds: set `task.currentIntentId` so subsequent tools pass the gatekeeper.
+- Task/session reset: clear `task.currentIntentId` when starting a new task or when the user explicitly “clears” intent (if such a command exists later).
+
+---
+
+## Phase 6: Integration checklist
+
+- [ ] **Tool:** `src/hooks/tools/selectActiveIntent.ts` (or `src/core/tools/SelectActiveIntentTool.ts`) implements BaseTool; reads YAML, validates intent_id, builds XML, pushToolResult.
+- [ ] **Types:** `select_active_intent` added to ToolName and param types; presentAssistantMessage has a case for it.
+- [ ] **Native tool def:** `src/core/prompts/tools/native-tools/select_active_intent.ts` added and exported; tool included in buildNativeToolsArrayWithRestrictions for the relevant mode(s).
+- [ ] **System prompt:** New section or rule “intent selection first” added and wired in system.ts.
+- [ ] **Pre-hook:** `selectActiveIntentPreHook` runs for every select_active_intent call; loads YAML, validates, sets task.currentIntentId and context; on failure pushes error and returns.
+- [ ] **XML context:** Tool (or pre-hook) returns an XML block with scope, constraints, acceptance_criteria to the LLM via tool result.
+- [ ] **Gatekeeper:** In presentAssistantMessage, before switch(block.name), if block.name !== "select_active_intent" and !task.currentIntentId, push error and skip execution.
+- [ ] **Schema:** Minimal `.orchestration/active_intents.yaml` schema documented (or a TypeScript type in packages/types or src/orchestration).
+- [ ] **Constitution:** Two-stage flow (intent selection → execution) and hook middleware respected; `.orchestration/` remains source of truth.
+
+---
+
+## File creation order (suggested)
+
+1. **Schema / types:** Define ActiveIntentsYaml type and minimal schema (e.g. in `src/orchestration/types.ts` or next to the tool).
+2. **Tool:** `src/hooks/tools/selectActiveIntent.ts` (or core/tools) — implement execute, YAML read, XML build, pushToolResult.
+3. **Native tool def:** `src/core/prompts/tools/native-tools/select_active_intent.ts` + register in index.
+4. **shared/tools.ts:** Add select_active_intent name and params.
+5. **presentAssistantMessage:** Add case "select_active_intent" and import tool.
+6. **Pre-hook:** Implement selectActiveIntentPreHook; call it when block.name === "select_active_intent" before invoking the tool.
+7. **System prompt:** Add intent-selection-first section and wire in system.ts.
+8. **Gatekeeper:** Add check before switch(block.name) in presentAssistantMessage; set task.currentIntentId after successful select_active_intent.
+
+---
+
+_This plan implements the select_active_intent tool and gatekeeper as specified; scope enforcement (blocking write_to_file outside scope) and constraint enforcement can be added in a follow-up task (pre-tool hook for write_to_file, edit_file, etc.)._
diff --git a/.specify/specs/002-intent-system/spec.md b/.specify/specs/002-intent-system/spec.md
new file mode 100644
index 00000000000..225fa82ac89
--- /dev/null
+++ b/.specify/specs/002-intent-system/spec.md
@@ -0,0 +1,103 @@
+# Spec: Intent system (ID format, scope, constraints, acceptance criteria, storage)
+
+**Feature:** 002-intent-system
+**Status:** Draft
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+**Depends on / extends:** [001-intent-orchestration](../001-intent-orchestration/spec.md) (orchestration layer and `.orchestration/` as source of truth)
+
+---
+
+## 1. Overview
+
+Define a concrete **Intent system**: a canonical format for intent IDs, and for each intent a **scope** (files it may modify), **constraints**, and **acceptance criteria**. Active intents are stored in **`.orchestration/active_intents.yaml`** so the orchestration layer and tool hooks can enforce scope and traceability.
+
+---
+
+## 2. User stories
+
+| ID | As a… | I want… | So that… |
+| ---- | --------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| US-1 | Developer | every intent to have a stable ID in the form `INT-XXX` | I can reference and trace intents consistently in logs and tool results |
+| US-2 | Developer | each intent to declare which files it is allowed to modify (scope) | The system can block or warn when the agent touches out-of-scope files |
+| US-3 | Developer | each intent to have explicit constraints (e.g. no delete, no run sudo) | Agent actions stay within safe and predictable bounds |
+| US-4 | Developer | each intent to have acceptance criteria | I can verify when an intent is “done” and gate completion on them |
+| US-5 | Developer | active intents to be stored in `.orchestration/active_intents.yaml` | The orchestration layer and hooks have a single, file-based source of truth |
+
+---
+
+## 3. Functional requirements
+
+### 3.1 Intent ID format
+
+- **FR-1** Intent IDs MUST follow the format **`INT-XXX`** where `XXX` is a unique identifier (e.g. numeric `INT-001`, `INT-002`, or alphanumeric per project convention). The format is case-sensitive; canonical form is uppercase `INT-XXX`.
+- **FR-2** Intent IDs are assigned when an intent is created or selected (e.g. in the intent selection phase). Once assigned, the same ID is used for all actions and traceability for that intent until it is closed or superseded.
+
+### 3.2 Scope (files an intent can modify)
+
+- **FR-3** Each intent MUST have a **scope** that defines which files (or paths) the intent is allowed to **modify** (write, edit, patch, delete). Scope may be expressed as:
+ - An explicit list of file paths (relative to workspace root), and/or
+ - Glob patterns (e.g. `src/**/*.ts`, `docs/*.md`), and/or
+ - A single directory and its descendants.
+- **FR-4** Tool execution (e.g. `write_to_file`, `edit_file`, `apply_diff`) MUST be checked against the active intent’s scope. Attempts to modify a file outside scope MUST be rejected or require explicit escalation (behavior to be defined in plan: reject vs. warn-and-approve).
+- **FR-5** Read-only operations (e.g. `read_file`, `list_files`, `search_files`) may be allowed outside scope for discovery; the plan will define whether reads are scoped or global.
+
+### 3.3 Constraints
+
+- **FR-6** Each intent MUST have a **constraints** section that defines what the agent is not allowed to do for this intent. Examples (to be refined in plan):
+ - Disallow certain tools (e.g. `execute_command` with shell, or `delete_file`).
+ - Disallow modifying files matching certain patterns (e.g. lockfiles, env files).
+ - Rate or count limits (e.g. max number of file writes per intent).
+- **FR-7** Constraints are enforced by the hook middleware (pre-tool or validation layer) before the tool executes. Violations MUST produce a clear error and optionally a tool_result explaining the constraint.
+
+### 3.4 Acceptance criteria (per intent)
+
+- **FR-8** Each intent MUST have **acceptance criteria**: a list of conditions that must hold for the intent to be considered **done**. Criteria are human- and/or machine-checkable (e.g. “File X contains function Y”, “Test suite Z passes”, “User confirmed in UI”).
+- **FR-9** The system MUST support recording whether each criterion is met (e.g. pending / met / failed). Where and how (e.g. in `active_intents.yaml` or a separate checklist file) is defined in the plan.
+- **FR-10** Completion or “attempt_completion” behavior MAY be gated on all acceptance criteria for the current intent being met (optional; to be decided in plan).
+
+### 3.5 Storage: `.orchestration/active_intents.yaml`
+
+- **FR-11** Active intents MUST be stored in **`.orchestration/active_intents.yaml`**. “Active” means intents that are currently in use (e.g. selected for the current task or session).
+- **FR-12** The file MUST be the source of truth for the current task/session for: intent ID, scope, constraints, acceptance criteria (and their status if stored there). Schema (YAML structure) is defined in the technical plan.
+- **FR-13** The orchestration layer and hooks MUST read from this file (or a validated in-memory view of it) to enforce scope and constraints. Writes to this file MUST go through a single writer or API so the format stays consistent.
+- **FR-14** When an intent is closed or superseded, the file is updated (e.g. move to history or remove from active). Retention and archival (e.g. `.orchestration/history/`) are out of scope for this spec unless minimal (e.g. append-only log); the plan may add a simple history.
+
+---
+
+## 4. Acceptance criteria (for this spec)
+
+- [ ] Intent ID format `INT-XXX` is documented and used consistently in code and in `.orchestration/active_intents.yaml`.
+- [ ] Each intent has a defined scope (paths/globs) for modifiable files; tool execution is checked against scope.
+- [ ] Each intent has a constraints section; constraints are enforced before tool execution (via hooks).
+- [ ] Each intent has acceptance criteria; criteria and their status can be stored and updated.
+- [ ] `.orchestration/active_intents.yaml` exists and is the single source of truth for active intents (ID, scope, constraints, acceptance criteria).
+- [ ] Constitution and 001-intent-orchestration are not violated (`.orchestration/` remains source of truth; two-stage state machine and hook middleware respected).
+
+---
+
+## 5. Constraints (from constitution)
+
+- TypeScript strict mode; follow existing repo patterns.
+- Hook middleware pattern for agent flows; scope/constraint checks run in that pipeline.
+- `.orchestration/` is source of truth; do not duplicate intent state elsewhere.
+
+---
+
+## 6. Out of scope for this spec
+
+- UI for editing intents (can be a later spec).
+- Full intent history, search, or analytics (beyond minimal “closed” state).
+- Schema versioning and migration of `active_intents.yaml` (can be added in plan if needed).
+
+---
+
+## 7. Review & acceptance checklist
+
+- [ ] No [NEEDS CLARIFICATION] markers remain.
+- [ ] Requirements are testable and unambiguous.
+- [ ] Success criteria are measurable.
+- [ ] Aligned with constitution and 001-intent-orchestration.
+
+---
+
+_Next: run `/speckit.clarify` to resolve ambiguities, or `/speckit.plan` to produce the technical plan (schema for `active_intents.yaml`, hook integration, scope/constraint enforcement)._
diff --git a/.specify/specs/002-intent-system/tasks.md b/.specify/specs/002-intent-system/tasks.md
new file mode 100644
index 00000000000..de08bb46eda
--- /dev/null
+++ b/.specify/specs/002-intent-system/tasks.md
@@ -0,0 +1,97 @@
+# Tasks: 002-intent-system
+
+**Spec:** [spec.md](./spec.md)
+**Plan:** [plan.md](./plan.md)
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+
+Actionable tasks derived from the spec and the select_active_intent implementation plan. Order follows plan Phase 0 → Phase 6.
+
+---
+
+## Phase 0: Prerequisites and schema
+
+| ID | Task | Status |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
+| 002-0.1 | Define minimal schema for `.orchestration/active_intents.yaml` (version, current_intent_id, intents with id, scope, constraints, acceptance_criteria) and document in plan or README | ☐ |
+| 002-0.2 | Add TypeScript types for ActiveIntentsYaml (e.g. in `src/orchestration/types.ts` or next to tool) | ☐ |
+| 002-0.3 | Add `select_active_intent` to ToolName and param type `{ intent_id: string }` in `src/shared/tools.ts` (or packages/types) | ☐ |
+| 002-0.4 | Ensure YAML parsing is available (e.g. `yaml` in package.json); add small loader for active_intents if needed | ☐ |
+
+---
+
+## Phase 1: Tool definition
+
+| ID | Task | Status |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| 002-1.1 | Create `src/hooks/tools/selectActiveIntent.ts`: class extending BaseTool, params `{ intent_id: string }`, validate INT-XXX format | ☐ |
+| 002-1.2 | In tool execute(): resolve workspace root, read `.orchestration/active_intents.yaml`, find intent by id, build XML context block, pushToolResult | ☐ |
+| 002-1.3 | Add `case "select_active_intent"` in `presentAssistantMessage.ts` and call tool handle(); import from hooks/tools | ☐ |
+| 002-1.4 | Create `src/core/prompts/tools/native-tools/select_active_intent.ts` (name, description, parameters intent_id); export and add to native tools index and buildNativeToolsArrayWithRestrictions | ☐ |
+| 002-1.5 | Add ToolUse<"select_active_intent"> type if codebase uses per-tool types | ☐ |
+
+---
+
+## Phase 2: System prompt
+
+| ID | Task | Status |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
+| 002-2.1 | Add getIntentSelectionSection() in `src/core/prompts/sections/` (or append to rules): require calling select_active_intent with valid INT-XXX before file-modifying or constrained actions | ☐ |
+| 002-2.2 | Wire intent-selection section into generatePrompt in `src/core/prompts/system.ts` (early in prompt) | ☐ |
+
+---
+
+## Phase 3: Pre-hook
+
+| ID | Task | Status |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
+| 002-3.1 | Create selectActiveIntentPreHook (e.g. in `src/hooks/preHooks/selectActiveIntent.ts` or `src/orchestration/selectActiveIntentPreHook.ts`) | ☐ |
+| 002-3.2 | Pre-hook: read `.orchestration/active_intents.yaml`, validate intent_id exists, set task.currentIntentId and task.currentIntentContext; on failure push error and return false | ☐ |
+| 002-3.3 | In presentAssistantMessage, when block.name === "select_active_intent", run pre-hook before invoking tool; if pre-hook returns false, skip tool execution | ☐ |
+
+---
+
+## Phase 4: Load YAML and return XML context
+
+| ID | Task | Status |
+| ------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| 002-4.1 | Load intent from YAML in pre-hook or tool; handle missing file or intent not found with clear pushToolResult error | ☐ |
+| 002-4.2 | Build XML block `` with scope, constraints, acceptance_criteria; pushToolResult(xmlString) | ☐ |
+| 002-4.3 | After successful select_active_intent, set task.currentIntentId and task.currentIntentContext for gatekeeper and future scope hooks | ☐ |
+
+---
+
+## Phase 5: Gatekeeper validation
+
+| ID | Task | Status |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
+| 002-5.1 | In presentAssistantMessage, before switch(block.name): if block.name !== "select_active_intent" and !task.currentIntentId, pushToolResult("No active intent selected…") and skip execution | ☐ |
+| 002-5.2 | Optionally define allowlist of tools that may run without intent (e.g. read_file, list_files); document in plan | ☐ |
+| 002-5.3 | Clear task.currentIntentId on task/session reset when implemented | ☐ |
+
+---
+
+## Phase 6: Integration and spec acceptance
+
+| ID | Task | Status |
+| ------- | ------------------------------------------------------------------------------------------------------------ | ------ |
+| 002-6.1 | Verify INT-XXX format is documented and used consistently in code and active_intents.yaml | ☐ |
+| 002-6.2 | Verify each intent has scope; plan follow-up for scope enforcement (write_to_file / edit_file checks) | ☐ |
+| 002-6.3 | Verify each intent has constraints section; plan follow-up for constraint enforcement in hooks | ☐ |
+| 002-6.4 | Verify acceptance criteria and status can be stored/updated in active_intents.yaml | ☐ |
+| 002-6.5 | Confirm `.orchestration/active_intents.yaml` is single source of truth and constitution/001 are not violated | ☐ |
+
+---
+
+## Suggested execution order
+
+1. 002-0.1 → 002-0.4 (schema and types)
+2. 002-1.1 → 002-1.5 (tool and native def)
+3. 002-3.1 → 002-3.3 (pre-hook)
+4. 002-4.1 → 002-4.3 (load + XML)
+5. 002-2.1 → 002-2.2 (system prompt)
+6. 002-5.1 → 002-5.3 (gatekeeper)
+7. 002-6.1 → 002-6.5 (integration and AC)
+
+---
+
+_Scope enforcement (blocking writes outside scope) and constraint enforcement are follow-up work; see plan._
diff --git a/.specify/specs/003-hook-middleware-security/plan.md b/.specify/specs/003-hook-middleware-security/plan.md
new file mode 100644
index 00000000000..6d04b0a0d84
--- /dev/null
+++ b/.specify/specs/003-hook-middleware-security/plan.md
@@ -0,0 +1,805 @@
+# Implementation plan: Hook Middleware & Security Boundary
+
+**Feature:** 003-hook-middleware-security
+**Spec:** [spec.md](./spec.md)
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+
+This plan covers the **security boundary layer** that enforces scope validation and provides UI-blocking authorization for destructive operations. It builds on Phase 1 (The Handshake) which implemented intent selection via `select_active_intent`.
+
+---
+
+## Architecture Overview
+
+We'll implement a middleware layer that intercepts tool execution in `presentAssistantMessage.ts`, with pre-hooks for validation and UI integration. The flow:
+
+1. **Pre-hook execution**: Before tool execution, pre-hooks validate scope and classify tools
+2. **UI authorization**: If blocked or destructive, show modal dialogs for user approval
+3. **Error formatting**: Return structured JSON errors that the LLM can parse and recover from
+4. **Caching**: Cache `owned_scope` after intent selection to avoid repeated YAML reads
+
+---
+
+## Phase 0: Prerequisites and Dependencies
+
+### 0.1 Verify dependencies
+
+- **glob package**: Already installed (`glob@^11.1.0` in `package.json`). For pattern matching, we can use:
+ - Option A: Install `minimatch` package (recommended for glob pattern matching)
+ - Option B: Use `glob` package's built-in matching if available
+ - Option C: Use a simple regex-based matcher for basic patterns
+- **vscode API**: Already available in extension context. Use `vscode.window.showWarningMessage` for modal dialogs.
+- **yamlLoader**: Already exists at `src/hooks/utils/yamlLoader.ts` with `findIntentById` function.
+
+**Note**: The plan uses `minimatch` for glob pattern matching. If `minimatch` is not installed, either install it (`npm install minimatch`) or adapt the implementation to use an alternative pattern matching library.
+
+### 0.2 Task class extension
+
+- **Location**: `src/core/task/Task.ts` (already has `currentIntentId: string | null` at line 393)
+- **Add**: `currentIntentScope: string[] | null = null` property to cache `owned_scope` after intent selection
+- **Purpose**: Avoid repeated YAML reads for scope validation
+
+---
+
+## Phase 1: Path Matcher Utility
+
+### 1.1 Create path matcher module
+
+- **File**: `src/hooks/utils/pathMatcher.ts`
+- **Purpose**: Handle glob pattern matching with Windows/Unix path normalization and negation support
+
+### 1.2 Implementation
+
+```typescript
+import { minimatch } from "minimatch"
+import * as path from "path"
+
+/**
+ * Normalize a file path relative to workspace root
+ * Handles Windows/Unix path separators and resolves relative paths
+ */
+export function normalizePath(filePath: string, workspaceRoot: string): string {
+ // Resolve relative paths
+ const resolved = path.isAbsolute(filePath)
+ ? filePath
+ : path.resolve(workspaceRoot, filePath)
+
+ // Normalize separators and relative segments
+ const normalized = path.normalize(resolved)
+
+ // Make relative to workspace root (use forward slashes for glob matching)
+ const relative = path.relative(workspaceRoot, normalized)
+ return relative.split(path.sep).join("/") // Normalize to forward slashes
+}
+
+/**
+ * Check if a file path matches a glob pattern
+ * Supports negation patterns (starting with !)
+ */
+export function matchesGlobPattern(
+ filePath: string,
+ pattern: string,
+ workspaceRoot: string
+): boolean {
+ const normalizedPath = normalizePath(filePath, workspaceRoot)
+ const isNegation = pattern.startsWith("!")
+ const actualPattern = isNegation ? pattern.slice(1) : pattern
+
+ // Use minimatch for glob pattern matching
+ const match = minimatch(normalizedPath, actualPattern, {
+ dot: true, // Match hidden files
+ nocase: false, // Case-sensitive matching
+ })
+
+ return isNegation ? !match : match
+}
+
+/**
+ * Check if a file path matches any pattern in an array
+ * Handles inclusion and exclusion patterns (exclusions override inclusions)
+ */
+export function matchesAnyGlobPattern(
+ filePath: string,
+ patterns: string[],
+ workspaceRoot: string
+): boolean {
+ if (patterns.length === 0) {
+ return false // No patterns = no match
+ }
+
+ const inclusionPatterns = patterns.filter(p => !p.startsWith("!"))
+ const exclusionPatterns = patterns.filter(p => p.startsWith("!"))
+
+ // Check exclusions first (if excluded, never matches)
+ for (const exclusionPattern of exclusionPatterns) {
+ if (matchesGlobPattern(filePath, exclusionPattern, workspaceRoot)) {
+ return false
+ }
+ }
+
+ // If no inclusions, only exclusions matter (and we've already checked)
+ if (inclusionPatterns.length === 0) {
+ return true // No inclusions means "allow everything except exclusions"
+ }
+
+ // Check if matches any inclusion pattern
+ for (const inclusionPattern of inclusionPatterns) {
+ if (matchesGlobPattern(filePath, inclusionPattern, workspaceRoot)) {
+ return true
+ }
+ }
+
+ return false
+}
+```
+
+### 1.3 Tests
+
+- **File**: `src/hooks/utils/pathMatcher.test.ts` (or `.spec.ts` depending on test framework)
+- **Test cases**:
+ - Inclusion patterns (e.g. `"src/**/*.ts"` matches `src/utils/file.ts`)
+ - Exclusion patterns (e.g. `"!**/*.test.ts"` excludes `src/utils/file.test.ts`)
+ - Combined inclusion/exclusion (inclusion + exclusion = excluded)
+ - Windows path normalization (backslashes → forward slashes)
+ - Relative path resolution
+ - Edge cases (empty patterns, root paths, hidden files)
+
+---
+
+## Phase 2: Command Classification Utility
+
+### 2.1 Create command classifier module
+
+- **File**: `src/hooks/utils/commandClassification.ts`
+- **Purpose**: Classify tools as SAFE (read-only) or DESTRUCTIVE (write/delete/execute)
+
+### 2.2 Implementation
+
+```typescript
+export enum CommandType {
+ SAFE = "SAFE",
+ DESTRUCTIVE = "DESTRUCTIVE",
+}
+
+/**
+ * Known SAFE (read-only) tools
+ */
+const SAFE_TOOLS = new Set([
+ "read_file",
+ "search_files",
+ "list_files",
+ "read_directory",
+ "grep",
+ "select_active_intent", // Intent selection is safe
+] as const)
+
+/**
+ * Known DESTRUCTIVE (write/delete/execute) tools
+ */
+const DESTRUCTIVE_TOOLS = new Set([
+ "write_to_file",
+ "delete_file",
+ "execute_command",
+ "apply_patch",
+ "edit_file", // If exists
+] as const)
+
+/**
+ * Classify a tool as SAFE or DESTRUCTIVE
+ * Unknown tools default to DESTRUCTIVE (fail-safe)
+ */
+export function classifyCommand(toolName: string): CommandType {
+ if (SAFE_TOOLS.has(toolName as any)) {
+ return CommandType.SAFE
+ }
+ if (DESTRUCTIVE_TOOLS.has(toolName as any)) {
+ return CommandType.DESTRUCTIVE
+ }
+ // Unknown tools default to DESTRUCTIVE (fail-safe)
+ return CommandType.DESTRUCTIVE
+}
+
+/**
+ * Check if a tool is destructive
+ */
+export function isDestructiveCommand(toolName: string): boolean {
+ return classifyCommand(toolName) === CommandType.DESTRUCTIVE
+}
+
+/**
+ * Determine if a tool requires user approval
+ * Requires approval if:
+ * - Tool is destructive AND not already blocked by scope
+ * - OR scope violation occurred (user can approve anyway)
+ */
+export function requiresApproval(
+ toolName: string,
+ blocked: boolean,
+ scopeViolation: boolean
+): boolean {
+ // If already blocked by scope, approval handled separately
+ if (blocked && scopeViolation) {
+ return true // Scope violation requires approval dialog
+ }
+ // Destructive commands require approval
+ return isDestructiveCommand(toolName)
+}
+```
+
+### 2.3 Tests
+
+- **File**: `src/hooks/utils/commandClassification.test.ts`
+- **Test cases**:
+ - SAFE tools return `CommandType.SAFE`
+ - DESTRUCTIVE tools return `CommandType.DESTRUCTIVE`
+ - Unknown tools return `CommandType.DESTRUCTIVE` (fail-safe)
+ - `requiresApproval` logic for various combinations
+
+---
+
+## Phase 3: YAML Loader Enhancement with Caching
+
+### 3.1 Update yamlLoader with caching
+
+- **File**: `src/hooks/utils/yamlLoader.ts` (update existing)
+- **Add**: Module-level cache for intent scope
+
+### 3.2 Implementation
+
+```typescript
+// Add to existing yamlLoader.ts
+
+/**
+ * Cache for intent scope (owned_scope)
+ * Key: intentId, Value: owned_scope array
+ */
+const intentScopeCache = new Map()
+
+/**
+ * Get cached intent scope
+ */
+export function getCachedIntentScope(intentId: string): string[] | null {
+ return intentScopeCache.get(intentId) || null
+}
+
+/**
+ * Set cached intent scope
+ */
+export function setCachedIntentScope(intentId: string, scope: string[]): void {
+ intentScopeCache.set(intentId, scope)
+}
+
+/**
+ * Clear cached intent scope (call when intent changes)
+ */
+export function clearCachedIntentScope(intentId?: string): void {
+ if (intentId) {
+ intentScopeCache.delete(intentId)
+ } else {
+ intentScopeCache.clear()
+ }
+}
+
+/**
+ * Enhanced findIntentById that caches scope
+ */
+export async function findIntentByIdWithCache(
+ workspaceRoot: string,
+ intentId: string
+): Promise {
+ // Check cache first
+ const cachedScope = getCachedIntentScope(intentId)
+ if (cachedScope !== null) {
+ // Return cached intent (we need full intent, so still load but use cached scope)
+ const intent = await findIntentById(workspaceRoot, intentId)
+ if (intent) {
+ return { ...intent, owned_scope: cachedScope }
+ }
+ }
+
+ // Load from YAML
+ const intent = await findIntentById(workspaceRoot, intentId)
+ if (intent) {
+ // Cache the scope
+ setCachedIntentScope(intentId, intent.owned_scope)
+ }
+
+ return intent
+}
+```
+
+### 3.3 Update selectActiveIntentPreHook
+
+- **File**: `src/hooks/preHooks/selectActiveIntent.ts`
+- **Update**: After loading intent, cache the scope:
+ ```typescript
+ // After finding intent, cache scope
+ if (intent) {
+ setCachedIntentScope(intent_id, intent.owned_scope)
+ }
+ ```
+
+---
+
+## Phase 4: Write File Pre-Hook Implementation
+
+### 4.1 Update writeFilePreHook
+
+- **File**: `src/hooks/preHooks/writeFile.ts` (update existing)
+- **Purpose**: Implement scope validation logic
+
+### 4.2 Implementation
+
+```typescript
+import { findIntentByIdWithCache, getCachedIntentScope } from "../utils/yamlLoader"
+import { matchesAnyGlobPattern } from "../utils/pathMatcher"
+import { formatStructuredError } from "../utils/errorFormatter"
+
+export async function writeFilePreHook(
+ args: WriteFilePreHookArgs,
+ context: WriteFilePreHookContext,
+): Promise {
+ const { path: filePath, content } = args
+ const { intentId, workspaceRoot } = context
+
+ // 1. Check if intent is active
+ if (!intentId) {
+ return {
+ blocked: true,
+ error: formatStructuredError(
+ "MISSING_INTENT",
+ "No active intent selected. You must call select_active_intent with a valid intent ID (INT-XXX) before writing files.",
+ "Call select_active_intent first to select an intent.",
+ true
+ ),
+ }
+ }
+
+ if (!workspaceRoot) {
+ return {
+ blocked: true,
+ error: formatStructuredError(
+ "MISSING_WORKSPACE_ROOT",
+ "Workspace root not provided. Cannot validate file path.",
+ "Ensure workspace root is available in context.",
+ false
+ ),
+ }
+ }
+
+ // 2. Load intent scope (use cache if available)
+ let ownedScope: string[] | null = null
+
+ // Try cache first
+ ownedScope = getCachedIntentScope(intentId)
+
+ // If cache miss, load from YAML
+ if (ownedScope === null) {
+ const intent = await findIntentByIdWithCache(workspaceRoot, intentId)
+ if (!intent) {
+ return {
+ blocked: true,
+ error: formatStructuredError(
+ "INTENT_NOT_FOUND",
+ `Intent "${intentId}" not found in .orchestration/active_intents.yaml.`,
+ "Select a different intent or ensure the intent exists in active_intents.yaml.",
+ true
+ ),
+ }
+ }
+ ownedScope = intent.owned_scope
+ }
+
+ // 3. Validate path against scope
+ const isInScope = matchesAnyGlobPattern(filePath, ownedScope, workspaceRoot)
+
+ if (!isInScope) {
+ return {
+ blocked: true,
+ error: formatStructuredError(
+ "SCOPE_VIOLATION",
+ `File "${filePath}" is outside the scope of intent "${intentId}". Scope patterns: ${ownedScope.join(", ")}`,
+ `Select a different intent that includes "${filePath}" or request scope expansion for intent "${intentId}".`,
+ true
+ ),
+ }
+ }
+
+ // 4. Path is in scope, allow execution
+ return { blocked: false }
+}
+```
+
+### 4.3 Update WriteFilePreHookResult interface
+
+- **Update**: `WriteFilePreHookResult` to include `scopeViolation?: boolean` flag:
+ ```typescript
+ export interface WriteFilePreHookResult {
+ blocked: boolean
+ error?: string
+ scopeViolation?: boolean // true if blocked due to scope violation
+ }
+ ```
+
+---
+
+## Phase 5: Error Formatter Utility
+
+### 5.1 Create error formatter module
+
+- **File**: `src/hooks/utils/errorFormatter.ts`
+- **Purpose**: Format structured JSON errors that LLM can parse
+
+### 5.2 Implementation
+
+```typescript
+export interface StructuredError {
+ error: string
+ reason: string
+ suggestion: string
+ recoverable: boolean
+}
+
+/**
+ * Format a structured error as JSON string
+ * LLM can parse this and attempt recovery
+ */
+export function formatStructuredError(
+ error: string,
+ reason: string,
+ suggestion: string = "",
+ recoverable: boolean = true
+): string {
+ const structured: StructuredError = {
+ error,
+ reason,
+ suggestion: suggestion || "Review the error and try again.",
+ recoverable,
+ }
+
+ return JSON.stringify(structured, null, 2)
+}
+
+/**
+ * Parse a structured error from JSON string
+ */
+export function parseStructuredError(errorString: string): StructuredError | null {
+ try {
+ return JSON.parse(errorString) as StructuredError
+ } catch {
+ return null
+ }
+}
+```
+
+---
+
+## Phase 6: UI Integration - Dialog Utilities
+
+### 6.1 Create dialog utility module
+
+- **File**: `src/hooks/utils/dialogs.ts`
+- **Purpose**: Show modal approval dialogs for scope violations and destructive actions
+
+### 6.2 Implementation
+
+```typescript
+import * as vscode from "vscode"
+
+export type DialogChoice = "approve" | "reject"
+
+/**
+ * Show approval dialog for scope violation
+ * Returns "approve" if user clicks "Approve Anyway", "reject" otherwise
+ */
+export async function showScopeViolationDialog(
+ filePath: string,
+ intentId: string,
+ scopePatterns: string[]
+): Promise {
+ const message = `Scope Violation: Intent "${intentId}" is not authorized to edit "${filePath}".\n\nScope patterns: ${scopePatterns.join(", ")}\n\nDo you want to approve this action anyway?`
+
+ const choice = await vscode.window.showWarningMessage(
+ message,
+ { modal: true },
+ "Approve Anyway",
+ "Reject"
+ )
+
+ return choice === "Approve Anyway" ? "approve" : "reject"
+}
+
+/**
+ * Show approval dialog for destructive action
+ * Returns "approve" if user clicks "Approve", "reject" otherwise
+ */
+export async function showDestructiveActionDialog(
+ toolName: string,
+ description: string
+): Promise {
+ const message = `Destructive Action: ${toolName}\n\n${description}\n\nDo you want to proceed?`
+
+ const choice = await vscode.window.showWarningMessage(
+ message,
+ { modal: true },
+ "Approve",
+ "Reject"
+ )
+
+ return choice === "Approve" ? "approve" : "reject"
+}
+```
+
+---
+
+## Phase 7: Integration in presentAssistantMessage
+
+### 7.1 Update presentAssistantMessage for write_to_file
+
+- **File**: `src/core/assistant-message/presentAssistantMessage.ts`
+- **Location**: `case "write_to_file":` block (around line 719)
+
+### 7.2 Implementation
+
+```typescript
+case "write_to_file": {
+ await checkpointSaveAndMark(cline)
+ const writeParams = (block.nativeArgs ?? block.params) as { path?: string; content?: string }
+
+ // Run pre-hook for scope validation
+ const writePreResult = await writeFilePreHook(
+ { path: writeParams?.path ?? "", content: writeParams?.content ?? "" },
+ {
+ intentId: cline.currentIntentId,
+ workspaceRoot: cline.cwd,
+ ownedScope: cline.currentIntentScope, // Pass cached scope if available
+ },
+ )
+
+ // If blocked, show approval dialog for scope violations
+ if (writePreResult.blocked) {
+ if (writePreResult.scopeViolation) {
+ // Show scope violation dialog
+ const scopePatterns = cline.currentIntentScope || []
+ const dialogChoice = await showScopeViolationDialog(
+ writeParams?.path ?? "",
+ cline.currentIntentId ?? "",
+ scopePatterns
+ )
+
+ if (dialogChoice === "reject") {
+ // User rejected, return structured error
+ pushToolResult(formatResponse.toolError(writePreResult.error ?? "Action rejected by user."))
+ break
+ }
+ // User approved anyway, continue to tool execution
+ } else {
+ // Other blocking reason (e.g. missing intent), return error
+ pushToolResult(formatResponse.toolError(writePreResult.error ?? "Action blocked."))
+ break
+ }
+ }
+
+ // Check if destructive (for approval dialog)
+ const isDestructive = isDestructiveCommand("write_to_file")
+ if (isDestructive && !writePreResult.blocked) {
+ const dialogChoice = await showDestructiveActionDialog(
+ "write_to_file",
+ `Write to file: ${writeParams?.path}`
+ )
+
+ if (dialogChoice === "reject") {
+ pushToolResult(formatResponse.toolError(
+ formatStructuredError(
+ "DESTRUCTIVE_ACTION_REJECTED",
+ "User rejected the destructive action.",
+ "The file write operation was cancelled.",
+ false
+ )
+ ))
+ break
+ }
+ }
+
+ // Proceed with tool execution (existing code)
+ // ... rest of write_to_file handling
+ break
+}
+```
+
+### 7.3 Update select_active_intent case to cache scope
+
+- **File**: `src/core/assistant-message/presentAssistantMessage.ts`
+- **Location**: `case "select_active_intent":` block (around line 692)
+
+```typescript
+case "select_active_intent": {
+ // ... existing code ...
+
+ cline.currentIntentId = intentId
+
+ // Cache the scope after successful intent selection
+ if (preHookResult.context) {
+ // Parse intent from context or load it
+ const intent = await findIntentByIdWithCache(cline.cwd, intentId)
+ if (intent) {
+ cline.currentIntentScope = intent.owned_scope
+ }
+ }
+
+ // ... rest of existing code ...
+ break
+}
+```
+
+### 7.4 Add Task class property
+
+- **File**: `src/core/task/Task.ts`
+- **Location**: Near `currentIntentId` property (around line 393)
+
+```typescript
+/** Set by select_active_intent pre-hook; used by gatekeeper and write_file scope enforcement. */
+currentIntentId: string | null = null
+/** Cached owned_scope from active intent; avoids repeated YAML reads. */
+currentIntentScope: string[] | null = null
+```
+
+---
+
+## Phase 8: Destructive Command Pre-Hooks
+
+### 8.1 Create deleteFilePreHook
+
+- **File**: `src/hooks/preHooks/deleteFile.ts` (new file)
+- **Purpose**: Check classification and show approval dialog
+
+```typescript
+import { isDestructiveCommand } from "../utils/commandClassification"
+
+export interface DeleteFilePreHookArgs {
+ path: string
+}
+
+export interface DeleteFilePreHookResult {
+ blocked: boolean
+ error?: string
+}
+
+export interface DeleteFilePreHookContext {
+ intentId: string | null
+ workspaceRoot?: string
+}
+
+export async function deleteFilePreHook(
+ args: DeleteFilePreHookArgs,
+ context: DeleteFilePreHookContext,
+): Promise {
+ // Destructive commands require approval (handled in presentAssistantMessage)
+ // This pre-hook just marks it as destructive
+ return { blocked: false }
+}
+```
+
+### 8.2 Create executeCommandPreHook
+
+- **File**: `src/hooks/preHooks/executeCommand.ts` (new file)
+- **Similar structure to deleteFilePreHook**
+
+### 8.3 Create applyPatchPreHook
+
+- **File**: `src/hooks/preHooks/applyPatch.ts` (new file)
+- **Purpose**: Validate all affected paths against scope
+
+```typescript
+import { findIntentByIdWithCache } from "../utils/yamlLoader"
+import { matchesAnyGlobPattern } from "../utils/pathMatcher"
+import { formatStructuredError } from "../utils/errorFormatter"
+
+export interface ApplyPatchPreHookArgs {
+ // Patch format depends on your implementation
+ // Example: { file: string, patch: string } or { files: Array<{path: string, ...}> }
+ [key: string]: unknown
+}
+
+export interface ApplyPatchPreHookResult {
+ blocked: boolean
+ error?: string
+ scopeViolation?: boolean
+}
+
+export interface ApplyPatchPreHookContext {
+ intentId: string | null
+ workspaceRoot?: string
+}
+
+export async function applyPatchPreHook(
+ args: ApplyPatchPreHookArgs,
+ context: ApplyPatchPreHookContext,
+): Promise {
+ // Extract affected file paths from patch
+ // Validate each path against scope
+ // Return blocked if any path is out of scope
+ // Implementation depends on patch format
+}
+```
+
+### 8.4 Integrate in presentAssistantMessage
+
+- Add cases for `delete_file`, `execute_command`, `apply_patch`
+- Follow same pattern as `write_to_file`: pre-hook → dialog → execute or reject
+
+---
+
+## Phase 9: Testing and Integration
+
+### 9.1 Unit tests
+
+- **Path matcher**: Test glob patterns, negation, Windows paths
+- **Command classifier**: Test SAFE/DESTRUCTIVE classification
+- **Error formatter**: Test JSON structure and parsing
+- **Pre-hooks**: Test scope validation, error cases, caching
+
+### 9.2 Integration tests
+
+- **End-to-end flow**: Intent selection → scope validation → dialog → execution
+- **Error recovery**: Verify LLM can parse structured errors
+- **Performance**: Verify caching works (no repeated YAML reads)
+
+### 9.3 Manual testing checklist
+
+- [ ] Scope violation shows approval dialog
+- [ ] Destructive command shows approval dialog
+- [ ] Rejected actions return structured errors
+- [ ] Approved actions proceed to execution
+- [ ] Scope caching works (check YAML read count)
+- [ ] Windows paths work correctly
+- [ ] Negation patterns work correctly
+
+---
+
+## File creation/modification summary
+
+### New files
+
+1. `src/hooks/utils/pathMatcher.ts` - Glob pattern matching
+2. `src/hooks/utils/commandClassification.ts` - Tool classification
+3. `src/hooks/utils/errorFormatter.ts` - Structured error formatting
+4. `src/hooks/utils/dialogs.ts` - VS Code dialog utilities
+5. `src/hooks/preHooks/deleteFile.ts` - Delete file pre-hook
+6. `src/hooks/preHooks/executeCommand.ts` - Execute command pre-hook
+7. `src/hooks/preHooks/applyPatch.ts` - Apply patch pre-hook
+
+### Modified files
+
+1. `src/hooks/utils/yamlLoader.ts` - Add caching functions
+2. `src/hooks/preHooks/writeFile.ts` - Implement scope validation
+3. `src/hooks/preHooks/selectActiveIntent.ts` - Cache scope after selection
+4. `src/core/task/Task.ts` - Add `currentIntentScope` property
+5. `src/core/assistant-message/presentAssistantMessage.ts` - Integrate pre-hooks and dialogs
+
+---
+
+## Implementation sequence
+
+1. **Phase 1**: Path matcher utility + tests
+2. **Phase 2**: Command classifier + tests
+3. **Phase 3**: YAML loader caching + update selectActiveIntentPreHook
+4. **Phase 5**: Error formatter (needed by Phase 4)
+5. **Phase 4**: Write file pre-hook implementation
+6. **Phase 6**: Dialog utilities
+7. **Phase 7**: Integration in presentAssistantMessage
+8. **Phase 8**: Other destructive pre-hooks
+9. **Phase 9**: Testing and integration
+
+---
+
+## Technical decisions
+
+- **glob package**: Use `glob@^11.1.0` (already installed) for pattern matching
+- **Caching strategy**: Cache `owned_scope` in `Task.currentIntentScope` and module-level cache in `yamlLoader`
+- **Dialog API**: Use `vscode.window.showWarningMessage` with `{ modal: true }` for blocking dialogs
+- **Error format**: Structured JSON with `{ error, reason, suggestion, recoverable }` fields
+- **Fail-safe defaults**: Unknown tools default to DESTRUCTIVE
+
+---
+
+_This plan implements the security boundary layer that enforces scope validation and provides UI-blocking authorization, building on Phase 1's intent selection foundation._
diff --git a/.specify/specs/003-hook-middleware-security/spec.md b/.specify/specs/003-hook-middleware-security/spec.md
new file mode 100644
index 00000000000..3526e24efe3
--- /dev/null
+++ b/.specify/specs/003-hook-middleware-security/spec.md
@@ -0,0 +1,185 @@
+# Spec: Hook Middleware & Security Boundary for Intent-Code Traceability
+
+**Feature:** 003-hook-middleware-security
+**Status:** Draft
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+**Depends on / extends:**
+- [001-intent-orchestration](../001-intent-orchestration/spec.md) (orchestration layer and `.orchestration/` as source of truth)
+- [002-intent-system](../002-intent-system/spec.md) (intent IDs, scope, constraints, `select_active_intent` tool)
+
+---
+
+## 1. Overview
+
+Implement the **security boundary layer** that enforces scope validation and provides UI-blocking authorization for destructive operations. This builds on Phase 1 (The Handshake) which implemented intent selection via `select_active_intent`. Phase 2 adds **pre-hook middleware** that validates file operations against the active intent's `owned_scope`, classifies tools as SAFE or DESTRUCTIVE, and presents modal approval dialogs when violations or destructive actions occur.
+
+---
+
+## 2. User stories
+
+| ID | As a… | I want… | So that… |
+| ---- | --------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| US-1 | Developer | file write operations to be validated against the active intent's scope | the agent cannot accidentally modify files outside the declared intent boundaries |
+| US-2 | Developer | clear error messages when scope violations occur | I understand why an action was blocked and can decide whether to approve it anyway |
+| US-3 | Developer | destructive operations to require explicit approval | I maintain control over risky actions like file deletion or command execution |
+| US-4 | Developer | the system to classify tools as safe or destructive automatically | read-only operations proceed smoothly while destructive ones require confirmation |
+| US-5 | Developer | structured error responses that the LLM can parse and recover from | the agent can autonomously handle errors and suggest alternative approaches |
+| US-6 | Developer | scope validation to be performant | the system remains responsive even with complex glob patterns |
+
+---
+
+## 3. Functional requirements
+
+### 3.1 Scope Enforcement
+
+- **FR-1** Every file write operation (e.g. `write_to_file`, `edit_file`, `apply_patch`) MUST be validated against the active intent's `owned_scope` before execution. The validation MUST occur in a pre-hook that runs before the tool's `handle()` method.
+- **FR-2** Files outside the intent's `owned_scope` MUST be blocked with clear error messages. The error MUST include:
+ - The target file path
+ - The active intent ID
+ - The scope patterns that were checked
+ - A suggestion to either select a different intent or request scope expansion
+- **FR-3** Scope validation MUST use glob pattern matching for path validation. The system MUST support:
+ - Inclusion patterns (e.g. `"src/**/*.ts"` matches all TypeScript files under `src/`)
+ - Exclusion patterns (e.g. `"!**/*.test.ts"` excludes test files)
+ - Both patterns in the same scope definition
+- **FR-4** Path resolution MUST normalize file paths relative to the workspace root before matching against glob patterns. Paths MUST be resolved consistently (e.g. handle Windows vs Unix path separators).
+- **FR-5** Read-only operations (e.g. `read_file`, `search_files`, `list_files`, `read_directory`, `grep`) MAY be allowed outside scope for discovery purposes. The plan will define whether reads are scoped or global (recommendation: allow reads globally).
+
+### 3.2 Command Classification
+
+- **FR-6** Tools MUST be classified as either **SAFE** (read-only) or **DESTRUCTIVE** (write/delete/execute). Classification MUST occur before tool execution (e.g. in a classification utility or pre-hook).
+- **FR-7** **SAFE tools** include (non-exhaustive list):
+ - `read_file`
+ - `search_files`
+ - `list_files`
+ - `read_directory`
+ - `grep`
+ - Any tool that does not modify files, execute commands, or delete resources
+- **FR-8** **DESTRUCTIVE tools** include (non-exhaustive list):
+ - `write_to_file`
+ - `delete_file`
+ - `execute_command`
+ - `apply_patch`
+ - Any tool that modifies files, deletes resources, or executes system commands
+- **FR-9** Unknown tools MUST default to **DESTRUCTIVE** (fail-safe principle). If a tool is not explicitly classified, it MUST be treated as destructive and require approval.
+- **FR-10** Tool classification MUST be extensible. The system MUST support adding new tools to the classification without modifying core middleware logic.
+
+### 3.3 UI-Blocking Authorization
+
+- **FR-11** When a scope violation is detected, the system MUST show a VS Code warning dialog that:
+ - Displays the violation details (file path, intent ID, scope patterns)
+ - Offers options: **"Approve Anyway"** (allows the action) or **"Reject"** (blocks the action)
+ - Is modal (blocks execution until the user responds)
+ - Returns the user's choice to the pre-hook
+- **FR-12** When a destructive command is detected (and not already blocked by scope), the system MUST show a VS Code warning dialog that:
+ - Displays the tool name and action description
+ - Offers options: **"Approve"** (allows the action) or **"Reject"** (blocks the action)
+ - Is modal (blocks execution until the user responds)
+ - Returns the user's choice to the pre-hook
+- **FR-13** Dialogs MUST be implemented using VS Code's native dialog API (e.g. `vscode.window.showWarningMessage` with modal options). The dialog MUST not be dismissible without selecting an option.
+- **FR-14** Rejected actions MUST return structured errors to the LLM (see FR-15). The tool execution MUST be skipped (pre-hook returns `blocked: true`).
+- **FR-15** Approved actions (either automatically allowed or user-approved) MUST proceed to tool execution. The pre-hook MUST return `blocked: false`.
+
+### 3.4 Autonomous Recovery
+
+- **FR-16** All errors returned to the LLM MUST be in structured JSON format:
+ ```json
+ {
+ "error": "string",
+ "reason": "string",
+ "suggestion": "string",
+ "recoverable": boolean
+ }
+ ```
+- **FR-17** Error messages MUST include:
+ - **error**: A short, machine-parseable error code or type (e.g. `"SCOPE_VIOLATION"`, `"DESTRUCTIVE_ACTION_REJECTED"`)
+ - **reason**: A human-readable explanation of why the action was blocked
+ - **suggestion**: An actionable suggestion for recovery (e.g. "Select a different intent" or "Request scope expansion")
+ - **recoverable**: A boolean indicating whether the LLM can recover from this error autonomously (e.g. `true` for scope violations, `false` for user-rejected destructive actions)
+- **FR-18** Structured errors MUST be returned via `pushToolResult` so the LLM receives them in the next turn. The error format MUST be consistent across all pre-hooks.
+- **FR-19** The LLM MUST be able to parse these errors and attempt recovery (e.g. by calling `select_active_intent` with a different intent ID, or by requesting scope expansion from the user).
+
+### 3.5 Performance Optimization
+
+- **FR-20** The active intent's `owned_scope` MUST be cached after intent selection to avoid repeated YAML file reads. The cache MUST be invalidated when:
+ - A new intent is selected (`select_active_intent` is called)
+ - The `active_intents.yaml` file is modified (optional: file watcher)
+- **FR-21** The cached scope MUST be passed to write_file pre-hook via the context parameter (e.g. `context.ownedScope`). The pre-hook MUST use the cached value if available, falling back to YAML read only if cache is invalid.
+- **FR-22** Glob pattern matching MUST be efficient. The system SHOULD use a well-tested glob library (e.g. `minimatch` or `picomatch`) and SHOULD cache compiled patterns when possible.
+- **FR-23** Performance MUST not regress compared to Phase 1. Pre-hook execution time MUST be negligible (< 10ms for typical scope checks).
+
+---
+
+## 4. Acceptance criteria (for this spec)
+
+- [ ] All file write operations are validated against `owned_scope` before execution
+- [ ] Scope violations show approval dialogs with "Approve Anyway" / "Reject" options
+- [ ] Destructive commands show approval dialogs with "Approve" / "Reject" options
+- [ ] Rejected actions return structured JSON errors via `pushToolResult`
+- [ ] LLM can parse errors and attempt recovery (e.g. select different intent)
+- [ ] Tool classification (SAFE vs DESTRUCTIVE) is implemented and extensible
+- [ ] Unknown tools default to DESTRUCTIVE (fail-safe)
+- [ ] Scope caching works (no repeated YAML reads for the same intent)
+- [ ] No performance regression (pre-hooks execute in < 10ms for typical cases)
+- [ ] All tests pass (unit tests for scope validation, classification, error formatting)
+- [ ] Constitution and 001/002 specs are not violated (hook middleware pattern, `.orchestration/` as source of truth)
+
+---
+
+## 5. Constraints (from constitution)
+
+- TypeScript strict mode; follow existing repo patterns
+- Hook middleware pattern for agent flows; scope/constraint checks run in that pipeline
+- `.orchestration/` is source of truth; do not duplicate intent state elsewhere
+- Two-stage state machine: intent selection → execution (Phase 1 must be complete)
+- Pre-hooks run before tool execution in `presentAssistantMessage` (before `switch (block.name)`)
+
+---
+
+## 6. Out of scope for this spec
+
+- Post-hook traceability (logging to `.orchestration/agent_trace.jsonl`) — this is Phase 3
+- Constraint enforcement beyond scope (e.g. disallow_tools, disallow_patterns) — can be added in a follow-up
+- Scope expansion workflow (user approval to expand scope) — can be added in a follow-up
+- File watchers for `active_intents.yaml` (manual cache invalidation is acceptable)
+- UI for editing intents or scope (can be a later spec)
+- Multi-intent scenarios (one active intent at a time)
+
+---
+
+## 7. Technical notes
+
+### 7.1 Pre-hook integration points
+
+- **write_to_file**: Pre-hook validates path against `owned_scope`, shows dialog if violation, returns structured error if rejected
+- **delete_file**: Pre-hook checks classification (DESTRUCTIVE), shows approval dialog, validates scope if applicable
+- **execute_command**: Pre-hook checks classification (DESTRUCTIVE), shows approval dialog
+- **apply_patch**: Pre-hook validates all affected paths against `owned_scope`, shows dialog if violation
+
+### 7.2 Scope caching strategy
+
+- Cache key: `currentIntentId` (from `task.currentIntentId`)
+- Cache value: `owned_scope` array (glob patterns)
+- Cache location: Task-level state or a module-level cache with intent ID as key
+- Invalidation: When `select_active_intent` succeeds, clear cache and load new scope
+
+### 7.3 Dialog implementation
+
+- Use `vscode.window.showWarningMessage` with `{ modal: true }` option
+- Options array: `["Approve", "Reject"]` or `["Approve Anyway", "Reject"]`
+- Return user choice to pre-hook; pre-hook returns `blocked: true/false` accordingly
+
+---
+
+## 8. Review & acceptance checklist
+
+- [ ] No [NEEDS CLARIFICATION] markers remain
+- [ ] Requirements are testable and unambiguous
+- [ ] Success criteria are measurable
+- [ ] Aligned with constitution and 001/002 specs
+- [ ] Error format is well-defined and LLM-parseable
+- [ ] Performance requirements are realistic
+
+---
+
+_Next: run `/speckit.clarify` to resolve ambiguities, or `/speckit.plan` to produce the technical implementation plan (pre-hook implementations, tool classification, dialog integration, caching strategy)._
diff --git a/.specify/specs/003-hook-middleware-security/tasks.md b/.specify/specs/003-hook-middleware-security/tasks.md
new file mode 100644
index 00000000000..2a2886c1df5
--- /dev/null
+++ b/.specify/specs/003-hook-middleware-security/tasks.md
@@ -0,0 +1,338 @@
+# Tasks: 003-hook-middleware-security
+
+**Spec:** [spec.md](./spec.md)
+**Plan:** [plan.md](./plan.md)
+**Constitution:** [.specify/memory/constitution.md](../../memory/constitution.md)
+**Depends on:** [002-intent-system](../002-intent-system/spec.md) (Phase 1: select_active_intent must be complete)
+
+Executable tasks for implementing hook middleware and security boundary for Phase 2.
+
+---
+
+## Task 2.1: Create Path Matcher Utility
+
+**File:** `src/hooks/utils/pathMatcher.ts`
+**Status:** ☐ Not started
+
+### Description
+Create a utility module for glob pattern matching with support for inclusion/exclusion patterns and Windows/Unix path normalization.
+
+### Implementation Steps
+1. Create `pathMatcher.ts` file
+2. Install `minimatch` package if not already available (`npm install minimatch`)
+3. Implement `normalizePath(filePath: string, workspaceRoot: string): string`
+4. Implement `matchesGlobPattern(filePath: string, pattern: string, workspaceRoot: string): boolean`
+5. Implement `matchesAnyGlobPattern(filePath: string, patterns: string[], workspaceRoot: string): boolean`
+6. Add unit tests
+
+### Acceptance Criteria
+- ✅ `matchesGlobPattern` works with all pattern types (wildcards, globstars, etc.)
+- ✅ `matchesAnyGlobPattern` works with multiple patterns (inclusion and exclusion)
+- ✅ Handles Windows paths correctly (normalizes separators)
+- ✅ Handles negation patterns (`!` prefix) correctly
+- ✅ Unit tests pass with comprehensive coverage
+
+### Dependencies
+- `minimatch` package (may need installation)
+
+---
+
+## Task 2.2: Create Command Classifier Utility
+
+**File:** `src/hooks/utils/commandClassification.ts`
+**Status:** ☐ Not started
+
+### Description
+Create a utility module that classifies tools as SAFE (read-only) or DESTRUCTIVE (write/delete/execute).
+
+### Implementation Steps
+1. Create `commandClassification.ts` file
+2. Define `CommandType` enum (SAFE, DESTRUCTIVE)
+3. Define SAFE tools set: `read_file`, `search_files`, `list_files`, `read_directory`, `grep`, `select_active_intent`
+4. Define DESTRUCTIVE tools set: `write_to_file`, `delete_file`, `execute_command`, `apply_patch`, `edit_file`
+5. Implement `classifyCommand(toolName: string): CommandType`
+6. Implement `isDestructiveCommand(toolName: string): boolean`
+7. Implement `requiresApproval(toolName: string, blocked: boolean, scopeViolation: boolean): boolean`
+8. Add unit tests
+
+### Acceptance Criteria
+- ✅ `classifyCommand` returns correct type for all known tools
+- ✅ `isDestructiveCommand` helper works correctly
+- ✅ `requiresApproval` logic is correct for all scenarios (destructive + not blocked, scope violation, etc.)
+- ✅ Unknown tools default to DESTRUCTIVE (fail-safe)
+- ✅ Unit tests pass with comprehensive coverage
+
+---
+
+## Task 2.3: Enhance YAML Loader with Caching
+
+**File:** `src/hooks/utils/yamlLoader.ts`
+**Status:** ☐ Not started
+
+### Description
+Add caching functionality to the YAML loader to avoid repeated file reads for the same intent's scope.
+
+### Implementation Steps
+1. Add module-level cache: `Map` for intent scope
+2. Implement `getCachedIntentScope(intentId: string): string[] | null`
+3. Implement `setCachedIntentScope(intentId: string, scope: string[]): void`
+4. Implement `clearCachedIntentScope(intentId?: string): void`
+5. Create `findIntentByIdWithCache(workspaceRoot: string, intentId: string): Promise`
+6. Update `selectActiveIntentPreHook` to cache scope after loading
+7. Add unit tests
+
+### Acceptance Criteria
+- ✅ `findIntentByIdWithCache` caches results after first load
+- ✅ `getCachedIntentScope` returns cached scope if available
+- ✅ Cache invalidates when intent changes (optional: file watcher)
+- ✅ Cache fallback works (reads from YAML if cache miss)
+- ✅ Unit tests pass (test caching, cache invalidation, fallback)
+
+---
+
+## Task 2.4: Update writeFilePreHook with Scope Validation
+
+**File:** `src/hooks/preHooks/writeFile.ts`
+**Status:** ☐ Not started
+
+### Description
+Implement scope validation logic in the write file pre-hook to block writes outside the intent's `owned_scope`.
+
+### Implementation Steps
+1. Import `findIntentByIdWithCache` and `getCachedIntentScope` from `yamlLoader`
+2. Import `matchesAnyGlobPattern` from `pathMatcher`
+3. Import `formatStructuredError` from `errorFormatter`
+4. Check for active intent (`context.intentId`)
+5. Load intent scope (use cache if available, fallback to YAML)
+6. Validate file path against `owned_scope` using `matchesAnyGlobPattern`
+7. Return blocked result with structured error if out of scope
+8. Return `blocked: false` if in scope
+9. Update `WriteFilePreHookResult` interface to include `scopeViolation?: boolean`
+10. Add unit tests
+
+### Acceptance Criteria
+- ✅ Checks for active intent (returns error if missing)
+- ✅ Loads intent (uses cache if available)
+- ✅ Validates file path against `owned_scope`
+- ✅ Returns proper blocked result with error message
+- ✅ Handles empty `owned_scope` gracefully (treats as no scope = block all)
+- ✅ Error messages are structured JSON (via `formatStructuredError`)
+- ✅ Unit tests pass (test scope violations, matches, missing intent, cache usage)
+
+### Dependencies
+- Task 2.1 (Path Matcher)
+- Task 2.3 (YAML Loader Caching)
+- Task 2.6 (Error Formatter)
+
+---
+
+## Task 2.5: Add UI Authorization Flow
+
+**File:** `src/core/assistant-message/presentAssistantMessage.ts`
+**Status:** ☐ Not started
+
+### Description
+Integrate UI dialogs for user approval of blocked operations and destructive commands in the `write_to_file` case.
+
+### Implementation Steps
+1. Import `showScopeViolationDialog` and `showDestructiveActionDialog` from `dialogs`
+2. Import `isDestructiveCommand` from `commandClassification`
+3. Import `formatStructuredError` from `errorFormatter`
+4. In `write_to_file` case, after pre-hook:
+ - If blocked and scope violation: show scope violation dialog
+ - If user rejects: return structured error via `pushToolResult`
+ - If user approves: continue to tool execution
+5. If not blocked but destructive: show destructive action dialog
+ - If user rejects: return structured error
+ - If user approves: continue to tool execution
+6. Add integration tests with mocked dialogs
+
+### Acceptance Criteria
+- ✅ Shows warning dialog for blocked operations (scope violations)
+- ✅ Shows confirmation dialog for destructive operations
+- ✅ Dialogs are modal (await user response)
+- ✅ User can approve or reject
+- ✅ Rejected actions return structured errors via `pushToolResult`
+- ✅ Approved actions proceed normally to tool execution
+- ✅ Integration tests pass (mock dialogs, test approval/rejection flows)
+
+### Dependencies
+- Task 2.2 (Command Classifier)
+- Task 2.4 (writeFilePreHook)
+- Task 2.6 (Error Formatter)
+- Task 2.7 (Dialog Utilities - if separate task)
+
+---
+
+## Task 2.6: Create Error Formatter
+
+**File:** `src/hooks/utils/errorFormatter.ts`
+**Status:** ☐ Not started
+
+### Description
+Create a utility module for formatting structured JSON errors that the LLM can parse and recover from.
+
+### Implementation Steps
+1. Create `errorFormatter.ts` file
+2. Define `StructuredError` interface: `{ error: string, reason: string, suggestion: string, recoverable: boolean }`
+3. Implement `formatStructuredError(error: string, reason: string, suggestion?: string, recoverable?: boolean): string`
+4. Implement `parseStructuredError(errorString: string): StructuredError | null` (helper for tests)
+5. Define error types: `SCOPE_VIOLATION`, `DESTRUCTIVE_ACTION_REJECTED`, `MISSING_INTENT`, `INTENT_NOT_FOUND`, `MISSING_WORKSPACE_ROOT`
+6. Add unit tests
+
+### Acceptance Criteria
+- ✅ `formatStructuredError` returns valid JSON string
+- ✅ Includes `error`, `reason`, `suggestion`, `recoverable` fields
+- ✅ Suggestion is optional but included when helpful
+- ✅ JSON is parseable by LLM (valid structure)
+- ✅ Unit tests pass (test JSON structure, all fields, parsing)
+
+---
+
+## Task 2.7: Update Context to Pass Cached Scope
+
+**Files:**
+- `src/core/assistant-message/presentAssistantMessage.ts` (select_active_intent case)
+- `src/hooks/preHooks/writeFile.ts` (update context interface)
+- `src/core/task/Task.ts` (add property)
+
+**Status:** ☐ Not started
+
+### Description
+Cache the `owned_scope` after intent selection and pass it to pre-hooks via context to avoid repeated YAML reads.
+
+### Implementation Steps
+1. Add `currentIntentScope: string[] | null = null` property to `Task` class
+2. In `select_active_intent` case in `presentAssistantMessage.ts`:
+ - After successful intent selection, load intent and cache scope
+ - Set `cline.currentIntentScope = intent.owned_scope`
+3. Update `WriteFilePreHookContext` interface to include `ownedScope?: string[]`
+4. In `write_to_file` case, pass `ownedScope: cline.currentIntentScope` in context
+5. Update `writeFilePreHook` to use cached scope from context if available
+6. Add tests to verify caching behavior
+
+### Acceptance Criteria
+- ✅ Owned scope cached after intent selection (`Task.currentIntentScope`)
+- ✅ Passed to `writeFilePreHook` in context (`context.ownedScope`)
+- ✅ `writeFilePreHook` uses cached scope when available (avoids YAML read)
+- ✅ Falls back to YAML read if cache not available
+- ✅ Tests verify caching reduces YAML reads
+
+### Dependencies
+- Task 2.3 (YAML Loader Caching)
+- Task 2.4 (writeFilePreHook)
+
+---
+
+## Task 2.8: Write Integration Tests
+
+**File:** `test/phase2/integration/scopeEnforcement.test.ts` (or similar)
+**Status:** ☐ Not started
+
+### Description
+Create comprehensive integration tests for the scope enforcement and authorization flow.
+
+### Implementation Steps
+1. Create test file for scope enforcement integration tests
+2. Mock VS Code dialogs (`vscode.window.showWarningMessage`)
+3. Test scenarios:
+ - Write in scope → succeeds
+ - Write out of scope → blocked with dialog
+ - Write without intent → blocked with error (no dialog needed)
+ - Destructive command → confirmation dialog
+ - User approval → proceeds
+ - User rejection → returns structured error
+4. Test error formatting and parsing
+5. Test caching behavior (verify YAML reads are minimized)
+
+### Acceptance Criteria
+- ✅ Tests all scenarios:
+ - Write in scope → succeeds
+ - Write out of scope → blocked with dialog
+ - Write without intent → blocked with error
+ - Destructive command → confirmation dialog
+ - User approval → proceeds
+ - User rejection → returns error
+- ✅ Mocks VS Code dialogs correctly
+- ✅ Tests error formatting (structured JSON)
+- ✅ Tests error parsing (LLM can parse)
+- ✅ Tests caching (performance improvement)
+
+### Dependencies
+- All previous tasks (2.1-2.7)
+
+---
+
+## Task 2.9: Update Documentation
+
+**Files:**
+- `docs/phase2/scope-enforcement.md` (new)
+- `README.md` (update)
+- `ARCHITECTURE_NOTES.md` (update)
+
+**Status:** ☐ Not started
+
+### Description
+Document the scope enforcement system, command classification, and authorization flow.
+
+### Implementation Steps
+1. Create `docs/phase2/scope-enforcement.md`:
+ - Explain how scope enforcement works
+ - Document command classification (SAFE vs DESTRUCTIVE)
+ - Show example `active_intents.yaml` with `owned_scope`
+ - Include troubleshooting guide
+ - Document error recovery flow
+2. Update `README.md`:
+ - Add section on scope enforcement
+ - Link to detailed documentation
+3. Update `ARCHITECTURE_NOTES.md`:
+ - Document hook middleware pattern
+ - Document pre-hook flow
+ - Document caching strategy
+
+### Acceptance Criteria
+- ✅ Documents how scope enforcement works
+- ✅ Explains command classification (SAFE/DESTRUCTIVE)
+- ✅ Shows example `active_intents.yaml` with `owned_scope` patterns
+- ✅ Includes troubleshooting guide (common issues, solutions)
+- ✅ Documents error recovery flow (how LLM handles structured errors)
+- ✅ README and ARCHITECTURE_NOTES updated
+
+---
+
+## Implementation Sequence
+
+Recommended order for executing tasks:
+
+1. **Task 2.1** → Path Matcher Utility (foundation)
+2. **Task 2.2** → Command Classifier Utility (foundation)
+3. **Task 2.6** → Error Formatter (needed by other tasks)
+4. **Task 2.3** → YAML Loader Caching (needed by Task 2.4)
+5. **Task 2.7** → Context Caching (needed by Task 2.4)
+6. **Task 2.4** → writeFilePreHook (core functionality)
+7. **Task 2.5** → UI Authorization Flow (integrates with Task 2.4)
+8. **Task 2.8** → Integration Tests (verifies everything works)
+9. **Task 2.9** → Documentation (final step)
+
+---
+
+## Dependencies Summary
+
+- **Phase 1 (002) must be complete**: `select_active_intent` tool, pre-hook, gatekeeper, and YAML loading must be working
+- **active_intents.yaml schema**: Must include `owned_scope` field with glob patterns
+- **VS Code API**: `vscode.window.showWarningMessage` must be available
+- **minimatch package**: May need installation for glob pattern matching
+
+---
+
+## Status Legend
+
+- ☐ Not started
+- ☑ In progress
+- ✅ Done
+
+Update task status as you work through implementation.
+
+---
+
+_This implements the security boundary layer that enforces scope validation and provides UI-blocking authorization for destructive operations, building on Phase 1's intent selection foundation._
diff --git a/.specify/tasks.md b/.specify/tasks.md
new file mode 100644
index 00000000000..9b14eb4fce1
--- /dev/null
+++ b/.specify/tasks.md
@@ -0,0 +1,35 @@
+# Spec Kit — Task index
+
+Generated from specs and plans. Use **speckit.tasks** to refresh or regenerate.
+
+---
+
+## Specs and task files
+
+| Spec | Tasks file | Summary |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| [001-intent-orchestration](specs/001-intent-orchestration/spec.md) | [001-intent-orchestration/tasks.md](specs/001-intent-orchestration/tasks.md) | Orchestration layer, `.orchestration/` source of truth, two-stage state machine, hook middleware, traceability |
+| [002-intent-system](specs/002-intent-system/spec.md) | [002-intent-system/tasks.md](specs/002-intent-system/tasks.md) | Intent IDs (INT-XXX), scope, constraints, acceptance criteria, `select_active_intent` tool, gatekeeper, `active_intents.yaml` |
+| [003-hook-middleware-security](specs/003-hook-middleware-security/spec.md) | [003-hook-middleware-security/tasks.md](specs/003-hook-middleware-security/tasks.md) | Hook middleware security boundary, scope enforcement, tool classification (SAFE/DESTRUCTIVE), UI-blocking authorization, structured error recovery |
+
+---
+
+## Quick reference: 002 implementation order
+
+1. **Phase 0:** Schema and types for `active_intents.yaml`; add `select_active_intent` to tool names.
+2. **Phase 1:** Tool class, presentAssistantMessage case, native tool definition.
+3. **Phase 3:** Pre-hook for select_active_intent (load YAML, validate, set task state).
+4. **Phase 4:** Load intent from YAML; build and return XML context block; set task.currentIntentId/Context.
+5. **Phase 2:** System prompt section “intent selection first”.
+6. **Phase 5:** Gatekeeper in presentAssistantMessage (block other tools until intent selected).
+7. **Phase 6:** Integration checklist and spec acceptance.
+
+---
+
+## Status legend
+
+- ☐ Not started
+- ☑ In progress
+- ✅ Done
+
+Update task status in the per-spec `tasks.md` files.
diff --git a/.vscode/mcp.json b/.vscode/mcp.json
new file mode 100644
index 00000000000..94c196720d2
--- /dev/null
+++ b/.vscode/mcp.json
@@ -0,0 +1,7 @@
+{
+ "mcpServers": {
+ "deepwiki": {
+ "url": "https://mcp.deepwiki.com/mcp"
+ }
+ }
+}
diff --git a/ARCHITECTURE_NOTES.md b/ARCHITECTURE_NOTES.md
new file mode 100644
index 00000000000..5fefd95dddb
--- /dev/null
+++ b/ARCHITECTURE_NOTES.md
@@ -0,0 +1,213 @@
+# Roo Code – Architecture Notes
+
+This document describes the VS Code extension architecture, tool execution flow, prompt building, key files, and where to inject hooks (e.g. for intent orchestration and traceability).
+
+---
+
+## 1. VS Code Extension Architecture
+
+### Entry and activation
+
+- **Entry point:** `src/package.json` → `"main": "./dist/extension.js"` (built from `src/extension.ts`).
+- **Activation:** `activationEvents: ["onLanguage", "onStartupFinished"]` — extension activates on first use or when a language is used.
+- **Activation logic:** `src/extension.ts` → `activate(context)`:
+ - Sets up output channel, network proxy, telemetry, i18n, terminal registry, OpenAI Codex OAuth.
+ - Gets/creates **ContextProxy** (extension state).
+ - Initializes **CodeIndexManager** per workspace folder.
+ - Creates **ClineProvider** (sidebar webview provider) and registers it.
+ - Registers commands, code actions, terminal actions, URI handler; starts MCP server manager, model cache refresh, etc.
+
+### Core components
+
+| Component | Location | Role |
+| --------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **ClineProvider** | `src/core/webview/ClineProvider.ts` | Webview provider for the Roo Code sidebar/panel; owns webview lifecycle, state, and message handling. |
+| **ContextProxy** | `src/core/config/ContextProxy.ts` | Source of truth for extension state (API config, mode, settings); used by settings and tasks. |
+| **Webview message handler** | `src/core/webview/webviewMessageHandler.ts` | Handles messages from the webview (chat, getSystemPrompt, run task, etc.). |
+| **Task** | `src/core/task/Task.ts` | Represents a single conversation/task: API conversation history, system prompt, tool execution trigger, streaming loop. |
+
+### Data flow (high level)
+
+1. User interacts with the **webview** (React UI in `webview-ui/`).
+2. Webview sends messages to the **extension host** via `postMessage`; **webviewMessageHandler** routes them.
+3. Creating or continuing a task uses **Task** in the extension. **Task** builds the system prompt, builds tools, calls **API handler** `createMessage(systemPrompt, messages, metadata)`, then consumes the stream.
+4. Streamed content (text, tool_use blocks) is appended to **Task**’s `assistantMessageContent`. **presentAssistantMessage** is called to process the current block (show text or run a tool).
+5. Tool execution is implemented in **src/core/tools/**; each tool’s `handle(task, block, callbacks)` performs the action and pushes results back via `pushToolResult`.
+
+---
+
+## 2. Tool Execution Flow
+
+### Where tools are defined and executed
+
+- **Tool types / names:** `src/shared/tools.ts` (e.g. `write_to_file`, `execute_command`, `read_file`, `apply_diff`, `use_mcp_tool`, …).
+- **Native tool definitions (for the LLM):** `src/core/prompts/tools/native-tools/` — one file per tool (e.g. `write_to_file.ts`, `execute_command.ts`) defining name, description, and parameters for the system prompt.
+- **Filtering per mode:** `src/core/prompts/tools/filter-tools-for-mode.ts` and `src/core/task/build-tools.ts` → **buildNativeToolsArrayWithRestrictions** produce the list of tools (and optional `allowedFunctionNames`) sent to the API.
+- **Execution:** All tool execution goes through **presentAssistantMessage** in `src/core/assistant-message/presentAssistantMessage.ts`.
+
+### Flow for a single tool call
+
+1. **Streaming:** The API stream yields events (e.g. `content_block_start` with `tool_use`).
+
+ - **NativeToolCallParser** (`src/core/assistant-message/NativeToolCallParser.ts`) parses and normalizes tool call blocks (including streaming partials).
+ - Completed blocks are pushed to **Task**’s `assistantMessageContent`.
+
+2. **presentAssistantMessage** runs (from the main streaming loop in **Task** when a content block is ready):
+
+ - Reads the current block from `assistantMessageContent[currentStreamingContentIndex]`.
+ - If `block.type === "tool_use"` (or `mcp_tool_use`), it:
+ - Resolves a human-readable **toolDescription** (for UI).
+ - Handles **didRejectTool** (skips execution, pushes error tool_result).
+ - Ensures **nativeArgs** exist for non-partial blocks (else pushes error and breaks).
+ - **Validates** the tool with **validateToolUse** (mode, disabled tools, custom modes, etc.).
+ - Runs **tool repetition** check (**ToolRepetitionDetector**).
+ - Dispatches to the correct tool handler via a **switch (block.name)**.
+
+3. **Tool handlers** (each extends **BaseTool** in `src/core/tools/`):
+
+ - **write_to_file** → `WriteToFileTool.handle()` in `src/core/tools/WriteToFileTool.ts`.
+ - **execute_command** → `ExecuteCommandTool.handle()` in `src/core/tools/ExecuteCommandTool.ts`.
+ - **read_file** → `ReadFileTool.handle()`, **apply_diff** → **ApplyDiffTool**, **edit_file** → **EditFileTool**, **use_mcp_tool** → **UseMcpToolTool**, etc.
+ - Each `handle(task, block, { askApproval, handleError, pushToolResult })`:
+ - Validates params (e.g. missing `path` or `command`).
+ - Optionally calls **askApproval** (user approval for dangerous tools).
+ - Performs the action (e.g. write file, run command in terminal).
+ - Pushes the result with **pushToolResult** (and optionally **handleError**).
+
+4. **pushToolResult** (defined inside presentAssistantMessage) pushes a `tool_result` into **Task**’s `userMessageContent` (and thus into the next API request).
+
+### Summary: where write_file and execute_command are handled
+
+- **write_to_file** (and **apply_diff**, **edit_file**, etc.):
+ **presentAssistantMessage** → `case "write_to_file"` → **writeToFileTool.handle(...)** in `src/core/tools/WriteToFileTool.ts`.
+- **execute_command**:
+ **presentAssistantMessage** → `case "execute_command"` → **executeCommandTool.handle(...)** in `src/core/tools/ExecuteCommandTool.ts`.
+
+File edits that support checkpoints call **checkpointSaveAndMark(cline)** before the tool handle.
+
+---
+
+## 3. Prompt Builder – Location and Structure
+
+### Entry points
+
+- **Task (runtime):** `Task.getSystemPrompt()` in `src/core/task/Task.ts` (around line 3745). Used when building each API request (e.g. in **attemptApiRequest**).
+- **Webview / preview:** `src/core/webview/generateSystemPrompt.ts` → **generateSystemPrompt(provider, message)**. Used for “get system prompt” and “copy system prompt” from the UI. Both ultimately call **SYSTEM_PROMPT** from `src/core/prompts/system.ts`.
+
+### SYSTEM_PROMPT and generatePrompt
+
+- **File:** `src/core/prompts/system.ts`.
+- **Function:** `SYSTEM_PROMPT(context, cwd, supportsComputerUse, mcpHub, diffStrategy, mode, customModePrompts, customModes, globalCustomInstructions, experiments, language, rooIgnoreInstructions, settings, todoList, modelId, skillsManager)`.
+- It delegates to **generatePrompt** with the same conceptual inputs. **generatePrompt** assembles one large string (the system prompt) from sections.
+
+### Sections (order and source)
+
+The system prompt is built from these sections (see **generatePrompt** in `system.ts` and exports in `src/core/prompts/sections/index.ts`):
+
+| Section | Function | File |
+| ------------------- | ------------------------------------------ | --------------------------------- |
+| Role / mode | From **getModeSelection** (roleDefinition) | `shared/modes`, custom modes |
+| Markdown formatting | **markdownFormattingSection()** | `sections/markdown-formatting.ts` |
+| Shared tool use | **getSharedToolUseSection()** | `sections/tool-use.ts` |
+| Tool use guidelines | **getToolUseGuidelinesSection()** | `sections/tool-use-guidelines.ts` |
+| Capabilities | **getCapabilitiesSection(cwd, mcpHub)** | `sections/capabilities.ts` |
+| Modes | **getModesSection(context)** | `sections/modes.ts` |
+| Skills | **getSkillsSection(skillsManager, mode)** | `sections/skills.ts` |
+| Rules | **getRulesSection(cwd, settings)** | `sections/rules.ts` |
+| System info | **getSystemInfoSection(cwd)** | `sections/system-info.ts` |
+| Objective | **getObjectiveSection()** | `sections/objective.ts` |
+| Custom instructions | **addCustomInstructions(...)** | `sections/custom-instructions.ts` |
+
+Tool definitions sent to the API are **not** part of this string; they are built separately in **buildNativeToolsArrayWithRestrictions** (see **build-tools.ts** and **prompts/tools/**) and passed in **metadata.tools** to **createMessage**.
+
+---
+
+## 4. Key Files and Responsibilities
+
+| File or folder | Responsibility |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **src/extension.ts** | Activation: ContextProxy, ClineProvider, commands, MCP, code index, cloud, telemetry. |
+| **src/core/webview/ClineProvider.ts** | Webview provider; state; postMessage to webview; getState(). |
+| **src/core/webview/webviewMessageHandler.ts** | Handles all webview messages (run task, getSystemPrompt, chat, etc.). |
+| **src/core/task/Task.ts** | Single task: conversation history, getSystemPrompt(), attemptApiRequest(), streaming loop, calls presentAssistantMessage for each content block. |
+| **src/core/assistant-message/presentAssistantMessage.ts** | Dispatches assistant content blocks: text vs tool_use; validation; approval; calls each tool’s `.handle()`. |
+| **src/core/assistant-message/NativeToolCallParser.ts** | Parses/normalizes streaming tool_use blocks (including partials). |
+| **src/core/tools/\*.ts** | One class per native tool (WriteToFileTool, ExecuteCommandTool, ReadFileTool, EditFileTool, etc.); each implements **handle()**. |
+| **src/core/tools/validateToolUse.ts** | Validates that a tool is allowed for the current mode and config. |
+| **src/core/task/build-tools.ts** | **buildNativeToolsArrayWithRestrictions**: builds the tools array (and allowedFunctionNames) for the API from mode, disabled tools, MCP, etc. |
+| **src/core/prompts/system.ts** | **SYSTEM_PROMPT** / **generatePrompt**: assembles the system prompt string from sections. |
+| **src/core/prompts/sections/\*.ts** | Sections: rules, system-info, capabilities, modes, skills, tool-use, custom-instructions, etc. |
+| **src/core/prompts/tools/native-tools/\*.ts** | Per-tool definitions (name, description, params) for the LLM. |
+| **src/shared/tools.ts** | Tool name types, param shapes, tool use types. |
+| **src/api/index.ts** | **buildApiHandler**; exports **ApiHandler**, **ApiStream**, provider list. |
+| **src/api/providers/base-provider.ts** | Abstract **createMessage(systemPrompt, messages, metadata)**. |
+| **src/api/providers/\*.ts** | Provider-specific **createMessage** (Anthropic, OpenAI, Gemini, etc.) and stream handling. |
+
+---
+
+## 5. Where to Inject Hooks
+
+These are the main places to plug in orchestration, intent IDs, or middleware without rewriting the whole flow.
+
+### 5.1 Before/after system prompt creation
+
+- **Task.getSystemPrompt()** (`src/core/task/Task.ts`, ~3745):
+ - **Before:** Compute or resolve intent ID; inject intent-specific instructions or tags into the prompt.
+ - **After:** Post-process or log the system prompt (e.g. attach intent ID for traceability).
+ You can wrap the existing `SYSTEM_PROMPT(...)` call or add a small wrapper that calls a “prompt hook” with (intentId, systemPrompt).
+
+### 5.2 Before/after API request (createMessage)
+
+- **Task.attemptApiRequest** (~4020–4285):
+ - **Before `this.api.createMessage(systemPrompt, cleanConversationHistory, metadata)`:**
+ - Attach **intent ID** (and optionally state-machine phase) to **metadata** so providers or stream handlers can log/trace.
+ - Optionally add a “request hook” that receives (intentId, systemPrompt, messages, metadata).
+ - **After the stream ends:**
+ - “Response hook” with (intentId, usage, finish reason) for traceability and analytics.
+
+### 5.3 Before/after tool execution (single tool call)
+
+- **presentAssistantMessage** (`src/core/assistant-message/presentAssistantMessage.ts`), inside the `block.type === "tool_use"` path:
+ - **Before the `switch (block.name)`** (and before **validateToolUse** if you want to allow middleware to reject or redirect):
+ - **Pre-tool hook:** (task, block, intentId) → allow / deny / transform params.
+ - Ensures every tool execution is tied to the current **intent ID** (e.g. from task or context).
+ - **After each `tool.handle(...)`** (or in a shared wrapper):
+ - **Post-tool hook:** (task, block, result, intentId) for logging and traceability (e.g. record in `.orchestration/` or a trace store).
+
+### 5.4 Tool-level hooks (per-tool class)
+
+- **BaseTool** in `src/core/tools/` (base class for WriteToFileTool, ExecuteCommandTool, etc.):
+ - Add optional **beforeHandle** / **afterHandle** (or a single **handleWithHooks**) so every tool run goes through a common middleware (e.g. attach intent ID, write to trace log).
+- Alternatively, wrap **handle** at the call site in presentAssistantMessage (one wrapper that calls pre/post hooks then `tool.handle(...)`).
+
+### 5.5 Tool list building (for intent- or phase-specific tools)
+
+- **buildNativeToolsArrayWithRestrictions** in `src/core/task/build-tools.ts`:
+ - **Hook:** Before returning, filter or augment the tools array based on **intent** or **state-machine phase** (e.g. “intent selection” vs “execution” might expose different tools).
+ - Caller is **Task** in several places (e.g. attemptApiRequest, context management). You can pass intent/phase via an options object if you add it to the task context.
+
+### 5.6 Validation and approval
+
+- **validateToolUse** in `src/core/tools/validateToolUse.ts`:
+ - **Hook:** Before or after validation, enforce orchestration rules (e.g. “only these tools in execution phase”) or attach intent ID to the validation context.
+- **askApproval** in presentAssistantMessage:
+ - **Hook:** Wrap **askApproval** so that approval decisions are logged with intent ID, or so that certain intents auto-approve.
+
+### 5.7 Streaming and tool call parsing
+
+- **NativeToolCallParser** (`src/core/assistant-message/NativeToolCallParser.ts`):
+ - When finalizing a tool call (full JSON parsed), you can emit an event or call a **hook** with (taskId, toolName, toolUseId, input) so downstream can record “tool X was invoked with intent Y” before execution.
+- **Task** streaming loop (where **content_block_delta** and **content_block_stop** are processed):
+ - After a tool_use block is finalized and before **presentAssistantMessage** runs, you can run a **hook** that tags the block with the current intent ID (e.g. store in a Map by content block index).
+
+### Suggested order for intent–code traceability
+
+1. **Intent selection phase:** Resolve or assign an **intent ID** when a user message is accepted (e.g. in the handler that pushes the user message and triggers **recursivelyMakeClineRequests**). Store it on **Task** (e.g. `task.currentIntentId`) or in a small context object.
+2. **Before createMessage:** Pass intent ID in **metadata** (e.g. `metadata.intentId`) and/or append a short line to the system prompt (e.g. “Current intent ID: …”).
+3. **Pre-tool hook in presentAssistantMessage:** Before the `switch (block.name)`, call a middleware that records (intentId, toolName, toolUseId, params) to `.orchestration/` or your trace store.
+4. **Post-tool hook:** After each `tool.handle(...)`, record (intentId, toolName, result status) for traceability.
+5. **Optional:** In **buildNativeToolsArrayWithRestrictions**, restrict or add tools based on phase (intent selection vs execution) if your two-stage state machine requires it.
+
+---
+
+_These notes align with the constitution in `.specify/memory/constitution.md`: intent–code traceability, `.orchestration/` as source of truth, two-stage state machine (intent selection → execution), and the hook middleware pattern._
diff --git a/INTERIM_REPORT.md b/INTERIM_REPORT.md
new file mode 100644
index 00000000000..192b7f596b8
--- /dev/null
+++ b/INTERIM_REPORT.md
@@ -0,0 +1,160 @@
+# TRP1 Challenge – Interim Submission: AI-Native IDE with Intent-Code Traceability
+
+**Author:** [Author Name]
+**Date:** February 18, 2025
+**Repository:** [Repository URL]
+
+---
+
+## 1. How the VS Code Extension Works
+
+### Extension host vs webview
+
+- **Extension host:** Node.js process where the VS Code extension runs. It has access to the workspace, file system, terminals, and APIs. Entry point is `src/extension.ts`; activation is via `activationEvents` (e.g. `onLanguage`, `onStartupFinished`).
+- **Webview:** Isolated UI (React app in `webview-ui/`) that renders the Roo Code sidebar/panel. It communicates with the extension host only via `postMessage`. The extension host owns the conversation state, API calls, and tool execution; the webview displays chat and sends user messages.
+
+### Key components
+
+| Component | Location | Role |
+| ------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **ClineProvider** | `src/core/webview/ClineProvider.ts` | Webview provider: owns webview lifecycle, state, and message handling for the sidebar. |
+| **ContextProxy** | `src/core/config/ContextProxy.ts` | Source of truth for extension state (API config, mode, settings); used by settings and tasks. |
+| **Task** | `src/core/task/Task.ts` | One conversation/task: holds API conversation history, system prompt, and drives the streaming loop; triggers tool execution via `presentAssistantMessage`. |
+| **Tool execution** | `src/core/assistant-message/presentAssistantMessage.ts` + `src/core/tools/*.ts` | Dispatches tool calls: validates, runs pre/post hooks where implemented, and calls each tool’s `handle(task, block, callbacks)`; results are pushed back via `pushToolResult`. |
+
+### Data flow
+
+1. User interacts with the **webview** (React UI).
+2. Webview sends messages to the **extension host** via `postMessage`; **webviewMessageHandler** routes them.
+3. Creating or continuing a task uses **Task**. Task builds the system prompt, builds tools, calls the API handler `createMessage(systemPrompt, messages, metadata)`, then consumes the stream.
+4. Streamed content (text, `tool_use` blocks) is appended to Task’s `assistantMessageContent`. **presentAssistantMessage** processes each block (show text or run a tool).
+5. Tool execution lives in **src/core/tools/**; each tool’s `handle(task, block, callbacks)` performs the action and pushes results via `pushToolResult` into the next API request.
+
+---
+
+## 2. Code and Design Architecture of the Agent
+
+### Tool loop
+
+- **Tool definitions (for the LLM):** `src/core/prompts/tools/native-tools/` — one file per tool (name, description, parameters). Filtering per mode is done in `build-tools.ts` → **buildNativeToolsArrayWithRestrictions**.
+- **Execution path:** All tool execution goes through **presentAssistantMessage** (`src/core/assistant-message/presentAssistantMessage.ts`). Flow for a single tool call:
+ 1. Streaming yields events (e.g. `content_block_start` with `tool_use`); **NativeToolCallParser** parses and normalizes blocks.
+ 2. **presentAssistantMessage** reads the block, resolves tool description, handles rejection/validation (e.g. **validateToolUse**), runs repetition check, then dispatches via **switch (block.name)**.
+ 3. Each tool handler (e.g. **WriteToFileTool**, **ExecuteCommandTool**) implements `handle(task, block, { askApproval, handleError, pushToolResult })`, performs the action, and pushes the result.
+
+### Key files and purposes
+
+| File or folder | Responsibility |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/extension.ts` | Activation: ContextProxy, ClineProvider, commands, MCP, code index. |
+| `src/core/webview/ClineProvider.ts` | Webview provider; state; postMessage to webview. |
+| `src/core/webview/webviewMessageHandler.ts` | Handles webview messages (run task, getSystemPrompt, chat, etc.). |
+| `src/core/task/Task.ts` | Single task: conversation history, `getSystemPrompt()`, `attemptApiRequest()`, streaming loop, calls **presentAssistantMessage** per block. |
+| `src/core/assistant-message/presentAssistantMessage.ts` | Dispatches blocks (text vs tool_use); validation; gatekeeper; pre/post hooks; calls each tool’s `.handle()`. |
+| `src/core/assistant-message/NativeToolCallParser.ts` | Parses/normalizes streaming tool_use blocks. |
+| `src/core/tools/*.ts` | One class per native tool; each implements **handle()**. |
+| `src/core/task/build-tools.ts` | **buildNativeToolsArrayWithRestrictions**: builds tools array for the API from mode, disabled tools, MCP, etc. |
+| `src/core/prompts/system.ts` | **SYSTEM_PROMPT** / **generatePrompt**: assembles the system prompt from sections. |
+| `src/core/prompts/sections/*.ts` | Sections: rules, system-info, capabilities, modes, skills, tool-use, custom-instructions. |
+| `src/core/prompts/tools/native-tools/*.ts` | Per-tool definitions for the LLM. |
+| `src/hooks/preHooks/*.ts`, `src/hooks/postHooks/*.ts` | Pre- and post-hooks for `select_active_intent` and `write_to_file`. |
+| `src/hooks/models/orchestration.ts` | Types for `.orchestration/` (e.g. **ActiveIntent**, **ActiveIntentsFile**). |
+
+### Prompt builder location
+
+- **Runtime:** **Task.getSystemPrompt()** in `src/core/task/Task.ts` (~line 3745), used when building each API request.
+- **Assembly:** **SYSTEM_PROMPT** / **generatePrompt** in `src/core/prompts/system.ts`; sections come from `src/core/prompts/sections/` (rules, capabilities, modes, skills, tool-use, system-info, objective, custom-instructions). Tool definitions are built separately in **buildNativeToolsArrayWithRestrictions** and passed in **metadata.tools**.
+
+### Hook injection points
+
+- **Before/after tool execution:** In **presentAssistantMessage**, before the **switch (block.name)**: gatekeeper (intent check) and per-tool pre-hooks (e.g. **selectActiveIntentPreHook**, **writeFilePreHook**). After the tool’s `handle()`: post-hooks (e.g. **writeFilePostHook**).
+- **Intent selection:** For `select_active_intent`, the pre-hook runs first (load/validate from `.orchestration/active_intents.yaml`, set `task.currentIntentId`), then the tool result (context XML) is pushed; the tool’s `handle()` is not invoked separately.
+- **Scope enforcement:** **writeFilePreHook** (Phase 2) will use `owned_scope` from active intents to block out-of-scope writes.
+- **Traceability:** **writeFilePostHook** (Phase 3) will append to `.orchestration/agent_trace.jsonl` and update `.orchestration/intent_map.md`.
+
+---
+
+## 3. Architectural Decisions for the Hook System
+
+| Decision | Choice | Rationale |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| **Two-stage state machine** | (1) Reasoning Intercept: agent selects intent, pre-hook loads context and injects it into the prompt; (2) Contextualized Action: LLM acts with that context, tool calls go through hooks for scope and trace. | Separates “what we’re working on” from “what we do.” Intent is fixed and visible before edits, so traceability and scope are consistent. |
+| **Pre-hook intercept pattern** | Before a tool runs, a pre-hook can validate (e.g. intent exists, path in scope) and block or allow. No change to tool implementations. | Single interception point in **presentAssistantMessage**; tools stay unaware of orchestration; easy to add new hooks per tool. |
+| **Gatekeeper pattern** | Before dispatching any tool except `select_active_intent`, require `task.currentIntentId` to be set; otherwise return an error and skip execution. | Ensures the agent always selects an intent before file-modifying or constrained actions, so every change is tied to an intent. |
+| **`.orchestration/` as source of truth** | Active intents in `.orchestration/active_intents.yaml`; trace log in `.orchestration/agent_trace.jsonl`; intent–path map in `.orchestration/intent_map.md`. | File-based, versionable, and independent of in-memory state; aligns with constitution and AI-native git. |
+| **Content hashing for spatial independence** | Post-hook computes a content hash (e.g. SHA-256) of changed code and stores it in the trace. | Enables verification and diff-agnostic traceability: “this intent produced this hash” without depending on line numbers. |
+| **Scope enforcement** | `owned_scope` in each intent is a list of globs (with `!` exclusions); write_file pre-hook resolves the target path and blocks if out of scope. | Keeps edits within the intent’s declared scope; reduces accidental cross-intent edits and supports multi-intent workspaces. |
+
+---
+
+## 4. Diagrams and Schemas
+
+### Two-stage state machine
+
+Diagram: **[docs/diagrams/two-stage-state-machine.md](docs/diagrams/two-stage-state-machine.md)**
+
+- States: **Request** (user prompt) → **Reasoning Intercept** (identify intent, call `select_active_intent`, pre-hook, validate, load context, build XML, inject context) → **Contextualized Action** (LLM generates changes, `write_file`, post-hook: hash, trace, log, map).
+
+### Hook flow
+
+Diagram: **[docs/diagrams/hook-flow.md](docs/diagrams/hook-flow.md)**
+
+- Extension host flow: User message → Tool call → Gatekeeper (intent selected?) → Route by tool type. Shows `select_active_intent` (pre-hook only), `write_to_file` (pre-hook → tool → post-hook), `execute_command` (no hooks), and connections to `.orchestration/` files.
+
+### active_intents.yaml schema
+
+Full schema and field reference: **[docs/schemas/active_intents.md](docs/schemas/active_intents.md)**.
+
+Minimal example:
+
+```yaml
+active_intents:
+ - id: INT-001
+ name: Add dark mode toggle to settings
+ status: IN_PROGRESS
+ owned_scope:
+ - "src/settings/**"
+ - "!**/node_modules/**"
+ constraints:
+ - "Use cachedState for inputs; do not bind to useExtensionState()"
+ acceptance_criteria:
+ - "Toggle appears in Settings UI and persists across reloads"
+```
+
+---
+
+## 5. Implementation Status
+
+| Area | Status | Notes |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Phase 0: Schema and types** | Complete | Schema documented in `docs/schemas/active_intents.md`; TypeScript types in `src/hooks/models/orchestration.ts`; `select_active_intent` in tool names and param type in `packages/types` / shared tools. |
+| **Hooks structure** | Complete | `src/hooks/preHooks/selectActiveIntent.ts`, `writeFile.ts`; `src/hooks/postHooks/writeFile.ts`; `src/hooks/tools/selectActiveIntent.ts`; `src/hooks/models/orchestration.ts`. |
+| **Models and utilities** | Implemented | **ActiveIntent**, **ActiveIntentsFile** (and related) in `orchestration.ts`; pre/post hook signatures and stubs in place. |
+| **Gatekeeper** | Implemented | In **presentAssistantMessage**: require `currentIntentId` for all tools except `select_active_intent`; error message pushed and execution skipped if missing. |
+| **select_active_intent in host** | Implemented | Case in **presentAssistantMessage**; calls **selectActiveIntentPreHook**; sets `cline.currentIntentId`; pushes context or message; no separate tool handle. |
+| **Native tool definition** | Implemented | `src/core/prompts/tools/native-tools/select_active_intent.ts`; added to native tools index. |
+| **Phase 1: Tool definition (full)** | Planned | YAML loader, XML context build, and full pre-hook logic (load from file, validate, return XML) to be completed. |
+| **Phase 2: System prompt** | Planned | Intent-selection section (require calling `select_active_intent` before file-modifying actions) and wire into **generatePrompt**. |
+| **Phase 3: Pre-hook (full)** | Planned | Pre-hook to read `.orchestration/active_intents.yaml`, validate intent_id, set `currentIntentId`/context, return XML block. |
+| **Phase 4: Load YAML + XML** | Planned | Load intent from YAML, build `` XML with scope, constraints, acceptance_criteria; push as tool result. |
+| **Phase 5: Gatekeeper (polish)** | Partial | Core gatekeeper done; allowlist for tools without intent and clear on reset are planned. |
+| **Scope enforcement (write_file)** | Planned | **writeFilePreHook** to resolve path against `owned_scope` and block out-of-scope writes (Phase 2 follow-up). |
+| **Traceability (write_file post-hook)** | Planned | **writeFilePostHook** to compute hash, create trace entry, append to `agent_trace.jsonl`, update `intent_map.md` (Phase 3). |
+
+---
+
+## 6. Next Steps (Final Submission)
+
+- **Phase 1:** Finish tool definition: YAML loader for `.orchestration/active_intents.yaml`, build XML context in pre-hook or tool, ensure `select_active_intent` case and types are fully wired.
+- **Phase 2:** Add intent-selection section to system prompt (e.g. **getIntentSelectionSection()** in `sections/`) and wire into **generatePrompt**; implement **writeFilePreHook** scope check using `owned_scope`.
+- **Phase 3:** Complete **selectActiveIntentPreHook** (read YAML, validate, set `task.currentIntentId` and context, return XML); complete **writeFilePostHook** (hash, trace entry, append to `agent_trace.jsonl`, update `intent_map.md`).
+- **Phase 4:** Load intent from YAML in pre-hook, build `` XML with scope, constraints, acceptance_criteria; push via tool result; document and verify INT-XXX format and integration (Phase 6 tasks).
+
+---
+
+## 7. References
+
+- **Challenge document:** [TRP1 challenge specification — link to be added]
+- **ARCHITECTURE_NOTES.md:** [ARCHITECTURE_NOTES.md](ARCHITECTURE_NOTES.md) — extension architecture, tool loop, prompt builder, hook injection points.
+- **GitHub Spec Kit:** [.specify/specs/](.specify/specs/) — intent orchestration (001), intent system (002); spec and plan in [.specify/specs/002-intent-system/](.specify/specs/002-intent-system/).
+- **AISpec:** [AISpec](https://github.com/aispec-dev/aispec) — specification and planning references.
diff --git a/docs/diagrams/hook-flow.md b/docs/diagrams/hook-flow.md
new file mode 100644
index 00000000000..0d0c6d92e60
--- /dev/null
+++ b/docs/diagrams/hook-flow.md
@@ -0,0 +1,96 @@
+# Hook Flow Architecture
+
+```mermaid
+graph TD
+ subgraph ExtensionHost["Extension Host"]
+ UM[User Message]
+ TC[Tool Call]
+ GK{Gatekeeper
Intent selected?}
+ BLOCK[Return error:
Call select_active_intent first]
+ ROUTE[Route by tool type]
+
+ UM --> TC
+ TC --> GK
+ GK -->|No & not select_active_intent| BLOCK
+ GK -->|Yes or select_active_intent| ROUTE
+ BLOCK --> END1([Stop])
+
+ subgraph SelectIntent["select_active_intent"]
+ SI_PRE[Pre-hook: selectActiveIntentPreHook]
+ SI_VAL{Valid intent?}
+ SI_LOAD[Load context from
active_intents.yaml]
+ SI_INJECT[Set currentIntentId
Inject context XML]
+ SI_PRE --> SI_VAL
+ SI_VAL -->|No| SI_BLOCK[Return blocked]
+ SI_VAL -->|Yes| SI_LOAD
+ SI_LOAD --> SI_INJECT
+ end
+
+ subgraph WriteFile["write_to_file"]
+ WF_PRE[Pre-hook: writeFilePreHook]
+ WF_SCOPE{In owned_scope?}
+ WF_TOOL[writeToFileTool.handle]
+ WF_POST[Post-hook: writeFilePostHook]
+ WF_PRE --> WF_SCOPE
+ WF_SCOPE -->|No| WF_BLOCK[Return scope violation]
+ WF_SCOPE -->|Yes| WF_TOOL
+ WF_TOOL --> WF_POST
+ WF_POST --> WF_HASH[Compute hash]
+ WF_POST --> WF_TRACE[Create trace]
+ WF_POST --> WF_LOG[Append to log]
+ WF_POST --> WF_MAP[Update map]
+ WF_HASH --> WF_TRACE
+ WF_TRACE --> WF_LOG
+ WF_LOG --> WF_MAP
+ end
+
+ subgraph ExecuteCmd["execute_command"]
+ EC_TOOL[executeCommand.handle]
+ end
+
+ ROUTE --> SI_PRE
+ ROUTE --> WF_PRE
+ ROUTE --> EC_TOOL
+ end
+
+ subgraph Orchestration[".orchestration/"]
+ AI[active_intents.yaml]
+ TR[agent_trace.jsonl]
+ IM[intent_map.md]
+ end
+
+ SI_LOAD -.->|Read & validate| AI
+ WF_PRE -.->|Load owned_scope| AI
+ WF_LOG -.->|Append line| TR
+ WF_MAP -.->|Update| IM
+```
+
+## Decision points
+
+| Node | Condition | Outcomes |
+| ----------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| **Gatekeeper** | Is an intent already selected for this turn? | If **no** and tool ≠ `select_active_intent` → return error and stop. If **yes** or tool is `select_active_intent` → route to tool. |
+| **Pre-hook (select_active_intent)** | Is the intent ID valid in `active_intents.yaml`? | **No** → return blocked. **Yes** → load context, set `currentIntentId`, inject XML. |
+| **Pre-hook (write_file)** | Is the target path within the intent’s `owned_scope`? | **No** → return scope violation. **Yes** → run `writeToFileTool.handle`. |
+
+## Flow summary
+
+1. **Extension host**
+ User message leads to a tool call. The **gatekeeper** enforces that every tool except `select_active_intent` runs only after an intent is selected (`currentIntentId` set by a prior `select_active_intent` call).
+
+2. **Tool types**
+
+ - **select_active_intent**
+ Pre-hook only. Reads and validates from `.orchestration/active_intents.yaml`, then sets intent and injects context; no tool implementation “execute” step.
+ - **write_to_file**
+ Pre-hook (scope check using `.orchestration/active_intents.yaml`) → tool execution → post-hook (hash, trace, append to `.orchestration/agent_trace.jsonl`, update `.orchestration/intent_map.md`).
+ - **execute_command**
+ No pre/post hooks; only passes the gatekeeper, then runs the command tool.
+
+3. **.orchestration/**
+ - **active_intents.yaml**
+ Used by the gatekeeper (via `currentIntentId`) and by both pre-hooks (intent list + `owned_scope`).
+ - **agent_trace.jsonl**
+ Written by the write_file post-hook (append trace lines).
+ - **intent_map.md**
+ Updated by the write_file post-hook (intent → path mapping).
diff --git a/docs/diagrams/two-stage-state-machine.md b/docs/diagrams/two-stage-state-machine.md
new file mode 100644
index 00000000000..55a26893580
--- /dev/null
+++ b/docs/diagrams/two-stage-state-machine.md
@@ -0,0 +1,84 @@
+# Two-Stage State Machine for Intent-Code Traceability
+
+
+
+```mermaid
+stateDiagram-v2
+ direction LR
+
+ title Two-Stage State Machine for Intent-Code Traceability
+
+ [*] --> Request
+
+ state Request {
+ direction TB
+ [*] --> user_prompt
+ note right of user_prompt : User sends prompt; conversation starts
+ }
+
+ state "Reasoning Intercept (handshake)" as RI {
+ direction TB
+ [*] --> agent_identifies_intent
+ agent_identifies_intent --> calls_select_active_intent
+ calls_select_active_intent --> prehook_intercepts
+ prehook_intercepts --> validates_intent
+ validates_intent --> loads_context
+ loads_context --> builds_xml_block
+ builds_xml_block --> injects_context
+ injects_context --> [*]
+ note right of agent_identifies_intent : Agent infers user intent from prompt
+ note right of calls_select_active_intent : Tool invoked to register/select intent
+ note right of prehook_intercepts : Pre-hook intercepts before tool runs
+ note right of validates_intent : Intent validated against allowed set
+ note right of loads_context : Context (rules, specs) loaded for intent
+ note right of builds_xml_block : XML block built with context for prompt
+ note right of injects_context : Context injected into system/user message
+ }
+
+ state "Contextualized Action" as CA {
+ direction TB
+ [*] --> llm_generates_changes
+ llm_generates_changes --> calls_write_file
+ calls_write_file --> posthook_intercepts
+ posthook_intercepts --> computes_hash
+ computes_hash --> creates_trace
+ creates_trace --> appends_to_log
+ appends_to_log --> updates_map
+ updates_map --> [*]
+ note right of llm_generates_changes : LLM produces edits using injected context
+ note right of calls_write_file : Agent calls write_file (or other tools)
+ note right of posthook_intercepts : Post-hook intercepts after tool execution
+ note right of computes_hash : Content hash computed for change
+ note right of creates_trace : Trace record created (intent → change)
+ note right of appends_to_log : Entry appended to traceability log
+ note right of updates_map : Intent–code map updated for lookup
+ }
+
+ Request --> RI : prompt received
+ RI --> CA : context injected
+ CA --> [*] : response complete
+```
+
+## Step summary
+
+| Stage | Step | Description |
+| ------------------------- | -------------------------- | ----------------------------------------------------------------- |
+| **Request** | User prompt | Conversation starts; user prompt is the trigger for the pipeline. |
+| **Reasoning Intercept** | Agent identifies intent | Model infers the user’s intent from the prompt. |
+| | Calls select_active_intent | Agent invokes the `select_active_intent` tool. |
+| | Pre-hook intercepts | Pre-hook runs before the tool executes (e.g. to capture args). |
+| | Validates intent | Intent is checked against the allowed intent set. |
+| | Loads context | Rules, specs, or other context for that intent are loaded. |
+| | Builds XML block | A structured XML block is built with the loaded context. |
+| | Injects context | The block is injected into the prompt (system/user message). |
+| **Contextualized Action** | LLM generates changes | LLM produces edits using the injected context. |
+| | Calls write_file | Agent calls `write_file` (or other tools) to apply changes. |
+| | Post-hook intercepts | Post-hook runs after tool execution to capture results. |
+| | Computes hash | A content hash is computed for the change. |
+| | Creates trace | A trace record is created linking intent to the change. |
+| | Appends to log | The trace is appended to the traceability log. |
+| | Updates map | The intent–code map is updated for later lookup. |
diff --git a/docs/schemas/active_intents.md b/docs/schemas/active_intents.md
new file mode 100644
index 00000000000..a8ae70d7e0d
--- /dev/null
+++ b/docs/schemas/active_intents.md
@@ -0,0 +1,102 @@
+# active_intents.yaml Schema
+
+Single source of truth for active intents. Used by the orchestration layer: `select_active_intent` pre-hook loads context from this file; the write_file pre-hook uses `owned_scope` for scope enforcement. Stored at `.orchestration/active_intents.yaml` (workspace root).
+
+---
+
+## Complete YAML Example
+
+```yaml
+# active_intents.yaml
+# Root key: list of intents the agent can select and work on.
+
+active_intents:
+ # --- Intent 1: Feature work ---
+ - id: INT-001
+ name: Add dark mode toggle to settings
+ status: IN_PROGRESS
+
+ # Glob patterns for files this intent is allowed to modify.
+ # Use ! prefix to exclude paths (e.g. !**/vendor/**).
+ owned_scope:
+ - "src/settings/**"
+ - "src/components/SettingsView.*"
+ - "!**/node_modules/**"
+ - "!**/*.test.*"
+
+ # Business or technical constraints the agent must respect.
+ constraints:
+ - "Use cachedState for inputs; do not bind directly to useExtensionState()"
+ - "Changes must not break existing settings persistence"
+
+ # Definition of Done: criteria that must be met to mark intent completed.
+ acceptance_criteria:
+ - "Toggle appears in Settings UI and persists across reloads"
+ - "AGENTS.md or equivalent documents the Settings View pattern"
+
+ # Optional: link to GitHub (or other) issues for traceability.
+ github_issues:
+ - "https://github.com/org/repo/issues/42"
+ - "org/repo#43"
+
+ # Optional: progress tracking (checklist or high-level status).
+ progress:
+ checklist:
+ - { done: true, label: "Add toggle component" }
+ - { done: true, label: "Wire to extension state" }
+ - { done: false, label: "Update AGENTS.md" }
+ notes: "Blocked on design review for contrast ratios"
+
+ # --- Intent 2: Refactor ---
+ - id: INT-002
+ name: Extract orchestration types to packages/types
+ status: PENDING
+
+ owned_scope:
+ - "packages/types/src/**"
+ - "src/hooks/models/**"
+ - "!**/node_modules/**"
+
+ constraints:
+ - "No runtime dependencies in packages/types"
+ - "Re-export from src/hooks/models for backward compatibility"
+
+ acceptance_criteria:
+ - "ActiveIntent and ActiveIntentsFile live in packages/types"
+ - "All imports updated; tests pass"
+
+ github_issues: []
+
+ # --- Intent 3: Bug fix (minimal optional fields) ---
+ - id: INT-003
+ name: Fix gatekeeper blocking select_active_intent on first turn
+ status: COMPLETED
+
+ owned_scope:
+ - "src/core/assistant-message/**"
+
+ constraints:
+ - "Gatekeeper must allow select_active_intent when currentIntentId is unset"
+
+ acceptance_criteria:
+ - "Agent can call select_active_intent before any other tool without error"
+```
+
+---
+
+## Field Reference
+
+| Field | Type | Required | Description |
+| ---------------------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **active_intents** | `array` | Yes | Root key. Array of intent objects. |
+| **id** | `string` | Yes | Unique intent ID in `INT-XXX` format (e.g. `INT-001`). Used by `select_active_intent` and the gatekeeper. |
+| **name** | `string` | Yes | Human-readable short name for the intent. |
+| **status** | `string` | Yes | One of: `PENDING`, `IN_PROGRESS`, `COMPLETED`, `BLOCKED`. Indicates current lifecycle state. |
+| **owned_scope** | `string[]` | Yes | Glob patterns defining which files this intent may modify. Paths are resolved relative to the workspace root. Used by the write_file pre-hook to block out-of-scope edits. |
+| **owned_scope (exclusions)** | — | — | Use a leading `!` in a pattern to exclude paths (e.g. `!**/node_modules/**`). Exclusions are applied after inclusions. |
+| **constraints** | `string[]` | Yes | Business or technical constraints the agent must follow while working on this intent (e.g. coding rules, invariants). |
+| **acceptance_criteria** | `string[]` | Yes | Definition of Done: list of criteria that must be satisfied to consider the intent complete. |
+| **github_issues** | `string[]` | No | Optional links to GitHub (or other) issues. Each entry can be a full URL or `org/repo#N`. |
+| **progress** | `object` | No | Optional progress tracking. Structure is flexible; typical use: checklist and notes. |
+| **progress.checklist** | `array` | No | Optional list of `{ done: boolean, label: string }` items for granular progress. |
+| **progress.notes** | `string` | No | Optional free-form notes (e.g. blockers, decisions). |
diff --git a/packages/types/src/tool.ts b/packages/types/src/tool.ts
index 4f90b63e9fc..3655a5f29ed 100644
--- a/packages/types/src/tool.ts
+++ b/packages/types/src/tool.ts
@@ -46,6 +46,7 @@ export const toolNames = [
"skill",
"generate_image",
"custom_tool",
+ "select_active_intent",
] as const
export const toolNamesSchema = z.enum(toolNames)
diff --git a/src/__tests__/phase2/fixtures/index.ts b/src/__tests__/phase2/fixtures/index.ts
new file mode 100644
index 00000000000..4752b1baf37
--- /dev/null
+++ b/src/__tests__/phase2/fixtures/index.ts
@@ -0,0 +1,54 @@
+import * as fs from "fs/promises"
+import * as path from "path"
+import * as os from "os"
+
+let lastWorkspaceRoot: string | null = null
+
+/**
+ * Create a temporary workspace directory for Phase 2 integration tests.
+ * Creates .orchestration/active_intents.yaml with a test intent.
+ */
+export async function setupTestWorkspace(): Promise {
+ const workspaceRoot = path.join(
+ os.tmpdir(),
+ `roo-phase2-test-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+ )
+ await fs.mkdir(workspaceRoot, { recursive: true })
+
+ const orchestrationDir = path.join(workspaceRoot, ".orchestration")
+ await fs.mkdir(orchestrationDir, { recursive: true })
+
+ const activeIntentsYaml = `
+active_intents:
+ - id: INT-001
+ name: Test Intent
+ status: IN_PROGRESS
+ owned_scope:
+ - "src/**"
+ - "tests/**"
+ - "!**/*.test.ts"
+ constraints: []
+ acceptance_criteria: []
+`.trim()
+
+ await fs.writeFile(path.join(orchestrationDir, "active_intents.yaml"), activeIntentsYaml, "utf-8")
+
+ lastWorkspaceRoot = workspaceRoot
+ return workspaceRoot
+}
+
+/**
+ * Remove the temporary workspace directory.
+ */
+export async function cleanupTestWorkspace(workspaceRoot?: string): Promise {
+ const toRemove = workspaceRoot ?? lastWorkspaceRoot
+ if (!toRemove) return
+ try {
+ await fs.rm(toRemove, { recursive: true, force: true })
+ } catch {
+ // Ignore if already removed or missing
+ }
+ if (toRemove === lastWorkspaceRoot) {
+ lastWorkspaceRoot = null
+ }
+}
diff --git a/src/__tests__/phase2/integration/scopeEnforcement.test.ts b/src/__tests__/phase2/integration/scopeEnforcement.test.ts
new file mode 100644
index 00000000000..821f3f7a709
--- /dev/null
+++ b/src/__tests__/phase2/integration/scopeEnforcement.test.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
+import * as vscode from "vscode"
+import { writeFilePreHook } from "../../../hooks/preHooks/writeFile"
+import { setupTestWorkspace, cleanupTestWorkspace } from "../fixtures"
+
+type TaskLike = { currentIntentId: string | null; currentIntentScope: string[] }
+
+vi.mock("vscode", () => ({
+ window: {
+ showWarningMessage: vi.fn(),
+ },
+}))
+
+describe("Phase 2 Integration: Scope Enforcement", () => {
+ let task: TaskLike
+ let workspaceRoot: string
+
+ beforeEach(async () => {
+ workspaceRoot = await setupTestWorkspace()
+ task = {
+ currentIntentId: "INT-001",
+ currentIntentScope: ["src/**", "tests/**", "!**/*.test.ts"],
+ }
+ })
+
+ afterEach(async () => {
+ await cleanupTestWorkspace(workspaceRoot)
+ vi.clearAllMocks()
+ })
+
+ it("should allow writing to files in scope", async () => {
+ const result = await writeFilePreHook(
+ { path: "src/utils/helper.ts", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(false)
+ expect(result.error).toBeUndefined()
+ })
+
+ it("should block writing to files out of scope", async () => {
+ const result = await writeFilePreHook(
+ { path: "docs/README.md", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("Scope Violation")
+ })
+
+ it("should respect exclusion patterns", async () => {
+ // Use single-segment path so **/*.test.ts (greedy .*) matches and excludes it
+ const result = await writeFilePreHook(
+ { path: "src/helper.test.ts", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("Scope Violation")
+ })
+
+ it("should block when no intent is active", async () => {
+ task.currentIntentId = null
+
+ const result = await writeFilePreHook(
+ { path: "src/utils/helper.ts", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("must cite a valid active Intent ID")
+ })
+
+ it("should show approval dialog for blocked operations", async () => {
+ vi.mocked(vscode.window.showWarningMessage).mockResolvedValue("Approve Anyway" as any)
+
+ const { requiresApproval } = await import("../../../hooks/utils/commandClassification")
+
+ const needsApproval = requiresApproval("write_to_file", true, true)
+ expect(needsApproval).toBe(true)
+ })
+
+ it("should return structured errors for rejected operations", async () => {
+ vi.mocked(vscode.window.showWarningMessage).mockResolvedValue("Reject" as any)
+
+ const { ErrorFormatters } = await import("../../../hooks/utils/errorFormatter")
+
+ const error = ErrorFormatters.scopeViolation("Test Intent", "INT-001", "out-of-scope.ts")
+ const parsed = JSON.parse(error)
+
+ expect(parsed.error).toBe("SCOPE_VIOLATION")
+ expect(parsed.reason).toContain("Test Intent")
+ expect(parsed.suggestion).toBeDefined()
+ expect(parsed.recoverable).toBe(true)
+ })
+})
diff --git a/src/core/assistant-message/presentAssistantMessage.ts b/src/core/assistant-message/presentAssistantMessage.ts
index 7f5862be154..bd5bbeb7b80 100644
--- a/src/core/assistant-message/presentAssistantMessage.ts
+++ b/src/core/assistant-message/presentAssistantMessage.ts
@@ -1,3 +1,4 @@
+import * as vscode from "vscode"
import { serializeError } from "serialize-error"
import { Anthropic } from "@anthropic-ai/sdk"
@@ -40,6 +41,12 @@ import { codebaseSearchTool } from "../tools/CodebaseSearchTool"
import { formatResponse } from "../prompts/responses"
import { sanitizeToolUseId } from "../../utils/tool-id"
+import { requiresApproval } from "../../hooks/utils/commandClassification"
+import { formatToolError, ErrorFormatters } from "../../hooks/utils/errorFormatter"
+import { findIntentById } from "../../hooks/utils/yamlLoader"
+import { selectActiveIntentPreHook } from "../../hooks/preHooks/selectActiveIntent"
+import { writeFilePreHook } from "../../hooks/preHooks/writeFile"
+import { writeFilePostHook } from "../../hooks/postHooks/writeFile"
/**
* Processes and presents assistant message content to the user interface.
@@ -383,6 +390,8 @@ export async function presentAssistantMessage(cline: Task) {
return `[${block.name} for '${block.params.skill}'${block.params.args ? ` with args: ${block.params.args}` : ""}]`
case "generate_image":
return `[${block.name} for '${block.params.path}']`
+ case "select_active_intent":
+ return `[${block.name} for '${(block.nativeArgs ?? block.params)?.intent_id ?? "?"}']`
default:
return `[${block.name}]`
}
@@ -675,15 +684,140 @@ export async function presentAssistantMessage(cline: Task) {
}
}
+ // Gatekeeper: require an active intent for all tools except select_active_intent (Phase 1 / orchestration)
+ if (!block.partial && block.name !== "select_active_intent" && !cline.currentIntentId) {
+ const gatekeeperError =
+ "No active intent selected. You must call select_active_intent with a valid intent ID (INT-XXX) before using other tools."
+ pushToolResult(formatResponse.toolError(gatekeeperError))
+ break
+ }
+
switch (block.name) {
- case "write_to_file":
+ case "select_active_intent": {
+ if (block.partial) break
+ const intentId = (block.nativeArgs?.intent_id ?? block.params?.intent_id) as string | undefined
+ if (!intentId) {
+ pushToolResult(
+ formatResponse.toolError("select_active_intent requires intent_id (e.g. INT-001)."),
+ )
+ break
+ }
+ const preHookResult = await selectActiveIntentPreHook(
+ { intent_id: intentId },
+ { task: cline, workspaceRoot: cline.cwd },
+ )
+ if (preHookResult.blocked) {
+ pushToolResult(
+ formatToolError(
+ "INTENT_SELECTION_FAILED",
+ preHookResult.error ?? "Unknown error",
+ "Check the intent ID in .orchestration/active_intents.yaml",
+ ),
+ )
+ break
+ }
+ cline.currentIntentId = intentId
+ // Load and cache the intent's owned_scope for write_file pre-hook
+ try {
+ const intent = await findIntentById(cline.cwd, intentId)
+ if (intent?.owned_scope?.length) {
+ cline.currentIntentScope = intent.owned_scope
+ } else {
+ cline.currentIntentScope = []
+ }
+ } catch (error) {
+ console.error("Error loading intent scope:", error)
+ cline.currentIntentScope = []
+ }
+ if (preHookResult.context) {
+ pushToolResult(preHookResult.context)
+ } else {
+ pushToolResult(`Selected intent: ${intentId}`)
+ }
+ break
+ }
+ case "write_to_file": {
await checkpointSaveAndMark(cline)
+ const writeParams = (block.nativeArgs ?? block.params) as {
+ path?: string
+ content?: string
+ }
+ if (!writeParams?.path || writeParams.content === undefined) {
+ pushToolResult(
+ formatToolError(
+ "INVALID_PARAMS",
+ "write_to_file requires path and content",
+ "Check the tool parameters",
+ ),
+ )
+ break
+ }
+
+ // Run pre-hook with cached scope
+ const writePreResult = await writeFilePreHook(
+ { path: writeParams.path, content: writeParams.content },
+ {
+ intentId: cline.currentIntentId,
+ workspaceRoot: cline.cwd,
+ ownedScope: cline.currentIntentScope,
+ },
+ )
+
+ const isScopeViolation = writePreResult.error?.includes("Scope Violation") ?? false
+
+ const needsApproval = requiresApproval("write_to_file", writePreResult.blocked, isScopeViolation)
+
+ if (needsApproval) {
+ let dialogMessage: string
+ if (writePreResult.blocked && writePreResult.error) {
+ dialogMessage = writePreResult.error
+ } else if (isScopeViolation) {
+ dialogMessage = writePreResult.error ?? "This operation may be outside the intent scope."
+ } else {
+ dialogMessage = `This operation will modify: ${writeParams.path}\n\nContinue?`
+ }
+ if (!writePreResult.blocked && !isScopeViolation) {
+ dialogMessage = `⚠️ Destructive Operation\n\n${dialogMessage}`
+ }
+ const approveButton = writePreResult.blocked ? "Approve Anyway" : "Approve"
+ const choice = await vscode.window.showWarningMessage(
+ dialogMessage,
+ { modal: true },
+ approveButton,
+ "Reject",
+ )
+ if (choice !== approveButton) {
+ pushToolResult(ErrorFormatters.userRejected(`write_file to ${writeParams.path}`))
+ break
+ }
+ if (writePreResult.blocked) {
+ console.warn(`User approved blocked operation: ${writeParams.path}`)
+ }
+ }
+
+ if (writePreResult.blocked && !isScopeViolation) {
+ pushToolResult(
+ formatToolError(
+ "OPERATION_BLOCKED",
+ writePreResult.error ?? "Operation blocked by security policy",
+ "Contact administrator or check intent configuration",
+ ),
+ )
+ break
+ }
+
await writeToFileTool.handle(cline, block as ToolUse<"write_to_file">, {
askApproval,
handleError,
pushToolResult,
})
+ writeFilePostHook(
+ { path: writeParams.path, content: writeParams.content },
+ { success: true },
+ { intentId: cline.currentIntentId, workspaceRoot: cline.cwd },
+ ).catch((err) => console.error("[hooks] writeFilePostHook error:", err))
break
+ }
case "update_todo_list":
await updateTodoListTool.handle(cline, block as ToolUse<"update_todo_list">, {
askApproval,
diff --git a/src/core/prompts/sections/rules.ts b/src/core/prompts/sections/rules.ts
index 4f6e573fa73..5b37d51fc6a 100644
--- a/src/core/prompts/sections/rules.ts
+++ b/src/core/prompts/sections/rules.ts
@@ -71,6 +71,7 @@ export function getRulesSection(cwd: string, settings?: SystemPromptSettings): s
RULES
+- You must call the select_active_intent tool with a valid intent ID (format INT-XXX, e.g. INT-001) before using write_to_file, execute_command, or other mutating tools. If no intent is selected, those tools will be blocked. Call select_active_intent first when the user asks you to change code or run commands.
- The project base directory is: ${cwd.toPosix()}
- All file paths must be relative to this directory. However, commands may change directories in terminals, so respect working directory specified by the response to execute_command.
- You cannot \`cd\` into a different directory to complete a task. You are stuck operating from '${cwd.toPosix()}', so be sure to pass in the correct 'path' parameter when using tools that require a path.
diff --git a/src/core/prompts/tools/native-tools/index.ts b/src/core/prompts/tools/native-tools/index.ts
index 758914d2d65..6d58703fec0 100644
--- a/src/core/prompts/tools/native-tools/index.ts
+++ b/src/core/prompts/tools/native-tools/index.ts
@@ -13,6 +13,7 @@ import newTask from "./new_task"
import readCommandOutput from "./read_command_output"
import { createReadFileTool, type ReadFileToolOptions } from "./read_file"
import runSlashCommand from "./run_slash_command"
+import selectActiveIntent from "./select_active_intent"
import skill from "./skill"
import searchReplace from "./search_replace"
import edit_file from "./edit_file"
@@ -60,6 +61,7 @@ export function getNativeTools(options: NativeToolsOptions = {}): OpenAI.Chat.Ch
readCommandOutput,
createReadFileTool(readFileOptions),
runSlashCommand,
+ selectActiveIntent,
skill,
searchReplace,
edit_file,
diff --git a/src/core/prompts/tools/native-tools/select_active_intent.ts b/src/core/prompts/tools/native-tools/select_active_intent.ts
new file mode 100644
index 00000000000..958f2ef2d15
--- /dev/null
+++ b/src/core/prompts/tools/native-tools/select_active_intent.ts
@@ -0,0 +1,23 @@
+import type OpenAI from "openai"
+
+const SELECT_ACTIVE_INTENT_DESCRIPTION = `Select the active intent to work on before performing file-modifying or constrained actions. You MUST call this tool first with a valid intent ID (format INT-XXX, e.g. INT-001) from .orchestration/active_intents.yaml. The tool returns the intent's scope, constraints, and acceptance criteria for the current turn.`
+
+export default {
+ type: "function",
+ function: {
+ name: "select_active_intent",
+ description: SELECT_ACTIVE_INTENT_DESCRIPTION,
+ strict: true,
+ parameters: {
+ type: "object",
+ properties: {
+ intent_id: {
+ type: "string",
+ description: "Intent ID in INT-XXX format (e.g. INT-001)",
+ },
+ },
+ required: ["intent_id"],
+ additionalProperties: false,
+ },
+ },
+} satisfies OpenAI.Chat.ChatCompletionTool
diff --git a/src/core/task/Task.ts b/src/core/task/Task.ts
index 6ba57e98ac3..5043b8baa18 100644
--- a/src/core/task/Task.ts
+++ b/src/core/task/Task.ts
@@ -389,6 +389,17 @@ export class Task extends EventEmitter implements TaskLike {
didAlreadyUseTool = false
didToolFailInCurrentTurn = false
didCompleteReadingStream = false
+ /** Set by select_active_intent pre-hook; used by gatekeeper and write_file scope enforcement. */
+ currentIntentId: string | null = null
+ /** Cached owned_scope from active intent for write_file pre-hook (avoids repeated YAML reads). */
+ currentIntentScope: string[] = []
+
+ /** Clear intent and scope (e.g. when starting a new assistant turn). */
+ clearIntent(): void {
+ this.currentIntentId = null
+ this.currentIntentScope = []
+ }
+
private _started = false
// No streaming parser is required.
assistantMessageParser?: undefined
@@ -2766,6 +2777,8 @@ export class Task extends EventEmitter implements TaskLike {
this.didRejectTool = false
this.didAlreadyUseTool = false
this.assistantMessageSavedToHistory = false
+ // Orchestration: require intent selection again each turn so gatekeeper can block if model skips select_active_intent
+ this.clearIntent()
// Reset tool failure flag for each new assistant turn - this ensures that tool failures
// only prevent attempt_completion within the same assistant message, not across turns
// (e.g., if a tool fails, then user sends a message saying "just complete anyway")
diff --git a/src/hooks/models/orchestration.ts b/src/hooks/models/orchestration.ts
new file mode 100644
index 00000000000..00d3caabc81
--- /dev/null
+++ b/src/hooks/models/orchestration.ts
@@ -0,0 +1,45 @@
+/**
+ * Data models for the .orchestration/ directory
+ * Based on the challenge specification
+ */
+
+export interface ActiveIntent {
+ id: string // e.g., "INT-001"
+ name: string // Human-readable name
+ status: "PENDING" | "IN_PROGRESS" | "COMPLETED" | "BLOCKED"
+ owned_scope: string[] // File patterns this intent can modify
+ constraints: string[] // Business/technical constraints
+ acceptance_criteria: string[] // Definition of Done
+}
+
+export interface ActiveIntentsFile {
+ active_intents: ActiveIntent[]
+}
+
+export interface AgentTraceEntry {
+ id: string // UUID v4
+ timestamp: string // ISO 8601
+ vcs: {
+ revision_id: string // Git SHA
+ }
+ files: {
+ relative_path: string
+ conversations: {
+ url: string // Session log ID
+ contributor: {
+ entity_type: "AI" | "HUMAN"
+ model_identifier?: string // e.g., "claude-3.5-sonnet"
+ }
+ ranges: {
+ start_line: number
+ end_line: number
+ content_hash: string // SHA-256 of the code block
+ }[]
+ related: {
+ type: "specification" | "requirement"
+ value: string // Intent ID or requirement ID
+ }[]
+ }[]
+ }[]
+ mutation_class?: "AST_REFACTOR" | "INTENT_EVOLUTION" | "BUG_FIX" | "DOCUMENTATION"
+}
diff --git a/src/hooks/postHooks/writeFile.ts b/src/hooks/postHooks/writeFile.ts
new file mode 100644
index 00000000000..894da020aac
--- /dev/null
+++ b/src/hooks/postHooks/writeFile.ts
@@ -0,0 +1,43 @@
+/**
+ * Post-hook for write_file
+ *
+ * Implements the AI-Native Git layer by:
+ * 1. Computing SHA-256 content hash of changed code
+ * 2. Creating trace entry with intent ID and hash
+ * 3. Appending to .orchestration/agent_trace.jsonl
+ * 4. Updating intent_map.md
+ *
+ * This repays Trust Debt with cryptographic verification.
+ */
+
+export interface WriteFilePostHookArgs {
+ path: string
+ content: string
+ [key: string]: unknown
+}
+
+export interface WriteFilePostHookResult {
+ success?: boolean
+ error?: string
+ [key: string]: unknown
+}
+
+export interface WriteFilePostHookContext {
+ intentId: string | null
+ workspaceRoot?: string
+ vcsRevisionId?: string
+ [key: string]: unknown
+}
+
+export async function writeFilePostHook(
+ args: WriteFilePostHookArgs,
+ result: WriteFilePostHookResult,
+ context: WriteFilePostHookContext,
+): Promise {
+ // To be implemented in Phase 3:
+ // 1. Compute SHA-256 hash of args.content (or changed ranges)
+ // 2. Build trace entry per Agent Trace schema (id, timestamp, vcs, files[].conversations[].ranges[].content_hash, related[intent_id])
+ // 3. Append line to .orchestration/agent_trace.jsonl
+ // 4. Optionally update .orchestration/intent_map.md (intent → path mapping)
+ // No return value; side effects only
+}
diff --git a/src/hooks/preHooks/__tests__/writeFile.spec.ts b/src/hooks/preHooks/__tests__/writeFile.spec.ts
new file mode 100644
index 00000000000..dd5f25abe85
--- /dev/null
+++ b/src/hooks/preHooks/__tests__/writeFile.spec.ts
@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import { writeFilePreHook } from "../writeFile"
+
+vi.mock("../../utils/pathMatcher", () => ({
+ matchesAnyGlobPattern: vi.fn(),
+}))
+
+vi.mock("../../utils/yamlLoader", () => ({
+ findIntentById: vi.fn(),
+ getCachedIntent: vi.fn(),
+}))
+
+const pathMatcher = await import("../../utils/pathMatcher")
+const yamlLoader = await import("../../utils/yamlLoader")
+
+const mockMatchesAnyGlobPattern = vi.mocked(pathMatcher.matchesAnyGlobPattern)
+const mockFindIntentById = vi.mocked(yamlLoader.findIntentById)
+const mockGetCachedIntent = vi.mocked(yamlLoader.getCachedIntent)
+
+const MOCK_INTENT = {
+ id: "INT-001",
+ name: "Add dark mode",
+ status: "IN_PROGRESS" as const,
+ owned_scope: ["src/**"],
+ constraints: [],
+ acceptance_criteria: [],
+}
+
+describe("writeFilePreHook", () => {
+ beforeEach(() => {
+ vi.clearAllMocks()
+ })
+
+ it("blocks when intentId is null", async () => {
+ const result = await writeFilePreHook(
+ { path: "src/foo.ts", content: "x" },
+ { intentId: null, workspaceRoot: "/ws" },
+ )
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("select_active_intent")
+ expect(mockFindIntentById).not.toHaveBeenCalled()
+ })
+
+ it("blocks when intent is not found in YAML", async () => {
+ mockFindIntentById.mockResolvedValue(null)
+ const result = await writeFilePreHook(
+ { path: "src/foo.ts", content: "x" },
+ { intentId: "INT-999", workspaceRoot: "/ws" },
+ )
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("INT-999")
+ expect(result.error).toContain("active_intents.yaml")
+ })
+
+ it("blocks when intent has no owned_scope", async () => {
+ mockFindIntentById.mockResolvedValue({
+ ...MOCK_INTENT,
+ owned_scope: [],
+ })
+ const result = await writeFilePreHook(
+ { path: "src/foo.ts", content: "x" },
+ { intentId: "INT-001", workspaceRoot: "/ws" },
+ )
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("no owned_scope")
+ expect(mockMatchesAnyGlobPattern).not.toHaveBeenCalled()
+ })
+
+ it("blocks when file path is out of scope", async () => {
+ mockFindIntentById.mockResolvedValue(MOCK_INTENT)
+ mockMatchesAnyGlobPattern.mockReturnValue(false)
+ const result = await writeFilePreHook(
+ { path: "other/foo.ts", content: "x" },
+ { intentId: "INT-001", workspaceRoot: "/ws" },
+ )
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("Scope Violation")
+ expect(result.error).toContain("Add dark mode")
+ expect(result.error).toContain("other/foo.ts")
+ })
+
+ it("allows write when file is in scope", async () => {
+ mockFindIntentById.mockResolvedValue(MOCK_INTENT)
+ mockMatchesAnyGlobPattern.mockReturnValue(true)
+ const result = await writeFilePreHook(
+ { path: "src/foo.ts", content: "x" },
+ { intentId: "INT-001", workspaceRoot: "/ws" },
+ )
+ expect(result.blocked).toBe(false)
+ expect(result.error).toBeUndefined()
+ expect(mockMatchesAnyGlobPattern).toHaveBeenCalledWith("src/foo.ts", ["src/**"], "/ws")
+ })
+
+ it("uses ownedScope from context when provided", async () => {
+ mockGetCachedIntent.mockReturnValue(MOCK_INTENT)
+ mockMatchesAnyGlobPattern.mockReturnValue(true)
+ const result = await writeFilePreHook(
+ { path: "app/bar.ts", content: "y" },
+ { intentId: "INT-001", workspaceRoot: "/ws", ownedScope: ["app/**"] },
+ )
+ expect(result.blocked).toBe(false)
+ expect(mockMatchesAnyGlobPattern).toHaveBeenCalledWith("app/bar.ts", ["app/**"], "/ws")
+ })
+})
diff --git a/src/hooks/preHooks/selectActiveIntent.ts b/src/hooks/preHooks/selectActiveIntent.ts
new file mode 100644
index 00000000000..28ea37c3467
--- /dev/null
+++ b/src/hooks/preHooks/selectActiveIntent.ts
@@ -0,0 +1,136 @@
+/**
+ * Pre-hook for select_active_intent
+ *
+ * Intercepts the select_active_intent call to:
+ * 1. Validate the intent ID exists in active_intents.yaml
+ * 2. Load intent context (scope, constraints, history)
+ * 3. Inject context as XML block into LLM's next prompt
+ *
+ * This implements the "Reasoning Intercept" from the two-stage state machine.
+ */
+
+import { findIntentById } from "../utils/yamlLoader"
+import type { ActiveIntent } from "../models/orchestration"
+
+export interface SelectActiveIntentPreHookArgs {
+ intent_id: string
+}
+
+export interface SelectActiveIntentPreHookResult {
+ blocked: boolean
+ context?: string
+ error?: string
+}
+
+/** Context passed by the host (task, workspace root, etc.). */
+export type SelectActiveIntentPreHookContext = {
+ task?: unknown
+ workspaceRoot?: string
+ [key: string]: unknown
+}
+
+/**
+ * Validate INT-XXX format for intent IDs
+ */
+function isValidIntentIdFormat(intentId: string): boolean {
+ return /^INT-\d{3,}$/.test(intentId)
+}
+
+/**
+ * Build XML context block from intent data
+ */
+function buildIntentContextXML(intent: ActiveIntent): string {
+ const lines: string[] = []
+ lines.push(``)
+ lines.push(` ${escapeXml(intent.name)}`)
+ lines.push(` ${escapeXml(intent.status)}`)
+
+ if (intent.owned_scope && intent.owned_scope.length > 0) {
+ lines.push(` `)
+ for (const scope of intent.owned_scope) {
+ lines.push(` ${escapeXml(scope)}`)
+ }
+ lines.push(` `)
+ }
+
+ if (intent.constraints && intent.constraints.length > 0) {
+ lines.push(` `)
+ for (const constraint of intent.constraints) {
+ lines.push(` ${escapeXml(constraint)}`)
+ }
+ lines.push(` `)
+ }
+
+ if (intent.acceptance_criteria && intent.acceptance_criteria.length > 0) {
+ lines.push(` `)
+ for (const criterion of intent.acceptance_criteria) {
+ lines.push(` ${escapeXml(criterion)}`)
+ }
+ lines.push(` `)
+ }
+
+ lines.push(``)
+ return lines.join("\n")
+}
+
+/**
+ * Escape XML special characters
+ */
+function escapeXml(text: string): string {
+ return text
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+ .replace(/'/g, "'")
+}
+
+export async function selectActiveIntentPreHook(
+ args: SelectActiveIntentPreHookArgs,
+ context: SelectActiveIntentPreHookContext,
+): Promise {
+ const { intent_id } = args
+ const workspaceRoot = context.workspaceRoot
+
+ // Validate workspace root is provided
+ if (!workspaceRoot) {
+ return {
+ blocked: true,
+ error: "Workspace root not provided. Cannot load active intents.",
+ }
+ }
+
+ // Validate INT-XXX format
+ if (!isValidIntentIdFormat(intent_id)) {
+ return {
+ blocked: true,
+ error: `Invalid intent ID format: "${intent_id}". Expected format: INT-XXX (e.g., INT-001, INT-123).`,
+ }
+ }
+
+ try {
+ // Load intent from YAML file
+ const intent = await findIntentById(workspaceRoot, intent_id)
+
+ if (!intent) {
+ return {
+ blocked: true,
+ error: `Intent "${intent_id}" not found in .orchestration/active_intents.yaml. Please ensure the intent exists and is properly formatted.`,
+ }
+ }
+
+ // Build XML context block
+ const contextXML = buildIntentContextXML(intent)
+
+ return {
+ blocked: false,
+ context: contextXML,
+ }
+ } catch (error) {
+ const errorMessage = error instanceof Error ? error.message : String(error)
+ return {
+ blocked: true,
+ error: `Failed to load intent context: ${errorMessage}`,
+ }
+ }
+}
diff --git a/src/hooks/preHooks/writeFile.ts b/src/hooks/preHooks/writeFile.ts
new file mode 100644
index 00000000000..3407b2d642f
--- /dev/null
+++ b/src/hooks/preHooks/writeFile.ts
@@ -0,0 +1,99 @@
+/**
+ * Pre-hook for write_file
+ *
+ * Enforces scope boundaries by:
+ * 1. Checking if an intent is active
+ * 2. Validating the target file is within the intent's owned_scope
+ * 3. Blocking writes outside the scope with clear error messages
+ *
+ * This is the "Gatekeeper" that prevents scope violations.
+ */
+
+import { matchesAnyGlobPattern } from "../utils/pathMatcher"
+import { findIntentById, getCachedIntent } from "../utils/yamlLoader"
+import type { ActiveIntent } from "../models/orchestration"
+
+export interface WriteFilePreHookArgs {
+ path: string
+ content: string
+}
+
+export interface WriteFilePreHookContext {
+ intentId: string | null
+ workspaceRoot: string
+ ownedScope?: string[] // Optional cached scope
+ [key: string]: unknown
+}
+
+export interface WriteFilePreHookResult {
+ blocked: boolean
+ error?: string
+ modifiedArgs?: WriteFilePreHookArgs
+}
+
+/**
+ * Pre-hook for write_file that enforces scope boundaries.
+ *
+ * This hook validates that the file being written is within the active intent's
+ * owned_scope. If not, it blocks the operation with a clear error message.
+ *
+ * @param args - The write_file arguments (path, content)
+ * @param context - Context including intentId and workspaceRoot
+ * @returns Result indicating if operation should be blocked
+ */
+export async function writeFilePreHook(
+ args: WriteFilePreHookArgs,
+ context: WriteFilePreHookContext,
+): Promise {
+ const { intentId, workspaceRoot, ownedScope } = context
+ const { path: filePath } = args
+
+ // Step 1: Check if intent is active
+ if (!intentId) {
+ return {
+ blocked: true,
+ error: "You must cite a valid active Intent ID using select_active_intent before modifying files.",
+ }
+ }
+
+ // Step 2: Load the intent (use cached scope if provided)
+ let intent: ActiveIntent | null = null
+
+ if (ownedScope) {
+ // Use cached scope but still need intent for name/error messages
+ intent = getCachedIntent(intentId) ?? (await findIntentById(workspaceRoot, intentId))
+ } else {
+ intent = await findIntentById(workspaceRoot, intentId)
+ }
+
+ if (!intent) {
+ return {
+ blocked: true,
+ error: `Intent ${intentId} not found in .orchestration/active_intents.yaml`,
+ }
+ }
+
+ // Step 3: Check if owned_scope is defined
+ const scope = ownedScope ?? intent.owned_scope
+ if (!scope || scope.length === 0) {
+ return {
+ blocked: true,
+ error: `Intent ${intentId} has no owned_scope defined. Cannot enforce scope boundaries.`,
+ }
+ }
+
+ // Step 4: Validate file path against owned_scope
+ const inScope = matchesAnyGlobPattern(filePath, scope, workspaceRoot)
+
+ if (!inScope) {
+ return {
+ blocked: true,
+ error: `Scope Violation: Intent '${intent.name}' (${intentId}) is not authorized to edit '${filePath}'. Request scope expansion or select a different intent.`,
+ }
+ }
+
+ // Step 5: All checks passed
+ return {
+ blocked: false,
+ }
+}
diff --git a/src/hooks/tools/selectActiveIntent.ts b/src/hooks/tools/selectActiveIntent.ts
new file mode 100644
index 00000000000..4004f357fa5
--- /dev/null
+++ b/src/hooks/tools/selectActiveIntent.ts
@@ -0,0 +1,23 @@
+/**
+ * select_active_intent tool
+ *
+ * This tool is called by the agent to select which intent it's working on.
+ * It triggers a pre-hook that loads the intent context from .orchestration/active_intents.yaml
+ * and injects it into the LLM's context window.
+ *
+ * @param intent_id - The ID of the intent to work on (e.g., "INT-001")
+ * @returns Context XML block with intent details
+ */
+export const selectActiveIntentTool = {
+ name: "select_active_intent",
+ description:
+ "Select an active intent to work on. Call this first before performing file-modifying or constrained actions. Returns context (scope, constraints, acceptance criteria) for the selected intent.",
+ schema: {
+ type: "object",
+ properties: {
+ intent_id: { type: "string", description: "Intent ID in INT-XXX format" },
+ },
+ required: ["intent_id"],
+ },
+ // Implementation (handle/execute) will be added in Phase 1
+} as const
diff --git a/src/hooks/utils/__tests__/commandClassification.spec.ts b/src/hooks/utils/__tests__/commandClassification.spec.ts
new file mode 100644
index 00000000000..6aca3bab696
--- /dev/null
+++ b/src/hooks/utils/__tests__/commandClassification.spec.ts
@@ -0,0 +1,84 @@
+import { describe, it, expect, vi } from "vitest"
+import { CommandType, classifyCommand, isDestructiveCommand, requiresApproval } from "../commandClassification"
+
+describe("commandClassification", () => {
+ describe("classifyCommand", () => {
+ it("returns SAFE for read-only tools", () => {
+ expect(classifyCommand("read_file")).toBe(CommandType.SAFE)
+ expect(classifyCommand("search_files")).toBe(CommandType.SAFE)
+ expect(classifyCommand("list_files")).toBe(CommandType.SAFE)
+ expect(classifyCommand("codebase_search")).toBe(CommandType.SAFE)
+ expect(classifyCommand("read_command_output")).toBe(CommandType.SAFE)
+ expect(classifyCommand("select_active_intent")).toBe(CommandType.SAFE)
+ expect(classifyCommand("access_mcp_resource")).toBe(CommandType.SAFE)
+ })
+
+ it("returns DESTRUCTIVE for file/command tools", () => {
+ expect(classifyCommand("write_to_file")).toBe(CommandType.DESTRUCTIVE)
+ expect(classifyCommand("execute_command")).toBe(CommandType.DESTRUCTIVE)
+ expect(classifyCommand("apply_diff")).toBe(CommandType.DESTRUCTIVE)
+ expect(classifyCommand("edit_file")).toBe(CommandType.DESTRUCTIVE)
+ expect(classifyCommand("apply_patch")).toBe(CommandType.DESTRUCTIVE)
+ expect(classifyCommand("update_todo_list")).toBe(CommandType.DESTRUCTIVE)
+ expect(classifyCommand("use_mcp_tool")).toBe(CommandType.DESTRUCTIVE)
+ })
+
+ it("normalizes tool name (lowercase, trim)", () => {
+ expect(classifyCommand(" READ_FILE ")).toBe(CommandType.SAFE)
+ expect(classifyCommand("Write_To_File")).toBe(CommandType.DESTRUCTIVE)
+ })
+
+ it("classifies alias write_file as DESTRUCTIVE", () => {
+ expect(classifyCommand("write_file")).toBe(CommandType.DESTRUCTIVE)
+ })
+
+ it("defaults unknown tools to DESTRUCTIVE and warns", () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+ expect(classifyCommand("unknown_tool")).toBe(CommandType.DESTRUCTIVE)
+ expect(warn).toHaveBeenCalledWith("Unknown tool classification: unknown_tool, defaulting to DESTRUCTIVE")
+ warn.mockRestore()
+ })
+ })
+
+ describe("isDestructiveCommand", () => {
+ it("returns false for safe tools", () => {
+ expect(isDestructiveCommand("read_file")).toBe(false)
+ expect(isDestructiveCommand("list_files")).toBe(false)
+ })
+
+ it("returns true for destructive tools", () => {
+ expect(isDestructiveCommand("write_to_file")).toBe(true)
+ expect(isDestructiveCommand("execute_command")).toBe(true)
+ })
+ })
+
+ describe("requiresApproval", () => {
+ it("returns true when blocked", () => {
+ expect(requiresApproval("read_file", true, false)).toBe(true)
+ expect(requiresApproval("write_to_file", true, false)).toBe(true)
+ })
+
+ it("returns true when scope violation", () => {
+ expect(requiresApproval("read_file", false, true)).toBe(true)
+ expect(requiresApproval("write_to_file", false, true)).toBe(true)
+ })
+
+ it("returns true for destructive commands when not blocked and no scope violation", () => {
+ expect(requiresApproval("write_to_file", false, false)).toBe(true)
+ expect(requiresApproval("execute_command", false, false)).toBe(true)
+ })
+
+ it("returns false for safe commands when not blocked and no scope violation", () => {
+ expect(requiresApproval("read_file", false, false)).toBe(false)
+ expect(requiresApproval("search_files", false, false)).toBe(false)
+ })
+
+ it("blocked takes precedence over tool type", () => {
+ expect(requiresApproval("read_file", true, false)).toBe(true)
+ })
+
+ it("scope violation takes precedence over safe tool", () => {
+ expect(requiresApproval("read_file", false, true)).toBe(true)
+ })
+ })
+})
diff --git a/src/hooks/utils/__tests__/errorFormatter.spec.ts b/src/hooks/utils/__tests__/errorFormatter.spec.ts
new file mode 100644
index 00000000000..5ff8c87d595
--- /dev/null
+++ b/src/hooks/utils/__tests__/errorFormatter.spec.ts
@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest"
+import { formatToolError, ErrorFormatters } from "../errorFormatter"
+
+describe("errorFormatter", () => {
+ describe("formatToolError", () => {
+ it("returns valid JSON with error, reason, and recoverable", () => {
+ const json = formatToolError("TEST_ERROR", "Something went wrong")
+ const parsed = JSON.parse(json)
+ expect(parsed.error).toBe("TEST_ERROR")
+ expect(parsed.reason).toBe("Something went wrong")
+ expect(parsed.recoverable).toBe(true)
+ expect(parsed.suggestion).toBeUndefined()
+ })
+
+ it("includes suggestion when provided", () => {
+ const json = formatToolError("ERR", "Reason", "Try again")
+ const parsed = JSON.parse(json)
+ expect(parsed.suggestion).toBe("Try again")
+ })
+
+ it("defaults recoverable to true", () => {
+ const json = formatToolError("ERR", "Reason")
+ expect(JSON.parse(json).recoverable).toBe(true)
+ })
+
+ it("accepts recoverable false", () => {
+ const json = formatToolError("ERR", "Reason", undefined, false)
+ expect(JSON.parse(json).recoverable).toBe(false)
+ })
+
+ it("outputs pretty-printed JSON (indented)", () => {
+ const json = formatToolError("A", "B")
+ expect(json).toContain("\n ")
+ })
+ })
+
+ describe("ErrorFormatters", () => {
+ it("missingIntent returns MISSING_INTENT with suggestion", () => {
+ const json = ErrorFormatters.missingIntent()
+ const parsed = JSON.parse(json)
+ expect(parsed.error).toBe("MISSING_INTENT")
+ expect(parsed.reason).toContain("No active intent")
+ expect(parsed.suggestion).toContain("select_active_intent")
+ })
+
+ it("intentNotFound includes intent ID", () => {
+ const json = ErrorFormatters.intentNotFound("INT-001")
+ const parsed = JSON.parse(json)
+ expect(parsed.error).toBe("INTENT_NOT_FOUND")
+ expect(parsed.reason).toContain("INT-001")
+ expect(parsed.reason).toContain("active_intents.yaml")
+ })
+
+ it("scopeViolation includes intent name, id, and path", () => {
+ const json = ErrorFormatters.scopeViolation("Add dark mode", "INT-001", "other/foo.ts")
+ const parsed = JSON.parse(json)
+ expect(parsed.error).toBe("SCOPE_VIOLATION")
+ expect(parsed.reason).toContain("Add dark mode")
+ expect(parsed.reason).toContain("INT-001")
+ expect(parsed.reason).toContain("other/foo.ts")
+ expect(parsed.suggestion).toContain("scope expansion")
+ })
+
+ it("userRejected includes action", () => {
+ const json = ErrorFormatters.userRejected("write_to_file")
+ const parsed = JSON.parse(json)
+ expect(parsed.error).toBe("USER_REJECTED")
+ expect(parsed.reason).toContain("write_to_file")
+ })
+
+ it("noScope includes intent ID and suggestion", () => {
+ const json = ErrorFormatters.noScope("INT-002")
+ const parsed = JSON.parse(json)
+ expect(parsed.error).toBe("NO_SCOPE_DEFINED")
+ expect(parsed.reason).toContain("INT-002")
+ expect(parsed.reason).toContain("owned_scope")
+ expect(parsed.suggestion).toContain("active_intents.yaml")
+ })
+ })
+})
diff --git a/src/hooks/utils/__tests__/yamlLoader.spec.ts b/src/hooks/utils/__tests__/yamlLoader.spec.ts
new file mode 100644
index 00000000000..765f04e493d
--- /dev/null
+++ b/src/hooks/utils/__tests__/yamlLoader.spec.ts
@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import * as fs from "fs/promises"
+import * as path from "path"
+import {
+ getActiveIntentsPath,
+ readActiveIntents,
+ findIntentById,
+ getCachedIntent,
+ clearIntentCache,
+} from "../yamlLoader"
+
+vi.mock("fs/promises", () => ({
+ readFile: vi.fn(),
+}))
+
+const mockReadFile = vi.mocked(fs.readFile)
+
+const VALID_YAML = `
+active_intents:
+ - id: INT-001
+ name: Add dark mode
+ status: IN_PROGRESS
+ owned_scope: ["src/**"]
+ constraints: []
+ acceptance_criteria: []
+ - id: INT-002
+ name: Fix login bug
+ status: PENDING
+ owned_scope: ["app/**"]
+ constraints: []
+ acceptance_criteria: []
+`.trim()
+
+describe("yamlLoader (caching)", () => {
+ beforeEach(() => {
+ clearIntentCache()
+ vi.clearAllMocks()
+ })
+
+ describe("getActiveIntentsPath", () => {
+ it("returns path under .orchestration/active_intents.yaml", () => {
+ const root = path.resolve("/workspace")
+ expect(getActiveIntentsPath(root)).toBe(path.join(root, ".orchestration", "active_intents.yaml"))
+ })
+ })
+
+ describe("readActiveIntents", () => {
+ it("returns parsed intents when file content is valid", async () => {
+ mockReadFile.mockResolvedValueOnce(VALID_YAML)
+ const root = "/ws"
+ const result = await readActiveIntents(root)
+ expect(result.active_intents).toHaveLength(2)
+ expect(result.active_intents[0].id).toBe("INT-001")
+ expect(result.active_intents[1].id).toBe("INT-002")
+ expect(mockReadFile).toHaveBeenCalledWith(path.join(root, ".orchestration", "active_intents.yaml"), "utf-8")
+ })
+
+ it("returns empty array when file read fails", async () => {
+ const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+ mockReadFile.mockRejectedValueOnce(new Error("ENOENT"))
+ const result = await readActiveIntents("/ws")
+ expect(result).toEqual({ active_intents: [] })
+ consoleSpy.mockRestore()
+ })
+
+ it("returns empty array when YAML has no active_intents array", async () => {
+ mockReadFile.mockResolvedValueOnce("other: value")
+ const result = await readActiveIntents("/ws")
+ expect(result).toEqual({ active_intents: [] })
+ })
+ })
+
+ describe("findIntentById", () => {
+ it("returns intent when found and populates cache", async () => {
+ mockReadFile.mockResolvedValueOnce(VALID_YAML)
+ const root = "/workspace"
+ const intent = await findIntentById(root, "INT-001")
+ expect(intent).not.toBeNull()
+ expect(intent?.id).toBe("INT-001")
+ expect(intent?.name).toBe("Add dark mode")
+ expect(mockReadFile).toHaveBeenCalledTimes(1)
+ })
+
+ it("returns null when intent ID not in file", async () => {
+ mockReadFile.mockResolvedValueOnce(VALID_YAML)
+ const intent = await findIntentById("/ws", "INT-999")
+ expect(intent).toBeNull()
+ })
+
+ it("uses cache on second call (same workspace, within TTL)", async () => {
+ mockReadFile.mockResolvedValue(VALID_YAML)
+ const root = "/ws"
+ const first = await findIntentById(root, "INT-001")
+ const second = await findIntentById(root, "INT-001")
+ expect(first?.id).toBe("INT-001")
+ expect(second?.id).toBe("INT-001")
+ expect(mockReadFile).toHaveBeenCalledTimes(1)
+ })
+
+ it("reloads when workspace root differs (different file path)", async () => {
+ mockReadFile.mockResolvedValueOnce(VALID_YAML).mockResolvedValueOnce(VALID_YAML)
+ await findIntentById("/ws1", "INT-001")
+ await findIntentById("/ws2", "INT-001")
+ expect(mockReadFile).toHaveBeenCalledTimes(2)
+ })
+ })
+
+ describe("getCachedIntent", () => {
+ it("returns null when cache is empty", () => {
+ expect(getCachedIntent("INT-001")).toBeNull()
+ })
+
+ it("returns intent after findIntentById has populated cache", async () => {
+ mockReadFile.mockResolvedValueOnce(VALID_YAML)
+ await findIntentById("/ws", "INT-002")
+ expect(getCachedIntent("INT-002")).not.toBeNull()
+ expect(getCachedIntent("INT-002")?.name).toBe("Fix login bug")
+ expect(getCachedIntent("INT-999")).toBeNull()
+ })
+ })
+
+ describe("clearIntentCache", () => {
+ it("clears cache so getCachedIntent returns null and next findIntentById reloads", async () => {
+ mockReadFile.mockResolvedValue(VALID_YAML)
+ await findIntentById("/ws", "INT-001")
+ expect(getCachedIntent("INT-001")).not.toBeNull()
+ clearIntentCache()
+ expect(getCachedIntent("INT-001")).toBeNull()
+ await findIntentById("/ws", "INT-001")
+ expect(mockReadFile).toHaveBeenCalledTimes(2)
+ })
+ })
+})
diff --git a/src/hooks/utils/commandClassification.ts b/src/hooks/utils/commandClassification.ts
new file mode 100644
index 00000000000..4f1cd9e5412
--- /dev/null
+++ b/src/hooks/utils/commandClassification.ts
@@ -0,0 +1,108 @@
+/**
+ * Command classification for tool execution (safe vs destructive).
+ * Used by hooks to decide approval and scope enforcement.
+ */
+
+/**
+ * Command classification types
+ */
+export enum CommandType {
+ SAFE = "SAFE",
+ DESTRUCTIVE = "DESTRUCTIVE",
+}
+
+/**
+ * Tools that only read or query; no file/system modifications.
+ */
+const SAFE_TOOLS = new Set([
+ "read_file",
+ "search_files",
+ "list_files",
+ "codebase_search",
+ "read_command_output",
+ "ask_followup_question",
+ "attempt_completion",
+ "switch_mode",
+ "new_task",
+ "select_active_intent",
+ "access_mcp_resource",
+])
+
+/**
+ * Tools that modify files, run commands, or have side effects.
+ * Includes aliases (e.g. write_file -> write_to_file) so classification works before alias resolution.
+ */
+const DESTRUCTIVE_TOOLS = new Set([
+ "write_to_file",
+ "write_file",
+ "execute_command",
+ "apply_diff",
+ "apply_patch",
+ "edit_file",
+ "edit",
+ "search_replace",
+ "search_and_replace",
+ "update_todo_list",
+ "generate_image",
+ "use_mcp_tool",
+ "skill",
+ "run_slash_command",
+ "custom_tool",
+])
+
+/**
+ * Classify a tool by name
+ * @param toolName - Name of the tool to classify
+ * @returns CommandType.SAFE or CommandType.DESTRUCTIVE
+ */
+export function classifyCommand(toolName: string): CommandType {
+ const normalizedName = toolName.toLowerCase().trim()
+
+ if (SAFE_TOOLS.has(normalizedName)) {
+ return CommandType.SAFE
+ }
+
+ if (DESTRUCTIVE_TOOLS.has(normalizedName)) {
+ return CommandType.DESTRUCTIVE
+ }
+
+ // Default to DESTRUCTIVE for unknown tools (fail-safe)
+ console.warn(`Unknown tool classification: ${toolName}, defaulting to DESTRUCTIVE`)
+ return CommandType.DESTRUCTIVE
+}
+
+/**
+ * Check if a tool is destructive
+ * @param toolName - Name of the tool
+ * @returns true if destructive, false if safe
+ */
+export function isDestructiveCommand(toolName: string): boolean {
+ return classifyCommand(toolName) === CommandType.DESTRUCTIVE
+}
+
+/**
+ * Determine if a tool execution requires user approval
+ * @param toolName - Name of the tool
+ * @param blocked - Whether the operation was blocked by pre-hook
+ * @param scopeViolation - Whether this is a scope violation
+ * @returns true if approval dialog should be shown
+ */
+export function requiresApproval(toolName: string, blocked: boolean, scopeViolation: boolean): boolean {
+ // Always require approval for blocked operations
+ if (blocked) {
+ return true
+ }
+
+ // Always require approval for scope violations (even if not blocked)
+ if (scopeViolation) {
+ return true
+ }
+
+ // Require approval for destructive commands
+ if (isDestructiveCommand(toolName)) {
+ return true
+ }
+
+ // Safe commands don't need approval
+ return false
+}
diff --git a/src/hooks/utils/contentHash.ts b/src/hooks/utils/contentHash.ts
new file mode 100644
index 00000000000..cf3aed21be7
--- /dev/null
+++ b/src/hooks/utils/contentHash.ts
@@ -0,0 +1,15 @@
+/**
+ * Hashing utilities for spatial independence
+ * SHA-256 content hashing ensures traces remain valid even if lines move
+ */
+import { createHash } from "crypto"
+
+export function sha256(content: string): string {
+ return createHash("sha256").update(content, "utf8").digest("hex")
+}
+
+export function computeContentHash(content: string, startLine: number, endLine: number): string {
+ const lines = content.split("\n")
+ const block = lines.slice(startLine - 1, endLine).join("\n")
+ return sha256(block)
+}
diff --git a/src/hooks/utils/errorFormatter.ts b/src/hooks/utils/errorFormatter.ts
new file mode 100644
index 00000000000..815d03875f8
--- /dev/null
+++ b/src/hooks/utils/errorFormatter.ts
@@ -0,0 +1,81 @@
+/**
+ * Structured error format for LLM recovery.
+ * Used by hooks and presentAssistantMessage to return parseable tool errors.
+ */
+
+/**
+ * Structured error format for LLM recovery
+ */
+export interface ToolError {
+ error: string
+ reason: string
+ suggestion?: string
+ recoverable: boolean
+}
+
+/**
+ * Format a tool error for LLM consumption
+ * @param error - Short error type/code
+ * @param reason - Detailed explanation
+ * @param suggestion - Optional suggestion for recovery
+ * @param recoverable - Whether the LLM can recover from this error
+ * @returns JSON string that LLM can parse
+ */
+export function formatToolError(
+ error: string,
+ reason: string,
+ suggestion?: string,
+ recoverable: boolean = true,
+): string {
+ const errorObject: ToolError = {
+ error,
+ reason,
+ recoverable,
+ }
+
+ if (suggestion) {
+ errorObject.suggestion = suggestion
+ }
+
+ return JSON.stringify(errorObject, null, 2)
+}
+
+/**
+ * Pre-defined error formatters for common scenarios
+ */
+export const ErrorFormatters = {
+ missingIntent: () =>
+ formatToolError(
+ "MISSING_INTENT",
+ "No active intent selected",
+ "Call select_active_intent with a valid intent ID before any file-modifying operations",
+ ),
+
+ intentNotFound: (intentId: string) =>
+ formatToolError(
+ "INTENT_NOT_FOUND",
+ `Intent ${intentId} does not exist in .orchestration/active_intents.yaml`,
+ "Check the intent ID or create it in active_intents.yaml",
+ ),
+
+ scopeViolation: (intentName: string, intentId: string, filePath: string) =>
+ formatToolError(
+ "SCOPE_VIOLATION",
+ `Intent '${intentName}' (${intentId}) cannot modify ${filePath}`,
+ "Select a different intent or request scope expansion in active_intents.yaml",
+ ),
+
+ userRejected: (action: string) =>
+ formatToolError(
+ "USER_REJECTED",
+ `User rejected the action: ${action}`,
+ "Review the action and try again with user approval",
+ ),
+
+ noScope: (intentId: string) =>
+ formatToolError(
+ "NO_SCOPE_DEFINED",
+ `Intent ${intentId} has no owned_scope defined`,
+ "Add owned_scope patterns to the intent in active_intents.yaml",
+ ),
+}
diff --git a/src/hooks/utils/pathMatcher.ts b/src/hooks/utils/pathMatcher.ts
new file mode 100644
index 00000000000..76314667f5b
--- /dev/null
+++ b/src/hooks/utils/pathMatcher.ts
@@ -0,0 +1,120 @@
+/**
+ * Path matcher utility for glob pattern matching
+ *
+ * Handles glob pattern matching with support for:
+ * - Inclusion patterns (e.g., "src/**\/*.ts")
+ * - Exclusion patterns (e.g., "!**\/*.test.ts")
+ * - Windows/Unix path normalization
+ */
+
+import * as path from "path"
+
+/**
+ * Check if a file path matches a glob pattern
+ * @param filePath - Absolute or relative path to the file
+ * @param pattern - Glob pattern (e.g. "src/**\/*.ts")
+ * @param workspaceRoot - Root directory of the workspace (for resolving relative paths)
+ * @returns true if the path matches the pattern
+ */
+export function matchesGlobPattern(filePath: string, pattern: string, workspaceRoot: string): boolean {
+ try {
+ // Normalize the file path
+ const absolutePath = path.isAbsolute(filePath) ? filePath : path.resolve(workspaceRoot, filePath)
+
+ // Normalize workspace root path
+ const normalizedWorkspaceRoot = path.normalize(workspaceRoot)
+
+ // Make path relative to workspace root
+ const relativePath = path.relative(normalizedWorkspaceRoot, absolutePath)
+
+ // Normalize separators for glob (always use forward slashes)
+ const normalizedPath = relativePath.split(path.sep).join("/")
+
+ // Check if pattern is a negation
+ const isNegation = pattern.startsWith("!")
+ const actualPattern = isNegation ? pattern.slice(1) : pattern
+
+ // Convert glob pattern to regex
+ const regexPattern = globToRegex(actualPattern)
+
+ // Test the pattern
+ const match = regexPattern.test(normalizedPath)
+
+ return isNegation ? !match : match
+ } catch (error) {
+ console.error(`Error matching glob pattern: ${error}`)
+ return false
+ }
+}
+
+/**
+ * Check if a file path matches any of the glob patterns
+ * @param filePath - Absolute or relative path to the file
+ * @param patterns - Array of glob patterns
+ * @param workspaceRoot - Root directory of the workspace
+ * @returns true if the path matches any pattern (considering negations)
+ */
+export function matchesAnyGlobPattern(filePath: string, patterns: string[], workspaceRoot: string): boolean {
+ if (!patterns || patterns.length === 0) {
+ return false
+ }
+
+ // Split into inclusion and exclusion patterns
+ const inclusions: string[] = []
+ const exclusions: string[] = []
+
+ for (const pattern of patterns) {
+ if (pattern.startsWith("!")) {
+ exclusions.push(pattern)
+ } else {
+ inclusions.push(pattern)
+ }
+ }
+
+ // If no inclusions, treat empty as no match (require explicit scope)
+ if (inclusions.length === 0) {
+ return false
+ }
+
+ // Check if path matches any inclusion
+ let matchesInclusion = false
+ for (const pattern of inclusions) {
+ if (matchesGlobPattern(filePath, pattern, workspaceRoot)) {
+ matchesInclusion = true
+ break
+ }
+ }
+
+ if (!matchesInclusion) {
+ return false
+ }
+
+ // Check if path matches any exclusion
+ for (const pattern of exclusions) {
+ if (matchesGlobPattern(filePath, pattern, workspaceRoot)) {
+ return false // Excluded
+ }
+ }
+
+ return true
+}
+
+/**
+ * Convert a glob pattern to a regex pattern
+ * Supports common glob patterns: *, **, ?, character classes
+ */
+function globToRegex(globPattern: string): RegExp {
+ // Escape special regex characters except *, ?, [, ]
+ let regex = globPattern
+ .replace(/[.+^${}()|\\]/g, "\\$&") // Escape regex special chars
+ .replace(/\*\*/g, "___DOUBLE_STAR___") // Temporarily replace **
+ .replace(/\*/g, "[^/]*") // * matches anything except /
+ .replace(/___DOUBLE_STAR___/g, ".*") // ** matches anything including /
+ .replace(/\?/g, "[^/]") // ? matches single char except /
+ .replace(/\[!/g, "[^") // [!...] becomes [^...]
+ .replace(/\[/g, "[") // Keep character classes
+ .replace(/\]/g, "]") // Keep character classes
+
+ // Anchor to start and end
+ return new RegExp(`^${regex}$`)
+}
diff --git a/src/hooks/utils/yamlLoader.ts b/src/hooks/utils/yamlLoader.ts
new file mode 100644
index 00000000000..194c2e95c1e
--- /dev/null
+++ b/src/hooks/utils/yamlLoader.ts
@@ -0,0 +1,133 @@
+/**
+ * YAML loader utility for .orchestration/active_intents.yaml
+ * Handles reading and parsing the active intents file with proper error handling.
+ * Supports in-memory caching for findIntentById; clear with clearIntentCache() or
+ * wire a file watcher on getActiveIntentsPath(workspaceRoot) to invalidate on change.
+ */
+
+import * as fs from "fs/promises"
+import * as path from "path"
+import * as yaml from "yaml"
+import { fileExistsAtPath } from "../../utils/fs"
+import type { ActiveIntentsFile, ActiveIntent } from "../models/orchestration"
+
+const ORCHESTRATION_DIR = ".orchestration"
+const ACTIVE_INTENTS_FILE = "active_intents.yaml"
+
+/** In-memory cache for loaded intents (by workspace file path + TTL) */
+interface IntentCache {
+ intents: Map
+ timestamp: number
+ filePath: string
+}
+
+let intentCache: IntentCache | null = null
+const CACHE_TTL_MS = 5000 // 5 seconds
+
+/**
+ * Get the path to the active_intents.yaml file
+ */
+export function getActiveIntentsPath(workspaceRoot: string): string {
+ return path.join(workspaceRoot, ORCHESTRATION_DIR, ACTIVE_INTENTS_FILE)
+}
+
+/**
+ * Read and parse active_intents.yaml (never throws).
+ * Returns { active_intents: [] } if file is missing or parse fails.
+ * Use for cache-friendly loading in findIntentById.
+ */
+export async function readActiveIntents(workspaceRoot: string): Promise {
+ const filePath = getActiveIntentsPath(workspaceRoot)
+ try {
+ const content = await fs.readFile(filePath, "utf-8")
+ const parsed = yaml.parse(content)
+ if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.active_intents)) {
+ return { active_intents: [] }
+ }
+ return { active_intents: parsed.active_intents as ActiveIntent[] }
+ } catch (error) {
+ console.error("Error reading active_intents.yaml:", error)
+ return { active_intents: [] }
+ }
+}
+
+/**
+ * Load and parse active_intents.yaml from the workspace
+ * Returns null if file doesn't exist (not an error - file may not be created yet)
+ * Throws if file exists but is invalid
+ */
+export async function loadActiveIntents(workspaceRoot: string): Promise {
+ const filePath = getActiveIntentsPath(workspaceRoot)
+
+ // Check if file exists
+ if (!(await fileExistsAtPath(filePath))) {
+ return null
+ }
+
+ try {
+ // Read file content
+ const content = await fs.readFile(filePath, "utf-8")
+
+ // Parse YAML
+ const parsed = yaml.parse(content)
+
+ // Validate structure - ensure it has active_intents array
+ if (!parsed || typeof parsed !== "object") {
+ throw new Error("Invalid YAML structure: expected an object")
+ }
+
+ if (!Array.isArray(parsed.active_intents)) {
+ throw new Error("Invalid YAML structure: active_intents must be an array")
+ }
+
+ // Return typed structure
+ return {
+ active_intents: parsed.active_intents as ActiveIntent[],
+ }
+ } catch (error) {
+ if (error instanceof yaml.YAMLParseError) {
+ throw new Error(`Failed to parse ${ACTIVE_INTENTS_FILE}: ${error.message}`)
+ }
+ throw error
+ }
+}
+
+/**
+ * Find an intent by ID with caching.
+ * Uses in-memory cache when the same file was loaded within CACHE_TTL_MS.
+ */
+export async function findIntentById(workspaceRoot: string, intentId: string): Promise {
+ const filePath = getActiveIntentsPath(workspaceRoot)
+ const now = Date.now()
+
+ if (intentCache && intentCache.filePath === filePath && now - intentCache.timestamp < CACHE_TTL_MS) {
+ return intentCache.intents.get(intentId) ?? null
+ }
+
+ const intentsFile = await readActiveIntents(workspaceRoot)
+ const intentMap = new Map()
+ for (const intent of intentsFile.active_intents) {
+ intentMap.set(intent.id, intent)
+ }
+ intentCache = { intents: intentMap, timestamp: now, filePath }
+ return intentMap.get(intentId) ?? null
+}
+
+/**
+ * Get a cached intent by ID without reloading the file.
+ * Returns null if cache is empty or intent is not in cache.
+ */
+export function getCachedIntent(intentId: string): ActiveIntent | null {
+ if (!intentCache) {
+ return null
+ }
+ return intentCache.intents.get(intentId) ?? null
+}
+
+/**
+ * Clear the intent cache. Call after editing .orchestration/active_intents.yaml
+ * or wire to a file watcher on getActiveIntentsPath(workspaceRoot) for automatic invalidation.
+ */
+export function clearIntentCache(): void {
+ intentCache = null
+}
diff --git a/src/shared/tools.ts b/src/shared/tools.ts
index 491ba693611..03e1c0501f8 100644
--- a/src/shared/tools.ts
+++ b/src/shared/tools.ts
@@ -115,6 +115,7 @@ export type NativeToolArgs = {
update_todo_list: { todos: string }
use_mcp_tool: { server_name: string; tool_name: string; arguments?: Record }
write_to_file: { path: string; content: string }
+ select_active_intent: { intent_id: string }
// Add more tools as they are migrated to native protocol
}
@@ -289,6 +290,7 @@ export const TOOL_DISPLAY_NAMES: Record = {
skill: "load skill",
generate_image: "generate images",
custom_tool: "use custom tools",
+ select_active_intent: "select active intent",
} as const
// Define available tool groups.
@@ -314,6 +316,7 @@ export const TOOL_GROUPS: Record = {
// Tools that are always available to all modes.
export const ALWAYS_AVAILABLE_TOOLS: ToolName[] = [
+ "select_active_intent", // Orchestration: must be available so model can select intent before other tools
"ask_followup_question",
"attempt_completion",
"switch_mode",
diff --git a/test/phase2/fixtures/index.ts b/test/phase2/fixtures/index.ts
new file mode 100644
index 00000000000..f94b70d16ce
--- /dev/null
+++ b/test/phase2/fixtures/index.ts
@@ -0,0 +1,55 @@
+import * as fs from "fs/promises"
+import * as path from "path"
+import * as os from "os"
+
+let lastWorkspaceRoot: string | null = null
+
+/**
+ * Create a temporary workspace directory for Phase 2 integration tests.
+ * Optionally creates .orchestration/active_intents.yaml with a test intent.
+ */
+export async function setupTestWorkspace(): Promise {
+ const workspaceRoot = path.join(
+ os.tmpdir(),
+ `roo-phase2-test-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+ )
+ await fs.mkdir(workspaceRoot, { recursive: true })
+
+ const orchestrationDir = path.join(workspaceRoot, ".orchestration")
+ await fs.mkdir(orchestrationDir, { recursive: true })
+
+ const activeIntentsYaml = `
+active_intents:
+ - id: INT-001
+ name: Test Intent
+ status: IN_PROGRESS
+ owned_scope:
+ - "src/**"
+ - "tests/**"
+ - "!**/*.test.ts"
+ constraints: []
+ acceptance_criteria: []
+`.trim()
+
+ await fs.writeFile(path.join(orchestrationDir, "active_intents.yaml"), activeIntentsYaml, "utf-8")
+
+ lastWorkspaceRoot = workspaceRoot
+ return workspaceRoot
+}
+
+/**
+ * Remove the temporary workspace directory.
+ * Pass the same path returned from setupTestWorkspace, or omit to clean last created.
+ */
+export async function cleanupTestWorkspace(workspaceRoot?: string): Promise {
+ const toRemove = workspaceRoot ?? lastWorkspaceRoot
+ if (!toRemove) return
+ try {
+ await fs.rm(toRemove, { recursive: true, force: true })
+ } catch {
+ // Ignore if already removed or missing
+ }
+ if (toRemove === lastWorkspaceRoot) {
+ lastWorkspaceRoot = null
+ }
+}
diff --git a/test/phase2/integration/scopeEnforcement.test.ts b/test/phase2/integration/scopeEnforcement.test.ts
new file mode 100644
index 00000000000..2110ebaffd8
--- /dev/null
+++ b/test/phase2/integration/scopeEnforcement.test.ts
@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
+import * as vscode from "vscode"
+import { writeFilePreHook } from "../../../src/hooks/preHooks/writeFile"
+import { setupTestWorkspace, cleanupTestWorkspace } from "../../fixtures"
+
+// Task is not constructed (constructor requires provider, etc.); we use a minimal context object.
+// To run: from repo root use the copy under src (pnpm --filter roo-cline test -- __tests__/phase2/integration)
+type TaskLike = { currentIntentId: string | null; currentIntentScope: string[] }
+
+vi.mock("vscode", () => ({
+ window: {
+ showWarningMessage: vi.fn(),
+ },
+}))
+
+describe("Phase 2 Integration: Scope Enforcement", () => {
+ let task: TaskLike
+ let workspaceRoot: string
+
+ beforeEach(async () => {
+ workspaceRoot = await setupTestWorkspace()
+ task = {
+ currentIntentId: "INT-001",
+ currentIntentScope: ["src/**", "tests/**", "!**/*.test.ts"],
+ }
+ })
+
+ afterEach(async () => {
+ await cleanupTestWorkspace(workspaceRoot)
+ vi.clearAllMocks()
+ })
+
+ it("should allow writing to files in scope", async () => {
+ const result = await writeFilePreHook(
+ { path: "src/utils/helper.ts", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(false)
+ expect(result.error).toBeUndefined()
+ })
+
+ it("should block writing to files out of scope", async () => {
+ const result = await writeFilePreHook(
+ { path: "docs/README.md", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("Scope Violation")
+ })
+
+ it("should respect exclusion patterns", async () => {
+ const result = await writeFilePreHook(
+ { path: "src/helper.test.ts", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("Scope Violation")
+ })
+
+ it("should block when no intent is active", async () => {
+ task.currentIntentId = null
+
+ const result = await writeFilePreHook(
+ { path: "src/utils/helper.ts", content: "test" },
+ {
+ intentId: task.currentIntentId,
+ workspaceRoot,
+ ownedScope: task.currentIntentScope,
+ },
+ )
+
+ expect(result.blocked).toBe(true)
+ expect(result.error).toContain("must cite a valid active Intent ID")
+ })
+
+ it("should show approval dialog for blocked operations", async () => {
+ vi.mocked(vscode.window.showWarningMessage).mockResolvedValue("Approve Anyway" as any)
+
+ const { requiresApproval } = await import("../../../src/hooks/utils/commandClassification")
+
+ const needsApproval = requiresApproval("write_to_file", true, true)
+ expect(needsApproval).toBe(true)
+ })
+
+ it("should return structured errors for rejected operations", async () => {
+ vi.mocked(vscode.window.showWarningMessage).mockResolvedValue("Reject" as any)
+
+ const { ErrorFormatters } = await import("../../../src/hooks/utils/errorFormatter")
+
+ const error = ErrorFormatters.scopeViolation("Test Intent", "INT-001", "out-of-scope.ts")
+ const parsed = JSON.parse(error)
+
+ expect(parsed.error).toBe("SCOPE_VIOLATION")
+ expect(parsed.reason).toContain("Test Intent")
+ expect(parsed.suggestion).toBeDefined()
+ expect(parsed.recoverable).toBe(true)
+ })
+})
diff --git a/test/vitest.config.ts b/test/vitest.config.ts
new file mode 100644
index 00000000000..f38f6e8d689
--- /dev/null
+++ b/test/vitest.config.ts
@@ -0,0 +1,21 @@
+import { defineConfig } from "vitest/config"
+import path from "path"
+
+const root = path.resolve(__dirname, "..")
+
+export default defineConfig({
+ root,
+ test: {
+ globals: true,
+ environment: "node",
+ include: ["test/phase2/**/*.test.ts"],
+ setupFiles: [path.join(root, "src/vitest.setup.ts")],
+ testTimeout: 20_000,
+ hookTimeout: 20_000,
+ },
+ resolve: {
+ alias: {
+ vscode: path.join(root, "src/__mocks__/vscode.js"),
+ },
+ },
+})