@benzotti/jdi 0.1.46 → 0.1.49

package/dist/index.js

@@ -12791,7 +12791,7 @@ var stateCommand = defineCommand({
 // package.json
 var package_default = {
   name: "@benzotti/jdi",
-  version: "0.1.46",
+  version: "0.1.49",
   description: "JDI - Context-efficient AI development framework for Claude Code",
   type: "module",
   bin: {

package/framework/agents/jdi-planner.md

@@ -22,7 +22,7 @@ Do not add unrelated extras (tooling, testing, linting, CI) unless the user expl
 2. **DO investigate the full scope of the request.** "Scope discipline" means no unrelated additions — it does NOT mean ignoring requirements that are clearly implied by the request. If the user asks for a UI view with specific columns, you must verify those columns exist in the backend response, and plan to add them if they don't.
 3. **When reference PRs/tickets are provided, analyse them thoroughly.** Read the actual diff, files changed, patterns used, columns/fields added, routes created, and data flow. The user provides reference PRs so you follow the same pattern — extract the full pattern, don't just skim.
 4. **When the user says "backend is already done", verify it.** Read the actual API endpoint, check what fields it returns, and confirm they match the frontend requirements. If there's a gap, include it in the plan.
-5. **Do not make subjective decisions.** If something is ambiguous (e.g. folder structure, routing library, state management), list it as an open question and ask the user — do not guess.
+5. **Do not make subjective decisions.** If something is ambiguous (e.g. folder structure, routing library, state management), list it as an open question and ask the user — do not guess. If pre-answered questions cover a decision point, use the pre-answered value rather than listing it as open.
 6. **Suggest optional additions separately.** After presenting the plan, list 3-5 common additions the user might want. These are suggestions, NOT part of the plan.
 7. **Same request = same plan.** Two identical requests must produce structurally identical plans. Achieve this by following the templates exactly and not improvising.
 
@@ -33,11 +33,27 @@ Before planning, ALWAYS:
 2. Apply any team preferences found (e.g. "always use path aliases", "prefer Zustand over Redux")
 3. Learnings override your defaults — if the team has a preference, follow it
 
+## CRITICAL: Respect Pre-Answered Questions
+
+When the spawn prompt includes a `PRE_ANSWERED_QUESTIONS` block:
+
+1. Parse each question-id and chosen answer
+2. Treat these as settled decisions — do NOT re-ask them
+3. Do NOT surface them as "Open Questions" in the plan
+4. Reference them in relevant task descriptions as
+   "Decision: {question} → {answer} (pre-plan gate)"
+5. Only surface NEW questions that genuinely emerged DURING
+   planning and could not have been anticipated from the
+   feature description alone
+
+Pre-answered questions represent explicit user choices made via
+interactive prompts. Overriding them silently is forbidden.
+
 ## CRITICAL: File Writing is Mandatory
 
 You MUST write files using Write/Edit tools. Returning plan content as text is NOT acceptable.
 
-**SANDBOX OVERRIDE:** Plan file creation is an EXCEPTION to AgentBase sandbox rules. You MUST use the Write tool to create plan files directly — do NOT defer them to `files_to_create`. Plan files WILL persist when written via the Write tool. This override applies ONLY to `.jdi/plans/` and `.jdi/config/` files listed below.
+You MUST use the Write tool to create plan files directly. You have full file permissions (`mode: "bypassPermissions"`).
 
 Required files (SPLIT FORMAT — one file per task):
 1. `.jdi/plans/{phase}-{plan}-{slug}.plan.md` (index file — manifest table only, NO inline task details)

package/framework/agents/jdi-programmer.md

@@ -73,7 +73,7 @@ For each task:
 
 ### Step 4: Plan Completion
 - Run plan-level verification
-- Generate SUMMARY.md (via `files_to_create`)
+- Generate SUMMARY.md (via Write tool)
 - Update final state
 
 ---
@@ -91,10 +91,8 @@ one_liner: "{brief summary}"
 next_action: {what should happen next}
 files_modified:
   - path/to/edited/file1.ts
-files_to_create:
-  - path: ".jdi/plans/{phase}-{plan}-{slug}.summary.md"
-    content: |
-      {full summary content}
+files_created:
+  - .jdi/plans/{phase}-{plan}-{slug}.summary.md
 commits_pending:
   - message: "{conventional commit message}"
     files: [path/to/file1.ts]

package/framework/agents/jdi-researcher.md

@@ -55,6 +55,78 @@ Write to `.jdi/research/{topic}-research.md`.
 
 ---
 
+## Pre-Plan Discovery Mode
+
+**Trigger:** Spawned by `create-plan` with mode flag `--pre-plan-discovery`.
+
+This is a lightweight, fast mode — NOT a full research report. The goal is to identify decision points in the codebase that the user should resolve before planning begins.
+
+### Constraints
+
+- **Budget:** Read at most 15 files
+- **Output:** Under 400 words
+- **No file writes** — do not create `.jdi/research/` files in this mode
+
+### Input
+
+- Feature description
+- `PRE_DISCOVERED_CONTEXT` (scaffolding already read by the orchestrator)
+
+### What to Look For
+
+Scan the codebase for decision points relevant to the feature:
+
+- **Competing patterns** — e.g. two state management approaches, two API styles, inconsistent naming conventions
+- **Missing data/fields** — the feature implies data that doesn't exist yet in current schemas/models
+- **Architectural choices** — where to put new code, which module to extend, whether to create a new module
+- **Dependency/library choices** — feature needs a capability the project doesn't have yet
+- **Existing conventions** — patterns that constrain the approach (established test patterns, folder structure, naming)
+
+### Output Format
+
+Return a structured YAML `RESEARCH_QUESTIONS` block:
+
+```yaml
+RESEARCH_DISCOVERY:
+  research_questions:
+    - id: RQ-01
+      question: "The codebase uses both X and Y for Z — which should this feature follow?"
+      header: "PATTERN"
+      options:
+        - label: "Use X"
+          description: "Consistent with src/foo/ — the newer pattern"
+        - label: "Use Y"
+          description: "Consistent with src/bar/ — the legacy pattern"
+      context: "Found X in src/foo/*.ts (3 files), Y in src/bar/*.ts (7 files)"
+    - id: RQ-02
+      question: "..."
+      header: "..."
+      options:
+        - label: "..."
+          description: "..."
+      context: "..."
+  research_context: "Brief summary of what was found for the planner"
+```
+
+Each question must include:
+- `id`: Sequential ID (`RQ-01`, `RQ-02`, ...)
+- `question`: Clear, specific question text
+- `header`: Category tag, max 12 chars (`PATTERN`, `STACK`, `DATA`, `APPROACH`, `BOUNDARY`)
+- `options`: 2-4 options with `label` and `description` grounded in codebase findings
+- `context`: Brief note on what evidence was found
+
+### If No Questions Found
+
+Return an empty array with a brief context summary. This is a valid outcome for clear-cut features:
+
+```yaml
+RESEARCH_DISCOVERY:
+  research_questions: []
+  research_context: "Scanned src/components/ and src/api/. Single pattern in use (React Query + Zustand). No competing approaches or ambiguous extension points found."
+```
+
+---
+
 ## Structured Returns
 
 ```yaml

package/framework/commands/build.md

@@ -1,7 +1,7 @@
 ---
 name: build
 description: "JDI: Guided setup and state-aware entry point for new and returning users"
-allowed-tools: Read, Glob, Grep, Bash
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion
 argument-hint: "[no arguments]"
 context: |
   !cat .jdi/config/state.yaml 2>/dev/null | head -20
@@ -51,6 +51,19 @@ If NEITHER condition is true, the user is new — proceed to step 3.
 
 Present exactly these four options. Frame them for software projects — no game-specific language, no engine/prototype vocabulary.
 
+**Preferred: AskUserQuestion.** Use AskUserQuestion with:
+- **header:** `STAGE`
+- **question:** `Which of these describes your situation best?`
+- **options:**
+  1. label: `No idea yet` — description: `I want to figure out what to build`
+  2. label: `Vague idea` — description: `I know the problem but not the shape of the solution`
+  3. label: `Clear concept` — description: `I know what I want to build and roughly how`
+  4. label: `Existing work` — description: `There's already code or scaffolding I want to continue from`
+
+The automatic "Other" option covers situations that don't fit. Route based on the selected option — same branch logic as step 4.
+
+**Fallback (if AskUserQuestion is unavailable):** Present as plain markdown instead:
+
 > **Welcome to JDI.**
 >
 > Before I suggest anything, I'd like to understand where you are. Which of these describes your situation best?
@@ -98,7 +111,16 @@ Each branch below is its own script. Follow the one that matches the user's choi
 
 ### 5. Confirm Before Handing Off
 
-After presenting your recommendation, ask this exact question:
+After presenting your recommendation, confirm with the user before proceeding.
+
+**Preferred: AskUserQuestion.** Use AskUserQuestion with:
+- **header:** `NEXT`
+- **question:** `Ready to proceed?`
+- **options:**
+  1. label: `{recommended command}` — description: `Start with the recommended next step`
+  2. label: `Something else` — description: `I want to do something different`
+
+**Fallback (if AskUserQuestion is unavailable):** Ask as plain text instead:
 
 > "Would you like to start with **{recommended command}**, or something else?"
 

package/framework/commands/commit.md

@@ -37,8 +37,9 @@ If there are unstaged changes but nothing is staged, ask the user:
 Spawn the committer via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text (see `framework/jdi.md` Critical Constraints):
 
 ```
-Task(
+Agent(
   subagent_type="general-purpose",
+  mode="bypassPermissions",
   prompt="You are jdi-committer. Read .jdi/framework/agents/jdi-committer.md for
   your full role and instructions. Also read .jdi/framework/components/meta/AgentBase.md
   for the JDI base protocol. If your spec has requires_components in frontmatter,

package/framework/commands/create-plan.md

@@ -1,7 +1,7 @@
 ---
 name: create-plan
 description: "JDI: Create implementation plan"
-allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task, AskUserQuestion
 argument-hint: "<feature to plan> [--worktree | --worktree-lightweight | --status]"
 context: |
   !cat .jdi/config/state.yaml 2>/dev/null | head -25
@@ -12,7 +12,7 @@ context: |
 
 Create an implementation plan using a single planner agent (includes research). Deterministic workflow — every invocation follows the same numbered steps, in order, without skipping.
 
-**This skill follows `<JDI:StrictnessProtocol />` and `<JDI:SilentDiscovery />`. Read those components before executing any step below.**
+**This skill follows `<JDI:StrictnessProtocol />`, `<JDI:SilentDiscovery />`, and `<JDI:InteractiveGate />`. Read those components before executing any step below.**
 
 ---
 
@@ -89,14 +89,40 @@ If the feature description looks trivial (single file, <30 minutes, no architect
 
 **Wait for the user's answer. Do not proceed until they respond.** If they pick quick, STOP — do not spawn the planner.
 
+### 4a. Pre-Plan Research Spawn
+
+Spawn `jdi-researcher` in `pre-plan-discovery` mode via `Agent(subagent_type="general-purpose", mode="bypassPermissions")`. The spawn prompt MUST include:
+
+- The feature description (`$ARGUMENTS`)
+- `PRE_DISCOVERED_CONTEXT` as a YAML block
+- Mode: `--pre-plan-discovery`
+- Spec path: `.jdi/framework/agents/jdi-researcher.md`
+- Instruction: _"Scan the codebase for decision points relevant to this feature. Return RESEARCH_QUESTIONS YAML. Budget: <=15 file reads, <400 word report."_
+
+Store the return as `RESEARCH_DISCOVERY`.
+
+### 4b. Pre-Planning Questions (Interactive Gate)
+
+Execute `<JDI:InteractiveGate mode="pre-plan" />`:
+
+1. Collect surface-level ambiguity questions from the feature description
+2. Collect research-driven questions from `RESEARCH_DISCOVERY.research_questions`
+3. Merge, deduplicate, prioritise (research-driven first)
+4. If questions exist, present via `AskUserQuestion`. Wait for answers.
+5. If zero questions from both sources, skip silently.
+
+Store answers as `PRE_ANSWERED_QUESTIONS`.
+
 ### 5. Spawn Planner
 
-Spawn `jdi-planner` via `Task(subagent_type="general-purpose")`. The spawn prompt MUST include:
+Spawn `jdi-planner` via `Agent(subagent_type="general-purpose", mode="bypassPermissions")`. The spawn prompt MUST include:
 
 - The feature description (`$ARGUMENTS`)
 - `PRE_DISCOVERED_CONTEXT` as a YAML block — planner must NOT re-read scaffolding
 - `AVAILABLE_AGENTS` catalogue — planner pins specialists via AgentRouter
-- Explicit instruction: _"Do NOT re-prompt the user for anything already in PRE_DISCOVERED_CONTEXT. Surface open questions ONLY for facts you cannot infer."_
+- `PRE_ANSWERED_QUESTIONS` YAML block (from step 4b, if any questions were asked)
+- `RESEARCH_DISCOVERY.research_context` (so the planner doesn't re-scan what the researcher already found)
+- Explicit instruction: _"Do NOT re-prompt the user for anything already in PRE_DISCOVERED_CONTEXT. These questions were already answered by the user — do NOT re-ask them. The research context below summarises what was found in the codebase — use it, don't re-scan. Only surface NEW questions that emerged during planning that could not have been anticipated."_
 - Spec path: `.jdi/framework/agents/jdi-planner.md`
 
 The planner creates split plan files (index `.plan.md` + per-task `.T{n}.md` files) directly via Write tool (sandbox override for plan files). It writes `available_agents:` into the index frontmatter and pins an `agent:` field in every task file.
@@ -114,7 +140,7 @@ If any check fails, STOP and report the gap to the user. Do not advance state on
 
 ### 7. Execute Deferred Ops
 
-If the planner returned `files_to_create` (scaffolding it could not write inside its sandbox), create those files now via the Write tool.
+The planner creates files directly (it has `bypassPermissions`). If any `files_to_create` entries were returned, create them now via the Write tool as a fallback.
 
 ### 8. Update State
 
@@ -156,7 +182,9 @@ Pre-written responses for known deviations. When one applies, follow the scripte
 |-----------|----------|
 | Scaffolding files missing (`.jdi/PROJECT.yaml` etc.) | Planner creates them from `framework/templates/` in step 5. Do NOT ask the user for values the template's defaults cover. |
 | `.claude/agents/` empty on both levels | Set `AVAILABLE_AGENTS = []`, note in summary, and proceed. The planner falls back to tech-stack defaults. |
-| Feature description is vague ("improve X") | Ask 2-3 targeted follow-ups BEFORE spawning the planner. Do not waste a planner invocation on an underspecified prompt. |
+| Feature description is vague ("improve X") | Steps 4a + 4b handle this: the researcher discovers codebase decision points, and the InteractiveGate surfaces ambiguity questions via AskUserQuestion. Do not waste a planner invocation on an underspecified prompt. |
+| Pre-plan researcher returns zero questions | Skip step 4b if surface-level analysis also yields zero questions. Proceed directly to step 5. This is expected for clear features. |
+| Pre-plan researcher returns >4 questions | Batch into multiple AskUserQuestion calls (max 4 per call). Present highest-priority questions first. |
 | Worktree flag but worktree already exists | Ask the user: reuse the existing worktree, or pick a new name? Do not silently proceed. |
 | `--status` with no current plan | Output "No current plan — run `/jdi:create-plan \"<feature>\"` to create one" and STOP. |
 | Planner returns without writing any files | STOP, report the failure, do NOT advance state. Ask the user to re-invoke or debug. |

package/framework/commands/generate-pr.md

@@ -45,8 +45,9 @@ Run `gh pr list --head {current-branch}`. If a PR already exists for this branch
 Spawn the specialist via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
 
 ```
-Task(
+Agent(
   subagent_type="general-purpose",
+  mode="bypassPermissions",
   prompt="You are jdi-pr-generator. Read .jdi/framework/agents/jdi-pr-generator.md
   for your full role and instructions. Also read
   .jdi/framework/components/meta/AgentBase.md for the JDI base protocol.

package/framework/commands/implement-plan.md

@@ -1,7 +1,7 @@
 ---
 name: implement-plan
 description: "JDI: Execute implementation plan"
-allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task, AskUserQuestion
 argument-hint: "[--team | --single | --dry-run | --skip-qa]"
 context: |
   !cat .jdi/config/state.yaml 2>/dev/null | head -30
@@ -101,15 +101,17 @@ Run `bun run src/index.ts state executing` (in installed projects: `npx jdi stat
 
 ### 8. Spawn and Execute
 
-**Platform constraint:** JDI specialists (`source: jdi`) are NOT registered Claude Code subagents and MUST be spawned via `subagent_type="general-purpose"` with identity injected via prompt text (`"You are {agent}. Read .jdi/framework/agents/{agent}.md..."`). Registered Claude Code subagents (`source: claude-code`) are spawned directly by name. See `framework/jdi.md` Critical Constraints and `framework/components/meta/AgentRouter.md` §4.
+**Platform constraints:**
+- JDI specialists (`source: jdi`) are NOT registered Claude Code subagents and MUST be spawned via `subagent_type="general-purpose"` with identity injected via prompt text. Registered Claude Code subagents (`source: claude-code`) are spawned directly by name. See `framework/jdi.md` Critical Constraints.
+- **All agents MUST be spawned with `mode: "bypassPermissions"`** — agents run in background and cannot prompt the user for Write/Edit approval. Without this mode, agents will be blocked on permission prompts and fail silently.
 
 **Single-agent mode:**
-- `source: jdi` → `Task(subagent_type="general-purpose", prompt="You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md... PLAN: {index-path}")`
-- `source: claude-code` → `Task(subagent_type="{plan.primary_agent}", prompt="<standard spawn prompt> PLAN: {index-path}")`
+- `source: jdi` → `Agent(subagent_type="general-purpose", mode="bypassPermissions", prompt="You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md... PLAN: {index-path}")`
+- `source: claude-code` → `Agent(subagent_type="{plan.primary_agent}", mode="bypassPermissions", prompt="<standard spawn prompt> PLAN: {index-path}")`
 
 For split plans, the agent reads task files one at a time via the `file:` field in `state.yaml`.
 
-**Agent Teams mode:** Spawn ONE Task call per task using the source-aware pattern above. Pass `TASK_FILE: {task-file-path}` so the agent loads only its assigned task.
+**Agent Teams mode:** Spawn ONE Agent call per task using the source-aware pattern above. Pass `TASK_FILE: {task-file-path}` so the agent loads only its assigned task. Every spawn MUST include `mode: "bypassPermissions"`.
 
 **Prompt scoping rules (non-negotiable):**
 - One task = one spawn. Never bundle multiple tasks into one prompt.
@@ -120,6 +122,27 @@ For split plans, the agent reads task files one at a time via the `file:` field
 
 **Wave-based execution:** honour `waves:` from the plan frontmatter. Spawn all tasks in wave N in parallel; wait for all returns before starting wave N+1.
 
+### 8a. Blocker Resolution
+
+When an agent returns `status: blocked`:
+
+1. Read the blocker context from the agent's structured return
+   (blocker_reason, blocker_context, suggested_options if any)
+2. Execute `<JDI:InteractiveGate mode="blocker-resolution" />`
+3. Present the blocker to the user via AskUserQuestion:
+   - header: "BLOCKED"
+   - question: "{task_name} is blocked: {blocker_reason}"
+   - options (pick 2-4 based on context):
+     a) Resolve with approach X (if agent suggested options)
+     b) Skip this task and continue
+     c) Modify the task scope
+     d) Halt the plan
+4. Route based on answer:
+   - Resolve: re-spawn the agent with the resolution context
+   - Skip: advance-task with skip status, continue to next
+   - Modify: enter inline edit of the task file, then re-spawn
+   - Halt: stop execution, enter review loop at step 14
+
 ### 9. Advance Task State
 
 After each task's programmer returns successfully, run:
@@ -141,7 +164,7 @@ After each task's programmer returns, invoke `jdi-qa-tester` in `post-task-verif
 
 ### 11. Execute Deferred Ops
 
-Collect `files_to_create` returns from every agent and execute them via Write tool. Apply any pending commit operations. Do NOT skip this step — sandbox-returned artefacts are real work.
+Agents create files directly (they have `bypassPermissions`), so `files_to_create` should be empty. If any agent does return `files_to_create` entries, create them via Write tool. Execute `commits_pending` via `git add` + `git commit`. Do NOT skip this step.
 
 ### 12. Run Verification Gates
 
@@ -185,7 +208,8 @@ Pre-written responses for known deviations. When one applies, follow the scripte
 | Plan status is not `approved` | STOP at step 2. Tell the user to approve the plan first. Do NOT force-advance. |
 | Pinned agent not installed | Downgrade to `general-purpose`, record the downgrade, continue. Surface in the final summary. |
 | Task file missing (listed in `task_files:` but not on disk) | STOP. Report the missing file. Do NOT advance state. |
-| Programmer returns with `status: blocked` | HALT the plan. Do NOT advance task state. Surface the blocker to the user and wait. |
+| Programmer returns with `status: blocked` | Enter step 8a (Blocker Resolution). Do NOT advance task state. Present the blocker interactively via AskUserQuestion and route based on user's choice. |
+| Agent suggests resolution options in structured return | Include agent's suggestions as the first AskUserQuestion options in step 8a, before the default options (skip/modify/halt). |
 | QA verification S1 or S2 failure | HALT the plan immediately. Record the failure in state. Wait for user direction before continuing. |
 | Verification gate failure at step 12 | STOP before completing. Report the failure, enter review loop. Do NOT advance state to `complete`. |
 | `--dry-run` with no changes needed | Output "no-op: plan is already at target state" and STOP. |

package/framework/commands/pr-feedback.md

@@ -32,8 +32,9 @@ Run `gh api repos/{owner}/{repo}/pulls/{number}/comments` (or equivalent) to con
 Spawn the specialist via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
 
 ```
-Task(
+Agent(
   subagent_type="general-purpose",
+  mode="bypassPermissions",
   prompt="You are jdi-pr-feedback. Read .jdi/framework/agents/jdi-pr-feedback.md
   for your full role and instructions. Also read
   .jdi/framework/components/meta/AgentBase.md for the JDI base protocol.

package/framework/commands/pr-review.md

@@ -42,8 +42,9 @@ Run `gh pr view {number}` to confirm the PR is reachable. If `gh` errors, STOP a
 Spawn the reviewer via Task tool. JDI specialists spawn as `general-purpose` with identity injected via prompt text:
 
 ```
-Task(
+Agent(
   subagent_type="general-purpose",
+  mode="bypassPermissions",
   prompt="Read .jdi/framework/components/meta/AgentBase.md for the base protocol.
 
   Read learnings before reviewing — these represent the team's coding standards

package/framework/components/meta/AgentBase.md

@@ -55,47 +55,43 @@ Return a YAML block with `status`, agent-specific fields, and `next_action` afte
 
 <section name="Sandbox">
 
-## Sandbox Awareness
+## File Operations
 
-You run in a sandboxed environment. Key constraints:
+You are spawned with full file permissions (`mode: "bypassPermissions"`). All standard tools work:
 
-| Operation | Tool / Method | Persists? | Notes |
-|-----------|--------------|-----------|-------|
-| Edit existing files | Edit tool | **Yes** | Primary way to modify code |
-| Delete files | Bash `rm` | **Yes** | Destructive — use with care |
-| Create new files | Write tool / Bash `cat >` | **No** | Silently fails — report in `files_to_create` |
-| Git commits | Bash `git commit` | **No** | Silently fails — report in `commits_pending` |
-| Read files | Read tool | **Yes** | Works reliably |
-| Run commands | Bash tool | **Yes** | Output is real; side-effects vary |
+| Operation | Tool / Method | Notes |
+|-----------|--------------|-------|
+| Edit existing files | Edit tool | Primary way to modify code |
+| Create new files | Write tool | Works — create files directly |
+| Delete files | Bash `rm` | Destructive — use with care |
+| Read files | Read tool | Works reliably |
+| Run commands | Bash tool | Output is real; side-effects vary |
 
 **Key Rules:**
-1. **NEVER attempt `git commit`** — it will appear to succeed but produces no real commit.
-2. **NEVER create new files** via Write tool or Bash redirection — they will not persist.
-3. **ALWAYS use the Edit tool** to modify existing files.
-4. **Report pending work** in structured returns using `files_to_create` and `commits_pending`.
+1. **Use the Edit tool** to modify existing files (read first).
+2. **Use the Write tool** to create new files directly — do NOT defer to the orchestrator.
+3. **Do NOT run `git commit`** — the orchestrator handles commits after all tasks complete. Report commits needed in `commits_pending`.
 
-### Structured Returns for Sandbox-Limited Operations
+### Structured Returns
 
 ```yaml
-files_to_create:
-  - path: "path/to/new/file.md"
-    content: |
-      Full file content here...
 files_modified:
   - path/to/edited/file1.ts
+files_created:
+  - path/to/new/file.md
 commits_pending:
   - message: |
       feat(01-01-T1): implement feature X
     files:
       - path/to/modified/file1.ts
+      - path/to/new/file.md
 ```
 
 ### Orchestrator Post-Agent Handling
 
-After a sandboxed agent completes, the orchestrator must:
-1. Create files from `files_to_create` using Write tool
-2. Execute commits from `commits_pending` via `git add` + `git commit`
-3. Record real commit hashes in `.jdi/config/state.yaml`
+After an agent completes, the orchestrator:
+1. Executes commits from `commits_pending` via `git add` + `git commit`
+2. Records real commit hashes in `.jdi/config/state.yaml`
 
 </section>
 
@@ -109,7 +105,7 @@ When operating within an Agent Team (spawned by coordinator):
 
 1. **Claim tasks**: Call TaskList, find tasks assigned to you
 2. **Execute**: Read task description, implement using Edit tool
-3. **Report**: SendMessage to coordinator with structured return (include `files_modified`, `files_to_create`, `commits_pending`)
+3. **Report**: SendMessage to coordinator with structured return (include `files_modified`, `files_created`, `commits_pending`)
 4. **Complete**: TaskUpdate(status: "completed") AFTER sending results
 5. **Next**: Check TaskList for more assigned tasks. If none, go idle.
 

package/framework/components/meta/AgentRouter.md

@@ -212,17 +212,20 @@ correct pattern for that source.
 
 ### Source-aware spawn pattern
 
-| `source` in catalogue | `subagent_type` | Identity mechanism |
-|----------------------|-----------------|--------------------|
-| `jdi` | `"general-purpose"` | Prompt text: `"You are {task.agent}. Read .jdi/framework/agents/{task.agent}.md for instructions."` |
-| `claude-code` | `"{task.agent}"` | Native — Claude Code loads the agent spec from `.claude/agents/` |
+**All agents MUST be spawned with `mode: "bypassPermissions"`** so they can create and edit files without blocking on permission prompts. Agents run in background — they cannot prompt the user for approval.
+
+| `source` in catalogue | `subagent_type` | `mode` | Identity mechanism |
+|----------------------|-----------------|--------|--------------------|
+| `jdi` | `"general-purpose"` | `"bypassPermissions"` | Prompt text: `"You are {task.agent}. Read .jdi/framework/agents/{task.agent}.md for instructions."` |
+| `claude-code` | `"{task.agent}"` | `"bypassPermissions"` | Native — Claude Code loads the agent spec from `.claude/agents/` |
 
 ### Single-agent mode
 
 ```
 # source: jdi (JDI framework specialist)
-Task(
+Agent(
   subagent_type: "general-purpose",
+  mode: "bypassPermissions",
   name: "{plan.primary_agent}",
   prompt: "You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md
   for your full role and instructions. Also read .jdi/framework/components/meta/AgentBase.md
@@ -232,8 +235,9 @@ Task(
 )
 
 # source: claude-code (user-added registered specialist)
-Task(
+Agent(
   subagent_type: "{plan.primary_agent}",   # e.g. unity-specialist
+  mode: "bypassPermissions",
   name: "{plan.primary_agent}",
   prompt: "<standard single-agent spawn prompt from ComplexityRouter>"
 )
@@ -246,21 +250,23 @@ fall back to `subagent_type="general-purpose"` with a `jdi-backend` /
 ### Agent-teams mode
 
 For each task, read its `agent:` frontmatter field and the matching `source:`
-from the plan's `available_agents` catalogue. Spawn ONE Task tool call per task
+from the plan's `available_agents` catalogue. Spawn ONE Agent tool call per task
 using the pattern that matches its source (see table above).
 
 ```
 # JDI specialist (source: jdi)
-Task(
+Agent(
   subagent_type: "general-purpose",
+  mode: "bypassPermissions",
   name: "{task.agent}-{task_id}",
   prompt: "You are {task.agent}. Read .jdi/framework/agents/{task.agent}.md for instructions.
   <spawn prompt from AgentTeamsOrchestration with TASK_FILE: {task file}>"
 )
 
 # Claude Code registered specialist (source: claude-code)
-Task(
+Agent(
   subagent_type: "{task.agent}",
+  mode: "bypassPermissions",
   name: "{task.agent}-{task_id}",
   prompt: "<spawn prompt from AgentTeamsOrchestration with TASK_FILE: {task file}>"
 )

package/framework/components/meta/AgentTeamsOrchestration.md

@@ -68,15 +68,15 @@ and the `agent_rationale` explaining why you were picked for this task).
 If TASK_FILE is not provided (legacy plan), claim tasks from TaskList and read
 task details from the PLAN file.
 
-1. Implement using Edit tool
+1. Implement using Edit tool (existing files) and Write tool (new files)
 2. SendMessage to coordinator with structured return
 3. Mark task completed via TaskUpdate
 
-Report: files_modified, files_to_create, commits_pending.
+Report: files_modified, files_created, commits_pending.
 No git commit (use commits_pending).
 ```
 
-Spawned via `Task(subagent_type="general-purpose", ...)` — see
+Spawned via `Agent(subagent_type="general-purpose", mode="bypassPermissions", ...)` — see
 `.jdi/framework/jdi.md` Critical Constraints for why.
 
 ### `source: claude-code` — registered Claude Code subagent
@@ -89,21 +89,20 @@ Your agent definition has already been loaded by Claude Code from
 <same TEAM / PLAN / TASK_FILE / WORKING_DIR block + steps + report as above>
 ```
 
-Spawned via `Task(subagent_type="{task.agent}", ...)` — Claude Code validates
+Spawned via `Agent(subagent_type="{task.agent}", mode="bypassPermissions", ...)` — Claude Code validates
 the subagent type against its registered list. See
 `.jdi/framework/components/meta/AgentRouter.md` §4 for full rules.
 
 ---
 
-## Deferred Operations Checklist
+## Post-Agent Operations
 
 After all specialist tasks complete:
 
-1. **Collect** — Aggregate `files_modified`, `files_to_create`, `commits_pending` from all SendMessage results
-2. **Create files** — Write tool for each `files_to_create` entry
-3. **Execute commits** — `git add` + `git commit` for each `commits_pending` entry
-4. **Record hashes** — Store real commit hashes in state.yaml
-5. **Verify** — Confirm all `files_modified` are present in working tree
+1. **Collect** — Aggregate `files_modified`, `files_created`, `commits_pending` from all SendMessage results
+2. **Execute commits** — `git add` + `git commit` for each `commits_pending` entry
+3. **Record hashes** — Store real commit hashes in state.yaml
+4. **Verify** — Confirm all `files_modified` and `files_created` are present in working tree
 
 ---
 

package/framework/components/meta/ComplexityRouter.md

@@ -56,8 +56,9 @@ See `.jdi/framework/components/meta/AgentRouter.md` §4 for full spawn rules.
 ### JDI specialist (source: jdi — the common case)
 
 ```
-Task(
+Agent(
   subagent_type: "general-purpose",   # MUST be general-purpose for JDI agents
+  mode: "bypassPermissions",          # REQUIRED: agents need file write permissions
   name: "{plan.primary_agent}",
   prompt: "You are {plan.primary_agent}. Read .jdi/framework/agents/{plan.primary_agent}.md
 for your full role and instructions. Also read
@@ -73,15 +74,16 @@ for your full role and instructions. Also read
 Execute all tasks in the plan sequentially. PLAN: {plan-path}.
 For split plans (task_files in frontmatter), read each task file one at a time
 from the file: field in state.yaml.
-Report: files_modified, files_to_create, commits_pending."
+Report: files_modified, files_created, commits_pending."
 )
 ```
 
 ### Claude Code registered specialist (source: claude-code)
 
 ```
-Task(
+Agent(
   subagent_type: "{plan.primary_agent}",   # e.g. unity-specialist
+  mode: "bypassPermissions",               # REQUIRED: agents need file write permissions
   name: "{plan.primary_agent}",
   prompt: "Your agent definition has already been loaded from .claude/agents/.
 Also read .jdi/framework/components/meta/AgentBase.md for the JDI base protocol.

package/framework/components/meta/InteractiveGate.md

@@ -0,0 +1,138 @@
+# InteractiveGate Component
+
+A reusable question gate that presents structured decisions to the user via `AskUserQuestion` before a phase transition. Questions are sourced from two channels: surface-level ambiguity detection and research-driven codebase analysis.
+
+When a command references `<JDI:InteractiveGate mode="..." />`, execute the steps below. Do NOT skip the merge/dedup logic even if only one source produces questions.
+
+---
+
+## Modes
+
+| Mode | When | Question Sources |
+|------|------|-----------------|
+| `pre-plan` | Before planner spawn in `create-plan` | Surface-level analysis of feature description + `RESEARCH_QUESTIONS` from pre-plan research spawn |
+| `blocker-resolution` | During implementation when a task is blocked | Surface-level analysis of the blocker description + context from the blocking task |
+
+---
+
+## Question Sources
+
+### Surface-Level (Ambiguity Detection)
+
+Analyse the feature description (or blocker description) for ambiguity signals:
+
+- **Vague scope words** — "improve", "enhance", "refactor", "clean up", "optimise" without measurable targets
+- **Missing tech stack specifics** — feature implies a technology choice but doesn't state one
+- **Unclear boundaries** — "and more", "etc.", "various", "all the things"
+- **Multiple possible approaches** — description could be solved in fundamentally different ways
+- **Implicit assumptions** — feature assumes context the user hasn't stated
+
+Generate questions only for genuine ambiguities. Do NOT manufacture questions for clear descriptions.
+
+### Research-Driven
+
+Consume the `RESEARCH_QUESTIONS` YAML block produced by the pre-plan research spawn (or equivalent). These are decision points discovered by analysing the actual codebase:
+
+- Competing patterns (e.g. two state management approaches in use)
+- Missing data/fields the feature will need
+- Architectural choices (where to place new code, which module to extend)
+- Dependency/library choices
+- Existing conventions that constrain the approach
+
+Research-driven questions arrive pre-formatted with `id`, `question`, `header`, `options`, and `context`.
+
+---
+
+## Merge and Prioritise
+
+1. Collect surface-level questions (assign IDs `SQ-01`, `SQ-02`, ...)
+2. Collect research-driven questions (IDs `RQ-01`, `RQ-02`, ... from the researcher)
+3. Deduplicate: if a surface question covers the same decision as a research question, keep the research version (it has codebase-grounded options)
+4. Sort: research-driven questions first (higher signal), then surface-level
+5. Cap at a reasonable total — if more than 8 questions survive, drop the lowest-priority surface-level questions
+
+---
+
+## AskUserQuestion Format
+
+Each question presented via `AskUserQuestion` must follow this structure:
+
+- **`header`**: Short category tag — max 12 characters. Examples: `SCOPE`, `STACK`, `APPROACH`, `PATTERN`, `DATA`, `BOUNDARY`
+- **`question`**: The actual question text. Clear, specific, and actionable.
+- **`options`**: 2-4 options, each with:
+  - `label`: Short option name
+  - `description`: One-line explanation. For research-driven questions, ground this in what the researcher found in the codebase.
+- **`multiSelect`**: Set to `true` only for non-mutually-exclusive choices. Default `false`.
+- An automatic "Other" option is always available (built into the tool).
+
+**Batching rule:** Maximum 4 questions per `AskUserQuestion` call (tool limit). If more than 4 questions survive merge, batch into multiple sequential calls. Present the highest-priority questions first.
+
+---
+
+## Output Format
+
+Store all answers as `PRE_ANSWERED_QUESTIONS` in YAML:
+
+```yaml
+PRE_ANSWERED_QUESTIONS:
+  - id: RQ-01
+    source: research
+    question: "The codebase uses both Redux and Zustand — which should this feature follow?"
+    chosen: "Use Zustand"
+    custom_text: null
+  - id: SQ-01
+    source: surface
+    question: "What does 'improve performance' mean concretely?"
+    chosen: "Reduce load time below 2s"
+    custom_text: "Specifically the dashboard page load"
+```
+
+Fields:
+- `id`: Question ID (`RQ-*` for research, `SQ-*` for surface)
+- `source`: `research` or `surface`
+- `question`: The question text (for downstream reference)
+- `chosen`: The selected option label (or "Other" if custom)
+- `custom_text`: User's free-text input if they chose "Other", otherwise `null`
+
+---
+
+## Skip Condition
+
+If BOTH sources yield zero questions after analysis, skip the gate entirely. Do NOT present an empty AskUserQuestion call. Proceed directly to the next step in the parent workflow.
+
+Log internally: `InteractiveGate: 0 questions from surface + 0 from research — skipping gate.`
+
+---
+
+## Fallback
+
+If `AskUserQuestion` is not available (not in the skill's `allowed-tools` list), fall back to plain markdown:
+
+```
+Before we proceed, I have a few questions:
+
+1. **[PATTERN]** The codebase uses both X and Y for Z — which should this feature follow?
+   - A) Use X — consistent with src/foo/ (newer pattern)
+   - B) Use Y — consistent with src/bar/ (legacy pattern)
+   - C) Other (please specify)
+
+2. **[SCOPE]** What does "improve" mean concretely?
+   - A) Reduce load time below 2s
+   - B) Reduce memory usage
+   - C) Other (please specify)
+
+Please respond with your choices (e.g. "1A, 2B") or provide details.
+```
+
+Parse the user's response and populate `PRE_ANSWERED_QUESTIONS` accordingly.
+
+---
+
+## Usage
+
+```
+<JDI:InteractiveGate mode="pre-plan" />
+<JDI:InteractiveGate mode="blocker-resolution" />
+```
+
+Referenced within a skill's numbered workflow steps. Requires that question sources (surface analysis input and/or `RESEARCH_QUESTIONS` block) are available in the execution context before invocation.

package/framework/jdi.md

@@ -35,22 +35,30 @@ model: opus
 
 ### Correct Pattern
 
-Agent identity is passed via the **prompt parameter**, NOT the `subagent_type` parameter:
+Agent identity is passed via the **prompt parameter**, NOT the `subagent_type` parameter.
+**Permission mode** MUST be `"bypassPermissions"` so agents can create and edit files without blocking on approval prompts.
 
 ```
-Task(
+Agent(
   prompt="You are jdi-programmer. Read .jdi/framework/agents/jdi-programmer.md for instructions. Execute: {task}",
-  subagent_type="general-purpose"   ← MUST be "general-purpose"
+  subagent_type="general-purpose",  ← MUST be "general-purpose"
+  mode="bypassPermissions"          ← REQUIRED: agents need file write permissions
 )
 ```
 
-### Incorrect Pattern (WILL FAIL)
+### Incorrect Patterns (WILL FAIL)
 
 ```
-Task(
+Agent(
   prompt="Execute the plan...",
   subagent_type="jdi-programmer"    ← WRONG: Causes classifyHandoffIfNeeded error
 )
+
+Agent(
+  prompt="Execute the plan...",
+  subagent_type="general-purpose"
+  # mode omitted                    ← WRONG: Agent blocked on Write/Edit permissions
+)
 ```
 
 ### Why This Matters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benzotti/jdi",
-  "version": "0.1.46",
+  "version": "0.1.49",
   "description": "JDI - Context-efficient AI development framework for Claude Code",
   "type": "module",
   "bin": {