{
  "id": "page:docs-harness-features-backlog-gaps-tools-capabilities-gap-tools-026",
  "_kind": "Page",
  "_file": "wiki/docs/harness-features-backlog/gaps/tools-capabilities/gap-tools-026.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/harness-features-backlog/gaps/tools-capabilities/GAP-TOOLS-026.md",
    "sourceKind": "repo-docs",
    "title": "GAP-TOOLS-026: Structured User Interaction from Within Effects",
    "displayName": "GAP-TOOLS-026: Structured User Interaction from Within Effects",
    "slug": "docs/harness-features-backlog/gaps/tools-capabilities/gap-tools-026",
    "articlePath": "wiki/docs/harness-features-backlog/gaps/tools-capabilities/GAP-TOOLS-026.md",
    "article": "\n# GAP-TOOLS-026: Structured User Interaction from Within Effects\n\n| Field | Value |\n|-------|-------|\n| Category | tools-capabilities |\n| Priority | Medium |\n| Effort | M |\n| Status | Partial |\n\n## Description\nEnable richer user interaction patterns from within orchestrated effects beyond the binary approve/reject model of breakpoints. Process definitions need to ask structured questions (multiple choice, free text input, file selection, parameter configuration) and receive typed responses during execution.\n\n## Current State\nThe breakpoint system (`ctx.breakpoint()`) provides approval gates with optional feedback text, strategy routing, and auto-approval rules. The interaction module (`packages/sdk/src/interaction/`) has arrow-key selectors, multi-select, and free-text input for CLI use. However, these are not available as effect intrinsics -- process definitions cannot dispatch structured questions as effects that harnesses render and return typed answers for.\n\n## Target State\nA `ctx.ask()` intrinsic that dispatches structured interaction effects with typed schemas: choice (single select from options), multiChoice (multi-select), freeText (with validation), confirm (yes/no with context), fileSelect (pick from file list), parameterForm (fill structured parameters). Interaction effects go through the journal like other effects. Harness adapters render interactions appropriately for their UI surface.\n\n## Dependencies\n- [GAP-UX-010](../user-experience/GAP-UX-010.md) -- typed effect interaction patterns\n- [GAP-JSON-003](../json-interaction/GAP-JSON-003.md) -- JSON breakpoint API for programmatic interaction\n\n## Key Files\n| Component | Path |\n|-----------|------|\n| Interaction module | `packages/sdk/src/interaction/` |\n| Breakpoints | `packages/sdk/src/breakpoints/` |\n| Process context | `packages/sdk/src/runtime/processContext.ts` |\n| Task definitions | `packages/sdk/src/tasks/` |\n\n## Recommendation\nPhase 3 implementation. Define interaction effect schema types. Add `ctx.ask()` to ProcessContext. Implement interaction rendering in harness adapters. Ensure interaction effects are journaled and replayable.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-harness-features-backlog",
      "to": "page:docs-harness-features-backlog-gaps-tools-capabilities-gap-tools-026",
      "kind": "contains_page"
    }
  ]
}