create-agdf 0.7.1 → 0.7.3

package/README.md

@@ -79,7 +79,7 @@ If no language is provided, `create-agdf` derives the preference from the local
 - `copilot` writes `AGENTS.md`, Copilot custom instructions under `.github/`, visible repository skills under `.github/skills/`, and AGDF control templates under `.agdf/control/`
 - `opencode` installs the AGDF npm plugin and nine native skills as a user-wide OpenCode surface
 - `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, session signals and repository surface presence
-- `opencode-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
+- `opencode-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit question/edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
 - `both` writes the Codex repository-local marketplace plus the Copilot-facing repository files
 - `config` writes or updates only `.agdf/control/config.json` for an already installed plugin or an existing repository
 
@@ -110,9 +110,9 @@ Use the `opencode-repo` target when AGDF should be available to OpenCode from re
 npm create agdf@latest -- opencode-repo
 ```
 
-OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `edit`/`bash`/`skill` permissions and canonical `agdf-` project skills under `.opencode/skills/`. Global adapters use the collision-safe `agdf-global-` prefix. AGDF for OpenCode has a global discoverability layer installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by `opencode-repo`.
+OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `question`/`edit`/`bash`/`skill` permissions and canonical `agdf-` project skills under `.opencode/skills/`. Global adapters use the collision-safe `agdf-global-` prefix. AGDF for OpenCode has a global discoverability layer installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by `opencode-repo`.
 Those generated skills load on demand through OpenCode's native `skill` tool. Use `agdf-gate-check` first for new build/change intent or unclear approval.
-If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment.
+The built-in `question` tool can present a gate choice, but `.agdf/control/` and exact post-response validation remain authoritative; technical permission and auto-mode outcomes never approve an AGDF gate. If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment. Preserve any explicit `permission.question` decision when reviewing that fragment; `deny` uses exact-text fallback.
 The global layer makes the nine native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has `.opencode/AGDF.md`, `.opencode/skills/agdf-gate-check/SKILL.md` and `.agdf/control/`. Use `opencode-repo` to write that repository surface.
 
 ## Control scaffold

package/bin/create-agdf.js

@@ -514,9 +514,10 @@ function installOpenCodeGlobalPlugin(configDir) {
   if (!nextConfig.instructions.includes("AGDF.md")) nextConfig.instructions.push("AGDF.md");
 
   if (nextConfig.permission === undefined) {
-    nextConfig.permission = { skill: { "agdf-*": "allow" } };
+    nextConfig.permission = { question: "allow", skill: { "agdf-*": "allow" } };
   } else if (nextConfig.permission && typeof nextConfig.permission === "object" && !Array.isArray(nextConfig.permission)) {
     nextConfig.permission = { ...nextConfig.permission };
+    if (nextConfig.permission.question === undefined) nextConfig.permission.question = "allow";
     if (nextConfig.permission.skill === undefined) {
       nextConfig.permission.skill = { "agdf-*": "allow" };
     } else if (nextConfig.permission.skill && typeof nextConfig.permission.skill === "object" && !Array.isArray(nextConfig.permission.skill)) {
@@ -1165,7 +1166,7 @@ function printNextSteps(target, destination, files, wroteAgentsFragment, wroteOp
   }
   if (target === "opencode-repo") {
     if (wroteOpenCodeConfigFragment) {
-      console.log(`- Existing opencode.json detected. Merge ${openCodeConfigFragmentPath} into your current opencode.json so OpenCode loads .opencode/AGDF.md.`);
+      console.log(`- Existing opencode.json detected. Review ${openCodeConfigFragmentPath} and merge its owned entries so OpenCode loads .opencode/AGDF.md; preserve an explicit permission.question decision.`);
     }
     console.log(`- OpenCode will install the ${pluginDefinition.opencode.npmPackage} npm plugin from opencode.json at startup.`);
     console.log("- Optional: also add create-agdf to ~/.config/opencode/opencode.json plugin[] for a user-wide OpenCode hook.");

package/generated/.github/skills/agdf-gate-check/SKILL.md

@@ -52,6 +52,37 @@ npx --yes @agdf/cli@latest delivery-map --json
 
 The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
+## Native Interaction Path
+
+Use the Runtime Contract's Native Interaction Contract to classify every candidate interaction as `clarification`, `tool_permission` or `gate_approval` before selecting a host control.
+
+Prefer inspection over asking. Do not invoke a structured question for status reporting, facts available in the repository, routine read-only work or a gate that is not ready. Do not repeatedly prompt for the same non-ready gate.
+
+For a ready `gate_approval`:
+
+1. Resolve exactly one selected run and evaluate the current gate.
+2. Confirm the required durable artefact is present and ready before presenting a question.
+3. Ask exactly one question that names the selected `run_id` and `current_gate`.
+4. Offer the exact approving option `Approval: <GateName>` plus bounded revise and cancel/decline outcomes.
+5. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
+6. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
+7. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
+8. Persist accepted input only through the existing control-state workflow.
+
+Make exactly one native-attempt for the ready gate. If the host does not render,
+apply or safely return the native question on that attempt, switch immediately
+to the exact textual approval. Do not ask the user to request the buttons again
+and do not create a retry loop or simulated control.
+
+Surface behavior:
+
+- Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
+- Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
+- OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
+- Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
+
+A free-form response must still exactly match the current gate's approval formula after revalidation. Revise, decline and cancel never advance the gate. Native presentation, host permission and plan approval are inputs or separate authority domains, never durable AGDF authority.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -72,6 +103,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 17. If multiple active scopes are plausible, list the evidenced competing lines and keep the current step at scope clarification or the earliest common safe gate.
 18. When maintaining `MASTER_BACKLOG.md`, use its canonical compact columns, readable status labels and document-relative Markdown links. Do not expose raw long paths or internal snake_case statuses in the human-facing table. The canonical status/artefact label vocabulary is defined in the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section; do not invent other labels.
 19. Preserve legacy backlog compatibility through the CLI parser; do not create a second surface-specific backlog format.
+20. Native interaction must follow the Runtime Contract's interaction envelope, readiness check, deliberate-user-input requirement and post-response revalidation boundary.
 
 ## Gate Evaluation
 

package/generated/.github/skills/agdf-runtime-contract.md

@@ -268,6 +268,63 @@ section or any other existing line.
 - `agdf-release-or` reports the run, but does not replace QA or produce the operative commit/PR handoff.
 - `agdf-delivery-closeout` owns the operative Git handoff text when QA/OR/UAT state allows it.
 
+## Native Interaction Contract
+
+Native host controls improve how a decision is presented; they do not create a second approval model or authority source.
+
+Every AGDF interaction belongs to exactly one semantic kind:
+
+- `clarification`: asks for missing intent or a choice that does not itself authorize a gated transition.
+- `tool_permission`: requests host-owned authority for a command, file change, network access, external path, app action or comparable technical side effect.
+- `gate_approval`: requests deliberate user input for the one current AGDF user gate after its durable artefact and selected run are ready.
+
+The semantic interaction envelope is:
+
+```text
+interaction_kind: clarification | tool_permission | gate_approval
+surface: codex | claude | opencode | fallback
+run_id: required for gate_approval
+current_gate: required for gate_approval
+prompt: required
+options: required for a structured question
+effects: required when the interaction can cause side effects
+required_evidence: required for gate_approval
+auto_resolution: forbidden for gate_approval
+response_origin: deliberate_user_input for gate_approval
+```
+
+This envelope is not a new persisted record. The selected canonical `RUN_STATE.md` and existing artefact chain remain the durable authority.
+
+Before presenting `gate_approval`, the agent must:
+
+1. resolve exactly one selected run;
+2. run the canonical gate evaluation and confirm that the current gate's durable artefact is present and ready;
+3. ask exactly one gate question that identifies `run_id` and `current_gate` and offers the exact approving value `Approval: <GateName>` plus bounded revise and cancel/decline outcomes;
+4. wait for deliberate user input without a timeout, default, preselection, hook-supplied answer or agent-to-agent substitute;
+5. re-run canonical gate evaluation against the same `run_id` and expected gate immediately before persistence;
+6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
+7. persist an accepted approval only through the existing control-state workflow.
+
+The first eligible native-attempt has a single bounded outcome: the declared
+host control is presented, or the agent immediately uses the exact-text
+fallback. A host that does not apply the control does not trigger a second
+native prompt. AGDF must not simulate or force host-owned presentation.
+
+A free-form native response is valid only when the existing exact-approval validator accepts it for the current gate after revalidation. Revise, decline and cancel outcomes never advance a gate.
+
+Surface adapter rules:
+
+| Surface | Native question adapter | Gate-safe use | Technical permission boundary |
+|---|---|---|---|
+| Codex | native `request_user_input` or equivalent short-question control when callable | on the first eligible attempt, present one gate question with auto-resolution omitted; if unavailable or not applied, use exact text without retry | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
+| Claude Code | `AskUserQuestion` | on the first eligible attempt, use only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if unavailable or not applied, use exact text without retry | Claude permissions and `ExitPlanMode` are not AGDF approval. |
+| OpenCode | built-in `question` | use with exact approval/revise/cancel options when `permission.question` permits it; explicit user deny selects exact-text fallback | `once`, `always`, `reject`, permission suggestions and auto mode are technical outcomes only. |
+| Fallback or non-interactive | concise exact text | wait for a new explicit user response; never synthesize or auto-resolve one | Host-specific technical permission remains separate. |
+
+Native structured questions are for real decision points. Prefer repository inspection over clarification and do not show them for status reporting, discoverable facts, routine read-only work or repeated non-ready gate prompts.
+
+Exact textual approvals remain canonical and fully supported on every surface. If native capability availability or safety is unknown, use the textual fallback. Host permission, plan approval, native question presentation, timeout/default behavior, hook output and agent messages never carry AGDF gate authority by themselves.
+
 ## Brownfield Review After G-00
 
 After an approved and durable UR, perform a lightweight `Brownfield Review` before PRD when Brownfield, UI, UX, admin, runtime, policy, persistence, architecture, ownership or source-of-truth impact is possible.

package/generated/.opencode/AGDF.md

@@ -108,6 +108,7 @@ For relevant runs that change durable state, code, artefacts or gate status:
 - For new build/change intent or unclear approval, load the `agdf-gate-check` skill before later artefacts or implementation.
 - The AGDF OpenCode plugin is loaded from npm through `opencode.json` `plugin: ["create-agdf"]`.
 - Use `npx --yes @agdf/cli@latest opencode-status --json` to verify global config, package loadability, global native-skill completeness, active session signals and repository surface presence separately.
-- OpenCode permissions keep `edit` and `bash` on explicit approval and allow the generated `agdf-*` skills explicitly; global adapters use the `agdf-global-*` namespace.
+- OpenCode permissions allow the built-in `question` tool, keep `edit` and `bash` on explicit approval and allow the generated `agdf-*` skills explicitly; global adapters use the `agdf-global-*` namespace.
+- An explicit user `permission.question: deny` remains authoritative and selects the exact-text AGDF fallback; never convert an OpenCode permission outcome or auto mode into gate approval.
 - Shared output and gate rules live in `.opencode/agdf-runtime-contract.md`.
 - Do not paste full control files, templates or artefact bodies into chat unless the user explicitly asks for the full content; summarize and link paths instead.

package/generated/.opencode/README.md

@@ -5,7 +5,8 @@ These files were generated from the AGDF source repository for OpenCode.
 - `opencode.json` loads the npm plugin `create-agdf` and `.opencode/AGDF.md` as repository instructions.
 - AGDF for OpenCode has a global npm/native-skill discoverability layer and this repository-local governance surface.
 - The global plugin and skills do not replace `.opencode/AGDF.md`, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- `opencode.json` keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills; global adapters use `agdf-global-*` to avoid same-name masking.
+- `opencode.json` allows the built-in `question` tool, keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills; global adapters use `agdf-global-*` to avoid same-name masking.
+- Preserve an explicit user `permission.question: deny`; AGDF then uses exact textual approval and never interprets OpenCode permission outcomes or auto mode as gate authority.
 - `.opencode/skills/` contains native OpenCode skills generated from the canonical AGDF skills.
 - For new build/change intent or unclear approval, load `agdf-gate-check` through OpenCode's native `skill` tool.
 - Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, session activity and this repository surface.

package/generated/.opencode/agdf-runtime-contract.md

@@ -268,6 +268,63 @@ section or any other existing line.
 - `agdf-release-or` reports the run, but does not replace QA or produce the operative commit/PR handoff.
 - `agdf-delivery-closeout` owns the operative Git handoff text when QA/OR/UAT state allows it.
 
+## Native Interaction Contract
+
+Native host controls improve how a decision is presented; they do not create a second approval model or authority source.
+
+Every AGDF interaction belongs to exactly one semantic kind:
+
+- `clarification`: asks for missing intent or a choice that does not itself authorize a gated transition.
+- `tool_permission`: requests host-owned authority for a command, file change, network access, external path, app action or comparable technical side effect.
+- `gate_approval`: requests deliberate user input for the one current AGDF user gate after its durable artefact and selected run are ready.
+
+The semantic interaction envelope is:
+
+```text
+interaction_kind: clarification | tool_permission | gate_approval
+surface: codex | claude | opencode | fallback
+run_id: required for gate_approval
+current_gate: required for gate_approval
+prompt: required
+options: required for a structured question
+effects: required when the interaction can cause side effects
+required_evidence: required for gate_approval
+auto_resolution: forbidden for gate_approval
+response_origin: deliberate_user_input for gate_approval
+```
+
+This envelope is not a new persisted record. The selected canonical `RUN_STATE.md` and existing artefact chain remain the durable authority.
+
+Before presenting `gate_approval`, the agent must:
+
+1. resolve exactly one selected run;
+2. run the canonical gate evaluation and confirm that the current gate's durable artefact is present and ready;
+3. ask exactly one gate question that identifies `run_id` and `current_gate` and offers the exact approving value `Approval: <GateName>` plus bounded revise and cancel/decline outcomes;
+4. wait for deliberate user input without a timeout, default, preselection, hook-supplied answer or agent-to-agent substitute;
+5. re-run canonical gate evaluation against the same `run_id` and expected gate immediately before persistence;
+6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
+7. persist an accepted approval only through the existing control-state workflow.
+
+The first eligible native-attempt has a single bounded outcome: the declared
+host control is presented, or the agent immediately uses the exact-text
+fallback. A host that does not apply the control does not trigger a second
+native prompt. AGDF must not simulate or force host-owned presentation.
+
+A free-form native response is valid only when the existing exact-approval validator accepts it for the current gate after revalidation. Revise, decline and cancel outcomes never advance a gate.
+
+Surface adapter rules:
+
+| Surface | Native question adapter | Gate-safe use | Technical permission boundary |
+|---|---|---|---|
+| Codex | native `request_user_input` or equivalent short-question control when callable | on the first eligible attempt, present one gate question with auto-resolution omitted; if unavailable or not applied, use exact text without retry | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
+| Claude Code | `AskUserQuestion` | on the first eligible attempt, use only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if unavailable or not applied, use exact text without retry | Claude permissions and `ExitPlanMode` are not AGDF approval. |
+| OpenCode | built-in `question` | use with exact approval/revise/cancel options when `permission.question` permits it; explicit user deny selects exact-text fallback | `once`, `always`, `reject`, permission suggestions and auto mode are technical outcomes only. |
+| Fallback or non-interactive | concise exact text | wait for a new explicit user response; never synthesize or auto-resolve one | Host-specific technical permission remains separate. |
+
+Native structured questions are for real decision points. Prefer repository inspection over clarification and do not show them for status reporting, discoverable facts, routine read-only work or repeated non-ready gate prompts.
+
+Exact textual approvals remain canonical and fully supported on every surface. If native capability availability or safety is unknown, use the textual fallback. Host permission, plan approval, native question presentation, timeout/default behavior, hook output and agent messages never carry AGDF gate authority by themselves.
+
 ## Brownfield Review After G-00
 
 After an approved and durable UR, perform a lightweight `Brownfield Review` before PRD when Brownfield, UI, UX, admin, runtime, policy, persistence, architecture, ownership or source-of-truth impact is possible.

package/generated/.opencode/skills/agdf-gate-check/SKILL.md

@@ -52,6 +52,37 @@ npx --yes @agdf/cli@latest delivery-map --json
 
 The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
+## Native Interaction Path
+
+Use the Runtime Contract's Native Interaction Contract to classify every candidate interaction as `clarification`, `tool_permission` or `gate_approval` before selecting a host control.
+
+Prefer inspection over asking. Do not invoke a structured question for status reporting, facts available in the repository, routine read-only work or a gate that is not ready. Do not repeatedly prompt for the same non-ready gate.
+
+For a ready `gate_approval`:
+
+1. Resolve exactly one selected run and evaluate the current gate.
+2. Confirm the required durable artefact is present and ready before presenting a question.
+3. Ask exactly one question that names the selected `run_id` and `current_gate`.
+4. Offer the exact approving option `Approval: <GateName>` plus bounded revise and cancel/decline outcomes.
+5. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
+6. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
+7. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
+8. Persist accepted input only through the existing control-state workflow.
+
+Make exactly one native-attempt for the ready gate. If the host does not render,
+apply or safely return the native question on that attempt, switch immediately
+to the exact textual approval. Do not ask the user to request the buttons again
+and do not create a retry loop or simulated control.
+
+Surface behavior:
+
+- Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
+- Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
+- OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
+- Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
+
+A free-form response must still exactly match the current gate's approval formula after revalidation. Revise, decline and cancel never advance the gate. Native presentation, host permission and plan approval are inputs or separate authority domains, never durable AGDF authority.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -72,6 +103,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 17. If multiple active scopes are plausible, list the evidenced competing lines and keep the current step at scope clarification or the earliest common safe gate.
 18. When maintaining `MASTER_BACKLOG.md`, use its canonical compact columns, readable status labels and document-relative Markdown links. Do not expose raw long paths or internal snake_case statuses in the human-facing table. The canonical status/artefact label vocabulary is defined in the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section; do not invent other labels.
 19. Preserve legacy backlog compatibility through the CLI parser; do not create a second surface-specific backlog format.
+20. Native interaction must follow the Runtime Contract's interaction envelope, readiness check, deliberate-user-input requirement and post-response revalidation boundary.
 
 ## Gate Evaluation
 

package/generated/opencode.json

@@ -7,6 +7,7 @@
     ".opencode/AGDF.md"
   ],
   "permission": {
+    "question": "allow",
     "edit": "ask",
     "bash": "ask",
     "skill": {

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
@@ -57,6 +57,7 @@
     "instructionsFileName": "AGDF.md",
     "npmPackage": "create-agdf",
     "permissions": {
+      "question": "allow",
       "edit": "ask",
       "bash": "ask",
       "skill": {
@@ -64,6 +65,35 @@
       }
     }
   },
+  "interactions": {
+    "fallback": "exact_text",
+    "surfaces": {
+      "codex": {
+        "questionAdapter": "request_user_input",
+        "availability": "when_callable",
+        "gateSafety": "omit_auto_resolution",
+        "technicalPermissionOwner": "codex_host"
+      },
+      "claude": {
+        "questionAdapter": "AskUserQuestion",
+        "availability": "when_no_auto_continue_timeout",
+        "gateSafety": "no_timeout_or_hook_supplied_answer",
+        "technicalPermissionOwner": "claude_host"
+      },
+      "opencode": {
+        "questionAdapter": "question",
+        "availability": "when_permission_question_allows",
+        "gateSafety": "preserve_explicit_deny",
+        "technicalPermissionOwner": "opencode_host"
+      },
+      "fallback": {
+        "questionAdapter": "exact_text",
+        "availability": "always",
+        "gateSafety": "wait_for_deliberate_user_input",
+        "technicalPermissionOwner": "host_specific"
+      }
+    }
+  },
   "skillSet": [
     {
       "slug": "delivery-path-search",

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -268,6 +268,63 @@ section or any other existing line.
 - `release-or` reports the run, but does not replace QA or produce the operative commit/PR handoff.
 - `delivery-closeout` owns the operative Git handoff text when QA/OR/UAT state allows it.
 
+## Native Interaction Contract
+
+Native host controls improve how a decision is presented; they do not create a second approval model or authority source.
+
+Every AGDF interaction belongs to exactly one semantic kind:
+
+- `clarification`: asks for missing intent or a choice that does not itself authorize a gated transition.
+- `tool_permission`: requests host-owned authority for a command, file change, network access, external path, app action or comparable technical side effect.
+- `gate_approval`: requests deliberate user input for the one current AGDF user gate after its durable artefact and selected run are ready.
+
+The semantic interaction envelope is:
+
+```text
+interaction_kind: clarification | tool_permission | gate_approval
+surface: codex | claude | opencode | fallback
+run_id: required for gate_approval
+current_gate: required for gate_approval
+prompt: required
+options: required for a structured question
+effects: required when the interaction can cause side effects
+required_evidence: required for gate_approval
+auto_resolution: forbidden for gate_approval
+response_origin: deliberate_user_input for gate_approval
+```
+
+This envelope is not a new persisted record. The selected canonical `RUN_STATE.md` and existing artefact chain remain the durable authority.
+
+Before presenting `gate_approval`, the agent must:
+
+1. resolve exactly one selected run;
+2. run the canonical gate evaluation and confirm that the current gate's durable artefact is present and ready;
+3. ask exactly one gate question that identifies `run_id` and `current_gate` and offers the exact approving value `Approval: <GateName>` plus bounded revise and cancel/decline outcomes;
+4. wait for deliberate user input without a timeout, default, preselection, hook-supplied answer or agent-to-agent substitute;
+5. re-run canonical gate evaluation against the same `run_id` and expected gate immediately before persistence;
+6. reject missing evidence, ambiguous or wrong run, wrong gate, stale state and any response that is no longer valid;
+7. persist an accepted approval only through the existing control-state workflow.
+
+The first eligible native-attempt has a single bounded outcome: the declared
+host control is presented, or the agent immediately uses the exact-text
+fallback. A host that does not apply the control does not trigger a second
+native prompt. AGDF must not simulate or force host-owned presentation.
+
+A free-form native response is valid only when the existing exact-approval validator accepts it for the current gate after revalidation. Revise, decline and cancel outcomes never advance a gate.
+
+Surface adapter rules:
+
+| Surface | Native question adapter | Gate-safe use | Technical permission boundary |
+|---|---|---|---|
+| Codex | native `request_user_input` or equivalent short-question control when callable | on the first eligible attempt, present one gate question with auto-resolution omitted; if unavailable or not applied, use exact text without retry | Codex command, edit, network, external-directory and app-action approvals remain host-owned `tool_permission`. |
+| Claude Code | `AskUserQuestion` | on the first eligible attempt, use only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if unavailable or not applied, use exact text without retry | Claude permissions and `ExitPlanMode` are not AGDF approval. |
+| OpenCode | built-in `question` | use with exact approval/revise/cancel options when `permission.question` permits it; explicit user deny selects exact-text fallback | `once`, `always`, `reject`, permission suggestions and auto mode are technical outcomes only. |
+| Fallback or non-interactive | concise exact text | wait for a new explicit user response; never synthesize or auto-resolve one | Host-specific technical permission remains separate. |
+
+Native structured questions are for real decision points. Prefer repository inspection over clarification and do not show them for status reporting, discoverable facts, routine read-only work or repeated non-ready gate prompts.
+
+Exact textual approvals remain canonical and fully supported on every surface. If native capability availability or safety is unknown, use the textual fallback. Host permission, plan approval, native question presentation, timeout/default behavior, hook output and agent messages never carry AGDF gate authority by themselves.
+
 ## Brownfield Review After G-00
 
 After an approved and durable UR, perform a lightweight `Brownfield Review` before PRD when Brownfield, UI, UX, admin, runtime, policy, persistence, architecture, ownership or source-of-truth impact is possible.

package/generated/plugins/agdf/skills/gate-check/SKILL.md

@@ -52,6 +52,37 @@ npx --yes @agdf/cli@latest delivery-map --json
 
 The CLI reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
+## Native Interaction Path
+
+Use the Runtime Contract's Native Interaction Contract to classify every candidate interaction as `clarification`, `tool_permission` or `gate_approval` before selecting a host control.
+
+Prefer inspection over asking. Do not invoke a structured question for status reporting, facts available in the repository, routine read-only work or a gate that is not ready. Do not repeatedly prompt for the same non-ready gate.
+
+For a ready `gate_approval`:
+
+1. Resolve exactly one selected run and evaluate the current gate.
+2. Confirm the required durable artefact is present and ready before presenting a question.
+3. Ask exactly one question that names the selected `run_id` and `current_gate`.
+4. Offer the exact approving option `Approval: <GateName>` plus bounded revise and cancel/decline outcomes.
+5. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution; otherwise request the same exact approval in concise text.
+6. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
+7. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
+8. Persist accepted input only through the existing control-state workflow.
+
+Make exactly one native-attempt for the ready gate. If the host does not render,
+apply or safely return the native question on that attempt, switch immediately
+to the exact textual approval. Do not ask the user to request the buttons again
+and do not create a retry loop or simulated control.
+
+Surface behavior:
+
+- Codex: invoke the native short-question/request-user-input control on the first eligible attempt when callable, ask one gate question and omit auto-resolution; if it is not rendered or applied, use exact text immediately.
+- Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
+- OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
+- Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
+
+A free-form response must still exactly match the current gate's approval formula after revalidation. Revise, decline and cancel never advance the gate. Native presentation, host permission and plan approval are inputs or separate authority domains, never durable AGDF authority.
+
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
@@ -72,6 +103,7 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 17. If multiple active scopes are plausible, list the evidenced competing lines and keep the current step at scope clarification or the earliest common safe gate.
 18. When maintaining `MASTER_BACKLOG.md`, use its canonical compact columns, readable status labels and document-relative Markdown links. Do not expose raw long paths or internal snake_case statuses in the human-facing table. The canonical status/artefact label vocabulary is defined in the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section; do not invent other labels.
 19. Preserve legacy backlog compatibility through the CLI parser; do not create a second surface-specific backlog format.
+20. Native interaction must follow the Runtime Contract's interaction envelope, readiness check, deliberate-user-input requirement and post-response revalidation boundary.
 
 ## Gate Evaluation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [