akiiwa-games/AgentCompass / skills/agent-compass
agent-compass
FlaggedMulti-agent task router and subscription quota scheduler. Choose owner, model and effort, outbound authorization, advisor use, and continuation for delegated work. Reads local usage and effective account policy, profiles the task with the configured System-One scorer, then allocates a compatible worker. Use for independent worker or advisor work; ordinary local execution needs no routing.
references/parent-address-gate.md
View on GitHub# Parent addressing and worker questions
The spawn gate prevents accidental unrouted launches. It is not a security boundary against a session that
deliberately disguises a launch: it judges the program each simple command of a shell line runs (seen through
interpreters and wrappers), and a line it cannot parse or a program that is not a literal is not a launch.
- Failure: an unaddressed worker cannot reach its coordinator; UI questions (including `request_user_input_async`) strand the workflow in the worker session.
- Action: refuse dispatch without an actual parent ID; refuse interactive user-question calls by an identified worker. Reads, repairs, messages and main-session questions remain allowed.
- Decision: use the launching session's host ID, include it and its messaging address in the delivered assignment, and preserve parentage in host metadata. Never substitute `top-level`, a task ID or the worker's own ID. Paseo resolves the parent before creation; native host orchestrators must carry the coordinator session ID plus its live inbox address and preamble.
- Recovery: obtain the actual parent from the host (`PASEO_AGENT_ID`, or the native host session ID and inbox address), supply it to `roll`, then deliver `worker_prompt_file` unchanged with the assignment. Workers send questions through the parent messaging channel.
- Degradation: missing parent information prevents launch. Missing worker-role evidence alone does not block a main-session question. Failed delivery after launch returns `BLOCKED / needs_input` through the existing result channel; it never permits a local question UI.
- Coverage: local hooks enforce questions for Paseo-labelled workers and CLI workers marked by the router. Native host preambles carry the same rule; runtime enforcement there depends on the host exposing worker identity to its hook.
## Completion-notification gate contract
- **Failure:** disabling completion notifications can lose the result of a worker without messaging tools.
- **Action:** block only `send_agent_prompt` with explicit `notifyOnFinish: false` from a parent to its own worker, including statically parsed wrapper calls.
- **Decision:** the hook's caller ID must equal the target's locally persisted `router.parent_id` / `paseo.parent-agent-id`; conflicting labels do not prove ownership. No network lookup is needed.
- **Recovery:** set `notifyOnFinish: true` or omit the parameter. Worker-to-parent questions and final reports remain allowed with `false`.
- **Degrade:** missing caller identity, missing/unreadable target records, ambiguous ownership or dynamic wrapper arguments leave this check open; other router checks still apply.
## Disabled-target, quota and context-rotation gate contract
The gate governs dispatch: a launch, and a parent handing more work to its own worker. It does not govern communication between sessions, and host policy (`allowed_accounts`) is not a gate condition: it says which accounts the router chooses by itself.
- **Failure:** launching new work on a model the user unchecked in model management without the user naming that route, on an account with leftover meter fields or on a quota-exhausted window ignores the user's model choice or the window limits; a native launch on the authority of a project rule (`hard_constraint`) would override one machine's choice to keep an account out of automatic routing; handing another turn to one's own worker on an exhausted window wastes the turn, and one at or above the configured context rotation threshold (`rotate_after_carried_tokens`, set in the tray) in historical uncompressed tokens risks context drift.
- **Action:** block new launches on an unchecked model unless the launch's authority is a `user_override` decision (a bound launch: the decision behind its `router.dispatch_id`; a native launch: its matched ledger row; Workflow, schedules and unbound `create_agent` launches never are). A native sub-agent (Claude Code `Agent`/`Task`, Codex `spawn_agent`) runs on the calling session's own account: a launch that names a model and no provider or account resolves to that account when discovery records it (the one account of the family whose home is the directory the session's `CLAUDE_CONFIG_DIR` / `CODEX_HOME` names) for the checkbox rule above only, and its refusal names the model the launch asked for, that account and the matched ledger row; every quota, window, floor and cooldown check on a native launch resolves the launch as it is written. Also block launches on an account with leftover meter fields or a quota-exhausted target, and a native launch whose matched ledger row is a project rule (`hard_constraint`, `dot_closed_loop`) carrying `host_policy_violation`. Block a parent's new turn to its own idle or unknown-state worker only for facts: leftover meter fields on its account, a quota window it draws that refuses a launch, or the rotation limit. Not blocked: a message to an agent the caller does not own (a peer, a session the user opened, a worker of another parent, an agent without labels, an ancestor), control messages to the caller's own running worker, and a turn to the caller's own worker on an account outside `allowed_accounts` or a model unchecked since its launch: continuing a worker that exists is not the router choosing that account or model. Completion-notification checks remain unchanged.
- **Decision:** ownership is the completion-notification test: every nonempty locally persisted `router.parent_id` / `paseo.parent-agent-id` of the target must name the caller, and the target is not the caller itself. A label names the caller when it equals one of the caller's identities (the calling Paseo agent ID from the payload or `PASEO_AGENT_ID`, and the host session ID the hook payload carries as `session_id`), or names a Paseo agent whose local record runs that host session (`persistence.sessionId` / `runtimeInfo.sessionId`). A caller with none of these, or labels that name another session, proves nothing, and the turn is communication. The caller's own worker is running when its local Paseo record says `lastStatus: running` (or `status: running` when present); an explicit current non-running `status` takes precedence, and `activeTurn` alone, tool arguments and prompt wording do not prove a running turn. A launch's host-policy standing is decided on the matched row's `constraint`: a `user_override` row is launch authority whatever it carries (v0.7.0 also wrote `host_policy_violation` on those rows); any other constraint carrying `host_policy_violation` (which `record` writes from `host_policy.account_allowed`) is not. No network lookup is required.
- **Recovery:** while the owned worker is running, send a control message with completion notifications enabled. Otherwise collect its existing output, use `cancel_agent` if necessary, write a handoff and run `agentcompass roll --brief <handoff.md>`. A launch on an unchecked model: roll among the checked ones, or, when the user named this model in this request, record it with `--constraint user_override --basis "<the user's words>"`; checking it again is the user's choice in model management. Leftover meter fields: `agentcompass setup` removes them. A launch refused for `host_policy_violation`: if the user named this route in this request, record it with `--constraint user_override --basis "<the user's words>"`; otherwise roll without naming a route. An over-limit worker still requires rotation.
- **Degrade:** a native launch whose own account is not recorded (no discovered account with that home, more than one, another harness) or that names no model resolves to no account when the model alone does not identify one, so the checkbox is not checked for it: the gate does not guess the caller's account. Missing caller identity, missing or unreadable target records and conflicting ownership make a turn communication, so it passes: the gate does not refuse on a guess. An unreadable fleet resolves no account or bundle and refuses nothing. Local `lastStatus` is the persisted snapshot, not an atomic daemon guarantee: status can change between the hook and message delivery, and offline records can be stale. Without a structured steer-only API this hook cannot eliminate that race; do not infer liveness from timestamps or message keywords. The session proof assumes one Paseo record per provider session: two records sharing one `persistence.sessionId` would both prove that session. A check the gate could not make (the fleet or a quota read that throws, a shell command line that parses in neither dialect, an exception inside the decision, stdin that is empty or not a JSON object) stays open as above, and the allow says so, naming the check and the error's type, never its text. Where the word goes: Claude Code and Codex, a `systemMessage` beside the allow (a field of their hook output for every hook, shown to the user); Antigravity, the optional `reason` of the PreToolUse answer (documented as the explanation shown to the agent or to the user; not run against Antigravity, so what it shows beside an allow is not established); Pi, a line on stderr that the generated extension shows with `ctx.ui.notify` where Pi has a UI (TUI, RPC) and writes to its own stderr in print and JSON mode, where UI methods are no-ops. The code of a code-mode tool is not a shell command line and never gets the notice. A crash inside the decision is an allow with exit 0 and the word on every host (it was an uncaught exception and exit 1: non-blocking by the documentation of Claude Code and Codex and by the Pi extension, except on Claude Code for Windows without Git Bash, where it blocked; Antigravity's documentation does not say). A recorded quota failure's refusal names the account, the recorded windows the launch draws and the command that clears the record, and says what lifts it: a newer successful usage reading that shows the window under 100% used or past its reset time; time alone never does.
What this leaves ungoverned: a session can feed work to an idle agent it does not own, on any account, without a check. That agent's account, quota and context are its own parent's or the user's to watch, the message is visible in both sessions, and no loss from it has been observed; a check would need a notion of "work" in a message that the gate cannot read from a prompt.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |