Add opt-in GWS context hooks

[omriariav]

Summary

• add disabled-by-default, read-only GWS hook runtime with bounded cache and source refreshes
• package thin Codex and Claude adapters plus mirrored setup guidance
• add privacy-safe status/test output and focused hook coverage

Closes #205
Closes #206
Closes #207

Verification

• go test -race ./internal/hooks ./cmd
• make test
• make vet
• make build
• make ci

[github-actions]

Summary

This PR adds opt-in Claude/Codex session hooks, including CLI configuration commands, Workspace context collection, caching, adapters, tests, and setup documentation.

What looks good

• Hook configuration is disabled and preview-only by default.
• Workspace reads use explicit command allowlisting and bounded timeouts.
• Config and snapshot writes use restrictive permissions and atomic renames.
• Tests cover TTL behavior, degraded refreshes, sensitive workspace config rejection, adapters, and time formatting.
• git diff --check passed.

Issues found

Critical

• Cached Workspace content is neither scoped to the current workspace nor bound to its configuration. cmd/hooks.go:431 always uses one shared snapshot path, while runtime.go:203 loads that snapshot without identifying its originating workspace or source configuration. Consequently, opening workspace B can inject cached Calendar/Gmail context collected in workspace A until refresh. Likewise, disabling a source or changing Chat spaces can continue injecting the old source’s content during the TTL. Key snapshots by workspace and configuration identity, or invalidate/filter them whenever either changes.

Warning

• The new hooks command hierarchy was not added to cmd/commands_test.go, contrary to the repository’s required command-structure coverage.
• README adds a hooks narrative but does not add gws hooks ... to the main command reference table. No skills/*/references/commands.md command reference was updated either, as required for new commands.

Verification

The Go tests could not run because the read-only environment prevented creation of the Go module cache. The PR is not ready to merge due to the cross-workspace cache leak.

[github-actions]

Summary

Adds optional session-context hooks, including CLI configuration commands, read-only Workspace collectors, host adapters, tests, and setup documentation.

What looks good

• Preview-before-apply configuration with atomic 0600 writes.
• Workspace config and command allowlists protect credentials and mutation.
• Runtime has bounded timeouts, cache isolation, and degraded-refresh handling.
• README, skill references, command registration tests, and runtime tests were added.
• git diff --check passes.

Issues found

Critical

• hooks/hooks.json uses an unsupported separate "args" field for Claude command hooks. Claude executes the "command" string; consequently this invokes bare sh without the script or event, so neither lifecycle hook runs. Put the complete invocation in "command", including the quoted script path and event.

Warning

• cmd/hooks.go always reports "healthy": true after configuration loads. Missing authentication or failure of every configured Workspace source still produces a healthy result, making the health check misleading. Derive health from auth readiness and configured source outcomes.

• .claude-plugin/plugin.json introduces the plugin at version 1.40.0, while the project is already 1.41.0. Align the new manifest with the current release version.

Tests could not run because the read-only environment prevented Go from creating /home/runner/go for its module cache.

[github-actions]

Summary

Adds opt-in time and Google Workspace session-context hooks, configuration commands, plugin adapters, caching/runtime logic, tests, and documentation.

What looks good

• Preview-first configuration with explicit --apply.
• Read-only command allowlist and bounded execution.
• Secrets and cached content excluded from status output.
• Good unit coverage for TTLs, workspace isolation, degraded refreshes, config precedence, and command structure.
• README and skill command references updated.
• Diff passes git diff --check.

Issues found

Warning

• internal/hooks/runtime.go:358: Email, Chat, Calendar, and Task content is injected directly into privileged additionalContext without identifying it as untrusted data. A malicious message could contain prompt-injection instructions. Wrap the Workspace section with an explicit directive to treat its contents only as data and never follow instructions embedded within it.

No other actionable issues found.

Testing note: go test ./... could not run because this review environment is entirely read-only and Go could not create its module/build cache.

[github-actions]

Summary

This PR adds opt-in session-context hooks, configuration/runtime packages, Claude/Codex adapters, documentation, and extensive tests.

What looks good

• Configuration changes default to preview-only and require --apply.
• Workspace reads use an explicit read-only command allowlist.
• Cached context and credentials are excluded from status/health output.
• Atomic, permission-restricted configuration/cache writes are used.
• README, command references, command registration tests, and runtime tests were added.

Issues found

Warning

• cmd/hooks.go:519: writeHookJSON directly uses json.Encoder, bypassing GetPrinter(). Consequently, public hook commands ignore --format text, --format yaml, and --quiet, despite those flags being documented in commands.md:17. Keep the hidden hook envelope JSON-specific, but route status, preview, and test output through the standard printer.

• cmd/hooks.go:24: All new subcommands omit Args: cobra.NoArgs, so accidental positional arguments such as gws hooks status typo are silently accepted. Add argument validation and command tests covering rejection.

Tests could not be executed because the review environment’s filesystem is read-only, including Go’s module/cache locations.

[github-actions]

Summary

The PR adds opt-in Claude/Codex session hooks, new gws hooks commands, configuration/cache handling, Workspace context providers, plugin manifests, documentation, and tests.

What looks good

• Cobra registration, flags, runXxx functions, and printer usage follow existing patterns.
• Configuration writes are atomic and permission-restricted.
• Workspace data is bounded, marked untrusted, and omitted from health/status output.
• README, plugin skills, command references, and command-structure tests were updated.

Issues found

• Critical — Repository-controlled configuration can enable access to private Workspace data. config.go merges .gws/hooks.json after user configuration, while the workspace schema permits both global and Workspace-provider enablement (line 321). Thus, after a user approves the plugin hook, any checked-out repository can commit configuration enabling Gmail, Calendar, and Tasks reads without separate user consent. Workspace configuration should not be allowed to override a user-scoped consent gate; restrict it to settings/source preferences beneath user-authorized providers.

• Warning — The read-only allowlist accepts a mutating Chat invocation. ReadOnlyArgs accepts every chat unread argument sequence, including chat unread spaces/id --mark-read. That flag updates the user’s read state. Validate the complete argument shape and explicitly reject --mark-read and unknown flags.

• Warning — Health checks can report healthy after a failed refresh. When refresh loses a source, workspace returns the previous successful snapshot. Its old “available” statuses then make hookHealthy return true despite the current failure appearing in diagnostics. Health should account for refresh diagnostics/current attempt results.

Tests could not be executed because the read-only environment prevented Go from creating its module cache.

[github-actions]

Summary

This PR adds optional time/Workspace context hooks, including new gws hooks commands, secure configuration/cache handling, host adapters, tests, and documentation.

What looks good

• Cobra registration and command structure follow repository conventions.
• Preview-before-apply and workspace consent restrictions are well enforced.
• Workspace reads use strict read-only argument allowlists and bounded timeouts.
• Sensitive cached content is permission-restricted and excluded from status output.
• README and both skill command references are updated.
• Coverage includes command structure, configuration, runtime behavior, adapters, and security cases.
• git diff --check passes.

Issues found

• Warning — Version was not bumped: This is a substantial new CLI feature, but Makefile and CLAUDE.md remain at v1.41.0 while the new plugin manifests also declare v1.41.0. Project conventions require a version bump for new commands; use the next intended version consistently.

No critical correctness or security problems were found.

Verification note: go test ./... could not start because the read-only sandbox prevented creation of /home/runner/go; this was an environment limitation, not a reported test failure.

[github-actions]

Summary

Adds opt-in, read-only session context hooks, configuration commands, plugin adapters, documentation, and extensive tests.

What looks good

• Cobra registration, flags, printer usage, and command tests follow project patterns.
• Strong read-only command allowlisting, bounded execution, atomic restricted-permission storage, and untrusted-data delimiters.
• README and skill command references are updated.
• Comprehensive runtime, configuration, manifest, and command-structure coverage.
• git diff --check passed.

Issues found

No Critical, Warning, or Suggestion issues found. The PR is clean and ready to merge.

Test execution was unavailable because the read-only environment prevented Go from creating its module cache; CI should confirm go test ./....