openclacky 1.5.6 → 1.5.8

data/docs/superpowers/plans/2026-08-09-chatcut-extension-bridge.md

@@ -0,0 +1,191 @@
+# ChatCut Extension Bridge Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use box:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a standalone ChatCut extension that works on existing OpenClacky clients through an OAuth-aware stdio bridge and automatically switches to native OAuth when available.
+
+**Architecture:** A setup command owns conflict-safe MCP configuration, capability detection, and cleanup. A focused Ruby bridge composes OAuth discovery/session classes with an MCP HTTP forwarder while keeping stdout protocol-only. Extension skills call the setup command and delegate all video work to `mcp:chatcut` and ChatCut's remote playbooks.
+
+**Tech Stack:** Ruby 2.6+, Net::HTTP, WEBrick, JSON, minitest, OpenClacky `ext.yml` and MCP configuration.
+
+---
+
+### Task 1: Standalone extension skeleton
+
+**Files:**
+- Create: `openclacky-chatcut/ext.yml`
+- Create: `openclacky-chatcut/README.md`
+- Create: `openclacky-chatcut/LICENSE`
+- Create: `openclacky-chatcut/Rakefile`
+- Create: `openclacky-chatcut/test/test_helper.rb`
+
+- [ ] **Step 1: Write a manifest validation test**
+
+Create a minitest that loads `ext.yml`, asserts `id == "chatcut"`, and asserts the three skill directories exist.
+
+- [ ] **Step 2: Run the test to verify RED**
+
+Run: `ruby -Itest test/manifest_test.rb`
+Expected: FAIL because `ext.yml` does not exist.
+
+- [ ] **Step 3: Add the minimal extension skeleton**
+
+Declare `chatcut-setup`, `chatcut`, and `chatcut-disconnect` under `contributes.skills`, add MIT project metadata for original adapter code, and add a Rake test task.
+
+- [ ] **Step 4: Run the test to verify GREEN**
+
+Run: `ruby -Itest test/manifest_test.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add . && git commit -m "chore: scaffold chatcut extension"`
+
+### Task 2: Conflict-safe MCP configuration
+
+**Files:**
+- Create: `openclacky-chatcut/lib/chatcut_extension/configurator.rb`
+- Create: `openclacky-chatcut/bin/chatcut-extension`
+- Create: `openclacky-chatcut/test/configurator_test.rb`
+
+- [ ] **Step 1: Write failing configuration tests**
+
+Cover merging a bridge entry while preserving another server, selecting native mode from `{"remote_oauth":true}`, falling back when the command is absent, refusing to replace an unowned conflicting `chatcut` entry, and disconnecting only an owned entry.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `ruby -Itest test/configurator_test.rb`
+Expected: FAIL because `ChatcutExtension::Configurator` is undefined.
+
+- [ ] **Step 3: Implement the configurator and executable**
+
+Implement `setup`, `status`, and `disconnect`. Probe `clacky mcp capabilities --json`; native mode writes `type`, `url`, and `auth`, while fallback writes `command` and absolute bridge path. Save a SHA-256 fingerprint of the managed entry under the extension data directory and chmod configuration/state files to 0600.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `ruby -Itest test/configurator_test.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add bin lib test && git commit -m "feat: configure chatcut mcp with native fallback"`
+
+### Task 3: OAuth discovery and credential storage
+
+**Files:**
+- Create: `openclacky-chatcut/lib/chatcut_bridge/credential_store.rb`
+- Create: `openclacky-chatcut/lib/chatcut_bridge/oauth_client.rb`
+- Create: `openclacky-chatcut/test/credential_store_test.rb`
+- Create: `openclacky-chatcut/test/oauth_client_test.rb`
+
+- [ ] **Step 1: Write failing OAuth unit tests**
+
+Test mode-0600 atomic persistence, protected-resource and authorization-server discovery, PKCE S256 calculation, state mismatch rejection, successful code exchange, refresh-token rotation, and redacted HTTP errors using a local WEBrick server.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `ruby -Itest test/credential_store_test.rb test/oauth_client_test.rb`
+Expected: FAIL because the bridge classes are undefined.
+
+- [ ] **Step 3: Implement minimal OAuth classes**
+
+Use `SecureRandom.urlsafe_base64`, SHA-256 PKCE, loopback callbacks on `127.0.0.1`, `Net::HTTP`, bounded JSON reads, endpoint HTTPS validation, and atomic JSON writes. Return an authorization header without logging credential values.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `ruby -Itest test/credential_store_test.rb test/oauth_client_test.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add lib test && git commit -m "feat: add chatcut bridge oauth session"`
+
+### Task 4: MCP stdio-to-HTTP bridge
+
+**Files:**
+- Create: `openclacky-chatcut/lib/chatcut_bridge/http_forwarder.rb`
+- Create: `openclacky-chatcut/lib/chatcut_bridge/server.rb`
+- Create: `openclacky-chatcut/bridge/chatcut_mcp_bridge.rb`
+- Create: `openclacky-chatcut/test/http_forwarder_test.rb`
+- Create: `openclacky-chatcut/test/server_test.rb`
+
+- [ ] **Step 1: Write failing bridge tests**
+
+Test JSON-RPC line forwarding, SSE `data:` extraction, session-id propagation, bearer injection, proactive refresh, a single refresh-and-retry on 401, notification handling, protocol-only stdout, and redacted diagnostics.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `ruby -Itest test/http_forwarder_test.rb test/server_test.rb`
+Expected: FAIL because forwarder and server classes are undefined.
+
+- [ ] **Step 3: Implement the bridge**
+
+Read one JSON-RPC object per stdin line, POST it to ChatCut, emit response objects as compact JSON lines, send diagnostics only to stderr, preserve `Mcp-Session-Id`, and use the OAuth client for authorization.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `ruby -Itest test/http_forwarder_test.rb test/server_test.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add bridge lib test && git commit -m "feat: bridge chatcut remote mcp over stdio"`
+
+### Task 5: Skills, packaging, and local installation
+
+**Files:**
+- Create: `openclacky-chatcut/skills/chatcut-setup/SKILL.md`
+- Create: `openclacky-chatcut/skills/chatcut/SKILL.md`
+- Create: `openclacky-chatcut/skills/chatcut-disconnect/SKILL.md`
+- Create: `openclacky-chatcut/test/skills_test.rb`
+
+- [ ] **Step 1: Write failing skill contract tests**
+
+Assert setup runs the extension executable, chatcut invokes `mcp:chatcut` and instructs the subagent to use `list_skills`/`load_skill`, and disconnect runs conflict-safe cleanup.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `ruby -Itest test/skills_test.rb`
+Expected: FAIL because the skills do not exist.
+
+- [ ] **Step 3: Write the three skills and local install instructions**
+
+Keep host-specific instructions in setup/disconnect and all editing knowledge remote. Document the local symlink into `~/.clacky/ext/local/chatcut` and the requirement to start a new session after first registration.
+
+- [ ] **Step 4: Verify GREEN and package**
+
+Run: `bundle exec rake test` and `bundle exec ruby bin/clacky ext verify` from the OpenClacky worktree with the symlink installed.
+Expected: all extension tests pass and verifier reports no ChatCut errors.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add skills test README.md && git commit -m "feat: add chatcut setup and editing skills"`
+
+### Task 6: End-to-end fallback and native-mode verification
+
+**Files:**
+- Create: `openclacky-chatcut/test/integration/setup_modes_test.rb`
+- Create: `openclacky-chatcut/test/integration/bridge_mcp_test.rb`
+
+- [ ] **Step 1: Write integration tests**
+
+Run setup against fake old/new `clacky` executables, launch the bridge against a local OAuth/MCP fixture, complete the callback programmatically, call `initialize`, `tools/list`, and `tools/call`, expire the token, and verify refresh.
+
+- [ ] **Step 2: Run and fix only implementation defects**
+
+Run: `bundle exec rake test`
+Expected: all tests pass with no token values in captured stdout/stderr.
+
+- [ ] **Step 3: Create the authorized local symlink**
+
+Run: `ln -sfn /Users/seng/Documents/GitHub/clacky/openclacky-chatcut ~/.clacky/ext/local/chatcut`
+Expected: the symlink resolves to the standalone repository.
+
+- [ ] **Step 4: Verify with local OpenClacky**
+
+Run: `bundle exec ruby bin/clacky ext verify` and inspect `bundle exec ruby bin/clacky ext list`.
+Expected: ChatCut and all three skills are resolved without errors.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add test && git commit -m "test: verify chatcut bridge fallback modes"`

data/docs/superpowers/plans/2026-08-09-native-mcp-oauth.md

@@ -0,0 +1,243 @@
+# Native Remote MCP OAuth Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use box:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add provider-neutral OAuth 2.1 support for remote MCP servers to OpenClacky, including secure credentials, CLI lifecycle commands, automatic refresh, and transport integration.
+
+**Architecture:** OAuth metadata/session logic is isolated from MCP JSON-RPC transport. A credential store persists per-server grants outside `mcp.json`; an authorization manager discovers metadata, performs DCR and PKCE, and supplies valid bearer tokens. HTTP transport accepts an authorization provider and retries exactly once after an authenticated 401.
+
+**Tech Stack:** Ruby 2.6+, Thor, Net::HTTP, WEBrick, JSON, RSpec.
+
+---
+
+### Task 1: OAuth configuration and capability contract
+
+**Files:**
+- Create: `lib/clacky/mcp/oauth/config.rb`
+- Create: `spec/clacky/mcp/oauth/config_spec.rb`
+- Modify: `lib/clacky/mcp/client.rb`
+- Modify: `lib/clacky/mcp/skill_provider.rb`
+- Modify: `lib/clacky/mcp/registry.rb`
+
+- [ ] **Step 1: Write failing configuration specs**
+
+Cover `auth: {type: oauth}`, explicit resource parsing, default resource equal to MCP URL, rejection of OAuth on non-HTTPS resources, and preservation of static-header servers.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/config_spec.rb`
+Expected: FAIL because `Clacky::Mcp::OAuth::Config` is undefined.
+
+- [ ] **Step 3: Implement minimal configuration parsing**
+
+Add a value object with `enabled?`, `resource`, and validation. Pass parsed OAuth configuration from registry specs into HTTP client construction without provider-specific constants.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/config_spec.rb spec/clacky/mcp/skill_provider_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add lib spec && git commit -m "feat(mcp): define remote oauth configuration"`
+
+### Task 2: Secure OAuth credential store
+
+**Files:**
+- Create: `lib/clacky/mcp/oauth/credential_store.rb`
+- Create: `spec/clacky/mcp/oauth/credential_store_spec.rb`
+
+- [ ] **Step 1: Write failing credential specs**
+
+Cover deterministic per-server lookup, mode-0600 writes, atomic replacement, refresh-token rotation, deletion, malformed-file recovery, and absence of token values from `inspect`.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/credential_store_spec.rb`
+Expected: FAIL because the store is undefined.
+
+- [ ] **Step 3: Implement the file-backed store**
+
+Persist JSON below `~/.clacky/mcp/oauth/`, sanitize server names for paths, serialize writes with a lock file, write to a same-directory temporary file, chmod 0600, fsync, and rename atomically.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/credential_store_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add lib spec && git commit -m "feat(mcp): store oauth credentials securely"`
+
+### Task 3: Metadata discovery, DCR, and PKCE authorization
+
+**Files:**
+- Create: `lib/clacky/mcp/oauth/http_client.rb`
+- Create: `lib/clacky/mcp/oauth/authorization_manager.rb`
+- Create: `spec/clacky/mcp/oauth/authorization_manager_spec.rb`
+- Create: `spec/support/oauth_mcp_server.rb`
+
+- [ ] **Step 1: Write failing authorization specs**
+
+Use a local HTTPS-capable fixture abstraction to test challenge parsing, RFC 9728 protected-resource discovery, RFC 8414 authorization-server discovery, DCR request fields, S256 PKCE, loopback-only callbacks, state verification, code exchange, denied consent, bounded responses, and redacted errors.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/authorization_manager_spec.rb`
+Expected: FAIL because the manager is undefined.
+
+- [ ] **Step 3: Implement authorization manager**
+
+Generate a random loopback port and state, register `application_type: native`, open the system browser, capture the callback, exchange the code, persist expiry and refresh credentials, and validate all remote endpoints as HTTPS.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/authorization_manager_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add lib spec && git commit -m "feat(mcp): authorize remote servers with pkce"`
+
+### Task 4: Token refresh session
+
+**Files:**
+- Create: `lib/clacky/mcp/oauth/session.rb`
+- Create: `spec/clacky/mcp/oauth/session_spec.rb`
+
+- [ ] **Step 1: Write failing session specs**
+
+Cover valid-token reuse, refresh within a one-minute expiry skew, refresh-token rotation, concurrent refresh serialization, invalid-grant cleanup, missing-login errors, one forced refresh, and secret-redacted exceptions.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/session_spec.rb`
+Expected: FAIL because `Session` is undefined.
+
+- [ ] **Step 3: Implement the session**
+
+Expose `authorization_headers` and `invalidate!`; refresh through the token endpoint when needed and persist only successful responses.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `bundle exec rspec spec/clacky/mcp/oauth/session_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add lib spec && git commit -m "feat(mcp): refresh oauth sessions automatically"`
+
+### Task 5: HTTP transport authentication integration
+
+**Files:**
+- Modify: `lib/clacky/mcp/http_transport.rb`
+- Modify: `lib/clacky/mcp/client.rb`
+- Modify: `spec/clacky/mcp/http_transport_spec.rb`
+
+- [ ] **Step 1: Write failing transport specs**
+
+Cover bearer injection without mutating static headers, proactive refresh use, exactly one invalidate-and-retry on 401, no retry for non-authenticated servers, no retry after the second 401, and redacted transport errors.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `bundle exec rspec spec/clacky/mcp/http_transport_spec.rb`
+Expected: FAIL because transport has no authorization provider.
+
+- [ ] **Step 3: Integrate OAuth session**
+
+Accept an optional authorization provider, merge its headers per request, capture the 401 challenge, invalidate once, retry the same body once, and preserve MCP session headers and existing static-header behavior.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `bundle exec rspec spec/clacky/mcp/http_transport_spec.rb spec/clacky/mcp/skill_provider_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add lib spec && git commit -m "feat(mcp): authenticate remote http transports"`
+
+### Task 6: MCP OAuth CLI
+
+**Files:**
+- Create: `lib/clacky/mcp/cli_commands.rb`
+- Create: `spec/clacky/mcp/cli_commands_spec.rb`
+- Modify: `lib/clacky/cli.rb`
+- Modify: `lib/clacky.rb`
+
+- [ ] **Step 1: Write failing CLI specs**
+
+Cover `mcp capabilities --json`, `mcp login SERVER`, `mcp status SERVER --json`, `mcp logout SERVER`, unknown servers, non-OAuth servers, and output that contains status metadata but no tokens.
+
+- [ ] **Step 2: Verify RED**
+
+Run: `bundle exec rspec spec/clacky/mcp/cli_commands_spec.rb`
+Expected: FAIL because `Clacky::Mcp::CliCommands` is undefined.
+
+- [ ] **Step 3: Implement and register the Thor subcommand**
+
+Expose `remote_oauth: true` as a capability, authorize configured servers, report connected/expired/disconnected states, and delete credentials on logout.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `bundle exec rspec spec/clacky/mcp/cli_commands_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add lib spec && git commit -m "feat(mcp): add oauth lifecycle commands"`
+
+### Task 7: Documentation and complete verification
+
+**Files:**
+- Modify: `docs/mcp-architecture.md`
+- Modify: `docs/mcp.example.json`
+- Modify: `README.md`
+- Modify: `README_CN.md`
+- Create: `spec/clacky/mcp/oauth/integration_spec.rb`
+
+- [ ] **Step 1: Write the end-to-end integration spec**
+
+Exercise login callback, credential persistence, MCP initialize/tools list/tool call, expiry refresh, 401 retry, status, and logout against the local fixture.
+
+- [ ] **Step 2: Verify the integration RED then GREEN**
+
+Run before final wiring: `bundle exec rspec spec/clacky/mcp/oauth/integration_spec.rb`; confirm the expected missing wiring failure. Complete wiring and rerun for PASS.
+
+- [ ] **Step 3: Document configuration and security behavior**
+
+Add a generic OAuth MCP example, CLI instructions, credential location, HTTPS and loopback rules, and automatic refresh behavior in English and Chinese user-facing documentation.
+
+- [ ] **Step 4: Run full verification**
+
+Run: `bundle exec rspec`, `bundle exec rubocop`, and `bundle exec rake build`.
+Expected: zero test failures, zero lint errors, and a successfully built gem.
+
+- [ ] **Step 5: Commit**
+
+Run: `git add docs README.md README_CN.md spec lib && git commit -m "docs(mcp): document remote oauth connections"`
+
+### Task 8: Upstream PR preparation
+
+**Files:**
+- Inspect: all files changed from `upstream/main`
+
+- [ ] **Step 1: Perform structured self-review**
+
+Run: `git diff upstream/main...HEAD`, inspect every changed file for provider-specific code, token leakage, compatibility regressions, unsupported Ruby syntax, debug output, and missing tests.
+
+- [ ] **Step 2: Run clean-room verification**
+
+Run the full test, lint, build, and gem-content checks from a clean checkout of the branch.
+
+- [ ] **Step 3: Push the feature branch**
+
+Run: `git push -u origin feature/mcp-oauth`.
+
+- [ ] **Step 4: Create the upstream PR**
+
+Run `gh pr create --repo clacky-ai/openclacky --base main --head RLBox:feature/mcp-oauth` with a summary of protocol support, security boundaries, tests, and ChatCut as an external validation case.
+
+- [ ] **Step 5: Inspect PR state**
+
+Run: `gh pr view --repo clacky-ai/openclacky --json url,state,headRefName,baseRefName,statusCheckRollup`.
+Expected: an OPEN PR targeting `main` from `feature/mcp-oauth`, with the URL recorded for handoff.

data/docs/superpowers/specs/2026-08-09-mcp-oauth-extension-fallback-design.md

@@ -0,0 +1,115 @@
+# Remote MCP OAuth and Extension Fallback Design
+
+## Purpose
+
+OpenClacky extensions need to connect users to OAuth-protected remote MCP servers without embedding access tokens in `mcp.json`. ChatCut is the first integration, but the client capability must remain provider-neutral.
+
+The delivery has two independently usable versions:
+
+1. A pure ChatCut extension that works on current OpenClacky releases by registering a local stdio bridge. The bridge owns OAuth and forwards MCP traffic to ChatCut's hosted Streamable HTTP endpoint.
+2. Native OpenClacky remote MCP OAuth. Once present, the same extension detects it and registers ChatCut as a direct HTTP MCP server; on older clients it falls back to the bridge.
+
+## User Experience
+
+Installing the ChatCut extension adds setup, status, and disconnect skills. Setup examines the installed OpenClacky capability instead of asking the user which mode to use.
+
+- On a client with native OAuth support, setup writes a direct HTTP server entry with `auth.type: oauth`, then runs the native login command.
+- On an older client, setup writes a stdio server entry pointing at the extension bridge. The bridge opens the browser when authorization is first required.
+- Both modes expose the same `mcp:chatcut` virtual skill and the same remote ChatCut tools and playbooks.
+- Setup merges the `chatcut` entry without overwriting other MCP servers. Disconnect removes only the entry owned by the extension and deletes only ChatCut credentials.
+- A newly registered MCP is used from a new session on current clients. Native hot reload may be added independently and is not required for protocol correctness.
+
+## Shared Configuration Contract
+
+Native mode uses a direct remote server:
+
+```json
+{
+  "mcpServers": {
+    "chatcut": {
+      "type": "http",
+      "url": "https://api.chatcut.io/api/external-mcp/mcp",
+      "auth": {
+        "type": "oauth",
+        "resource": "https://api.chatcut.io/api/external-mcp/mcp"
+      },
+      "description": "Edit and create videos through ChatCut"
+    }
+  }
+}
+```
+
+Fallback mode uses the installed extension bridge:
+
+```json
+{
+  "mcpServers": {
+    "chatcut": {
+      "command": "ruby",
+      "args": ["/absolute/extension/path/bridge/chatcut_mcp_bridge.rb"],
+      "description": "Edit and create videos through ChatCut"
+    }
+  }
+}
+```
+
+The extension records its selected mode and managed configuration fingerprint under `~/.clacky/ext-data/chatcut/`. It does not silently replace a user-managed `chatcut` entry that differs from the recorded fingerprint.
+
+## Extension Bridge
+
+The bridge is a provider-specific compatibility adapter distributed with the extension. It speaks MCP JSON-RPC over stdin/stdout toward OpenClacky and Streamable HTTP toward ChatCut.
+
+The bridge performs OAuth protected-resource discovery, authorization-server discovery, dynamic client registration, Authorization Code with PKCE S256, loopback callback handling, access-token injection, refresh-token rotation, and one refresh-and-retry after a 401. It stores credentials in a mode-0600 JSON file below `~/.clacky/ext-data/chatcut/`; stdout remains protocol-only and diagnostics go to stderr with secrets redacted.
+
+The bridge validates that discovered authorization endpoints are HTTPS and belong to the authorization server advertised by the protected resource. Its callback binds only to `127.0.0.1`, uses a random available port, verifies `state`, and applies timeouts and response-size limits.
+
+## Native OpenClacky OAuth
+
+Native OAuth adds a provider-neutral authorization layer around HTTP MCP transport:
+
+- `clacky mcp login SERVER`, `status SERVER`, and `logout SERVER` commands.
+- OAuth metadata discovery from a 401 `WWW-Authenticate` challenge or an explicit resource URL.
+- Dynamic Client Registration and Authorization Code with PKCE for public native clients.
+- A credential store outside `mcp.json`, with mode-0600 files as the portable baseline.
+- Automatic bearer injection, proactive refresh near expiry, and one refresh-and-retry after a 401.
+- Secret-safe exceptions and logs.
+
+The HTTP transport remains responsible only for MCP HTTP semantics. An OAuth session supplies headers and handles authorization-specific retries. Static `headers` remain supported for non-OAuth servers.
+
+## Capability Detection
+
+The native client exposes capability detection through `clacky mcp capabilities --json`. The extension selects native mode only when the response includes `remote_oauth: true`. Absence of the command, invalid JSON, or a false value selects bridge mode.
+
+This avoids version string comparisons and permits backports. The bridge remains installed even in native mode so downgrading OpenClacky and rerunning setup produces a working fallback.
+
+## Security and Failure Behavior
+
+- Tokens, authorization codes, PKCE verifiers, client secrets, and refresh tokens never appear in `mcp.json`, agent prompts, or stdout protocol frames.
+- OAuth is refused for non-HTTPS remote resources and authorization endpoints; loopback HTTP is allowed only for the local callback.
+- A mismatched OAuth `state`, missing code, registration failure, denied consent, invalid refresh response, or malformed metadata produces an actionable error without leaking secrets.
+- Concurrent processes serialize credential updates and write through a temporary file followed by an atomic rename.
+- Refresh-token rotation replaces the stored refresh token only after a successful token response.
+- A user-managed conflicting MCP entry is preserved and setup stops with a clear conflict message.
+
+## Compatibility and Distribution
+
+The extension package contains Ruby source, skills, manifest, icon, tests, and documentation only. It does not bundle FFmpeg or copy ChatCut's Codex plugin. ChatCut playbooks are loaded from the MCP server through `list_skills` and `load_skill`.
+
+The OpenClacky change remains generic and carries no ChatCut constants, UI labels, endpoints, or business logic.
+
+## Acceptance Scenarios
+
+1. On an unmodified current OpenClacky build, extension setup installs a stdio `chatcut` entry without disturbing another MCP entry.
+2. First bridge use opens ChatCut authorization, persists protected credentials, lists ChatCut tools, and keeps stdout valid JSON-RPC.
+3. An expired access token is refreshed without user action, with rotated refresh credentials persisted.
+4. On a native-OAuth OpenClacky build, extension setup installs a direct HTTP entry and does not invoke the bridge.
+5. Native `mcp login`, `status`, and `logout` work against a standards-compliant local test authorization server.
+6. Native MCP calls inject the bearer token, refresh once after 401, and never expose tokens in errors.
+7. Downgrading to a client without the capability and rerunning setup changes the extension-managed entry back to bridge mode.
+8. Disconnect removes the managed ChatCut entry and ChatCut credentials while preserving unrelated MCP configuration.
+
+## Assumptions
+
+- ChatCut continues to support MCP protocol version `2024-11-05`, Dynamic Client Registration, PKCE S256, refresh tokens, `list_skills`, and `load_skill` as documented in its WorkBuddy integration.
+- The first release uses a protected file credential store for portability. OS keychain integration can be added behind the same store interface later.
+- Publishing the standalone extension repository is separate from the OpenClacky upstream PR; both artifacts are committed and testable locally before publication.

data/lib/clacky/agent/cost_tracker.rb

@@ -13,6 +13,21 @@ module Clacky
         @billing_store ||= Billing::BillingStore.new
       end
 
+      # Merge a finished subagent's spend into this agent's cumulative total.
+      # Fan-out runs several subagents on separate threads against the same
+      # parent, so the read-modify-write must be atomic.
+      # @return [Float] the cost that was absorbed
+      def absorb_subagent_cost(result, notify_ui: true)
+        cost = result && result[:total_cost_usd] || 0.0
+        add_cost(cost)
+        @ui&.update_sessionbar(cost: @total_cost, cost_source: @cost_source) if notify_ui
+        cost
+      end
+
+      private def add_cost(amount)
+        @cost_mutex.synchronize { @total_cost += amount }
+      end
+
       # Track cost from API usage
       # Updates total cost and displays iteration statistics
       # @param usage [Hash] Usage data from API response
@@ -22,7 +37,7 @@ module Clacky
         # Priority 1: Use API-provided cost if available (OpenRouter, LiteLLM, etc.)
         iteration_cost = nil
         if usage[:api_cost]
-          @total_cost += usage[:api_cost]
+          add_cost(usage[:api_cost])
           @cost_source = :api
           @task_cost_source = :api
           iteration_cost = usage[:api_cost]
@@ -39,7 +54,7 @@ module Clacky
           # Only accumulate cost when the model has known pricing.
           # Unknown models return nil — display N/A, don't add to total.
           if cost
-            @total_cost += cost
+            add_cost(cost)
             iteration_cost = cost
             @cost_source = pricing_source
             @task_cost_source = pricing_source

data/lib/clacky/agent/hook_manager.rb

@@ -12,8 +12,11 @@ module Clacky
       :session_rollback
     ].freeze
 
-    def initialize
+    attr_accessor :agent
+
+    def initialize(agent: nil)
       @hooks = Hash.new { |h, k| h[k] = [] }
+      @agent = agent
     end
 
     def add(event, &block)
@@ -21,20 +24,28 @@ module Clacky
       @hooks[event] << block
     end
 
+    # @return [Hash] `{action: :allow}`, `{action: :deny, reason:}`, or
+    #   `{action: :handled, result:}` when a hook fulfilled the call itself.
+    # Extra trailing arg: the agent that owns this hook chain, so ext hooks can
+    # call `agent.emit_event(...)`. Blocks are procs — those declaring fewer
+    # params (`|call|`, `|call, result|`) silently ignore it.
     def trigger(event, *args)
       validate_event!(event)
       result = { action: :allow }
 
       @hooks[event].each do |hook|
         begin
-          hook_result = hook.call(*args)
+          hook_result = hook.call(*args, @agent)
           next unless hook_result.is_a?(Hash)
           # First deny wins and stops the chain: a weaker later verdict must
           # never clobber a stronger earlier one, and the first deny's reason
           # is the one that reaches the agent. Rewrite hooks mutate `call` in
           # place (chained rewrite), so for non-deny results there's nothing to
           # merge — we just keep going.
-          if hook_result[:action] == :deny
+          #
+          # :handled short-circuits the same way — the hook has already produced
+          # the tool's result, so later hooks have nothing left to act on.
+          if hook_result[:action] == :deny || hook_result[:action] == :handled
             result = hook_result
             break
           end