@benzotti/jdi 0.1.47 → 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.47",
+  version: "0.1.49",
   description: "JDI - Context-efficient AI development framework for Claude Code",
   type: "module",
   bin: {

package/framework/agents/jdi-planner.md

@@ -53,7 +53,7 @@ interactive prompts. Overriding them silently is forbidden.
 
 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/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

@@ -91,7 +91,7 @@ If the feature description looks trivial (single file, <30 minutes, no architect
 
 ### 4a. Pre-Plan Research Spawn
 
-Spawn `jdi-researcher` in `pre-plan-discovery` mode via `Task(subagent_type="general-purpose")`. The spawn prompt MUST include:
+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
@@ -115,7 +115,7 @@ 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
@@ -140,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
 

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

@@ -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.
@@ -162,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
 

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/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.47",
+  "version": "0.1.49",
   "description": "JDI - Context-efficient AI development framework for Claude Code",
   "type": "module",
   "bin": {