CLI injection
How Qoc exposes a scoped set of qoc commands and workspace files into the agent runtime so the agent can research, propose trades, and write results back safely.
CLI injection gives the agent a controlled, workspace-scoped command surface — a subset of qoc subcommands plus read/write access to workspace files — so it can act without touching anything outside its sandbox.
How the agent sees the workspace
When qoc run (or a scheduled run) starts, Qoc launches the agent runtime (for example, Claude Code via the MCP integration) and makes two things available:
Workspace file tree — the agent can read all files in the workspace directory and write to a defined set of output paths (issues/, inbox/, orders/, research/, snapshots/).
Scoped `qoc` commands — a restricted command palette is injected as tool definitions so the agent can call them natively without shell access.
Commands available to the agent during a run
| Command | What the agent can do | Write access |
|---|---|---|
qoc status | Read workspace state, open issues, last run summary | No |
qoc snapshot | Capture current portfolio snapshot to snapshots/ | Yes — snapshots/ |
qoc run <issue> | Re-queue a specific issue for this run | No |
qoc inbox write | Create a new inbox item for human review | Yes — inbox/ |
qoc orders propose | Write a draft order file for human approval | Yes — orders/pending/ |
qoc research write | Persist a research note to research/ | Yes — research/ |
What the agent cannot do
The scoped surface is intentionally narrow. The agent cannot call qoc connect, qoc schedule, or any command that modifies workspace configuration or external connections.
The agent has no direct shell access. It cannot install packages, read files outside the workspace directory, or make outbound HTTP requests except through connectors explicitly enabled for the workspace.
Order files written to orders/pending/ are not executed automatically. A human approves them via qoc status or the Qoc UI before they reach a venue — every order is a commit you approve.
Example: agent proposes a trade
# orders/pending/20260705-aapl-trim.yaml
action: sell
symbol: AAPL
quantity: 50
order_type: limit
limit_price: 192.40
venue: NASDAQ
rationale: >
Trimming 20 % of AAPL position after earnings beat.
Position exceeds target weight by 1.8 pp post-move.
See research/2026-07-05-aapl-earnings.md for analysis.
proposed_by: agent-run-20260705T0830Z
status: pending_approvalSafety scoping is enforced by the host process, not the agent
The qoc binary acts as the gatekeeper. Even if the agent attempts to call a disallowed subcommand, the host process rejects it and logs the attempt. You do not need to trust the agent to self-limit.
How a typical agent run flows
- 1
Workspace context injected
Qoc assembles the context bundle (settings, entities, house rules) and starts the agent session.
- 2
Agent reads open issues
The agent calls
qoc statusto list open issues, then reads each issue file fromissues/. - 3
Agent researches and reasons
The agent reads
research/, calls enabled data connectors, and writes any new findings toresearch/. - 4
Agent writes outputs
Depending on findings, the agent writes draft orders to
orders/pending/, inbox items, or updated issue files. - 5
Run completes — human reviews
The run log is written to
snapshots/. You review pending orders and inbox items before anything executes.
Limit connector scope per workspace
Enable only the data connectors a workspace actually needs. A macro-research workspace does not need live order routing; restrict it to read-only market-data connectors in its desk.toml [connectors] block.