feat(cli): add direct headless extension API

[taltas]

Stack

Position 2 of 6 in the Zoo CLI stack.

• Parent/base: fm/zoo-cli-contracts (PR feat(cli): define Zoo protocol contracts #1150)
• Child: fm/zoo-cli-host-security (planned)
• Native stack tracking remains (main) <- contracts <- headless-api; GitHub uses the approved classic fallback because native submit reported stacked PRs are not enabled.

Scope

• Adds direct headless initialize/start/resume methods without focus, webview readiness, or webview message interpretation.
• Adds task-and-ask-ID-safe approve/reject/message responses.
• Adds canonical non-rehydrating cancellation that persists interrupted status before settlement.
• Adds typed ask, terminal-failure, and root-result events.
• Ignores child completion and verifies persisted root completed status before one authoritative result.
• Adds bounded failure semantics for unexpected abort, persistence failure, and shutdown.
• Preserves all existing VS Code API methods and inherited apps/cli behavior.

Acceptance Evidence

• pnpm --dir src test extension/__tests__/api-headless.spec.ts (5 tests)
• pnpm --dir src check-types
• pnpm --dir packages/types check-types
• Targeted suppression-pruning ESLint; suppression count reduced by five.
• Repository pre-commit lint and pre-push typecheck passed.

Risk

The facade is additive, but it touches canonical task cancellation and ask identity. Existing cancellation keeps rehydration by default; only the explicit headless path disables replacement-task creation. Run overrides remain on the next stack layer and are not represented as persisted headless configuration semantics here.

sequenceDiagram
    participant H as zoo-host
    participant A as Headless API
    participant T as Canonical task tree
    participant S as Task history
    H->>A: startHeadlessTask
    A->>T: createTask directly
    T-->>A: typed asks/events
    H->>A: respond(taskId, askId)
    T-->>A: root TaskCompleted
    A->>S: verify root status=completed
    S-->>A: persisted
    A-->>H: exactly one root result

Loading

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9ff973ba-5dd5-4207-8681-ed128645144c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 87.60331% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/extension/api.ts	88.77%	5 Missing and 6 partials ⚠️
src/core/task/Task.ts	66.66%	3 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!