feat(cowork): observe Claude Cowork tool calls via per-session settings injection

[tumberger]

Summary

Adds Claude Cowork observation and enforcement to the managed-observe daemon, reusing the existing Claude Code pipeline end to end (classify → store → stream → ledger). Cowork activity is recorded with agent: "cowork", so it appears alongside Claude Code with no downstream or schema changes. The posture follows the deployment-level managed.json mode — observe records would-decisions, enforce returns real deny/allow verdicts to the in-VM CLI.

Background

Claude Cowork runs the bundled Claude Code CLI inside a per-session VM whose root filesystem is rebuilt on each boot, so hooks can't be persisted in the image and the host daemon's unix socket is unreachable from the guest. What does survive — and cross the boundary — is the per-session CLAUDE config dir, which Cowork mounts from the host. This PR uses that mount as both transport legs: settings injection inbound, an event spool plus decision files outbound/return.

What this adds

• internal/agent/cowork — registers the cowork agent, reusing the Claude decoder/encoder (Cowork ships the same CLI, same hook formats).
• internal/coworkobserve — two host-side loops started by the daemon:
  • injector: merges a PreToolUse command hook into each new per-session settings.json (preserving existing settings/hooks, atomic write, stale variants replaced on mode switches).
  • collector: tails the spool files and replays each event into the daemon's existing localruntime socket as agent cowork. At-least-once delivery: offsets only advance past complete, successfully replayed lines and persist across restarts (cowork-spool-offsets.json), so restarts never duplicate ledger rows.
• Observe mode: the hook is fire-and-forget (append, exit 0); decisions are recorded as would-allow/deny, nothing blocks.
• Enforce mode (managed.json mode: "enforce", now accepted by config validation and plumbed through RunDaemon → runtimehost, so it drives every hook edge consistently):
  • the hook wraps each event in an envelope with a hook-generated request id, appends it to the spool, and polls kontext-cowork-decisions/<rid>.json for up to 10s inside the conventional 20s hook timeout;
  • the collector evaluates through the same socket (whose per-edge transform returns the real verdict when not observing), renders it with the standard Claude encoder, and writes the decision file atomically — the CLI honors the permissionDecision;
  • no verdict in time → the hook emits deny "Kontext daemon unavailable" itself: fail-closed, mirroring the sidecar's enforce behavior;
  • request ids originate in the VM and are validated against a strict charset before naming any file the daemon writes (path-traversal guard); orphaned decision files are TTL-cleaned; the scan tightens to 100ms under enforce.
• Health heartbeat: sessions seen vs hooked vs spooling, replay/deny/drop counters, logged every 5 minutes with explicit warnings — so a Cowork-internals change that breaks observation (or enforcement) is visible instead of silent.
• Drained spools (raw tool inputs) are deleted after an hour idle. Gated by cowork_enabled in managed.json (off by default); KONTEXT_COWORK_OBSERVE stays as a dev override.
• Unit tests: injector merge/mode-switch, collector partial lines, transport-failure retry, malformed lines, restart persistence, spool cleanup, camelCase decoding, enforce deny round-trip, unsafe-rid rejection.

Not changed

No changes to the ledger batch builder, the ingest contract, the store schema, or the stream. Cowork events flow through the existing path, tagged agent: cowork.

Caveats (also in the package doc)

• Spool events are self-reported in-VM telemetry — forgeable from inside the VM; not attested records.
• Enforcement gates agent-via-CLI actions only. A tool call landing before settings injection runs unguarded (heartbeat surfaces such sessions; FSEvents follow-up shrinks the window). A hook killed at the CLI's own timeout reads as allow, so fail-closed is best-effort within the timeout budget.
• Delivery is at-least-once; a replay retried after a partial send can very occasionally duplicate a ledger event (never silently drop one).
• The mechanism rides on undocumented Cowork internals (session dir layout, host mount, settings tier); the health heartbeat exists to make breakage visible.
• Run the daemon in the session user's context (LaunchAgent, not root LaunchDaemon) so injected files aren't root-owned.

Verified

Observe path locally end to end: real Cowork tool calls (bash + Chrome MCP tools) recorded and streamed, tagged agent: cowork. Enforce path covered by collector round-trip tests against a daemon-socket fake; needs one manual end-to-end pass in a real Cowork session before enabling for any customer (deny rendering in the Cowork UI, decision latency under real VM mount). gofmt/go vet/go build/go test -race ./... clean.

Follow-ups

• Injector uses a short poll loop; switch to FSEvents to shrink the injection window (which under enforce is a bypass window).
• Optional: a static linux/arm64 helper binary dropped into the session mount to replace the shell handshake (fsync, tighter deadlines) — depends on the mount allowing exec.

[tumberger]

• feat(cowork): observe Claude Cowork tool calls via per-session settings injection #283 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR adds Claude Cowork observation and enforcement to the managed observe daemon. The main changes are:

• Registers a new cowork agent adapter using the Claude hook format.
• Adds Cowork settings injection, event spooling, replay, decision files, cleanup, and health logging.
• Allows managed config mode to be either observe or enforce.
• Starts the Cowork observer from the managed daemon when enabled by config or environment.
• Adds unit tests for settings merge, spool replay, offset persistence, cleanup, and enforce decisions.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
internal/coworkobserve/coworkobserve.go	Adds the Cowork injector, collector, replay, decision, cleanup, and heartbeat loops.
internal/managedobserve/daemon.go	Plumbs managed mode into runtimehost and starts Cowork observation when enabled.
internal/managedconfig/config.go	Adds enforce mode validation and the cowork_enabled managed config field.

Sequence Diagram

sequenceDiagram
  participant CoworkCLI as Cowork Claude CLI
  participant Settings as Injected settings.json hook
  participant Spool as Session spool file
  participant Collector as coworkobserve collector
  participant Daemon as localruntime socket
  participant Decision as Decision file

  CoworkCLI->>Settings: PreToolUse event
  Settings->>Spool: Append event or envelope
  Collector->>Spool: Read complete JSONL lines
  Collector->>Daemon: Evaluate as agent cowork
  Daemon-->>Collector: Allow or deny result
  alt enforce mode
    Collector->>Decision: Write rendered Claude decision
    Settings->>Decision: Poll and emit verdict
  end

Loading

_{Reviews (1): Last reviewed commit: "docs(coworkobserve): document mode seman..." | Re-trigger Greptile}

[hasandemirkiran]

Looks good overall, left a few comments also:

Since enforce mode depends on shell behavior ($HOME, RID generation, append, polling, stdout shape, fail-closed timeout), I’d add a small integration-style test that runs the generated observe/enforce command under sh with a temp HOME and verifies append, decision emission, and fail-closed behavior.

Minor nit: comments still mention cowork_observe even though the field is now cowork_enabled:

• internal/coworkobserve/coworkobserve.go:98-100
• internal/managedobserve/daemon.go:103-106

[hasandemirkiran]

inject skips .claude dirs older than 3 minutes before recording them in health state or checking whether the installed hook matches the current mode. If the daemon starts late, or if config changes from observe to enforce while a Cowork session is already running, that session can remain unhooked or keep the observe hook without the heartbeat surfacing it. I’d either track stale discovered sessions before the cutoff and warn on them, or re-check/re-merge existing settings when mode changes

[tumberger]

Went with your second suggestion (re-apply settings when the mode changes) in 14267a1.

The thing that made it click: the watch/block setting is only read once, when the daemon starts — it can't change while the daemon is running. So both of your cases are really the same moment: the daemon coming up while sessions are already alive (either it restarted, or someone changed the setting and restarted it to apply the change). By then the session folder hasn't changed in a while, so the normal every-few-seconds check always skips it and can never catch up to those sessions on its own.

Fix: when the daemon starts, it now does one pass over every recent session and re-applies the correct hook (watch or block), ignoring the "looks old, skip it" rule. After that, the normal check only has to handle brand-new sessions, which always look fresh. It also records each session before installing the hook, so if installing ever fails, the health log surfaces it instead of staying silent.

[hasandemirkiran]

The spool cleanup can race with the hook append path. The hook appends to $HOME/kontext-cowork-events.jsonl, while cleanup stats the file and then removes it if it looks drained and old. If Cowork appends between the stat and remove, that new event can be written to a file that gets unlinked. I’d avoid deleting spools for still-live session dirs, or add a stronger coordination mechanism such as locking/per-event files/re-stat-and-backoff

[tumberger]

Agreed, real TOCTOU. Fixed in 411792a: cleanup re-stats the spool (size + modtime) immediately before os.Remove and bails if either changed since the drained/idle check — so an append landing in that window is left for the next tick to drain instead of being unlinked.

Kept it a narrow guard rather than a redesign because the window only opens after a full hour of spool idleness, and under enforce the call still fails closed. TestCleanupSkipsSpoolAppendedInRemoveWindow drives the race deterministically via a test-only seam.

[tumberger]

Thanks for the review @hasandemirkiran — addressed both points from the top-level comment:

• Shell integration test (39d47f5): added tests that run the actual observe/enforce command strings under /bin/sh with cwd in outputs/. They cover the spool append + exit 0, empty-stdin deny, the enforce decision round-trip (discovering the shell-generated rid from the spooled envelope, then parking the decision the hook polls for), and fail-closed when no decision arrives (loop count substituted 100→3 to keep it fast, with a guard asserting the real constant is unchanged).
• cowork_observe → cowork_enabled doc nit (bd9a93c): both comments corrected; only the KONTEXT_COWORK_OBSERVE env var keeps that spelling (deliberately a different name).