Giving ADK agents a tool that runs on your own machine (open-source async bridge)

[abhinaykrupa]

One limit I kept running into with ADK: a deployed agent can reason about my development machine perfectly well, but it can't reach it. Once the agent runs on Cloud Run, in Agent Engine, or in any sandbox, the things I actually want automated — run the test suite, check what's eating the disk, push a branch, tail a container's logs — are on the other side of a wall. The filesystem, the toolchain, the local Docker daemon, and the git credentials are all on my laptop.

cowork-to-code-bridge (MIT) is a small async bridge for exactly that. The sandboxed agent queues a task; a daemon on my own Mac/Linux box runs it and hands the result back.

How it works

Intentionally unexciting: no network call from the agent side, no inbound ports, nothing listening on the internet. Both sides read and write files in a shared directory holding queue/, results/, and to_cowork/. That's what makes it survive reboots and sandbox timeouts instead of dropping work on the floor.

from cowork_to_code_bridge import call_remote, queue_task, poll_task_result

# blocking — you want the answer now
call_remote("scripts/git_status.sh", args=["~/src/myrepo"])

# non-blocking — long work, short request timeout
job = queue_task("scripts/run_claude.sh",
                 args=["run the test suite and fix what breaks"],
                 timeout=1800,
                 idempotency_key="ci-fix-2026-07-25")
poll_task_result(job["task_id"])

Where it fits in ADK

The clean seam is a FunctionTool wrapping queue_task + poll_task_result. Because polling is idempotent and non-blocking, it fits the long-running-tool pattern well: the agent kicks off a 20-minute build, returns control, and picks the result up on a later turn rather than holding a request open. Wrapping it as an AgentTool on a dedicated "local machine" sub-agent also works nicely if you want the LLM to route to it explicitly.

The headline script is run_claude.sh, which hands the task to a full Claude Code agent on the machine instead of a fixed command — so the local end can plan and iterate, not just execute. About 22 other bundled scripts cover the smaller stuff (health, RAM, disk, ports, Docker, git, package state).

The parts worth scrutinizing

Giving an agent a shell on your own machine needs guardrails, so each task can set:

• max_budget_usd — spend ceiling, so a runaway loop can't drain credits
• permission_scope — plan / readonly / edit / full
• plan="…" — a human approves before anything executes
• idempotency_key — retries don't double-fire state-changing work

Progress streams back (call_remote_streaming) so a long build isn't a silent wait, and there's a bidirectional mode where the machine-side agent can ask the calling agent a question mid-task.

Status

Working and tested (330+ tests), MIT, macOS/Linux/WSL2. I'm the author and I'm after feedback more than stars. Open question I'd value ADK-specific input on: is the long-running FunctionTool really the right primitive for "this step must execute on host hardware," or is there a more idiomatic extension point I should be targeting instead?

Repo: https://github.com/abhinaykrupa/cowork-to-code-bridge

[farfromexact]

The FunctionTool seam is reasonable for the control plane: enqueue a task, return a task ID, and let a later call retrieve status or results. I would avoid holding one tool invocation open while the local machine performs a 20-minute build. A separate status or cancel operation makes retries and sandbox timeouts much easier to reason about.

The file mailbox also deserves a security review because it crosses a trust boundary. Use restrictive directory permissions, an allowlist of executable scripts, protection against symlink and path traversal attacks, task expiry, idempotency, bounded result sizes, and redaction of command output. The local daemon should run with the least privilege possible, and git credentials should never be included in task payloads or results.

For ADK integration, expose a small typed task schema and explicit progress states rather than asking the model to construct arbitrary shell commands. A long-running or background tool abstraction is a good fit for the lifecycle, while the bridge remains the host-side transport.

[abhinaykrupa]

This is the most useful review I've gotten on this project — thank you. Taking the three parts in turn.

The control plane

Agreed, and this is already the shape: queue_task returns a task_id and returns immediately, poll_task_result is idempotent and non-blocking, and they're separate operations. call_remote (the hold-it-open variant) exists for genuinely quick things like git_status.sh, and the guidance in the repo is to switch to queue_task past ~30s. Your framing is sharper than mine, though — I'd been presenting the blocking call as the default and the queue as the escape hatch, when the queue is the honest primitive and blocking is the convenience wrapper. I'll flip that emphasis in the docs.

Cancel is the real gap you've found. There's a cancellation path in the daemon but no first-class cancel(task_id) in the client surface, so today a wedged 20-minute build is waited out rather than killed. That's a legitimate operation for exactly the reason you give, and I'm adding it.

The trust boundary

This is the part I most wanted scrutinized, so let me answer it point by point rather than in general terms — including the two places you were right and I wasn't covered.

Already in place:

• Restrictive permissions — the daemon chmod 0o700s BRIDGE_ROOT, queue/, scripts/, and both to_cowork/ directories on every startup if it finds any group/other bit set, and logs when it tightens them. The token file and journal are opened 0o600. World-writable there would let any local user inject commands, so it's checked rather than assumed.
• Executable allowlist — no arbitrary shell, ever. script must fullmatch scripts/[A-Za-z0-9_/.-]+\.(sh|py), and fullmatch specifically because re.match only anchors the start. The named script must already exist under scripts/; the queue cannot deliver code, only select it.
• Symlink and traversal — defence in depth on top of the regex. The path is resolve()d and then checked with relative_to(SCRIPTS_DIR.resolve()), so a symlink pointing outside the scripts directory fails even if it satisfies the character class.
• Idempotency — idempotency_key is journal-backed. A replayed key returns the cached result instead of re-running, which is what makes retry-on-timeout safe for things like git push.
• Least privilege — the daemon runs as the user, not root, and per-task permission_scope (plan / readonly / edit / full) is clamped against an owner-set ceiling, so a caller holding the bridge token can request less trust but never more. Security-critical env vars (CLAUDE_FLAGS, BRIDGE_TOKEN, the ceilings, the task-correlation id) are protected: caller-supplied env can add new vars but attempts to override those are refused and logged. Otherwise a token holder could disarm the restrictions the owner configured in launchd.
• Auth — commands carry a token compared with hmac.compare_digest, and the daemon refuses to start with no token unless BRIDGE_ALLOW_UNAUTH=1 is set explicitly.

You were right about the rest:

• Bounded result sizes — this was a real bug, and worse than merely missing. Output looked bounded ([-65536:] on the way out) but the buffer it clipped was an unbounded list, so the cap applied to the result file and not to the daemon's memory. A loud child filled RAM first, and the tail only arrived if the process lived long enough to produce it. The progress log had no cap at all. Fixed: the tail is now bounded while streaming with oldest-chunk eviction, so resident size is O(limit) rather than O(total output); the progress log stops appending past its own cap. Both are env-tunable.

  Your point cuts deeper than sizing, though — silent truncation is its own hazard, because a caller can't distinguish a genuinely small output from the tail of an enormous one and will read a clipped stream as complete. Results now carry stdout_truncated and stdout_total_bytes (and the stderr pair), present only when something was actually dropped so untruncated results keep their existing shape.

• Task expiry — partial, and I'd overcounted it. There's a MAX_TIMEOUT ceiling per task and stale-queue draining on startup, but no TTL reaper on results/, so completed output accumulates until something clears it. Real gap; queued behind cancel.

• Redaction — not implemented, and I want to be careful not to oversell what I'll do here. Credentials are kept out of payloads structurally: git auth is whatever the machine's own credential helper provides, so it's never in a task payload or result, and the design intent is that secrets live on the host and never transit the mailbox. But that's a property of how the bundled scripts are written, not something enforced — a custom script that echoes env would put secrets in a result file today. Output-scanning redaction is heuristic and I'd rather not have it read as a guarantee it can't provide, so my inclination is to enforce the structural property harder and document the boundary plainly rather than ship a filter that catches AKIA… and misses everything shaped differently. If you've seen redaction done in a way that's actually load-bearing rather than reassuring, I'd genuinely like the pointer.

The bounded-output fix is pushed, with a resident-size test and a negative control confirming the old unbounded buffer would have failed it.

Typed schema over model-authored shell

This is the part that changed my thinking, and it's a sharper version of the question I asked. I'd been treating "the local end can plan and iterate" as the headline feature — run_claude.sh hands the task to a full Claude Code agent rather than a fixed command. Your framing separates two things I had collapsed: the transport should carry a typed task with explicit progress states, and how much autonomy the host end exercises is a property of the script being invoked, not of the interface. A typed schema doesn't cost me the agentic script; it stops the model from constructing arbitrary shell to reach it.

So: a typed task schema plus explicit progress states, with the model choosing among named tasks rather than composing command lines, and the long-running-tool abstraction owning the lifecycle while the bridge stays the host-side transport. That's a better answer to the ADK question in my original post than the one I was fishing for.

Thanks again — this was concretely useful, and it found a live bug.